Provides APIs for Websocket. More...

Collaboration diagram for Websocket:

Data Structures
struct	websocket_t
	structure to manage websocket client/server More...

struct	websocket_info_t
	data structure to use in callbacks. More...

Macros
#define	WEBSOCKET_DEBUG_PRINT

#define	WEBSOCKET_DEBUG ndbg

#define	WS_GUID "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
	Websocket GUID defined by RFC 6455. More...

#define	WEBSOCKET_STACKSIZE (1024 * 10)
	The maximum stack size of websocket. More...

#define	WEBSOCKET_PRI 100
	The priority of websocket. More...

#define	WEBSOCKET_SCHED_POLICY SCHED_RR
	The schedule policy of websocket.. More...

#define	WEBSOCKET_WQ LPWORK
	Websocket timer workqueue. More...

#define	WEBSOCKET_CLIENT_KEY_LEN (24)
	Websocket http handshake key buffer size. More...

#define	WEBSOCKET_ACCEPT_KEY_LEN (29)
	Websocket http handshake key buffer size. More...

#define	WEBSOCKET_HANDSHAKE_HEADER_SIZE (2048)
	Websocket http handshake buffer size. More...

#define	WEBSOCKET_SERVERNAME "localhost"
	Set host name for servername TLS extension. More...

#define	WEBSOCKET_SOCK_RCV_TIMEOUT (5 * 1000)
	Websocket socket input timeout value, msec. More...

#define	WEBSOCKET_SERVER_CHECK_INTERVAL (500)
	Websocket accept server select() timeout value, msec. More...

#define	WEBSOCKET_SERVER_TIMEOUT (3 * 60 * 1000)
	Websocket accept server select() timeout limit, msec. More...

#define	WEBSOCKET_HANDLER_TIMEOUT (300)
	Websocket event handler select() timeout value, msec. More...

#define	WEBSOCKET_MAX_PING_IGNORE (3)
	Ping message limits without pong. More...

#define	WEBSOCKET_PING_INTERVAL (20 * 100)
	Websocket ping message interval, MSEC_PER_TICK. More...

#define	WEBSOCKET_MAX_LENGTH_QUEUE (100 * 1024)
	The maximum amount of websocket messages to be stored in queue. More...

#define	WEBSOCKET_MAX_NUMBER_QUEUE (20)
	The maximum amount of websocket messages to be stored in queue. More...

#define	WEBSOCKET_MAX_CLIENT (3)
	The maximum amount of client to accept from server. More...

#define	websocket_context_ptr wslay_event_context_ptr
	Websocket context pointer wrapper. More...

#define	websocket_cb_t struct wslay_event_callbacks
	Websocket structure wrapper to carry call back pointers. More...

#define	websocket_frame_t struct wslay_event_msg
	Websocket structure wrapper to send a frame. More...

#define	websocket_fragmented_frame_t struct wslay_event_fragmented_msg
	Websocket structure wrapper to send a fragmented frame. More...

#define	websocket_on_msg_arg struct wslay_event_on_msg_recv_arg
	Websocket structure wrapper to receive a message. More...

#define	websocket_recv_start_arg struct wslay_event_on_frame_recv_start_arg
	Websocket structure wrapper to receive a raw frame. More...

#define	websocket_recv_chunk_arg struct wslay_event_on_frame_recv_chunk_arg
	Websocket structure wrapper to receive a chunked frame. More...

#define	WEBSOCKET_CHECK_NOT_CTRL_FRAME(x) (!(((x) >> 3) & 1))
	a macro that checks the websocket frame is not a control frame. More...

#define	WEBSOCKET_CHECK_TEXT_FRAME(x) (((uint8_t)(x)) == ((uint8_t)(WEBSOCKET_TEXT_FRAME)))
	a macro that checks the websocket frame is a text frame. More...

#define	WEBSOCKET_CHECK_BINARY_FRAME(x) (((uint8_t)(x)) == ((uint8_t)(WEBSOCKET_BINARY_FRAME)))
	a macro that checks the websocket frame is a binary frame. More...

#define	WEBSOCKET_CHECK_CTRL_CLOSE(x) (((uint8_t)(x)) == ((uint8_t)(WEBSOCKET_CONNECTION_CLOSE)))
	a macro that checks the websocket frame is a close frame. More...

