websocket.h File Reference

websocket.h interface. More...

#include <cwist/http.h>
#include <stdint.h>
#include <stdbool.h>

Include dependency graph for websocket.h:

Go to the source code of this file.

Classes
struct	cwist_websocket
struct	cwist_ws_frame

Typedefs
typedef struct cwist_websocket	cwist_websocket
typedef struct cwist_ws_frame	cwist_ws_frame

Enumerations
enum	cwist_ws_opcode_t {   CWIST_WS_FRAME_CONTINUATION = 0x0 , CWIST_WS_FRAME_TEXT = 0x1 , CWIST_WS_FRAME_BINARY = 0x2 , CWIST_WS_FRAME_CLOSE = 0x8 ,   CWIST_WS_FRAME_PING = 0x9 , CWIST_WS_FRAME_PONG = 0xA }

Functions
cwist_websocket *	cwist_websocket_upgrade (cwist_http_request *req, int client_fd)
	Upgrade an HTTP request to WebSocket.
cwist_ws_frame *	cwist_websocket_receive (cwist_websocket *ws)
	Receive a frame. Blocks until a frame is received or connection closed.
int	cwist_websocket_send (cwist_websocket *ws, cwist_ws_opcode_t opcode, const uint8_t *data, size_t len)
	Send a frame.
void	cwist_websocket_frame_destroy (cwist_ws_frame *frame)
	Destroy a frame.
void	cwist_websocket_close (cwist_websocket *ws)
	Close the WebSocket connection.
void	cwist_websocket_destroy (cwist_websocket *ws)
	Destroy the WebSocket context.

Detailed Description

websocket.h interface.

Definition in file websocket.h.

Typedef Documentation

cwist_websocket

typedef struct cwist_websocket cwist_websocket

cwist_ws_frame

typedef struct cwist_ws_frame cwist_ws_frame

Enumeration Type Documentation

cwist_ws_opcode_t

enum cwist_ws_opcode_t

Enumerator
CWIST_WS_FRAME_CONTINUATION
CWIST_WS_FRAME_TEXT
CWIST_WS_FRAME_BINARY
CWIST_WS_FRAME_CLOSE
CWIST_WS_FRAME_PING
CWIST_WS_FRAME_PONG

Definition at line 16 of file websocket.h.

Function Documentation

cwist_websocket_close()

void cwist_websocket_close

(

cwist_websocket *

ws

)

Close the WebSocket connection.

Close the WebSocket connection.

Parameters

ws	Connection to close. NULL is ignored.

Definition at line 512 of file websocket.c.

cwist_websocket_destroy()

void cwist_websocket_destroy

(

cwist_websocket *

ws

)

Destroy the WebSocket context.

Destroy the WebSocket context.

Parameters

ws	Wrapper to release. NULL is ignored.

Definition at line 523 of file websocket.c.

cwist_websocket_frame_destroy()

void cwist_websocket_frame_destroy

(

cwist_ws_frame *

frame

)

Destroy a frame.

Destroy a frame.

Parameters

frame

Frame object to destroy. NULL is ignored.

Definition at line 436 of file websocket.c.

Referenced by cwist_websocket_receive_sequenced().

cwist_websocket_receive()

cwist_ws_frame * cwist_websocket_receive

(

cwist_websocket *

ws

)

Receive a frame. Blocks until a frame is received or connection closed.

Returns

NULL on error or connection close.

Receive a frame. Blocks until a frame is received or connection closed.

Receive a frame, blocking until data arrives or the socket closes.

Transparently reassembles fragmented messages (RFC 6455 section 5.4): frames with FIN=0 are buffered internally and the function blocks until the final FIN=1 frame arrives, at which point the fully-assembled payload is returned as a single frame. Control frames (CLOSE, PING, PONG) are always FIN=1 and are delivered immediately even when a fragmented data message is in progress.

Client frames are required to be masked by RFC 6455, so unmasked payloads are rejected. The returned payload is null-terminated for convenience.

Parameters

ws	WebSocket connection wrapper returned by cwist_websocket_upgrade().

Returns

Newly allocated frame, or NULL when the connection is closed or invalid.

Definition at line 217 of file websocket.c.

Referenced by cwist_websocket_receive_sequenced().

cwist_websocket_send()

int cwist_websocket_send	(	cwist_websocket *	ws,
		cwist_ws_opcode_t	opcode,
		const uint8_t *	data,
		size_t	len
	)

Send a frame.

Send a frame.

Send a frame with the specified opcode and payload.

Parameters

ws	Active WebSocket connection wrapper.
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, or -1 when the socket write fails.

Definition at line 398 of file websocket.c.

Referenced by cwist_websocket_close(), cwist_websocket_receive(), and cwist_websocket_send_sequenced().

cwist_websocket_upgrade()

cwist_websocket * cwist_websocket_upgrade	(	cwist_http_request *	req,
		int	client_fd
	)

Upgrade an HTTP request to WebSocket.

Returns

NULL if the handshake fails or the request is not a valid WebSocket upgrade.

Upgrade an HTTP request to WebSocket.

Upgrade a standard HTTP request to a WebSocket connection.

The function validates the required upgrade headers, computes the Sec-WebSocket-Accept response, emits the 101 Switching Protocols reply, and returns a lightweight wrapper around the already-open client socket.

Parameters

req	Parsed HTTP request that requested the upgrade.
client_fd	Accepted client socket descriptor.

Returns

WebSocket wrapper on success, or NULL when the handshake fails.

Definition at line 119 of file websocket.c.