Websocket Client API
Overview
The Websocket client library allows Zephyr to connect to a Websocket server. The Websocket client API can be used directly by application to establish a Websocket connection to server, or it can be used as a transport for other network protocols like MQTT.
See this Websocket Wikipedia article for a detailed overview of how Websocket works.
For more information about the protocol itself, see IETF RFC6455 The WebSocket Protocol.
Websocket Transport
The Websocket API allows it to be used as a transport for other high level
protocols like MQTT. The Zephyr MQTT client library can be configured to use
Websocket transport by enabling CONFIG_MQTT_LIB_WEBSOCKET and
CONFIG_WEBSOCKET_CLIENT Kconfig options.
First a socket needs to be created and connected to the Websocket server:
sock = socket(family, SOCK_STREAM, IPPROTO_TCP);
...
ret = connect(sock, addr, addr_len);
...
The Websocket transport socket is then created like this:
ws_sock = websocket_connect(sock, &config, timeout, user_data);
The Websocket socket can then be used to send or receive data, and the
Websocket client API will encapsulate the sent or received data to/from
Websocket packet payload. Both the websocket_xxx() API or normal
BSD socket API functions can be used to send and receive application data.
ret = websocket_send_msg(ws_sock, buf_to_send, buf_len,
WEBSOCKET_OPCODE_DATA_BINARY, true, true,
K_FOREVER);
...
ret = send(ws_sock, buf_to_send, buf_len, 0);
If normal BSD socket functions are used, then currently only TEXT data
is supported. In order to send BINARY data, the websocket_send_msg()
must be used.
When done, the Websocket transport socket must be closed. User should handle the lifecycle(close/reuse) of tcp socket after websocket_disconnect.
ret = close(ws_sock);
or
ret = websocket_disconnect(ws_sock);
API Reference
- group websocket
Websocket API.
Defines
-
WEBSOCKET_FLAG_FINAL
Message type values.
Returned in websocket_recv_msg() Final frame
-
WEBSOCKET_FLAG_TEXT
Textual data
-
WEBSOCKET_FLAG_BINARY
Binary data
-
WEBSOCKET_FLAG_CLOSE
Closing connection.
-
WEBSOCKET_FLAG_PING
Ping message
-
WEBSOCKET_FLAG_PONG
Pong message
Typedefs
-
typedef int (*websocket_connect_cb_t)(int ws_sock, struct http_request *req, void *user_data)
Callback called after Websocket connection is established.
- Param ws_sock:
Websocket id
- Param req:
HTTP handshake request
- Param user_data:
A valid pointer on some user data or NULL
- Return:
0 if ok, <0 if there is an error and connection should be aborted
Enums
-
enum websocket_opcode
Websocket option codes.
Values:
-
enumerator WEBSOCKET_OPCODE_CONTINUE = 0x00
Message continues.
-
enumerator WEBSOCKET_OPCODE_DATA_TEXT = 0x01
Textual data.
-
enumerator WEBSOCKET_OPCODE_DATA_BINARY = 0x02
Binary data.
-
enumerator WEBSOCKET_OPCODE_CLOSE = 0x08
Closing connection.
-
enumerator WEBSOCKET_OPCODE_PING = 0x09
Ping message.
-
enumerator WEBSOCKET_OPCODE_PONG = 0x0A
Pong message.
-
enumerator WEBSOCKET_OPCODE_CONTINUE = 0x00
Functions
-
int websocket_connect(int http_sock, struct websocket_request *req, int32_t timeout, void *user_data)
Connect to a server that provides Websocket service.
The callback is called after connection is established. The returned value is a new socket descriptor that can be used to send / receive data using the BSD socket API.
- Parameters:
http_sock – Socket id to the server. Note that this socket is used to do HTTP handshakes etc. The actual Websocket connectivity is done via the returned websocket id. Note that the http_sock must not be closed after this function returns as it is used to deliver the Websocket packets to the Websocket server.
req – Websocket request. User should allocate and fill the request data.
timeout – Max timeout to wait for the connection. The timeout value is in milliseconds. Value SYS_FOREVER_MS means to wait forever.
user_data – User specified data that is passed to the callback.
- Returns:
Websocket id to be used when sending/receiving Websocket data.
-
int websocket_send_msg(int ws_sock, const uint8_t *payload, size_t payload_len, enum websocket_opcode opcode, bool mask, bool final, int32_t timeout)
Send websocket msg to peer.
The function will automatically add websocket header to the message.
- Parameters:
ws_sock – Websocket id returned by websocket_connect().
payload – Websocket data to send.
payload_len – Length of the data to be sent.
opcode – Operation code (text, binary, ping, pong, close)
mask – Mask the data, see RFC 6455 for details
final – Is this final message for this message send. If final == false, then the first message must have valid opcode and subsequent messages must have opcode WEBSOCKET_OPCODE_CONTINUE. If final == true and this is the only message, then opcode should have proper opcode (text or binary) set.
timeout – How long to try to send the message. The value is in milliseconds. Value SYS_FOREVER_MS means to wait forever.
- Returns:
<0 if error, >=0 amount of bytes sent
-
int websocket_recv_msg(int ws_sock, uint8_t *buf, size_t buf_len, uint32_t *message_type, uint64_t *remaining, int32_t timeout)
Receive websocket msg from peer.
The function will automatically remove websocket header from the message.
- Parameters:
ws_sock – Websocket id returned by websocket_connect().
buf – Buffer where websocket data is read.
buf_len – Length of the data buffer.
message_type – Type of the message.
remaining – How much there is data left in the message after this read.
timeout – How long to try to receive the message. The value is in milliseconds. Value SYS_FOREVER_MS means to wait forever.
- Return values:
>=0 – amount of bytes received.
-EAGAIN – on timeout.
-ENOTCONN – on socket close.
-errno – other negative errno value in case of failure.
-
int websocket_disconnect(int ws_sock)
Close websocket.
One must call websocket_connect() after this call to re-establish the connection.
- Parameters:
ws_sock – Websocket id returned by websocket_connect().
- Returns:
<0 if error, 0 the connection was closed successfully
-
int websocket_register(int http_sock, uint8_t *recv_buf, size_t recv_buf_len)
Register a socket as websocket.
This is called by HTTP server when a connection is upgraded to a websocket connection.
- Parameters:
http_sock – Underlying socket connection socket.
recv_buf – Temporary receive buffer for websocket parsing. This must point to a memory area that is valid for the duration of the whole websocket session.
recv_buf_len – Length of the temporary receive buffer.
- Returns:
<0 if error, >=0 the actual websocket to be used by application
-
int websocket_unregister(int ws_sock)
Unregister a websocket.
This is called when we no longer need the underlying “real” socket. This will close first the websocket and then the original socket.
- Parameters:
ws_sock – Websocket connection socket.
- Returns:
<0 if error, 0 the websocket connection is now fully closed
-
struct websocket_request
- #include <websocket.h>
Websocket client connection request.
This contains all the data that is needed when doing a Websocket connection request.
Public Members
-
const char *host
Host of the Websocket server when doing HTTP handshakes.
-
const char *url
URL of the Websocket.
-
http_header_cb_t optional_headers_cb
User supplied callback function to call when optional headers need to be sent.
This can be NULL, in which case the optional_headers field in http_request is used. The idea of this optional_headers callback is to allow user to send more HTTP header data that is practical to store in allocated memory.
-
const char **optional_headers
A NULL terminated list of any optional headers that should be added to the HTTP request.
May be NULL. If the optional_headers_cb is specified, then this field is ignored.
-
websocket_connect_cb_t cb
User supplied callback function to call when a connection is established.
-
const struct http_parser_settings *http_cb
User supplied list of callback functions if the calling application wants to know the parsing status or the HTTP fields during the handshake.
This is optional parameter and normally not needed but is useful if the caller wants to know something about the fields that the server is sending.
-
uint8_t *tmp_buf
User supplied buffer where HTTP connection data is stored.
-
size_t tmp_buf_len
Length of the user supplied temp buffer.
-
const char *host
-
WEBSOCKET_FLAG_FINAL