#define	WEBSOCKET_CHECK_CTRL_PING(x) (((uint8_t)(x)) == ((uint8_t)(WEBSOCKET_PING)))
	a macro that checks the websocket frame is a ping frame. More...

#define	WEBSOCKET_CHECK_CTRL_PONG(x) (((uint8_t)(x)) == ((uint8_t)(WEBSOCKET_PONG)))
	a macro that checks the websocket frame is a pong frame. More...

#define	EXTERN extern

Enumerations

Functions
void	websocket_create_accept_key (unsigned char dst, size_t dlen, const unsigned char src, size_t slen)
	websocket_create_accept_key More...

int	websocket_count_table (void)
	websocket_count_table() returns amount of working websocket server. More...

websocket_t *	websocket_find_table (void)
	websocket_find_table() returns websocket_t * to manage websocket server. More...

websocket_return_t	websocket_client_open (websocket_t client, char addr, char port, char path)
	websocket_client_open() initiates websocket client ready to send and receive websocket message. More...

websocket_return_t	websocket_server_open (websocket_t *server)
	websocket_server_open() initiates websocket server. More...

websocket_return_t	websocket_server_init (websocket_t *server)
	websocket_server_init More...

void	websocket_register_cb (websocket_t websocket, websocket_cb_t cb)
	websocket_register_cb() changes a websocket callback structure in a websocket context. More...

websocket_return_t	websocket_queue_msg (websocket_t websocket, websocket_frame_t tx_frame)

websocket_return_t	websocket_queue_ping (websocket_t *websocket)
	websocket_queue_ping() is used to send a websocket ping message. More...

websocket_return_t	websocket_queue_close (websocket_t websocket, const char close_message)
	websocket_queue_close() closes the websocket. More...

void	websocket_update_state (websocket_t *websocket, int state)
	websocket_update_state() changes websocket state. More...

void	websocket_set_error (websocket_t *websocket, int val)
	websocket_set_error() sets an error number to websocket context. More...

Detailed Description

Provides APIs for Websocket.

Macro Definition Documentation

#define EXTERN extern

Definition at line 402 of file websocket.h.

#define WEBSOCKET_ACCEPT_KEY_LEN (29)

Websocket http handshake key buffer size.

Definition at line 97 of file websocket.h.

#define websocket_cb_t struct wslay_event_callbacks

Websocket structure wrapper to carry call back pointers.

Definition at line 168 of file websocket.h.

#define WEBSOCKET_CHECK_BINARY_FRAME ( x ) (((uint8_t)(x)) == ((uint8_t)(WEBSOCKET_BINARY_FRAME)))

a macro that checks the websocket frame is a binary frame.

if the websocket frame is a binary frame, then it will return 1, else 0

Definition at line 265 of file websocket.h.

#define WEBSOCKET_CHECK_CTRL_CLOSE ( x ) (((uint8_t)(x)) == ((uint8_t)(WEBSOCKET_CONNECTION_CLOSE)))

a macro that checks the websocket frame is a close frame.

if the websocket frame is a close frame, then it will return 1, else 0

Definition at line 272 of file websocket.h.

#define WEBSOCKET_CHECK_CTRL_PING ( x ) (((uint8_t)(x)) == ((uint8_t)(WEBSOCKET_PING)))

a macro that checks the websocket frame is a ping frame.

if the websocket frame is a ping frame, then it will return 1, else 0

Definition at line 279 of file websocket.h.

#define WEBSOCKET_CHECK_CTRL_PONG ( x ) (((uint8_t)(x)) == ((uint8_t)(WEBSOCKET_PONG)))

a macro that checks the websocket frame is a pong frame.

if the websocket frame is a pong frame, then it will return 1, else 0

Definition at line 286 of file websocket.h.

#define WEBSOCKET_CHECK_NOT_CTRL_FRAME ( x ) (!(((x) >> 3) & 1))

a macro that checks the websocket frame is not a control frame.

if the websocket frame is not a control frame, then it will return 1, else 0

Definition at line 251 of file websocket.h.

#define WEBSOCKET_CHECK_TEXT_FRAME ( x ) (((uint8_t)(x)) == ((uint8_t)(WEBSOCKET_TEXT_FRAME)))

a macro that checks the websocket frame is a text frame.

