websocket_async.h File Reference

Reactor-driven, callback-shaped non-blocking WebSocket API (C1M mode). More...

#include <cwist/net/websocket/websocket.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for websocket_async.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct cwist_websocket_async	cwist_websocket_async
typedef void(*	cwist_ws_on_message_t) (cwist_websocket_async *ws, cwist_ws_frame *frame, void *user_data)
	Callback invoked for each complete WebSocket message on the C1M path.
typedef void(*	cwist_ws_on_close_t) (cwist_websocket_async *ws, void *user_data)
	Optional teardown hook for the callback-shaped WS path (see cwist_websocket_async_attach_ex in ws_async_internal.h).

Functions
int	cwist_websocket_async_send (cwist_websocket_async *ws, cwist_ws_opcode_t opcode, const uint8_t *data, size_t len)
	Serialize and send one FIN-terminated frame without blocking.
void	cwist_websocket_async_close (cwist_websocket_async *ws)
	Initiate the close handshake without blocking.

Detailed Description

Reactor-driven, callback-shaped non-blocking WebSocket API (C1M mode).

Classic mode (CWIST_C1M_MODE=0) keeps the blocking cwist_websocket_receive() API in websocket.h. This header exposes the C1M-only path where the reactor watches the socket and delivers each complete message through cwist_ws_on_message_t, mirroring how HTTP handlers receive requests.

Definition in file websocket_async.h.

Typedef Documentation

cwist_websocket_async

typedef struct cwist_websocket_async cwist_websocket_async

Definition at line 22 of file websocket_async.h.

cwist_ws_on_close_t

typedef void(* cwist_ws_on_close_t) (cwist_websocket_async *ws, void *user_data)

Optional teardown hook for the callback-shaped WS path (see cwist_websocket_async_attach_ex in ws_async_internal.h).

Parameters

ws	Connection being torn down; do not send on it.
user_data	Opaque pointer registered at attach time.

Definition at line 41 of file websocket_async.h.

cwist_ws_on_message_t

typedef void(* cwist_ws_on_message_t) (cwist_websocket_async *ws, cwist_ws_frame *frame, void *user_data)

Callback invoked for each complete WebSocket message on the C1M path.

Parameters

ws	Connection the message arrived on. Safe to pass to cwist_websocket_async_send() and cwist_websocket_async_close().
frame	Owning frame pointer (same shape as cwist_ws_frame). The callback MUST release it with cwist_websocket_frame_destroy().
user_data	Opaque pointer registered with cwist_app_ws_async().

Definition at line 32 of file websocket_async.h.

Function Documentation

cwist_websocket_async_close()

void cwist_websocket_async_close

(

cwist_websocket_async *

ws

)

Initiate the close handshake without blocking.

Queues a CLOSE frame and schedules connection cleanup. Must be callable from inside the on_message callback (i.e. from the reactor thread); the connection state is released once the current reactor turn unwinds.

Parameters

ws	Connection to close. NULL is ignored.

Initiate the close handshake without blocking.

Idempotent: calling again on a connection already closing is a no-op. The connection is torn down once the CLOSE frame has drained or, on queueing failure, via a deferred termination.

Parameters

ws	Async connection to close. Safe to call with NULL.

Definition at line 725 of file websocket_async.c.

References cap, and CWIST_WS_FRAME_CLOSE.

cwist_websocket_async_send()

int cwist_websocket_async_send	(	cwist_websocket_async *	ws,
		cwist_ws_opcode_t	opcode,
		const uint8_t *	data,
		size_t	len
	)

Serialize and send one FIN-terminated frame without blocking.

The header and payload are serialized into a single buffer and sent with MSG_DONTWAIT|MSG_NOSIGNAL. On EAGAIN or a short write the unsent remainder is parked on a one-shot reactor write slot (same model as the HTTP parked-response writer) and drained when the socket becomes writable again.

Parameters

ws	Active async WebSocket connection.
opcode	WebSocket opcode describing the payload semantics.
data	Optional payload buffer. May be NULL when len is zero.
len	Number of payload bytes to transmit.

Returns

0 on success, -1 on failure.

Serialize and send one FIN-terminated frame without blocking.

May be called from the reactor thread (e.g. inside the on_message callback); partial writes are parked and resumed by a POLLOUT slot.

Parameters

ws	Async connection.
opcode	Frame opcode (text, binary, PING, ...).
data	Payload bytes; may be NULL when len is 0.
len	Payload length in bytes.

Return values

0	The frame was sent or parked.
-1	Invalid arguments, the connection is already closing/closed, or queueing failed (the connection is torn down).

Definition at line 710 of file websocket_async.c.