Zephyr API Documentation  3.7.0-rc2
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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_sockWebsocket id
reqHTTP handshake request
user_dataA 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

#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_sockSocket 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.
reqWebsocket request. User should allocate and fill the request data.
timeoutMax timeout to wait for the connection. The timeout value is in milliseconds. Value SYS_FOREVER_MS means to wait forever.
user_dataUser 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_sockWebsocket 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_sockWebsocket id returned by websocket_connect().
bufBuffer where websocket data is read.
buf_lenLength of the data buffer.
message_typeType of the message.
remainingHow much there is data left in the message after this read.
timeoutHow long to try to receive the message. The value is in milliseconds. Value SYS_FOREVER_MS means to wait forever.
Return values
>=0amount of bytes received.
-EAGAINon timeout.
-ENOTCONNon socket close.
-errnoother 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_sockUnderlying socket connection socket.
recv_bufTemporary 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_lenLength 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_sockWebsocket id returned by websocket_connect().
payloadWebsocket data to send.
payload_lenLength of the data to be sent.
opcodeOperation code (text, binary, ping, pong, close)
maskMask the data, see RFC 6455 for details
finalIs 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.
timeoutHow 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 underlying "real" socket. This will close first the websocket and then the original socket.

Parameters
ws_sockWebsocket connection socket.
Returns
<0 if error, 0 the websocket connection is now fully closed