HTTPc_WebSockUpgrade()

Owned by Former user (Deleted)
Last updated: Jan 12, 2021 by WES Admin
3 min read

Upgrade a HTTP client connection to a WebSocket.

Files

http-c.h/http-c.c

Prototype

          CPU_BOOLEAN HTTPc_WebSockUpgrade (HTTPc_CONN_OBJ        *p_conn_obj,
                                            HTTPc_REQ_OBJ         *p_req_obj,
                                            HTTPc_RESP_OBJ        *p_resp_obj,
                                            HTTPc_WEBSOCK_OBJ     *p_ws_obj,
                                            CPU_CHAR              *p_resource_path,
                                            CPU_INT16U             resource_path_len,
											HTTPc_FLAGS			   flags,
                                            HTTPc_ERR             *p_err)


Arguments

p_conn_obj

Pointer to the HTTPc Connection Object for which to open the socket.

p_req_obj

       Pointer to request to send.

p_resp_obj

       Pointer to response object that will be filled with the received response.

p_ws_obj

        Pointer to WebSocket object.

p_resource_path

        Pointer to complete URI (or only resource path) of the request.

resource_path_len

        Resource path length.

flags

Configuration flags:

HTTPc_FLAG_WEBSOCK_NO_BLOCK

p_err

Pointer to variable that will receive the return error code from this function:

    HTTPc_ERR_NONE 
    HTTPc_ERR_WEBSOCK_CONN_ALREADY_WEBSOCKET 
    HTTPc_ERR_INIT_NOT_COMPLETED 
    HTTPc_ERR_NULL_PTR 
    HTTPc_ERR_CONN_IS_RELEASED 
    HTTPc_ERR_REQ_IS_USED
    HTTPc_ERR_REQ_PARAM_METHOD_INVALID
    HTTPc_ERR_REQ_PARAM_RESOURCE_PATH_INVALID
    HTTPc_ERR_FEATURE_DIS
    HTTPc_ERR_PARAM_INVALID
    HTTPc_ERR_MSG_Q_FULL
    HTTPc_ERR_MSG_Q_SIGNAL_FAULT 
    HTTPc_ERR_CONN_SIGNAL_CREATE
    HTTPc_ERR_CONN_SIGNAL_TIMEOUT
    HTTPc_ERR_CONN_SIGNAL_FAULT 
    HTTPc_ERR_CONN_SIGNAL_DEL 
    HTTPc_ERR_WEBSOCK_REQ_MEM_ERR 
    HTTPc_ERR_WEBSOCK_SHA1_ENCODE_FAIL
    HTTPc_ERR_WEBSOCK_BASE64_ENCODE_FAIL

Returned Values

DEF_OK, 

      if the operation is successful.

DEF_FAIL,

      if the operation has failed.

Required Configuration

None.

Notes / Warnings

  1. Since the WebSocket Upgrade handshake is based on a HTTP request, the connection object p_conn_obj MUST have already established connected to the desired host server. The Connection MUST be initialized has PERSISTENT.

  2. Any HTTP request/response features available can be used during the Websocket Upgrade Request

  3. During a WebSocket Upgrade handshake, the following mandatory header fields are managed by the WebSocket module and MUST NOT be set by the Application:
        Connection
        Upgrade
        Sec-WebSocket-Key
        Sec-WebSocket-Accept
        Sec-WebSocket-Version

  4. During a Websocket Upgrade Handshake, the following optional Header fields can be managed by the Application using the standard HTTPc Request/Response API:
        Sec-WebSocket-Protocol
        Sec-WebSocket-Extensions

  5. If the Websocket Upgrade Handshake is successful, Status Code in the response object should be '101'. This means that the Host server has switched to the Websocket protocol. Otherwise, the response object will TYPICALLY described the reason of the failure.

  6. When the WebSocket Upgrade is completed, any HTTP request is no more allowed and it is not possible to switch the connection protocol to HTTP. However, if a HTTP request is required to be sent by the Application, it SHOULD do one of the following procedure:

    1. Close the current WebSocket Connection by sending a Close Message and open again the HTTP connection.

    2. Open a different HTTP connection with the Host Server.