websocket.h

#include <modkit/websocket.h>16 functions · 6 structs · 1 enums · 9 typedefs · 2 macros

Poll-driven WebSocket client and server APIs.

Event payloads and strings are non-owning views valid only for the duration of their callback. Client connections are available on native and web targets; servers and HTTP-server routes are native-only.

Functions

mk_http_server_ws_routefunction

mk_result mk_http_server_ws_route(mk_http_server_t server, const mk_ws_route_desc *route)

Register an integrated WebSocket route before its HTTP server starts.

Parameter	Type	Description
server	mk_http_server_t	Value for server.
route	const mk_ws_route_desc *	Value for route.

Returns MK_SUCCESS or an error result.

mk_websocket_validfunction

bool mk_websocket_valid(mk_websocket_t handle)

Return whether a WebSocket connection handle is nonzero.

Parameter	Type	Description
handle	mk_websocket_t	Value for handle.

Returns True when the operation succeeds.

mk_ws_broadcast_binaryfunction

mk_result mk_ws_broadcast_binary(mk_ws_server_t server, const void *data, size_t size)

Queue a binary message for every open connection on a standalone server.

Parameter	Type	Description
server	mk_ws_server_t	Value for server.
data	const void *	Data buffer.
size	size_t	Size in bytes.

Returns MK_SUCCESS or an error result.

mk_ws_broadcast_textfunction

mk_result mk_ws_broadcast_text(mk_ws_server_t server, const char *text, size_t size)

Queue a text message for every open connection on a standalone server.

Parameter	Type	Description
server	mk_ws_server_t	Value for server.
text	const char *	Value for text.
size	size_t	Size in bytes.

Returns MK_SUCCESS or an error result.

mk_ws_closefunction

mk_result mk_ws_close(mk_websocket_t connection, uint16_t code, const char *reason)

Begin closing; code zero selects 1000 and reason may contain at most 123 bytes.

Parameter	Type	Description
connection	mk_websocket_t	Value for connection.
code	uint16_t	Value for code.
reason	const char *	Value for reason.

Returns MK_SUCCESS or an error result.

mk_ws_connectfunction

mk_result mk_ws_connect(const mk_ws_connect_desc *desc, mk_websocket_t *out_connection)

Start an asynchronous WebSocket client connection.

Descriptor strings, headers, subprotocols, and TLS data are copied before return. Connection progress and messages are delivered through mk_net_poll().

Parameter	Type	Description
desc	const mk_ws_connect_desc *	Configuration descriptor.
out_connection	mk_websocket_t *	Receives the connection.

Returns MK_SUCCESS or an error result.

mk_ws_connect_desc_initfunction

mk_ws_connect_desc mk_ws_connect_desc_init(void)

Return 10-second connect, 3-second ping, 16-MiB message, and 4-MiB queue defaults.

Returns The resulting value.

mk_ws_is_openfunction

bool mk_ws_is_open(mk_websocket_t connection)

Return whether the connection is currently open for sends.

Parameter	Type	Description
connection	mk_websocket_t	Value for connection.

Returns True when the condition holds.

mk_ws_send_binaryfunction

mk_result mk_ws_send_binary(mk_websocket_t connection, const void *data, size_t size)

Queue one binary message.

Parameter	Type	Description
connection	mk_websocket_t	Value for connection.
data	const void *	Data buffer.
size	size_t	Size in bytes.

Returns MK_SUCCESS or an error result.

mk_ws_send_textfunction

mk_result mk_ws_send_text(mk_websocket_t connection, const char *text, size_t size)

Queue one UTF-8 text message; size excludes any terminating NUL.

Parameter	Type	Description
connection	mk_websocket_t	Value for connection.
text	const char *	Value for text.
size	size_t	Size in bytes.

Returns MK_SUCCESS or an error result.

mk_ws_server_closefunction

mk_result mk_ws_server_close(mk_ws_server_t server)

Stop a standalone server and close all of its connections.

Parameter	Type	Description
server	mk_ws_server_t	Value for server.

Returns MK_SUCCESS or an error result.

mk_ws_server_createfunction

mk_result mk_ws_server_create(const mk_ws_server_desc *desc, mk_ws_server_t *out_server)

Create a standalone native server; start it with mk_ws_server_start().

Parameter	Type	Description
desc	const mk_ws_server_desc *	Configuration descriptor.
out_server	mk_ws_server_t *	Receives the server.

Returns MK_SUCCESS or an error result.

mk_ws_server_desc_initfunction

mk_ws_server_desc mk_ws_server_desc_init(void)

Return all-interface, 1024-client, 16-MiB message, and 4-MiB queue defaults.

Returns The resulting value.

mk_ws_server_portfunction

uint16_t mk_ws_server_port(mk_ws_server_t server)

Return the server's bound port, including an automatically selected port.

Parameter	Type	Description
server	mk_ws_server_t	Value for server.

Returns The resulting value.

mk_ws_server_startfunction

mk_result mk_ws_server_start(mk_ws_server_t server)

Start accepting connections on a standalone server.

Parameter	Type	Description
server	mk_ws_server_t	Value for server.

Returns MK_SUCCESS or an error result.

mk_ws_server_validfunction

bool mk_ws_server_valid(mk_ws_server_t handle)

Return whether a WebSocket server handle is nonzero.

Parameter	Type	Description
handle	mk_ws_server_t	Value for handle.

Returns True when the operation succeeds.

Structs

mk_websocket_handlestruct

Generational handle for a WebSocket connection.

