Group PJ_WEBSOCK

group PJ_WEBSOCK

Introduction

This is an experimental WebSocket client implementation (RFC 6455), created as initial work toward real-time AI service connectivity (e.g. speech-to-text, LLM streaming). It supports both ws:// (plain) and wss:// (TLS) connections.

Current Limitations

Client mode only (no server/accept).
DNS resolution uses blocking pj_getaddrinfo().
No automatic reconnection.
Single pending send at a time (returns PJ_EBUSY if busy).

Defines

PJ_WEBSOCK_MAX_HEADERS: Maximum number of custom HTTP headers for the handshake.

PJ_WEBSOCK_MAX_RX_MSG_SIZE: Default maximum receive message size (256 KB).

PJ_WEBSOCK_RX_BUF_SIZE: Default receive buffer size (64 KB). Sized to handle typical real-time API messages (e.g., audio deltas up to ~50 KB) in a single read, avoiding incremental frame accumulation.

PJ_WEBSOCK_TX_BUF_SIZE: Default transmit buffer size (64 KB).

PJ_WEBSOCK_DEFAULT_PING_INTERVAL: Default ping interval in seconds. 0 to disable.

Typedefs

typedef struct pj_websock pj_websock: Forward declaration.

Enums

enum pj_websock_opcode

WebSocket opcodes.

Values:

enumerator PJ_WEBSOCK_OP_CONT: Continuation frame

enumerator PJ_WEBSOCK_OP_TEXT: Text frame

enumerator PJ_WEBSOCK_OP_BIN: Binary frame

enumerator PJ_WEBSOCK_OP_CLOSE: Connection close

enumerator PJ_WEBSOCK_OP_PING: Ping

enumerator PJ_WEBSOCK_OP_PONG: Pong

enum pj_websock_readystate

WebSocket ready states.

Values:

enumerator PJ_WEBSOCK_STATE_CONNECTING: Connecting/handshaking

enumerator PJ_WEBSOCK_STATE_OPEN: Connected and ready

enumerator PJ_WEBSOCK_STATE_CLOSING: Close handshake

enumerator PJ_WEBSOCK_STATE_CLOSED: Connection closed

Functions

void pj_websock_param_default(pj_websock_param *param)

Initialize WebSocket parameters with default values.

Parameters:: param – The parameters to initialize.

void pj_websock_connect_param_default(pj_websock_connect_param *cparam)

Initialize WebSocket connect parameters with default values.

Parameters:: cparam – The connect parameters to initialize.

pj_status_t pj_websock_create(pj_pool_t *pool, const pj_websock_param *param, pj_websock **p_ws)

Create a WebSocket instance. The WebSocket will create its own memory pool from the pool factory obtained from the supplied pool.

Parameters:

pool – Pool to use for obtaining the pool factory.
param – Creation parameters.
p_ws – Pointer to receive the WebSocket instance.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pj_websock_connect(pj_websock *ws, const pj_str_t *url, const pj_websock_connect_param *cparam)

