wsServer constants and functions. More...

#include <stdbool.h>
#include <stdint.h>
#include <inttypes.h>

Classes
struct	ws_events
	events Web Socket events types. More...

struct	ws_server_t
	server Web Socket server parameters More...

Macros
#define	WS_CLSE_INVUTF8 1007
	Inconsistent message (invalid utf-8) More...

#define	SEND(client, buf, len) send_all((client), (buf), (len), MSG_NOSIGNAL)

#define	RECV(fd, buf, len) recv((fd)->client_sock, (buf), (len), 0)

Global configurations
#define	MAX_CLIENTS 8
	Max clients connected simultaneously. More...

Key and message configurations.
#define	MESSAGE_LENGTH 2048
	Message buffer length. More...

#define	MAX_FRAME_LENGTH (1610241024)
	Maximum frame/message length. More...

#define	WS_KEY_LEN 24
	WebSocket key length. More...

#define	WS_MS_LEN 36
	Magic string length. More...

#define	WS_KEYMS_LEN (WS_KEY_LEN + WS_MS_LEN)
	Accept message response length. More...

#define	MAGIC_STRING "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
	Magic string. More...

Handshake constants.
#define	WS_HS_REQ "Sec-WebSocket-Key"
	Alias for 'Sec-WebSocket-Key'. More...

#define	WS_HS_ACCLEN 130
	Handshake accept message length. More...

#define	WS_HS_ACCEPT
	Handshake accept message. More...

#define	DEBUG(...)
	Debug. More...

Frame types.
#define	WS_FIN 128
	Frame FIN. More...

#define	WS_FIN_SHIFT 7
	Frame FIN shift. More...

#define	WS_FR_OP_CONT 0
	Continuation frame. More...

#define	WS_FR_OP_TXT 1
	Text frame. More...

#define	WS_FR_OP_BIN 2
	Binary frame. More...

#define	WS_FR_OP_CLSE 8
	Close frame. More...

#define	WS_FR_OP_PING 0x9
	Ping frame. More...

#define	WS_FR_OP_PONG 0xA
	Pong frame. More...

#define	WS_FR_OP_UNSUPPORTED 0xF
	Unsupported frame. More...

Close codes
#define	WS_CLSE_NORMAL 1000
	Normal close. More...

#define	WS_CLSE_PROTERR 1002
	Protocol error. More...

Connection states
#define	WS_STATE_CONNECTING 0
	Connection not established yet. More...

#define	WS_STATE_OPEN 1
	Communicating. More...

#define	WS_STATE_CLOSING 2
	Closing state. More...

#define	WS_STATE_CLOSED 3
	Closed. More...

Timeout util
#define	MS_TO_NS(x) ((x)*1000000)
	Nanoseconds macro converter. More...

#define	TIMEOUT_MS (500)
	Timeout in milliseconds. More...

Functions
void *	ws_get_server_context (ws_cli_conn_t *cli)
	Get server context. More...

void	ws_set_connection_context (ws_cli_conn_t cli, void ptr)
	Set connection context. More...

void *	ws_get_connection_context (ws_cli_conn_t *cli)
	Get connection context. More...

int	get_handshake_accept (char wsKey, unsigned char *dest)
	Gets the field Sec-WebSocket-Accept on response, by an previously informed key. More...

int	get_handshake_response (char hsrequest, char *hsresponse)
	Gets the complete response to accomplish a succesfully handshake. More...

char *	ws_getaddress (ws_cli_conn_t *client)
	Gets the IP address relative to a client connection opened by the server. More...

char *	ws_getport (ws_cli_conn_t *client)
	Gets the IP port relative to a client connection opened by the server. More...

int	ws_sendframe (ws_cli_conn_t cli, const char msg, uint64_t size, int type)
	Send an WebSocket frame with some payload data. More...

int	ws_sendframe_bcast (uint16_t port, const char *msg, uint64_t size, int type)
	Send an WebSocket frame with some payload data to all clients connected into the same port. More...

int	ws_sendframe_txt (ws_cli_conn_t cli, const char msg)
	Sends a WebSocket text frame. More...

