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.
| Code Block | ||
|---|---|---|
| ||
#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. */
}
|