Connect to a WebSocket server. The URL scheme determines whether a plain (ws://) or TLS (wss://) connection is used. The handshake is performed asynchronously; the on_connect callback will be called when complete.

Parameters:

ws – The WebSocket instance.
url – WebSocket URL (ws:// or wss://).
cparam – Optional connect parameters (extra headers, subprotocol). May be NULL.

Returns:

PJ_SUCCESS if the connection attempt was started successfully, or the appropriate error code.

pj_status_t pj_websock_send(pj_websock *ws, pj_websock_opcode opcode, const void *data, pj_size_t len)

Send a WebSocket message.

Parameters:

ws – The WebSocket instance.
opcode – Frame type: PJ_WEBSOCK_OP_TEXT or PJ_WEBSOCK_OP_BIN.
data – Pointer to the payload data.
len – Length of the payload data.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pj_websock_close(pj_websock *ws, pj_uint16_t status_code, const pj_str_t *reason)

Initiate a graceful close of the WebSocket connection.

Parameters:

ws – The WebSocket instance.
status_code – WebSocket close status code (e.g. 1000 for normal closure). See RFC 6455 Section 7.4.
reason – Optional close reason string. May be NULL.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_websock_readystate pj_websock_get_state(const pj_websock *ws)

Get the current ready state of the WebSocket.

Parameters:: ws – The WebSocket instance.
Returns:: The current ready state.

void *pj_websock_get_user_data(const pj_websock *ws)

Get the user data associated with the WebSocket instance.

Parameters:: ws – The WebSocket instance.
Returns:: The user data pointer.

pj_status_t pj_websock_set_user_data(pj_websock *ws, void *user_data)

Set the user data for the WebSocket instance.

Parameters:

ws – The WebSocket instance.
user_data – The user data pointer.

Returns:

PJ_SUCCESS on success.

pj_status_t pj_websock_destroy(pj_websock *ws)

Destroy the WebSocket instance and release resources. If the connection is still open, it will be closed abruptly (no close handshake).

Parameters:: ws – The WebSocket instance.
Returns:: PJ_SUCCESS on success.

struct pj_websock_cb

#include <websock.h>

WebSocket callbacks.

Public Members

void (*on_connect)(pj_websock *ws, pj_status_t status)

Called when the WebSocket connection is established (handshake completed successfully) or when the connection attempt fails.

Param ws:: The WebSocket instance.
Param status:: PJ_SUCCESS on success, or error code on failure.

void (*on_rx_msg)(pj_websock *ws, pj_websock_opcode opcode, const void *data, pj_size_t len)

Called when a complete message (possibly reassembled from fragments) has been received.

Param ws:: The WebSocket instance.
Param opcode:: Message type (PJ_WEBSOCK_OP_TEXT or PJ_WEBSOCK_OP_BIN).
Param data:: Pointer to the message payload.
Param len:: Length of the message payload.

void (*on_close)(pj_websock *ws, pj_uint16_t status_code, const pj_str_t *reason)

Called when the WebSocket connection has been closed, either by the remote peer, locally, or due to a transport error.

Param ws:: The WebSocket instance.
Param status_code:: WebSocket close code (1000=normal), or 0 if closed due to transport error.
Param reason:: Close reason string, may be empty.

struct pj_websock_param

#include <websock.h>

Definition of WebSocket creation parameters.

Public Members

pj_ioqueue_t *ioqueue: Specify the ioqueue to use for asynchronous socket operations.

pj_timer_heap_t *timer_heap: Specify the timer heap to use for ping and timeout timers.

pj_websock_cb cb: Specify WebSocket callbacks, see pj_websock_cb.

void *user_data: Specify WebSocket user data.

pj_size_t max_rx_msg_size

Specify the maximum receive message size in bytes. Incoming messages larger than this will cause a protocol error.

Default value is PJ_WEBSOCK_MAX_RX_MSG_SIZE (256 KB).

pj_ssl_sock_param *ssl_param: Specify the SSL/TLS parameters for wss:// connections. Set to NULL to use defaults. Ignored for ws:// connections. Only SSL-specific fields (ciphers, certificates, verify mode, etc.) are used; infrastructure fields (ioqueue, timer_heap, cb, user_data) are overridden internally by the WebSocket layer.

unsigned ping_interval

Specify the ping interval in seconds. Set to 0 to disable automatic ping.

Default value is PJ_WEBSOCK_DEFAULT_PING_INTERVAL (30 seconds).

pj_grp_lock_t *grp_lock: Optional group lock to be assigned to the WebSocket instance. If NULL, the WebSocket will create its own group lock. If supplied, the WebSocket will add a reference and register a destroy handler. The application may supply a shared group lock to coordinate lifetime with other objects (e.g. a media port).

struct pj_websock_connect_param

#include <websock.h>

Definition of WebSocket connect parameters. These parameters are specific to the client-side connect operation.

Public Members

pj_http_headers extra_hdr: Specify additional HTTP headers to include in the WebSocket handshake request (e.g. Authorization, custom headers).

pj_str_t subprotocol: Specify the subprotocol to request via the Sec-WebSocket-Protocol header. Set to empty string to omit.