int	ws_sendframe_txt_bcast (uint16_t port, const char *msg)
	Sends a broadcast WebSocket text frame. More...

int	ws_sendframe_bin (ws_cli_conn_t cli, const char msg, uint64_t size)
	Sends a WebSocket binary frame. More...

int	ws_sendframe_bin_bcast (uint16_t port, const char *msg, uint64_t size)
	Sends a broadcast WebSocket binary frame. More...

int	ws_get_state (ws_cli_conn_t *cli)
	For a given `client`, gets the current state for the connection, or -1 if invalid. More...

int	ws_close_client (ws_cli_conn_t *cli)
	Close the client connection for the given `client` with normal close code (1000) and no reason string. More...

int	ws_socket (struct ws_server *ws_srv)
	Main loop for the server. More...

void	ws_ping (ws_cli_conn_t *cli, int threshold)
	Sends a PING frame to the client `cli` with threshold `threshold`. More...

Detailed Description

wsServer constants and functions.

Macro Definition Documentation

◆ DEBUG

#define DEBUG ( ... )

Debug.

◆ MAGIC_STRING

#define MAGIC_STRING "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"

Magic string.

◆ MAX_CLIENTS

#define MAX_CLIENTS 8

Max clients connected simultaneously.

◆ MAX_FRAME_LENGTH

#define MAX_FRAME_LENGTH (16*1024*1024)

Maximum frame/message length.

◆ MESSAGE_LENGTH

#define MESSAGE_LENGTH 2048

Message buffer length.

◆ MS_TO_NS

#define MS_TO_NS ( x ) ((x)*1000000)

Nanoseconds macro converter.

◆ RECV

#define RECV	(	fd,
		buf,
		len
	)	recv((fd)->client_sock, (buf), (len), 0)

◆ SEND

#define SEND	(	client,
		buf,
		len
	)	send_all((client), (buf), (len), MSG_NOSIGNAL)

◆ TIMEOUT_MS

#define TIMEOUT_MS (500)

Timeout in milliseconds.

◆ WS_CLSE_INVUTF8

#define WS_CLSE_INVUTF8 1007

Inconsistent message (invalid utf-8)

◆ WS_CLSE_NORMAL

#define WS_CLSE_NORMAL 1000

Normal close.

◆ WS_CLSE_PROTERR

#define WS_CLSE_PROTERR 1002

Protocol error.

◆ WS_FIN

#define WS_FIN 128

Frame FIN.

◆ WS_FIN_SHIFT

#define WS_FIN_SHIFT 7

Frame FIN shift.

◆ WS_FR_OP_BIN

#define WS_FR_OP_BIN 2

Binary frame.

◆ WS_FR_OP_CLSE

#define WS_FR_OP_CLSE 8

Close frame.

◆ WS_FR_OP_CONT

#define WS_FR_OP_CONT 0

Continuation frame.

◆ WS_FR_OP_PING

#define WS_FR_OP_PING 0x9

Ping frame.

◆ WS_FR_OP_PONG

#define WS_FR_OP_PONG 0xA

Pong frame.

◆ WS_FR_OP_TXT

#define WS_FR_OP_TXT 1

Text frame.

◆ WS_FR_OP_UNSUPPORTED

#define WS_FR_OP_UNSUPPORTED 0xF

Unsupported frame.

◆ WS_HS_ACCEPT

#define WS_HS_ACCEPT

Value:

                                "HTTP/1.1 101 Switching Protocols\r\n" \
                                "Upgrade: websocket\r\n"               \
                                "Connection: Upgrade\r\n"              \
                                "Sec-WebSocket-Accept: "

Handshake accept message.

◆ WS_HS_ACCLEN

#define WS_HS_ACCLEN 130

Handshake accept message length.

◆ WS_HS_REQ

#define WS_HS_REQ "Sec-WebSocket-Key"

Alias for 'Sec-WebSocket-Key'.

◆ WS_KEY_LEN

#define WS_KEY_LEN 24

WebSocket key length.

◆ WS_KEYMS_LEN

#define WS_KEYMS_LEN (WS_KEY_LEN + WS_MS_LEN)

Accept message response length.

◆ WS_MS_LEN

