#include <curl/curl.h>
#include "error.h"
#include "logconf.h"

Include dependency graph for websockets.h:

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

Data Structures
struct	ws_info
	Stores info on the latest transfer performed via websockets. More...

struct	ws_callbacks
	WebSockets callbacks. More...

struct	ws_attr
	WebSockets handle initialization attributes. More...

Macros
#define	ws_is_alive(ws) (ws_get_status(ws) != WS_DISCONNECTED)
	Check if a WebSockets connection is alive. More...

#define	ws_is_functional(ws) (ws_get_status(ws) == WS_CONNECTED)
	Check if WebSockets connection is functional. More...

Enumerations
enum	ws_status { WS_DISCONNECTED = 0 , WS_CONNECTED , WS_DISCONNECTING , WS_CONNECTING }
	The WebSockets client status. More...

enum	ws_close_reason { WS_CLOSE_REASON_NORMAL = 1000 , WS_CLOSE_REASON_GOING_AWAY = 1001 , WS_CLOSE_REASON_PROTOCOL_ERROR = 1002 , WS_CLOSE_REASON_UNEXPECTED_DATA = 1003 , WS_CLOSE_REASON_NO_REASON = 1005 , WS_CLOSE_REASON_ABRUPTLY = 1006 , WS_CLOSE_REASON_INCONSISTENT_DATA = 1007 , WS_CLOSE_REASON_POLICY_VIOLATION = 1008 , WS_CLOSE_REASON_TOO_BIG = 1009 , WS_CLOSE_REASON_MISSING_EXTENSION = 1010 , WS_CLOSE_REASON_SERVER_ERROR = 1011 , WS_CLOSE_REASON_IANA_REGISTRY_START = 3000 , WS_CLOSE_REASON_IANA_REGISTRY_END = 3999 , WS_CLOSE_REASON_PRIVATE_START = 4000 , WS_CLOSE_REASON_PRIVATE_END = 4999 }
	WebSockets CLOSE opcodes. More...

Functions
struct websockets *	ws_init (struct ws_callbacks cbs, CURLM mhandle, struct ws_attr *attr)
	Create a new (CURL-based) WebSockets handle. More...

void	ws_cleanup (struct websockets *ws)
	Free a WebSockets handle created with ws_init() More...

void	ws_set_url (struct websockets *ws, const char base_url[], const char ws_protocols[])
	Set the URL for the WebSockets handle to connect. More...

_Bool	ws_send_binary (struct websockets ws, struct ws_info info, const char msg[], size_t msglen)
	Send a binary message of given size. More...

_Bool	ws_send_text (struct websockets ws, struct ws_info info, const char text[], size_t len)
	Send a text message of given size. More...

_Bool	ws_ping (struct websockets ws, struct ws_info info, const char reason[], size_t len)
	Send a PING (opcode 0x9) frame with reason as payload. More...

_Bool	ws_pong (struct websockets ws, struct ws_info info, const char reason[], size_t len)
	Send a PONG (opcode 0xA) frame with reason as payload. More...

CURL *	ws_start (struct websockets *ws)
	Signals connecting state before entering the WebSockets event loop. More...

void	ws_end (struct websockets *ws)
	Cleanup and reset `ws` connection resources. More...

_Bool	ws_easy_run (struct websockets ws, uint64_t wait_ms, uint64_t tstamp)
	Reads/Write available data from WebSockets. More...

_Bool	ws_multi_socket_run (struct websockets ws, uint64_t tstamp)
	Reads/Write available data from WebSockets. More...

enum ws_status	ws_get_status (struct websockets *ws)
	Returns the WebSockets handle connection status. More...

const char *	ws_close_opcode_print (enum ws_close_reason opcode)
	Returns a enum ws_close_reason opcode in a string format. More...

uint64_t	ws_timestamp (struct websockets *ws)
	The WebSockets event-loop concept of "now". More...

uint64_t	ws_timestamp_update (struct websockets *ws)
	Update the WebSockets event-loop concept of "now". More...

void	ws_close (struct websockets *ws, const enum ws_close_reason code, const char reason[], const size_t len)
	Thread-safe way to stop websockets connection. More...

void	ws_add_header (struct websockets *ws, const char field[], const char value[])
	Add a header field/value pair. More...

Macro Definition Documentation

◆ ws_is_alive

#define ws_is_alive ( ws ) (ws_get_status(ws) != WS_DISCONNECTED)

Check if a WebSockets connection is alive.

