WebSockets API

Yimmo WebSockets public API.

Server Settings

type ymo_ws_server_flags_t

Type for flags param passed in to ymo_proto_ws_create().

Definition
typedef uint8_t ymo_ws_server_flags_t;
YMO_WS_SERVER_DEFAULT

The receive callback will be invoked with data, as it is received from the client. Applications must buffer their own multi-message payloads and check for the FIN bit using YMO_WS_FLAG_FIN.

Definition
#define YMO_WS_SERVER_DEFAULT 0x0
YMO_WS_SERVER_BUFFERED

The receive callback will be invoked with complete messages. The WS module will buffer multi-part messages for the application — up to YMO_WS_MSG_LEN_MAX bytes — and invoke the receive callback once the FIN bit is set.

Definition
#define YMO_WS_SERVER_BUFFERED 0x01
YMO_WS_MSG_LEN_MAX

Max length of a buffered WS message.

Todo

Move this to runtime configuration!

Definition
#  define YMO_WS_MSG_LEN_MAX 4096

Message Header

Note

See RFC6455: Framing for more info.

Byte 0

YMO_WS_FLAG_FIN
Definition
#define YMO_WS_FLAG_FIN  0x80
YMO_WS_OP_CONTINUATION

Indicates that the frame is a continuation frame.

Definition
#define YMO_WS_OP_CONTINUATION 0x00
YMO_WS_OP_TEXT

Indicates that the frame is a text frame.

Definition
#define YMO_WS_OP_TEXT         0x01
YMO_WS_OP_BINARY

Indicates that the frame is a binary frame.

Definition
#define YMO_WS_OP_BINARY       0x02
YMO_WS_OP_CLOSE

Indicates that the frame is a connection close.

Definition
#define YMO_WS_OP_CLOSE        0x08
YMO_WS_OP_PING

Indicates that the frame is a ping.

Definition
#define YMO_WS_OP_PING         0x09
YMO_WS_OP_PONG

Indicates that the frame is a pong.

Definition
#define YMO_WS_OP_PONG         0x0a

Byte 1

YMO_WS_FLAG_MASKED
Definition
#define YMO_WS_FLAG_MASKED 0x80
YMO_WS_MASK_LEN
Definition
#define YMO_WS_MASK_LEN    0x7f

Types

type ymo_ws_session_t

Opaque date type used to represent WebSocket connecctions

Definition
typedef struct ymo_ws_session ymo_ws_session_t;
type ymo_ws_connect_cb_t

WebSocket connect callback type.

Session

a new websocket connection

Returns

NULL or a void* to custom data to associate with the session

Definition
typedef ymo_status_t (*ymo_ws_connect_cb_t)(ymo_ws_session_t* session);
type ymo_ws_recv_cb_t

WebSocket receive callback type — invoked for each packet of data.

Session

the WebSocket session sending the message

User_data

an optional pointer to user data associated with the session

Flags

flags from the incoming Message Header

Msg

frame payload

Len

frame length

Returns

YMO_OKAY on success, errno.h value on failure

Definition
typedef ymo_status_t (*ymo_ws_recv_cb_t)(
        ymo_ws_session_t* session,
        void* user_data,
        uint8_t flags,
        const char* msg,
        size_t len);
type ymo_ws_close_cb_t

WebSocket close callback type.

Session

the session for the closed websocket

User_data

an optional pointer to user data associated with the session

Definition
typedef void (*ymo_ws_close_cb_t)(ymo_ws_session_t* session, void* user_data);

Session Data

Protocol Management

ymo_proto_t *ymo_proto_ws_create(ymo_ws_server_flags_t flags, ymo_ws_connect_cb_t connect_cb, ymo_ws_recv_cb_t recv_cb, ymo_ws_close_cb_t close_cb)

Create a WebSocket protocol object.

Parameters
Returns

ymo_proto_t pointer.

ymo_http_upgrade_handler_t *ymo_ws_http_upgrade_handler(ymo_proto_t *proto)

Given a websocket protocol object, return a ymo_http_upgrade_handler_t which handles WebSocket upgrade requests, which can be passed to ymo_http_simple_init().

ymo_status_t ymo_ws_session_send(ymo_ws_session_t *session, uint8_t flags, ymo_bucket_t *payload)

Send a message to the given websocket session.

Parameters

  • session – the websocket session

  • flags – flags for the outgoing Message Header

  • payload – a ymo_bucket_t encapsulating the data to be sent (NOTE: the payload can be a single bucket _or_ a chain of buckets).

Returns

YMO_OKAY on success; errno value on failure.

Example:

ymo_bucket_t* my_msg = YMO_BUCKET_FROM_REF("Hello, world!", 13);
return ymo_ws_session_send(
        session, YMO_WS_FLAG_FIN | YMO_WS_OP_TEXT, my_msg);