Upgrading a HTTP Connection

Because it use many HTTP fonctionalities for opening handshake, WebSocket protocol has been integrated has a part of uC/HTTP-client. Furthermore, all the uC/HTTP-client request features, such as query string, are available during the opening handshake request. Here are the usual steps to upgrade a HTTP connection to WebSocket.

First, create a HTTPc Connection to the desired server using HTTPc_ConnOpen(). If successful, it will return a valid HTTPc_CONN_OBJ object that can be used for the next request.
Before sending a Upgrade Request to the server, an HTTPc_WEBSOCK_OBJ object may be configured by using HTTPc_WebSockSetParam() function. Note that WebSocket Message Reception is done through hook functions that are configured in HTTPc_WEBSOCK_OBJ object passed during the WebSocket Upgrade.
Because the WebSocket opening handshake is essentially a specific HTTP Request with specific headers, HTTPc_WebSockUpgrade() function is available to simplify the connection upgrade. It will automatically set the mandatory headers and validates the response from the server. Because it also use a HTTPc_REQ_OBJ object, you can use all the features available during a normal HTTP Request.
Finally, when the opening handshake is successful, the connection that has been established in step 1 has now upgraded to WebSocket and is no more related to HTTP. At this point, HTTPc_WebSockSend() can be used for WebSocket Message Transmission and the WebSocket Message Reception will be processed through the RX hook configured in HTTPc_WEBSOCK_OBJ.

Related Hooks

Name	Description	Object	Parameter Type
On Open	Called when a WebSocket Upgrade is successful.	HTTPc_WEBSOCK_OBJ	HTTPc_PARAM_TYPE_WEBSOCK_ON_OPEN
On Close	Called when a connection that has been successfully upgraded close.	HTTPc_WEBSOCK_OBJ	HTTPc_PARAM_TYPE_WEBSOCK_ON_CLOSE

Example

The following example simply show how to create a WebSocket with the . As you can see below, it will first open a HTTP connection to the remote server and then upgrade it. Note that there's no Message Reception mechanism configured in this example.

#include <Client/Source/http-c.h>
 
/*
*********************************************************************************************************
*                                            LOCAL DEFINES
*********************************************************************************************************
*/
#define  HTTPc_EXAMPLE_URI              "server.example.com"					
#define  HTTPc_EXAMPLE_RESSOURCE        "/echo"
#define  HTTPc_EXAMPLE_CONN_BUF_LEN     1024


/*
*********************************************************************************************************
*                                       LOCAL GLOBAL VARIABLES
*********************************************************************************************************
*/

static  HTTPc_CONN_OBJ         HTTPcExample_Conn;
static  CPU_CHAR               HTTPcExample_ConnBuf[HTTPc_EXAMPLE_CONN_BUF_LEN];
static  HTTPc_REQ_OBJ          HTTPcExample_Req;
static  HTTPc_RESP_OBJ         HTTPcExample_Resp;
static  HTTPc_WEBSOCK_OBJ      HTTPcExample_WebSock;


/*
*********************************************************************************************************
*                                      LOCAL FUNCTION PROTOTYPES
*********************************************************************************************************
*/

static void  HTTPcExample_ConnOnClose    (HTTPc_CONN_OBJ              *p_conn,
                                          HTTPc_CONN_CLOSE_STATUS      close_status,
                                          HTTPc_ERR                    err);

static void  HTTPcExample_WebSockOnOpen  (HTTPc_CONN_OBJ              *p_conn);

static void  HTTPcExample_WebSockOnClose (HTTPc_CONN_OBJ              *p_conn,
                                          HTTPc_WEBSOCK_CLOSE_CODE     close_code,
                                          HTTPc_WEBSOCK_CLOSE_REASON  *p_reason) ;


