curl-websocket.h File Reference

#include <curl/curl.h>
#include <string.h>
#include <stdbool.h>

Include dependency graph for curl-websocket.h:

Go to the source code of this file.

Data Structures
struct	cws_callbacks

Enumerations
enum	cws_close_reason {   CWS_CLOSE_REASON_NORMAL = 1000 , CWS_CLOSE_REASON_GOING_AWAY = 1001 , CWS_CLOSE_REASON_PROTOCOL_ERROR = 1002 , CWS_CLOSE_REASON_UNEXPECTED_DATA = 1003 ,   CWS_CLOSE_REASON_NO_REASON = 1005 , CWS_CLOSE_REASON_ABRUPTLY = 1006 , CWS_CLOSE_REASON_INCONSISTENT_DATA = 1007 , CWS_CLOSE_REASON_POLICY_VIOLATION = 1008 ,   CWS_CLOSE_REASON_TOO_BIG = 1009 , CWS_CLOSE_REASON_MISSING_EXTENSION = 1010 , CWS_CLOSE_REASON_SERVER_ERROR = 1011 , CWS_CLOSE_REASON_IANA_REGISTRY_START = 3000 ,   CWS_CLOSE_REASON_IANA_REGISTRY_END = 3999 , CWS_CLOSE_REASON_PRIVATE_START = 4000 , CWS_CLOSE_REASON_PRIVATE_END = 4999 }

Functions
CURL *	cws_new (const char *url, const char *websocket_protocols, const struct cws_callbacks *callbacks)
void	cws_free (CURL *easy)
bool	cws_send (CURL *easy, bool text, const void *msg, size_t msglen)
bool	cws_ping (CURL *easy, const char *reason, size_t len)
bool	cws_pong (CURL *easy, const char *reason, size_t len)
bool	cws_close (CURL *easy, enum cws_close_reason reason, const char *reason_text, size_t reason_text_len)
void	cws_add_header (CURL *easy, const char field[], const char value[])

Enumeration Type Documentation

cws_close_reason

enum cws_close_reason

Enumerator
CWS_CLOSE_REASON_NORMAL
CWS_CLOSE_REASON_GOING_AWAY
CWS_CLOSE_REASON_PROTOCOL_ERROR
CWS_CLOSE_REASON_UNEXPECTED_DATA
CWS_CLOSE_REASON_NO_REASON
CWS_CLOSE_REASON_ABRUPTLY
CWS_CLOSE_REASON_INCONSISTENT_DATA
CWS_CLOSE_REASON_POLICY_VIOLATION
CWS_CLOSE_REASON_TOO_BIG
CWS_CLOSE_REASON_MISSING_EXTENSION
CWS_CLOSE_REASON_SERVER_ERROR
CWS_CLOSE_REASON_IANA_REGISTRY_START
CWS_CLOSE_REASON_IANA_REGISTRY_END
CWS_CLOSE_REASON_PRIVATE_START
CWS_CLOSE_REASON_PRIVATE_END

Function Documentation

cws_new()

CURL * cws_new	(	const char *	url,
		const char *	websocket_protocols,
		const struct cws_callbacks *	callbacks
	)

Create a new CURL-based WebSocket handle.

This is a regular CURL easy handle properly setup to do WebSocket. You can add more headers and cookies, but do not mess with the following headers:

• Content-Length
• Content-Type
• Transfer-Encoding
• Connection
• Upgrade
• Expect
• Sec-WebSocket-Version
• Sec-WebSocket-Key

And do not change the HTTP method or version, callbacks (read, write or header) or private data.

Parameters

url	the URL to connect, such as ws://echo.websockets.org
websocket_protocols	#NULL or something like "chat", "superchat"...
callbacks	set of functions to call back when server report events.

Returns

newly created CURL easy handle, free with cws_free()

cws_free()

void cws_free

(

CURL *

easy

)

Free a handle created with cws_new()

cws_send()

bool cws_send	(	CURL *	easy,
		bool	text,
		const void *	msg,
		size_t	msglen
	)

Send a text or binary message of given size.

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

Parameters

easy	the CURL easy handle created with cws_new()
text	if #true, opcode will be 0x1 (text-frame), otherwise opcode will be 0x2 (binary-frame).
msg	the pointer to memory (linear) to send.
msglen	the length in bytes of msg.

Returns

#true if sent, #false on errors.

See also

cws_send_binary()

cws_send_text()

cws_ping()

bool cws_ping	(	CURL *	easy,
		const char *	reason,
		size_t	len
	)

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

Parameters

easy	the CURL easy handle created with cws_new()
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.

cws_pong()

bool cws_pong	(	CURL *	easy,
		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

easy	the CURL easy handle created with cws_new()
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.

cws_close()

bool cws_close	(	CURL *	easy,
		enum cws_close_reason	reason,
		const char *	reason_text,
		size_t	reason_text_len
	)

Send a CLOSE (opcode 0x8) frame with reason as payload.

Parameters

easy	the CURL easy handle created with cws_new()
reason	the reason why it was closed, see the well-known numbers.
reason_text	#NULL or some UTF-8 string null ('\0') terminated.
reason_text_len	the length of reason_text in bytes. If #SIZE_MAX, uses strlen() on reason_text if it's not #NULL.

Returns

#true if sent, #false on errors.

cws_add_header()

void cws_add_header	(	CURL *	easy,
		const char	field[],
		const char	value[]
	)

Add a header field/value pair

Parameters

easy	the CURL easy handle created with cws_new()
field	the header field
value	the header value