Data Structures
struct	onion_websocket_t
	Websocket data type, as returned by onion_websocket_new. More...

Typedefs
typedef onion_connection_status(*	onion_websocket_t::onion_websocket_callback_t )(void privdata, onion_websocket ws, ssize_t data_ready_length)
	Prototype for websocket callbacks.
typedef ssize_t(	lpwriter_sig_t )(onion_request req, const char data, size_t len)
typedef ssize_t(	lpreader_sig_t )(onion_request req, char data, size_t len)

Enumerations
enum	onion_websocket_t::onion_websocket_opcode_e
	Types of fragments that websockets support. More...
enum	onion_websocket_flags_e { WS_FIN = 1, WS_MASK = 2 }

Functions
void	onion_websocket_set_opcode (onion_websocket *ws, onion_websocket_opcode opcode)
	Sets the opcode for the websocketThis can be called before writes to change the meaning of the write.
onion_websocket_opcode	onion_websocket_get_opcode (onion_websocket *ws)
	Returns current in use opcodes.
onion_websocket *	onion_websocket_t::onion_websocket_new (onion_request req, onion_response res)
	Creates a websocket connection from the given request to the response.
void	onion_websocket_t::onion_websocket_free (onion_websocket *ws)
	Frees the websocket.
int	onion_websocket_t::onion_websocket_write (onion_websocket ws, const char buffer, size_t _len)
	Writes a fragment to the websocket.
int	onion_websocket_t::onion_websocket_read (onion_websocket ws, char buffer, size_t len)
	Reads some data from the websocket.
int	onion_websocket_t::onion_websocket_vprintf (onion_websocket ws, const char fmt, va_list args)
	Uses vprintf-style writing to the websocket.
int	onion_websocket_t::onion_websocket_printf (onion_websocket ws, const char fmt,...)
	Uses printf-style writing to the websocket.
void	onion_websocket_t::onion_websocket_set_callback (onion_websocket *ws, onion_websocket_callback_t cb)
	Sets the next callback to call if more data is available.
void	onion_websocket_t::onion_websocket_set_userdata (onion_websocket ws, void userdata, void(free_userdata)(void ))
	Sets the userdata to use for this websocket connection.
onion_connection_status	onion_websocket_t::onion_websocket_call (onion_websocket *ws)
	Used internally when new data is ready on the websocket file descriptor.

Detailed Description

Typedef Documentation

typedef ssize_t( lpreader_sig_t)(onion_request *req, char *data, size_t len)

typedef ssize_t( lpwriter_sig_t)(onion_request *req, const char *data, size_t len)

typedef onion_connection_status(* onion_websocket_callback_t)(void *privdata, onion_websocket *ws, ssize_t data_ready_length)

Prototype for websocket callbacks.

The callbacks are the functions to be called when new data is available on websockets.

They are not mandatory, but when used they can be changed from the callback itself, using onion_websocket_set_callback. If data is left for read after a callback call, next callback is called with that data. If same callback stays, and no data has been consumed, it will not be called until new data is available. End of input, or websocket removal is notified with a negative data_ready_length.

The private data is that of the original request handler.

This chaining of callbacks allows easy creation of state machines.

Returns: OCS_INTERNAL_ERROR | OCS_CLOSE_CONNECTION | OCS_NEED_MORE_DATA. Other returns result in OCS_INTERNAL_ERROR.

Enumeration Type Documentation

enum onion_websocket_flags_e

Enumerator:

WS_FIN
WS_MASK

enum onion_websocket_opcode_e

Types of fragments that websockets support.

Function Documentation

onion_connection_status onion_websocket_call ( onion_websocket * ws )

Used internally when new data is ready on the websocket file descriptor.

References onion_websocket_t::callback, onion_request_t::connection, onion_websocket_t::data_left, onion_request_t::fd, OCS_CLOSE_CONNECTION, OCS_INTERNAL_ERROR, OCS_NEED_MORE_DATA, ONION_DEBUG, ONION_ERROR, onion_websocket_t::req, and onion_websocket_t::user_data.

Referenced by onion_handler_t::onion_handler_handle().

void onion_websocket_free ( onion_websocket * ws )

Frees the websocket.

Frees the websocket, and if possible, the userdata. There is no need to call it as the request does it when the request finishes.

Parameters

ws

References onion_websocket_t::callback, onion_websocket_t::free_user_data, onion_low_free(), onion_random_free(), onion_websocket_t::req, onion_websocket_t::user_data, and onion_request_t::websocket.

Referenced by onion_request_t::onion_request_free().

onion_websocket_opcode onion_websocket_get_opcode ( onion_websocket * ws )

Returns current in use opcodes.

Parameters

ws	The websocket

Returns: The current opcodes in use

References onion_websocket_t::opcode.

onion_websocket * onion_websocket_new	(	onion_request *	req,
		onion_response *	res
	)

Creates a websocket connection from the given request to the response.

It makes all the checks about it being a proper websocket connection, and returns the websocket object.

Default opcode mode is OWS_TEXT.

Parameters

req	The request
res	The response

Returns: The websocket if possible, or NULL if not possible.