if the websocket frame is a text frame, then it will return 1, else 0

Definition at line 258 of file websocket.h.

#define WEBSOCKET_CLIENT_KEY_LEN (24)

Websocket http handshake key buffer size.

Definition at line 93 of file websocket.h.

#define websocket_context_ptr wslay_event_context_ptr

Websocket context pointer wrapper.

Definition at line 163 of file websocket.h.

#define WEBSOCKET_DEBUG ndbg

Definition at line 59 of file websocket.h.

#define WEBSOCKET_DEBUG_PRINT

websocket debug print option if defined, enables debug print

Definition at line 56 of file websocket.h.

#define websocket_fragmented_frame_t struct wslay_event_fragmented_msg

Websocket structure wrapper to send a fragmented frame.

    The original structure of websocket_fragmented_frame_t :
        struct wslay_event_fragmented_msg {
            uint8_t opcode;                                 //operation code
            union wslay_event_msg_source source;            //source data to make message
            wslay_event_fragmented_msg_cb read_callback;    //callback to read fragmented frame.
        };

Definition at line 196 of file websocket.h.

#define websocket_frame_t struct wslay_event_msg

Websocket structure wrapper to send a frame.

    The original structure of websocket_frame_t :
        struct wslay_event_msg {
            uint8_t opcode;                 //operation code
            const uint8_t *msg;             //received message
            size_t msg_length;              //message length
        };

Definition at line 182 of file websocket.h.

#define WEBSOCKET_HANDLER_TIMEOUT (300)

Websocket event handler select() timeout value, msec.

Definition at line 130 of file websocket.h.

#define WEBSOCKET_HANDSHAKE_HEADER_SIZE (2048)

Websocket http handshake buffer size.

Definition at line 101 of file websocket.h.

#define WEBSOCKET_MAX_CLIENT (3)

The maximum amount of client to accept from server.

Definition at line 153 of file websocket.h.

#define WEBSOCKET_MAX_LENGTH_QUEUE (100 * 1024)

The maximum amount of websocket messages to be stored in queue.

Definition at line 144 of file websocket.h.

#define WEBSOCKET_MAX_NUMBER_QUEUE (20)

The maximum amount of websocket messages to be stored in queue.

Definition at line 148 of file websocket.h.

#define WEBSOCKET_MAX_PING_IGNORE (3)

Ping message limits without pong.

Definition at line 135 of file websocket.h.

#define websocket_on_msg_arg struct wslay_event_on_msg_recv_arg

Websocket structure wrapper to receive a message.

    The original structure of websocket_on_msg_arg :
        struct wslay_event_on_msg_recv_arg {
            uint8_t rsv;                    //reserved bits: rsv = (RSV1 << 2) | (RSV2 << 1) | RSV3
            uint8_t opcode;                 //operation code
            const uint8_t *msg;             //received message
            size_t msg_length;              //message length
            uint16_t status_code;           //status code
        };

Definition at line 212 of file websocket.h.

#define WEBSOCKET_PING_INTERVAL (20 * 100)

Websocket ping message interval, MSEC_PER_TICK.

Definition at line 139 of file websocket.h.

#define WEBSOCKET_PRI 100

The priority of websocket.

Definition at line 80 of file websocket.h.

#define websocket_recv_chunk_arg struct wslay_event_on_frame_recv_chunk_arg

Websocket structure wrapper to receive a chunked frame.

    The original structure of websocket_recv_chunk_arg :
        struct wslay_event_on_frame_recv_chunk_arg {
            const uint8_t *data;            //chunk of payload data
            size_t data_length;             //size of data
        };

Definition at line 240 of file websocket.h.

#define websocket_recv_start_arg struct wslay_event_on_frame_recv_start_arg

Websocket structure wrapper to receive a raw frame.

    The original structure of websocket_recv_start_arg :
        struct wslay_event_on_frame_recv_start_arg {
            uint8_t fin;                    //fin bit. 1 is for final frame, or 0
            uint8_t rsv;                    //reserved bits: (RSV1 << 2) | (RSV2 << 1) | RSV3
            uint8_t opcode;                 //operation code
            uint64_t payload_length;        //payload length
        };

Definition at line 227 of file websocket.h.

#define WEBSOCKET_SCHED_POLICY SCHED_RR

The schedule policy of websocket..

Definition at line 84 of file websocket.h.

#define WEBSOCKET_SERVER_CHECK_INTERVAL (500)

Websocket accept server select() timeout value, msec.

Definition at line 121 of file websocket.h.

#define WEBSOCKET_SERVER_TIMEOUT (3 * 60 * 1000)

Websocket accept server select() timeout limit, msec.

Definition at line 125 of file websocket.h.

#define WEBSOCKET_SERVERNAME "localhost"

Set host name for servername TLS extension.

This definition will be used in TLS handshake routine for authentication.

Definition at line 111 of file websocket.h.

#define WEBSOCKET_SOCK_RCV_TIMEOUT (5 * 1000)

Websocket socket input timeout value, msec.

Definition at line 117 of file websocket.h.

#define WEBSOCKET_STACKSIZE (1024 * 10)

The maximum stack size of websocket.

Definition at line 76 of file websocket.h.

#define WEBSOCKET_WQ LPWORK

Websocket timer workqueue.

Definition at line 88 of file websocket.h.

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

Websocket GUID defined by RFC 6455.

Definition at line 71 of file websocket.h.

Enumeration Type Documentation

enum websocket_io_flag

websocket io flags

Enumerator
WEBSOCKET_MSG_MORE

Definition at line 319 of file websocket.h.

enum websocket_opcode

websocket operation code.

Operation codes are sent with a message

Enumerator
WEBSOCKET_CONTINUATION_FRAME	a fragmented frame
WEBSOCKET_TEXT_FRAME	a normal websocket frame
WEBSOCKET_BINARY_FRAME	a binary websocket frame
WEBSOCKET_CONNECTION_CLOSE	a control frame to close websocket
WEBSOCKET_PING	a control frame to ping
WEBSOCKET_PONG	a control frame to pong

Definition at line 345 of file websocket.h.

enum websocket_return_t

websocket return definitions

Enumerator
WEBSOCKET_SUCCESS	SUCCESS.
WEBSOCKET_ALLOCATION_ERROR	malloc fail
WEBSOCKET_INIT_ERROR	websocket context init fail
WEBSOCKET_SOCKET_ERROR	socket setting fail
WEBSOCKET_CONNECT_ERROR	socket connecting fail
WEBSOCKET_HANDSHAKE_ERROR	http handshake fail
WEBSOCKET_SEND_ERROR	message sending fail
WEBSOCKET_RECEIVE_ERROR	message reading fail
WEBSOCKET_TLS_INIT_ERROR	TLS context init fail.
WEBSOCKET_TLS_HANDSHAKE_ERROR	TLS handshake fail.

Definition at line 294 of file websocket.h.

enum websocket_socket_error

websocket socket error codes

this error codes are used in websocket_set_error function

Enumerator
WEBSOCKET_ERR_WANT_READ
WEBSOCKET_ERR_WANT_WRITE
WEBSOCKET_ERR_PROTO
WEBSOCKET_ERR_INVALID_ARGUMENT
WEBSOCKET_ERR_INVALID_CALLBACK
WEBSOCKET_ERR_NO_MORE_MSG
WEBSOCKET_ERR_CALLBACK_FAILURE
WEBSOCKET_ERR_WOULDBLOCK
WEBSOCKET_ERR_NOMEM

Definition at line 328 of file websocket.h.

enum websocket_state

websocket states

Enumerator
WEBSOCKET_STOP	stopped
WEBSOCKET_RUNNING	running
WEBSOCKET_MAX_STATE	websocket number of max state.

Definition at line 310 of file websocket.h.

Function Documentation

websocket_return_t websocket_client_open	(	websocket_t *	client,
		char *	addr,
		char *	port,
		char *	path
	)

websocket_client_open() initiates websocket client ready to send and receive websocket message.

This function offers steps to connect socket, enable TLS by option, http handshake and init websocket context.

Parameters

[in]	client	websocket structure manages file descriptor, websocket context and TLS context. users must give a pointer of websocket callback structure in websocket_t *client
[in]	addr	websocket server ip address.
[in]	port	websocket server port number. usually 80 is normal websocket, 443 is secured websocket.
[in]	path	uri path.

Returns: On success, return WEBSOCKET_SUCCESS. On failure, return values defined in websocket_return_t.

Since: Tizen RT v1.0

int websocket_count_table ( void )

websocket_count_table() returns amount of working websocket server.

Parameters

[in] none.

Returns: return amount of working websocket server

Since: Tizen RT v1.0

void websocket_create_accept_key	(	unsigned char *	dst,
		size_t	dlen,
		const unsigned char *	src,
		size_t	slen
	)

websocket_create_accept_key

This function makes encrypted key for websocket http handshake.

Parameters

[out]	dst	created accept key is stored to destination buffer.
[in]	dlen	destination buffer length.
[in]	src	source to create accept key.
[in]	slen	source buffer length.

Returns: none

Since: Tizen RT v1.0

websocket_t* websocket_find_table ( void )

websocket_find_table() returns websocket_t * to manage websocket server.

This function returns websocket_t * to manage websocket server.
The maximum number of client that websocket can handle is defined WEBSOCKET_MAX_CLIENT.

Parameters

[in] none.

Returns: On success, return websocket_t *. On failure, return NULL.

Since: Tizen RT v1.0

websocket_return_t websocket_queue_close	(	websocket_t *	websocket,
		const char *	close_message
	)

websocket_queue_close() closes the websocket.

This function doesn't guarantee the current packet transfer.
As it is control frame, it has more priority than non-control frames.
This means users need to manage the packet transfer status before calling this function.

Parameters

[in]	websocket	websocket structure manages websocket context.
[in]	close_message	close message to be sent.

Returns: On success, return WEBSOCKET_SUCCESS. On failure, return values defined in websocket_return_t.

Since: Tizen RT v1.0

websocket_return_t websocket_queue_msg	(	websocket_t *	websocket,
		websocket_frame_t *	tx_frame
	)

websocket_return_t websocket_queue_ping ( websocket_t * websocket )

websocket_queue_ping() is used to send a websocket ping message.

This function has following steps to send websocket frame.
It contains queueing a message, triggering the websocket send event and sending through socket file descriptor.

Parameters

[in] websocket websocket structure manages websocket context.

Returns: On success, return WEBSOCKET_SUCCESS. On failure, return values defined in websocket_return_t.

Since: Tizen RT v1.0

void websocket_register_cb	(	websocket_t *	websocket,
		websocket_cb_t *	cb
	)

websocket_register_cb() changes a websocket callback structure in a websocket context.

Websocket callbacks are basically registered when initiation, but users can change callbacks with this function.

Parameters

[in]	websocket	websocket structure to store callbacks.
[in]	cb	callbacks structure pointer to change

Returns: none

Since: Tizen RT v1.0

websocket_return_t websocket_server_init ( websocket_t * server )

websocket_server_init

This function start message handling loop.
It initiates websocket context structure and select() fd to handle the messages.

Parameters

[in] server websocket structure manages file descriptor, websocket context and TLS context. users must give a pointer of websocket callback structure in websocket_t *server

Returns: On success, return WEBSOCKET_SUCCESS. On failure, return values defined in websocket_return_t.

Since: Tizen RT v1.0

websocket_return_t websocket_server_open ( websocket_t * server )

websocket_server_open() initiates websocket server.

This function offers steps to accept client socket, enable TLS by option, http handshake and calls websocket_server_init() to start message handling loop.
websocket server uses callbacks that users defined to initiate websocket server.

Parameters

[in] server websocket strucutre manages file descriptor, websocket context and TLS context. users must give a pointer of websocket callback structure in websocket_t *server

Returns: On success, return WEBSOCKET_SUCCESS. On failure, return values defined in websocket_return_t.

Since: Tizen RT v1.0

void websocket_set_error	(	websocket_t *	websocket,
		int	val
	)

websocket_set_error() sets an error number to websocket context.

This function is used to notice serious error to websocket context.
After this function triggered, websocket context will be closed.

Parameters

[in]	websocket	websocket structure manages websocket context.
[in]	val	error value to be set.

Returns: none

Since: Tizen RT v1.0

void websocket_update_state	(	websocket_t *	websocket,
		int	state
	)

websocket_update_state() changes websocket state.

This function is used to control websocket state.
websocket state are defined at websocket_state.

Parameters

[in]	websocket	websocket structure.
[in]	state	websocket state.

Returns: none

Since: Tizen RT v1.0

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation