Websocket API

Websocket API. More...

Data Structures
struct	websocket_request
	Websocket client connection request. More...

Macros
#define	WEBSOCKET_FLAG_FINAL   0x00000001
	Message type values.
#define	WEBSOCKET_FLAG_TEXT   0x00000002
	Textual data
#define	WEBSOCKET_FLAG_BINARY   0x00000004
	Binary data
#define	WEBSOCKET_FLAG_CLOSE   0x00000008
	Closing connection.
#define	WEBSOCKET_FLAG_PING   0x00000010
	Ping message
#define	WEBSOCKET_FLAG_PONG   0x00000020
	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.

Enumerations
enum	websocket_opcode {   WEBSOCKET_OPCODE_CONTINUE = 0x00 , WEBSOCKET_OPCODE_DATA_TEXT = 0x01 , WEBSOCKET_OPCODE_DATA_BINARY = 0x02 , WEBSOCKET_OPCODE_CLOSE = 0x08 ,   WEBSOCKET_OPCODE_PING = 0x09 , WEBSOCKET_OPCODE_PONG = 0x0A }
	Websocket option codes. More...

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.
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.
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.
int	websocket_disconnect (int ws_sock)
	Close websocket.
int	websocket_register (int http_sock, uint8_t *recv_buf, size_t recv_buf_len)
	Register a socket as websocket.
int	websocket_unregister (int ws_sock)
	Unregister a websocket.

Detailed Description

Websocket API.

Macro Definition Documentation

WEBSOCKET_FLAG_BINARY

#define WEBSOCKET_FLAG_BINARY   0x00000004

#include <zephyr/net/websocket.h>

Binary data

WEBSOCKET_FLAG_CLOSE

#define WEBSOCKET_FLAG_CLOSE   0x00000008

#include <zephyr/net/websocket.h>

Closing connection.

WEBSOCKET_FLAG_FINAL

#define WEBSOCKET_FLAG_FINAL   0x00000001

#include <zephyr/net/websocket.h>

Message type values.

Returned in websocket_recv_msg() Final frame

WEBSOCKET_FLAG_PING

#define WEBSOCKET_FLAG_PING   0x00000010

#include <zephyr/net/websocket.h>

Ping message

WEBSOCKET_FLAG_PONG

#define WEBSOCKET_FLAG_PONG   0x00000020

#include <zephyr/net/websocket.h>

Pong message

WEBSOCKET_FLAG_TEXT

#define WEBSOCKET_FLAG_TEXT   0x00000002

#include <zephyr/net/websocket.h>

Textual data

Typedef Documentation

websocket_connect_cb_t

websocket_connect_cb_t

#include <zephyr/net/websocket.h>

Callback called after Websocket connection is established.

Parameters

ws_sock	Websocket id
req	HTTP handshake request
user_data	A valid pointer on some user data or NULL

Returns

0 if ok, <0 if there is an error and connection should be aborted

Enumeration Type Documentation

websocket_opcode

enum websocket_opcode

#include <zephyr/net/websocket.h>

Websocket option codes.

Enumerator
WEBSOCKET_OPCODE_CONTINUE	Message continues.
WEBSOCKET_OPCODE_DATA_TEXT	Textual data.
WEBSOCKET_OPCODE_DATA_BINARY	Binary data.
WEBSOCKET_OPCODE_CLOSE	Closing connection.
WEBSOCKET_OPCODE_PING	Ping message.
WEBSOCKET_OPCODE_PONG	Pong message.

Function Documentation

websocket_connect()

int websocket_connect	(	int	http_sock,
		struct websocket_request *	req,
		int32_t	timeout,
		void *	user_data
	)

#include <zephyr/net/websocket.h>

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.

websocket_disconnect()

int websocket_disconnect

(

int

ws_sock

)

#include <zephyr/net/websocket.h>

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

websocket_recv_msg()

int websocket_recv_msg	(	int	ws_sock,
		uint8_t *	buf,
		size_t	buf_len,
		uint32_t *	message_type,
		uint64_t *	remaining,
		int32_t	timeout
	)

#include <zephyr/net/websocket.h>

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.

websocket_register()

int websocket_register	(	int	http_sock,
		uint8_t *	recv_buf,
		size_t	recv_buf_len
	)

#include <zephyr/net/websocket.h>

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

websocket_send_msg()

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
	)

#include <zephyr/net/websocket.h>

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

websocket_unregister()

int websocket_unregister

(

int

ws_sock

)

#include <zephyr/net/websocket.h>

Unregister a websocket.

This is called when we no longer need the underlaying "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