WebSockets API
================
Yimmo WebSockets public API.
.. toctree::
:hidden:
:maxdepth: 3
index
.. contents:: Contents
:local:
---------------------------------------------------------------
Server Settings
---------------------------------------------------------------
.. c:type:: ymo_ws_server_flags_t
Type for `flags` param passed in to :c:func:`ymo_proto_ws_create`.
.. code-block:: c
:caption: Definition
typedef uint8_t ymo_ws_server_flags_t;
.. c:macro:: 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 :c:macro:`YMO_WS_FLAG_FIN`.
.. code-block:: c
:caption: Definition
#define YMO_WS_SERVER_DEFAULT 0x0
.. c:macro:: 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
:c:macro:`YMO_WS_MSG_LEN_MAX` bytes — and
invoke the receive callback once the FIN bit is set.
.. code-block:: c
:caption: Definition
#define YMO_WS_SERVER_BUFFERED 0x01
.. c:macro:: YMO_WS_MSG_LEN_MAX
Max length of a *buffered* WS message.
.. todo::
Move this to runtime configuration!
.. code-block:: c
:caption: Definition
# define YMO_WS_MSG_LEN_MAX 4096
---------------------------------------------------------------
Message Header
---------------------------------------------------------------
.. note::
See `RFC6455: Framing <https://datatracker.ietf.org/doc/html/rfc6455#section-5>`_
for more info.
Byte 0
~~~~~~~~
.. c:macro:: YMO_WS_FLAG_FIN
.. code-block:: c
:caption: Definition
#define YMO_WS_FLAG_FIN 0x80
.. c:macro:: YMO_WS_OP_CONTINUATION
Indicates that the frame is a continuation frame.
.. code-block:: c
:caption: Definition
#define YMO_WS_OP_CONTINUATION 0x00
.. c:macro:: YMO_WS_OP_TEXT
Indicates that the frame is a text frame.
.. code-block:: c
:caption: Definition
#define YMO_WS_OP_TEXT 0x01
.. c:macro:: YMO_WS_OP_BINARY
Indicates that the frame is a binary frame.
.. code-block:: c
:caption: Definition
#define YMO_WS_OP_BINARY 0x02
.. c:macro:: YMO_WS_OP_CLOSE
Indicates that the frame is a connection close.
.. code-block:: c
:caption: Definition
#define YMO_WS_OP_CLOSE 0x08
.. c:macro:: YMO_WS_OP_PING
Indicates that the frame is a ping.
.. code-block:: c
:caption: Definition
#define YMO_WS_OP_PING 0x09
.. c:macro:: YMO_WS_OP_PONG
Indicates that the frame is a pong.
.. code-block:: c
:caption: Definition
#define YMO_WS_OP_PONG 0x0a
Byte 1
~~~~~~
.. c:macro:: YMO_WS_FLAG_MASKED
.. code-block:: c
:caption: Definition
#define YMO_WS_FLAG_MASKED 0x80
.. c:macro:: YMO_WS_MASK_LEN
.. code-block:: c
:caption: Definition
#define YMO_WS_MASK_LEN 0x7f
---------------------------------------------------------------
Types
---------------------------------------------------------------
.. c:type:: ymo_ws_session_t
Opaque date type used to represent WebSocket connecctions
.. code-block:: c
:caption: Definition
typedef struct ymo_ws_session ymo_ws_session_t;
.. c: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
.. code-block:: c
:caption: Definition
typedef ymo_status_t (*ymo_ws_connect_cb_t)(ymo_ws_session_t* session);
.. c: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: :c:macro:`YMO_OKAY` on success, errno.h value on failure
.. code-block:: c
:caption: 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);
.. c: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
.. code-block:: c
:caption: Definition
typedef void (*ymo_ws_close_cb_t)(ymo_ws_session_t* session, void* user_data);
---------------------------------------------------------------
Session Data
---------------------------------------------------------------
---------------------------------------------------------------
Protocol Management
---------------------------------------------------------------
.. c:function:: 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.
:param flags: see `Server Settings`_
:param connect_cb: see :c:type:`ymo_ws_connect_cb_t`
:param recv_cb: see :c:type:`ymo_ws_recv_cb_t`
:param close_cb: see :c:type:`ymo_ws_close_cb_t`
:returns: :c:type:`ymo_proto_t` pointer.
.. c:function:: ymo_http_upgrade_handler_t* ymo_ws_http_upgrade_handler(ymo_proto_t* proto)
Given a websocket protocol object, return a
:c:type:`ymo_http_upgrade_handler_t` which handles WebSocket upgrade
requests, which can be passed to :c:func:`ymo_http_simple_init`.
.. c:function:: 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.
:param session: the websocket session
:param flags: flags for the outgoing `Message Header`_
:param payload: a :c:type:`ymo_bucket_t` encapsulating the data
to be sent (**NOTE**: the payload can be a single bucket _or_ a chain
of buckets).
:returns: :c:macro:`YMO_OKAY` on success; ``errno`` value on failure.
**Example:**
.. code-block:: c
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);