This will only return true if the connection status is different than WS_DISCONNECTED

Parameters

ws	the WebSockets handle created with ws_init()

Returns: true if WebSockets status is different than WS_DISCONNECTED, false otherwise.

◆ ws_is_functional

#define ws_is_functional ( ws ) (ws_get_status(ws) == WS_CONNECTED)

Check if WebSockets connection is functional.

This will only return true if the connection status is WS_CONNECTED

Parameters

ws	the WebSockets handle created with ws_init()

Returns: true if is functional, false otherwise

Enumeration Type Documentation

◆ ws_status

enum ws_status

The WebSockets client status.

See also: ws_get_status()

Enumerator
WS_DISCONNECTED	client disconnected from ws
WS_CONNECTED	client connected to ws
WS_DISCONNECTING	client in the process of disconnecting from ws
WS_CONNECTING	client in the process of connecting to ws

◆ ws_close_reason

enum ws_close_reason

WebSockets CLOSE opcodes.

See also: ws_close_opcode_print(); https://tools.ietf.org/html/rfc6455#section-7.4.1

Enumerator
WS_CLOSE_REASON_NORMAL
WS_CLOSE_REASON_GOING_AWAY
WS_CLOSE_REASON_PROTOCOL_ERROR
WS_CLOSE_REASON_UNEXPECTED_DATA
WS_CLOSE_REASON_NO_REASON
WS_CLOSE_REASON_ABRUPTLY
WS_CLOSE_REASON_INCONSISTENT_DATA
WS_CLOSE_REASON_POLICY_VIOLATION
WS_CLOSE_REASON_TOO_BIG
WS_CLOSE_REASON_MISSING_EXTENSION
WS_CLOSE_REASON_SERVER_ERROR
WS_CLOSE_REASON_IANA_REGISTRY_START
WS_CLOSE_REASON_IANA_REGISTRY_END
WS_CLOSE_REASON_PRIVATE_START
WS_CLOSE_REASON_PRIVATE_END

Function Documentation

◆ ws_init()

struct websockets * ws_init	(	struct ws_callbacks *	cbs,
		CURLM *	mhandle,
		struct ws_attr *	attr
	)

Create a new (CURL-based) WebSockets handle.

Parameters

cbs	set of functions to call back when server report events.
mhandle	user-owned curl_multi handle for performing non-blocking transfers
attr	optional attributes to override defaults

Returns: newly created WebSockets handle, free with ws_cleanup()

◆ ws_cleanup()

void ws_cleanup ( struct websockets * ws )

Free a WebSockets handle created with ws_init()

Parameters

ws	the WebSockets handle created with ws_init()

◆ ws_set_url()

void ws_set_url	(	struct websockets *	ws,
		const char	base_url[],
		const char	ws_protocols[]
	)

Set the URL for the WebSockets handle to connect.

Parameters

ws	the WebSockets handle created with ws_init()
base_url	the URL to connect, such as ws://echo.websockets.org
ws_protocols	NULL or something like "chat", "superchat",...

◆ ws_send_binary()

_Bool ws_send_binary	(	struct websockets *	ws,
		struct ws_info *	info,
		const char	msg[],
		size_t	msglen
	)

Send a binary message of given size.

Binary messages do not need to include the null terminator (\0), they will be read up to msglen.

Parameters

ws	the WebSockets handle created with ws_init()
info	get information on how this transfer went
msg	the pointer to memory (linear) to send.
msglen	the length in bytes of msg.

Returns: true if sent, false on errors.

◆ ws_send_text()

_Bool ws_send_text	(	struct websockets *	ws,
		struct ws_info *	info,
		const char	text[],
		size_t	len
	)

Send a text message of given size.

Text messages do not need to include the null terminator (\0), they will be read up to len.

Parameters

ws	the WebSockets handle created with ws_init()
info	get information on how this transfer went
text	the pointer to memory (linear) to send.
len	the length in bytes of text.

Returns: true if sent, false on errors.

◆ ws_ping()

_Bool ws_ping	(	struct websockets *	ws,
		struct ws_info *	info,
		const char	reason[],
		size_t	len
	)

Send a PING (opcode 0x9) frame with reason as payload.

Parameters

ws	the WebSockets handle created with ws_init()
info	get information on how this transfer went
reason	NULL or some UTF-8 string null ('\0') terminated.
len	the length of reason in bytes. If SIZE_MAX, uses strlen() on reason if it's not NULL.

Returns: true if sent, false on errors.