#define WS_MS_LEN 36

Magic string length.

◆ WS_STATE_CLOSED

#define WS_STATE_CLOSED 3

Closed.

◆ WS_STATE_CLOSING

#define WS_STATE_CLOSING 2

Closing state.

◆ WS_STATE_CONNECTING

#define WS_STATE_CONNECTING 0

Connection not established yet.

◆ WS_STATE_OPEN

#define WS_STATE_OPEN 1

Communicating.

Function Documentation

◆ get_handshake_accept()

int get_handshake_accept	(	char *	wsKey,
		unsigned char **	dest
	)

Gets the field Sec-WebSocket-Accept on response, by an previously informed key.

Parameters

wsKey	Sec-WebSocket-Key
dest	source to be stored the value.

Returns: Returns 0 if success and a negative number otherwise.

Attention: This is part of the internal API and is documented just for completeness.

◆ get_handshake_response()

int get_handshake_response	(	char *	hsrequest,
		char **	hsresponse
	)

Gets the complete response to accomplish a succesfully handshake.

Parameters

hsrequest	Client request.
hsresponse	Server response.

Returns: Returns 0 if success and a negative number otherwise.

Attention: This is part of the internal API and is documented just for completeness.

◆ ws_close_client()

int ws_close_client ( ws_cli_conn_t * client )

Close the client connection for the given client with normal close code (1000) and no reason string.

Parameters

client Client connection.

Returns: Returns 0 on success, -1 otherwise.

Note: If the client did not send a close frame in TIMEOUT_MS milliseconds, the server will close the connection with error code (1002).

◆ ws_get_connection_context()

void* ws_get_connection_context ( ws_cli_conn_t * cli )

Get connection context.

◆ ws_get_server_context()

void* ws_get_server_context ( ws_cli_conn_t * cli )

Get server context.

Set when initializing .context in struct ws_server.

Assumed to be set once, when initializing .context in struct ws_server.

◆ ws_get_state()

int ws_get_state ( ws_cli_conn_t * client )

For a given client, gets the current state for the connection, or -1 if invalid.

Parameters

client Client connection.

Returns: Returns the connection state or -1 if invalid client.

See also: WS_STATE_CONNECTING; WS_STATE_OPEN; WS_STATE_CLOSING; WS_STATE_CLOSED

◆ ws_getaddress()

char* ws_getaddress ( ws_cli_conn_t * client )

Gets the IP address relative to a client connection opened by the server.

Parameters

client Client connection.

Returns: Pointer the ip address, or NULL if fails.

Note: The returned string is static, no need to free up memory.

◆ ws_getport()

char* ws_getport ( ws_cli_conn_t * client )

Gets the IP port relative to a client connection opened by the server.

Parameters

client Client connection.

Returns: Pointer the port, or NULL if fails.

Note: The returned string is static, no need to free up memory.

◆ ws_ping()

void ws_ping	(	ws_cli_conn_t *	cli,
		int	threshold
	)

Sends a PING frame to the client cli with threshold threshold.

This routine sends a PING to a single client pointed to by cli or a broadcast PING if cli is NULL. If the specified client does not respond up to threshold PINGs, the connection is aborted.

ws_ping() is not automatic: the user who wants to send keep-alive PINGs must call this routine in a timely manner, whether on a different thread or inside an event.

See examples/ping/ping.c for a minimal example usage.

Parameters

cli	Client to be sent, if NULL, broadcast.
threshold	How many ignored PINGs should tolerate? (should be positive and greater than 0).

Note: It should be noted that the time between each call to ws_ping() is the timeout itself for receiving the PONG.

It is also important to note that for devices with unstable connections (such as a weak WiFi signal or 3/4/5G from a cell phone), a threshold greater than 1 is advisable.

◆ ws_sendframe()

int ws_sendframe	(	ws_cli_conn_t *	client,
		const char *	msg,
		uint64_t	size,
		int	type
	)

Send an WebSocket frame with some payload data.

Parameters

client	Target to be send. If NULL, broadcast the message.
msg	Message to be send.
size	Binary message size.
type	Frame type.

Returns: Returns the number of bytes written, -1 if error.