Field	Type	Description
id	uint32_t	Opaque identifier; zero is invalid.

mk_ws_connect_descstruct

Descriptor for an asynchronous WebSocket client connection.

Field	Type	Description
url	const char *	Required absolute ws:// or wss:// URL.
headers	const mk_http_header *	Native handshake headers, copied on submit.
header_count	uint32_t	Number of handshake headers.
subprotocols	const char *const *	Ordered offered subprotocol names.
subprotocol_count	uint32_t	Number of offered subprotocols.
connect_timeout_ms	uint32_t	Opening timeout; zero uses the default.
ping_interval_ms	uint32_t	Native ping interval; zero disables pings.
max_message_bytes	size_t	Message limit; zero uses 16 MiB.
max_send_queue_bytes	size_t	Send-queue limit; zero uses 4 MiB.
tls	const mk_tls_client_config *	Optional native WSS trust configuration.
callback	mk_ws_event_fn	Required connection callback.
user_data	void *	Opaque value passed to callback.

mk_ws_eventstruct

WebSocket event delivered by mk_net_poll().

Field	Type	Description
type	mk_ws_event_type	Event kind.
connection	mk_websocket_t	Connection associated with the event.
server	mk_ws_server_t	Standalone server, or invalid for other connections.
http_server	mk_http_server_t	Integrated HTTP server, or invalid otherwise.
data	const void *	Complete TEXT or BINARY message bytes.
size	size_t	Number of bytes in data.
close_code	uint16_t	CLOSE status code, or zero if unavailable.
close_reason	const char *	CLOSE reason, or an empty string.
path	const char *	Request path for accepted server connections.
subprotocol	const char *	Negotiated subprotocol, or an empty string.
error	mk_net_error	CLOSE/error detail; NONE for a clean close.

mk_ws_route_descstruct

WebSocket route registered on a native HTTP server before it starts.

Field	Type	Description
path	const char *	Absolute pattern with :params or trailing *wildcard.
subprotocols	const char *const *	Supported protocols in preference order.
subprotocol_count	uint32_t	Number of supported subprotocols.
max_message_bytes	size_t	Route message limit; zero uses 16 MiB.
authorize	mk_ws_upgrade_fn	Optional owner-thread authorization callback.
callback	mk_ws_event_fn	Required route connection callback.
user_data	void *	Opaque value passed to both callbacks.

mk_ws_server_descstruct

Descriptor for a standalone native WebSocket or WSS server.

Field	Type	Description
bind_address	const char *	Local address; NULL means all IPv4 interfaces.
port	uint16_t	Local port; zero selects an available port.
max_connections	uint32_t	Connection limit; zero uses 1024.
ping_interval_ms	uint32_t	Server ping interval; zero disables pings.
max_message_bytes	size_t	Message limit; zero uses 16 MiB.
max_send_queue_bytes	size_t	Per-client send limit; zero uses 4 MiB.
tls	const mk_tls_server_config *	NULL for WS, credentials for WSS.
callback	mk_ws_event_fn	Required server/connection callback.
user_data	void *	Opaque value passed to callback.

mk_ws_server_handlestruct

Generational handle for a standalone native WebSocket server.

Field	Type	Description
id	uint32_t	Opaque identifier; zero is invalid.

Enums

mk_ws_event_typeenum

WebSocket connection event kind.

Value	Description
MK_WS_EVENT_OPEN	The opening handshake completed.
MK_WS_EVENT_TEXT	A complete UTF-8 text message was received.
MK_WS_EVENT_BINARY	A complete binary message was received.
MK_WS_EVENT_CLOSE	The connection closed; terminal event.

Typedefs

mk_websocket_ttypedef

typedef struct mk_websocket_handle mk_websocket_t

Generational handle for a WebSocket connection.

mk_ws_connect_desctypedef

typedef struct mk_ws_connect_desc mk_ws_connect_desc

Descriptor for an asynchronous WebSocket client connection.

mk_ws_eventtypedef

typedef struct mk_ws_event mk_ws_event

WebSocket event delivered by mk_net_poll().

mk_ws_event_fntypedef

typedef void(*) mk_ws_event_fn(const mk_ws_event *event, void *user_data)

WebSocket callback invoked by mk_net_poll() on the owner thread.

mk_ws_event_typetypedef

typedef enum mk_ws_event_type mk_ws_event_type

WebSocket connection event kind.

mk_ws_route_desctypedef

typedef struct mk_ws_route_desc mk_ws_route_desc

WebSocket route registered on a native HTTP server before it starts.

mk_ws_server_desctypedef

typedef struct mk_ws_server_desc mk_ws_server_desc

Descriptor for a standalone native WebSocket or WSS server.

mk_ws_server_ttypedef

typedef struct mk_ws_server_handle mk_ws_server_t

Generational handle for a standalone native WebSocket server.

mk_ws_upgrade_fntypedef

typedef bool(*) mk_ws_upgrade_fn(const mk_http_request_view *request, const char **accepted_subprotocol, int *rejection_status, void *user_data)

Authorize a native HTTP-server WebSocket route.

The request view is valid only during this callback. A true return accepts the connection. accepted_subprotocol may be set to one of the offered route protocols; its text is copied after return. A false return rejects the connection. rejection_status may be set when the backend can reject before completing the upgrade.

Macros

MK_WEBSOCKET_INVALIDdefine

MK_WEBSOCKET_INVALID

Invalid WebSocket connection handle.

MK_WS_SERVER_INVALIDdefine

MK_WS_SERVER_INVALID

Invalid standalone WebSocket server handle.