◆ ws_pong()

_Bool ws_pong	(	struct websockets *	ws,
		struct ws_info *	info,
		const char	reason[],
		size_t	len
	)

Send a PONG (opcode 0xA) frame with reason as payload.

Note that pong is sent automatically if no "on_ping" callback is defined. If one is defined you must send pong manually.

Parameters

ws	the WebSockets handle created with ws_init()
info	get information on how this transfer went
reason	NULL or some UTF-8 string null ('\0') terminated.
len	the length of reason in bytes. If SIZE_MAX, uses strlen() on reason if it's not NULL.

Returns: true if sent, false on errors.

◆ ws_start()

CURL * ws_start ( struct websockets * ws )

Signals connecting state before entering the WebSockets event loop.

Parameters

ws	the WebSockets handle created with ws_init()

Returns: the WebSockets easy_handle that is free'd at ws_end()

◆ ws_end()

void ws_end ( struct websockets * ws )

Cleanup and reset ws connection resources.

Parameters

ws	the WebSockets handle created with ws_init()

◆ ws_easy_run()

_Bool ws_easy_run	(	struct websockets *	ws,
		uint64_t	wait_ms,
		uint64_t *	tstamp
	)

Reads/Write available data from WebSockets.

Note: Helper over curl_multi_wait()

Parameters

ws	the WebSockets handle created with ws_init()
wait_ms	limit amount in milliseconds to wait for until activity
tstamp	get current timestamp for this iteration

Returns: true if connection is still alive, false otherwise

Note: This is an easy, yet highly abstracted way of performing transfers. If a higher control is necessary, users are better of using ws_multi_socket_run()

◆ ws_multi_socket_run()

_Bool ws_multi_socket_run	(	struct websockets *	ws,
		uint64_t *	tstamp
	)

Reads/Write available data from WebSockets.

Note: Helper over curl_multi_socket_all()

Parameters

ws	the WebSockets handle created with ws_init()
tstamp	get current timestamp for this iteration

Returns: true if connection is still alive, false otherwise

◆ ws_get_status()

enum ws_status ws_get_status ( struct websockets * ws )

Returns the WebSockets handle connection status.

Parameters

ws	the WebSockets handle created with ws_init()

Returns: a ws_status opcode

◆ ws_close_opcode_print()

const char * ws_close_opcode_print ( enum ws_close_reason opcode )

Returns a enum ws_close_reason opcode in a string format.

Parameters

opcode the opcode to be converted to string

Returns: a read-only string literal of the opcode

◆ ws_timestamp()

uint64_t ws_timestamp ( struct websockets * ws )

The WebSockets event-loop concept of "now".

Parameters

ws	the WebSockets handle created with ws_init()

Returns: the timestamp in milliseconds from when ws_timestamp_update() was last called

Note: the timestamp is updated at the start of each event-loop iteration

◆ ws_timestamp_update()

uint64_t ws_timestamp_update ( struct websockets * ws )

Update the WebSockets event-loop concept of "now".

Parameters

ws	the WebSockets handle created with ws_init()

Returns: the timestamp in milliseconds

◆ ws_close()

void ws_close	(	struct websockets *	ws,
		const enum ws_close_reason	code,
		const char	reason[],
		const size_t	len
	)

Thread-safe way to stop websockets connection.

This will activate a internal WS_USER_CMD_EXIT flag that will force disconnect when the next iteration begins.

Note: it will create a copy of the reason string

Parameters

ws	the WebSockets handle created with ws_init()
code	the WebSockets CLOSE opcode
reason	the close reason
len	the reason length

◆ ws_add_header()

void ws_add_header	(	struct websockets *	ws,
		const char	field[],
		const char	value[]
	)

Add a header field/value pair.

Parameters

ws	the WebSockets handle created with ws_init()
field	the header field
value	the header value

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

◆ ws_is_alive

◆ ws_is_functional

Enumeration Type Documentation

◆ ws_status

◆ ws_close_reason

Function Documentation

◆ ws_init()

◆ ws_cleanup()

◆ ws_set_url()

◆ ws_send_binary()

◆ ws_send_text()

◆ ws_ping()

◆ ws_pong()

◆ ws_start()

◆ ws_end()

◆ ws_easy_run()

◆ ws_multi_socket_run()

◆ ws_get_status()

◆ ws_close_opcode_print()

◆ ws_timestamp()

◆ ws_timestamp_update()

◆ ws_close()

◆ ws_add_header()