Note: If size is -1, it is assumed that a text frame is being sent, otherwise, a binary frame. In the later case, the size is used.

◆ ws_sendframe_bcast()

int ws_sendframe_bcast	(	uint16_t	port,
		const char *	msg,
		uint64_t	size,
		int	type
	)

Send an WebSocket frame with some payload data to all clients connected into the same port.

Parameters

port	Server listen port to broadcast message.
msg	Message to be send.
size	Binary message size.
type	Frame type.

Returns: Returns the number of bytes written, -1 if error.

Note: If size is -1, it is assumed that a text frame is being sent, otherwise, a binary frame. In the later case, the size is used.

◆ ws_sendframe_bin()

int ws_sendframe_bin	(	ws_cli_conn_t *	client,
		const char *	msg,
		uint64_t	size
	)

Sends a WebSocket binary frame.

Parameters

client	Target to be send.
msg	Message to be send.
size	Binary message size.

Returns: Returns the number of bytes written, -1 if error.

◆ ws_sendframe_bin_bcast()

int ws_sendframe_bin_bcast	(	uint16_t	port,
		const char *	msg,
		uint64_t	size
	)

Sends a broadcast WebSocket binary frame.

Parameters

port	Server listen port to broadcast message.
msg	Message to be send.
size	Binary message size.

Returns: Returns the number of bytes written, -1 if error.

◆ ws_sendframe_txt()

int ws_sendframe_txt	(	ws_cli_conn_t *	client,
		const char *	msg
	)

Sends a WebSocket text frame.

Parameters

client	Target to be send.
msg	Message to be send, null terminated.

Returns: Returns the number of bytes written, -1 if error.

◆ ws_sendframe_txt_bcast()

int ws_sendframe_txt_bcast	(	uint16_t	port,
		const char *	msg
	)

Sends a broadcast WebSocket text frame.

Parameters

port	Server listen port to broadcast message.
msg	Message to be send, null terminated.

Returns: Returns the number of bytes written, -1 if error.

◆ ws_set_connection_context()

void ws_set_connection_context	(	ws_cli_conn_t *	cli,
		void *	ptr
	)

Set connection context.

◆ ws_socket()

int ws_socket ( struct ws_server * ws_srv )

Main loop for the server.

Parameters

ws_srv Web Socket server parameters.

Returns: If thread_loop != 0, returns 0. Otherwise, never returns.

Classes

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ DEBUG

◆ MAGIC_STRING

◆ MAX_CLIENTS

◆ MAX_FRAME_LENGTH

◆ MESSAGE_LENGTH

◆ MS_TO_NS

◆ RECV

◆ SEND

◆ TIMEOUT_MS

◆ WS_CLSE_INVUTF8

◆ WS_CLSE_NORMAL

◆ WS_CLSE_PROTERR

◆ WS_FIN

◆ WS_FIN_SHIFT

◆ WS_FR_OP_BIN

◆ WS_FR_OP_CLSE

◆ WS_FR_OP_CONT

◆ WS_FR_OP_PING

◆ WS_FR_OP_PONG

◆ WS_FR_OP_TXT

◆ WS_FR_OP_UNSUPPORTED

◆ WS_HS_ACCEPT

◆ WS_HS_ACCLEN

◆ WS_HS_REQ

◆ WS_KEY_LEN

◆ WS_KEYMS_LEN

◆ WS_MS_LEN

◆ WS_STATE_CLOSED

◆ WS_STATE_CLOSING

◆ WS_STATE_CONNECTING

◆ WS_STATE_OPEN

Function Documentation

◆ get_handshake_accept()

◆ get_handshake_response()

◆ ws_close_client()

◆ ws_get_connection_context()

◆ ws_get_server_context()

◆ ws_get_state()

◆ ws_getaddress()

◆ ws_getport()

◆ ws_ping()

◆ ws_sendframe()

◆ ws_sendframe_bcast()

◆ ws_sendframe_bin()

◆ ws_sendframe_bin_bcast()

◆ ws_sendframe_txt()

◆ ws_sendframe_txt_bcast()

◆ ws_set_connection_context()

◆ ws_socket()