/*
*********************************************************************************************************
*                                               EXAMPLE
*********************************************************************************************************
*/
CPU_BOOLEAN  HTTPcExample_OpenWebSocket (void)
{
    CPU_BOOLEAN  result;
    HTTPc_ERR    err;
                                                                /* ----------- INIT NEW CONNECTION & REQUEST ---------- */
                                                                /* Always Clear the object.                             */
    HTTPc_ConnClr(&HTTPcExample_Conn, &err);
    if (err != HTTPc_ERR_NONE) {
        return (DEF_FAIL);
    }
    HTTPc_ReqClr(&HTTPcExample_Req, &err);
    if (err != HTTPc_ERR_NONE) {
        return (DEF_FAIL);
    }
    HTTPc_WebSockClr(&HTTPcExample_WebSock, &err);
    if (err != HTTPc_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                                /* ------------- SET ON CONNECTION CLOSE -------------- */
                                                                /* This callback is always required.                    */
    HTTPc_ConnSetParam(        &HTTPcExample_Conn,
                                HTTPc_PARAM_TYPE_CONN_CLOSE_CALLBACK,
                       (void *) HTTPcExample_ConnOnClose,
                               &err);
    if (err != HTTPc_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                                /* ----------------- OPEN CONNECTION ------------------ */
    result = HTTPc_ConnOpen(&HTTPcExample_Conn,
                             HTTPcExample_ConnBuf,
                             HTTPc_EXAMPLE_CONN_BUF_LEN,
                             HTTPc_EXAMPLE_URI,
                             sizeof(HTTPc_EXAMPLE_URI),
                             HTTPc_FLAG_NONE,
                            &err);
    if (err != HTTPc_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                                /* --------------- SET WEBSOCK ON OPEN ---------------- */
    HTTPc_WebSockSetParam(        &HTTPcExample_WebSock,
                                   HTTPc_PARAM_TYPE_WEBSOCK_ON_OPEN,
                          (void *) HTTPcExample_WebSockOnOpen,
                                  &err);
    if (err != HTTPc_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                                /* --------------- SET WEBSOCK ON CLOSE --------------- */
    HTTPc_WebSockSetParam(        &HTTPcExample_WebSock,
                                   HTTPc_PARAM_TYPE_WEBSOCK_ON_CLOSE,
                          (void *) HTTPcExample_WebSockOnClose,
                                  &err);
    if (err != HTTPc_ERR_NONE) {
        return (DEF_FAIL);
    }
                                                                /* ------- UPGRADE HTTP CONNECTION TO WEBSOCKET ------- */
    result = HTTPc_WebSockUpgrade(&HTTPcExample_Conn,
                                  &HTTPcExample_Req,
                                  &HTTPcExample_Resp,
                                  &HTTPcExample_WebSock,
                                   HTTPc_EXAMPLE_RESSOURCE,
                                   sizeof(HTTPc_EXAMPLE_RESSOURCE),
                                   HTTPc_FLAG_NONE,
                                  &err);
    if (result != DEF_OK) {
        return (DEF_FAIL);
    }
    return (DEF_OK);
}
/*
*********************************************************************************************************
*                                      CONNECTION ON CLOSE CALLBACK
*********************************************************************************************************
*/
static void  HTTPcExample_ConnOnClose (HTTPc_CONN_OBJ           *p_conn,
                                       HTTPc_CONN_CLOSE_STATUS   close_status,
                                       HTTPc_ERR                 err)
{
                                                                /* Called  when a connection close.                     */
}
/*
*********************************************************************************************************
*                                        WEBSOCK ON OPEN CALLBACK
*********************************************************************************************************
*/
static void  HTTPcExample_WebSockOnOpen (HTTPc_CONN_OBJ           *p_conn)
{
                                                                /* Called  when a WebSocket Upgrade is successful.      */
}
/*
*********************************************************************************************************
*                                        WEBSOCK ON CLOSE CALLBACK
*********************************************************************************************************
*/
static void  HTTPcExample_WebSockOnClose (HTTPc_CONN_OBJ              *p_conn,
                                          HTTPc_WEBSOCK_CLOSE_CODE     close_code,
                                          HTTPc_WEBSOCK_CLOSE_REASON  *p_reason)
{
                                                                /* Called when a WebSocket Connection has close.        */
}