References onion_websocket_t::callback, onion_request_t::data, onion_websocket_t::data_left, onion_response_t::flags, onion_websocket_t::flags, onion_websocket_t::free_user_data, HTTP_SWITCH_PROTOCOL, onion_base64_encode(), ONION_DEBUG, ONION_ERROR, onion_low_free(), onion_low_malloc(), onion_random_init(), onion_request_t::onion_request_get_header(), onion_response_t::onion_response_set_code(), onion_response_t::onion_response_set_header(), onion_response_t::onion_response_write(), onion_response_t::onion_response_write_headers(), onion_sha1(), onion_websocket_t::opcode, OR_CONNECTION_UPGRADE, OR_LENGTH_SET, OWS_TEXT, onion_websocket_t::req, onion_websocket_t::user_data, and onion_request_t::websocket.

int onion_websocket_printf	(	onion_websocket *	ws,
		const char *	fmt,
			...
	)

Uses printf-style writing to the websocket.

It writes the message as a single fragment, using onion_websocket_vprintf ...

Parameters

ws	The websocket
fmt	printf-like format string, and next parameters are the arguments

Returns: Number of bytes written

References onion_websocket_t::onion_websocket_vprintf().

int onion_websocket_read	(	onion_websocket *	ws,
		char *	buffer,
		size_t	len
	)

Reads some data from the websocket.

It attemps to read len bytes from the websocket. If there is enought data it reads it from the current fragment, but it may block waiting for next fragment if data is exhausted.

Check onion_websocket_set_callback for more info on how to use websockets.

Parameters

ws	Wbsocket object
buffer	Data to write
len	Length of buffer to write

Returns: number of bytes written or <0 if error.

References onion_websocket_t::callback, onion_request_t::connection, onion_websocket_t::data_left, onion_websocket_t::flags, onion_request_t::listen_point, onion_websocket_t::mask, onion_websocket_t::mask_pos, ONION_DEBUG, ONION_ERROR, onion_listen_point_t::read, onion_websocket_t::req, and WS_MASK.

void onion_websocket_set_callback	(	onion_websocket *	ws,
		onion_websocket_callback_t	cb
	)

Sets the next callback to call if more data is available.

Websockets are callback/blocking based. Users of websockets can choose which option to use, as required by the application.

Both are not incompatible.

The blocking mode just tries to read more data than available, so it will block until some data is ready.

The non-blocking asynchronous mode sets a callback to call when data is ready, and it passes this callback the websocket, some internal data, and the lenght of data ready to be read. In this callback the callback can be changed, so that next calls will call that callback. If not all data is used, it will be called inmediatly on exit.

Parameters

ws	Websocket
cb	The callback function to call: onion_connection_status callback_signature(void data, onion_websocket ws, size_t data_ready_len);

References onion_websocket_t::callback.

void onion_websocket_set_opcode	(	onion_websocket *	ws,
		onion_websocket_opcode	opcode
	)

Sets the opcode for the websocketThis can be called before writes to change the meaning of the write.

WARNING: If untouched, its the opcode of the last received fragment.

This is the normal desired way, as if server talks to you in text normally you answer in text, and so on.

Parameters

ws	The websocket
opcode	The new opcode, from onion_websocket_opcode enum (matches specification numbers)

References onion_websocket_t::opcode.

Referenced by onion_websocket_close().

void onion_websocket_set_userdata	(	onion_websocket *	ws,
		void *	userdata,
		void()(void )	free_userdata
	)

Sets the userdata to use for this websocket connection.

By default it will contain the request user data, but can be changed to any.

If a free user data funtion is provided it will be called to free old userdatas when a new one is set, or when websocket is destroyed.

This userdata can be used to store connection session data between callback calls.

Parameters

ws	Websocket connection
userdata	User data
free_userdata	Function to call to free user data.

References onion_websocket_t::free_user_data, and onion_websocket_t::user_data.

int onion_websocket_vprintf	(	onion_websocket *	ws,
		const char *	fmt,
		va_list	args
	)

Uses vprintf-style writing to the websocket.

It writes the message as a single fragment. Above 512 bytes, a scalar buffer is temporarily malloc-ed then free-d ...

Parameters

ws	The websocket
fmt	printf-like format string, and args containing the arguments

Returns: Number of bytes written

References ONION_ERROR, onion_low_free(), onion_low_scalar_malloc(), and onion_websocket_t::onion_websocket_write().

Referenced by onion_websocket_t::onion_websocket_printf().

int onion_websocket_write	(	onion_websocket *	ws,
		const char *	buffer,
		size_t	_len
	)

Writes a fragment to the websocket.

Parameters

ws	The Websocket
buffer	Data to write
_len	Length of data to write

Returns: Bytes written or <0 if error writting.

FIXME! powerup using int32_t as basic type.

References onion_request_t::connection, onion_request_t::listen_point, ONION_DEBUG, onion_websocket_t::opcode, onion_websocket_t::req, and onion_listen_point_t::write.

Referenced by onion_websocket_close(), and onion_websocket_t::onion_websocket_vprintf().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation