code/iwire.h File Reference

Web Socket wire protocol (in-bound) for C. More...

#include "types.h"

Go to the source code of this file.

Classes
struct	ws_iwire
	Incremental parser for WebSocket wire protocol (in-bound). More...
Functions
void	ws_iwire_init (struct ws_iwire *stream)
	Initialize a parser.
uint64	ws_iwire_feed (struct ws_iwire *stream, const void *data, uint64 size)
	Consume available data and trigger appropriate application callbacks.
int	ws_iwire_mask (const struct ws_iwire *stream)
	Check if the current frame is masked.
int	ws_iwire_last (const struct ws_iwire *stream)
	Check if the current frame is the message's last fragment.
int	ws_iwire_ping (const struct ws_iwire *stream)
	Check if the current frame is a ping message.
int	ws_iwire_pong (const struct ws_iwire *stream)
	Check if the current frame is a pong message.
int	ws_iwire_text (const struct ws_iwire *stream)
	Check if the current fragment is a UTF-8 text message.
int	ws_iwire_data (const struct ws_iwire *stream)
	Check if the current fragment is a binary message.
int	ws_iwire_dead (const struct ws_iwire *stream)
	Check if the current fragment is a close frame.

---

Detailed Description

Web Socket wire protocol (in-bound) for C.

See also:

http://tools.ietf.org/html/rfc6455

Definition in file iwire.h.

---

Function Documentation

int ws_iwire_data

(

const struct ws_iwire *

stream

)

Check if the current fragment is a binary message.

Parameters:

stream

The current parser state.

Returns:

1 if the fragment contains a binary payload, else 0.

Warning:

This cannot be used inside the ws_iwire::new_message callback because that callback is triggered before the message frame is parsed.

See also:

ws_iwire::new_fragment

ws_iwire::accept_content

Definition at line 446 of file iwire.c.

int ws_iwire_dead

(

const struct ws_iwire *

stream

)

Check if the current fragment is a close frame.

Parameters:

stream

The current parser state.

Returns:

1 if the fragment is the last message, else 0.

Closing frames may supply a 16-bit unsigned integer and a UTF-8 payload to describe the reason for closing the connection. Interpretation of the status code and error text are up to the application. The WebSocket specification does not require the UTF-8 error text to be human readable.

Warning:

This cannot be used inside the ws_iwire::new_message callback because that callback is triggered before the message frame is parsed.

See also:

ws_iwire::new_fragment

ws_iwire::accept_content

ws_iwire::end_message

Definition at line 451 of file iwire.c.

uint64 ws_iwire_feed	(	struct ws_iwire *	stream,
		const void *	data,
		uint64	size
	)

Consume available data and trigger appropriate application callbacks.

Parameters:

stream	The current parser state.
data	Array of bytes available to the parser. Accessing past size bytes in this array results in undefined behavior.
size	Number of bytes in data the state can process.

Returns:

The number of bytes consumed by the state. This is normally always equal to size. If they are different, an error most likely occured in parsing. However, the returned value being equal to size does not guarantee the absence of an error.

This function always consumes as much data as it can. Therefore, a single invocation of this function may happend to parse many messages if lots of data has accumulated in the application's buffers. It is recommended that the application call this method often to ensure prompt responses and low latency.

Definition at line 416 of file iwire.c.

void ws_iwire_init

(

struct ws_iwire *

stream

)

Initialize a parser.

Parameters:

stream

Uninitialized parser object.

Invoking this function clears all state, including application callbacks.

Definition at line 401 of file iwire.c.

int ws_iwire_last

(

const struct ws_iwire *

stream

)

Check if the current frame is the message's last fragment.

Parameters:

stream

The current parser state.

Returns:

1 if the fragment ends a message, else 0.

Warning:

This cannot be used inside the ws_iwire::new_message callback because that callback is triggered before the message frame is parsed.

See also:

ws_iwire::new_fragment

Definition at line 426 of file iwire.c.

int ws_iwire_mask

(

const struct ws_iwire *

stream

)

Check if the current frame is masked.

Parameters:

stream

The current parser state.

Returns:

1 if the fragment is masked, else 0.

Warning:

This cannot be used inside the ws_iwire::new_message callback because that callback is triggered before the message frame is parsed.

See also:

ws_iwire::new_fragment

ws_iwire::reqm

Definition at line 421 of file iwire.c.

int ws_iwire_ping

(

const struct ws_iwire *

stream

)

Check if the current frame is a ping message.

Parameters:

stream

The current parser state.

Returns:

1 if the fragment consists of a ping message, else 0.

The application should respond with a pong message containing identical data. Ping pong messages help reset timeouts, ensuring the connection is not killed until either peer decides to close it.

Note:

Ping and pong messages implement "heartbeats". This helps reset timeouts, ensuring the connection is not killed until either peer decides to close it.

Warning:

This cannot be used inside the ws_iwire::new_message callback because that callback is triggered before the message frame is parsed.

See also:

ws_iwire::new_fragment

ws_iwire::accept_content

Definition at line 431 of file iwire.c.

int ws_iwire_pong

(

const struct ws_iwire *

stream

)

Check if the current frame is a pong message.

Parameters:

stream

The current parser state.

Returns:

1 if the fragment consists of a pong message, else 0.

The application should validate that the pong message contains data identical to that sent in a ping message. Note that the WebSocket specification allows unsolicited pong messages for implementation of unidirectional heartbeats. This may be useful if the application wants to test the socket for writability, which is the only reliable way to determine if a TCP connection has been broken).

Note:

Ping and pong messages implement "heartbeats". This helps reset timeouts, ensuring the connection is not killed until either peer decides to close it.

Warning:

This cannot be used inside the ws_iwire::new_message callback because that callback is triggered before the message frame is parsed.

See also:

ws_iwire::new_fragment

ws_iwire::accept_content

Definition at line 436 of file iwire.c.

int ws_iwire_text

(

const struct ws_iwire *

stream

)

Check if the current fragment is a UTF-8 text message.

Parameters:

stream

The current parser state.

Returns:

1 if the fragment contains a UTF-8 payload, else 0.

Warning:

This cannot be used inside the ws_iwire::new_message callback because that callback is triggered before the message frame is parsed.

See also:

ws_iwire::new_fragment

ws_iwire::accept_content

Definition at line 441 of file iwire.c.