code/owire.h File Reference

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

#include "types.h"

Go to the source code of this file.

Classes
struct	ws_owire
	Incremental writer for WebSocket wire protocol (out-bound). More...
Enumerations
enum	ws_owire_error { ws_owire_eok, ws_owire_enotready }
	Writer error codes. More...
Functions
void	ws_owire_init (struct ws_owire *stream)
	Initialize a writer.
void	ws_owire_new_message (struct ws_owire *stream)
	Start a new message.
void	ws_owire_end_message (struct ws_owire *stream)
	End a message, clearing the state for the next message.
void	ws_owire_new_frame (struct ws_owire *stream, uint64 size)
	Start a frame with a size byte payload.
void	ws_owire_end_frame (struct ws_owire *stream)
	End a frame, clearing the state for the next frame.
void	ws_owire_last (struct ws_owire *stream)
	Mark the current frame as the last fragment in a message.
void	ws_owire_eval (struct ws_owire *stream, uint8 eval)
	Set the WebSocket extension code.
void	ws_owire_code (struct ws_owire *stream, uint8 code)
	Set the WebSocket message opcode.
void	ws_owire_mask (struct ws_owire *stream)
	Mark the fragment as masked.
uint64	ws_owire_feed (struct ws_owire *stream, const void *data, uint64 size)
	Add data to the application payload.
void	ws_owire_ping (struct ws_owire *stream)
	Mark the current frame as a ping message.
void	ws_owire_pong (struct ws_owire *stream)
	Mark the current frame as a pong message.
void	ws_owire_text (struct ws_owire *stream)
	Mark the current frame as a text message.
void	ws_owire_data (struct ws_owire *stream)
	Mark the current frame as a binary data message.
void	ws_owire_kill (struct ws_owire *stream)
	Mark the current frame as an end-of-stream control message.
void	ws_owire_put_text (struct ws_owire *stream, const void *data, uint64 size)
	Send a full text message in a single call.
void	ws_owire_put_data (struct ws_owire *stream, const void *data, uint64 size)
	Send a full binary data message in a single call.
void	ws_owire_put_ping (struct ws_owire *stream, const void *data, uint64 size)
	Send a full ping message in a single call.
void	ws_owire_put_pong (struct ws_owire *stream, const void *data, uint64 size)
	Send a full pong message in a single call.
void	ws_owire_put_kill (struct ws_owire *stream, const void *data, uint64 size)
	Send a full end-of-stream message in a single call.

---

Detailed Description

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

See also:

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

Definition in file owire.h.

---

Enumeration Type Documentation

enum ws_owire_error

Writer error codes.

Enumerator:

ws_owire_eok	No error, the parser is in good state.
ws_owire_enotready	Attempted to send a frame's payload before the header was ready.

Definition at line 63 of file owire.h.

---

Function Documentation

void ws_owire_code	(	struct ws_owire *	stream,
		uint8	code
	)

Set the WebSocket message opcode.

Parameters:

stream	The curernt writer state.
code	The message opcode.

This method should not be used unless the WebSocket protocol specification is updated add new control message codes before the library is updated to implement the extended specification. Use the explicit named functions for application clarity.

See also:

ws_owire_text()

ws_owire_data()

ws_owire_ping()

ws_owire_pong()

Definition at line 336 of file owire.c.

void ws_owire_data

(

struct ws_owire *

stream

)

Mark the current frame as a binary data message.

Parameters:

stream

The current writer state.

See also:

ws_owire_code()

ws_owire_feed()

void ws_owire_end_frame

(

struct ws_owire *

stream

)

End a frame, clearing the state for the next frame.

Parameters:

stream

Current writer state.

See also:

ws_owire_new_frame()

ws_owire_end_message()

Definition at line 316 of file owire.c.

void ws_owire_end_message

(

struct ws_owire *

stream

)

End a message, clearing the state for the next message.

Parameters:

stream

Current writer state.

See also:

ws_owire_new_message()

Definition at line 277 of file owire.c.

void ws_owire_eval	(	struct ws_owire *	stream,
		uint8	eval
	)

Set the WebSocket extension code.

Parameters:

stream	The current writer state.
eval	Extension value, must be in [0,8).

Definition at line 329 of file owire.c.

uint64 ws_owire_feed	(	struct ws_owire *	stream,
		const void *	data,
		uint64	size
	)

Add data to the application payload.

Parameters:

stream	The current writer state.
data	Array of bytes to write. Accessing past size bytes in this array results in undefined behavior.
size	Number of bytes in data to forward.

You may invoke this function multiple times to reach the total fragment payload size given to ws_owire_new_frame().

See also:

ws_owire_new_frame()

ws_owire_end_frame()

Definition at line 350 of file owire.c.

void ws_owire_init

(

struct ws_owire *

stream

)

Initialize a writer.

Parameters:

stream

Uninitialized writer object.

Invoking this function clears all state, including application callbacks.

Definition at line 258 of file owire.c.

void ws_owire_kill

(

struct ws_owire *

stream

)

Mark the current frame as an end-of-stream control message.

Parameters:

stream

The current frame state.

Control messages cannot be fragmented. Always mark end-of-stream messages with ws_owire_last().

See also:

ws_owire_code()

ws_owire_last()

ws_owire_feed()

void ws_owire_last

(

struct ws_owire *

stream

)

Mark the current frame as the last fragment in a message.

Parameters:

stream

The current writer state.

When sending non-fragmented messages, this should always mark the only fragment sent as part of the message.

Definition at line 323 of file owire.c.

void ws_owire_mask

(

struct ws_owire *

stream

)

Mark the fragment as masked.

Parameters:

stream

The current writer state.

This will indirectly invoke the ws_owire::rand callback to generate a random mask.

See also:

ws_owire::prng

ws_owire::rand

Definition at line 343 of file owire.c.

void ws_owire_new_frame	(	struct ws_owire *	stream,
		uint64	size
	)

Start a frame with a size byte payload.

Parameters:

stream	Current writer state.
size	Size of the frame payload, in bytes.

See also:

ws_owire_last()

ws_owire_eval()

ws_owire_code()

ws_owire_mask()

ws_owire_feed()

Definition at line 284 of file owire.c.

void ws_owire_new_message

(

struct ws_owire *

stream

)

Start a new message.

Parameters:

stream

Current writer state.

See also:

ws_owire_new_frame()

Definition at line 270 of file owire.c.

void ws_owire_ping

(

struct ws_owire *

stream

)

Mark the current frame as a ping message.

Parameters:

stream

The current frame state.

Control messages cannot be fragmented. Always mark ping messages with ws_owire_last().

See also:

ws_owire_code()

ws_owire_last()

ws_owire_feed()

void ws_owire_pong

(

struct ws_owire *

stream

)

Mark the current frame as a pong message.

Parameters:

stream

The current frame state.

Control messages cannot be fragmented. Always mark pong messages with ws_owire_last().

See also:

ws_owire_code()

ws_owire_last()

ws_owire_feed()

void ws_owire_put_data	(	struct ws_owire *	stream,
		const void *	data,
		uint64	size
	)

Send a full binary data message in a single call.

Parameters:

stream	The current writer state.
data	Payload data.
size	Payload size, in bytes.

See also:

ws_owire::auto_fragment

Definition at line 362 of file owire.c.

void ws_owire_put_kill	(	struct ws_owire *	stream,
		const void *	data,
		uint64	size
	)

Send a full end-of-stream message in a single call.

Parameters:

stream	The current writer state.
data	Payload data.
size	Payload size, in bytes.

The payload must be UTF-8 encoded text.

Note:

Control messages are never fragmented, regardless of the ws_owire::auto_fragment setting.

Bug:

The end-of-stream message must set a 2-byte status code before it writes the fragment's payload.

Definition at line 368 of file owire.c.

void ws_owire_put_ping	(	struct ws_owire *	stream,
		const void *	data,
		uint64	size
	)

Send a full ping message in a single call.

Parameters:

stream	The current writer state.
data	Payload data.
size	Payload size, in bytes.

Note:

Control messages are never fragmented, regardless of the ws_owire::auto_fragment setting.

Definition at line 374 of file owire.c.

void ws_owire_put_pong	(	struct ws_owire *	stream,
		const void *	data,
		uint64	size
	)

Send a full pong message in a single call.

Parameters:

stream	The current writer state.
data	Payload data.
size	Payload size, in bytes.

Note:

Control messages are never fragmented, regardless of the ws_owire::auto_fragment setting.

Definition at line 380 of file owire.c.

void ws_owire_put_text	(	struct ws_owire *	stream,
		const void *	data,
		uint64	size
	)

Send a full text message in a single call.

Parameters:

stream	The current writer state.
data	Payload data.
size	Payload size, in bytes.

See also:

ws_owire::auto_fragment

Definition at line 356 of file owire.c.

void ws_owire_text

(

struct ws_owire *

stream

)

Mark the current frame as a text message.

Parameters:

stream

The current writer state.

Warning:

Remember that text messages' payload must be UTF-8 encoded data. This library implements no automatic encoding or decoding of text and it is the application's responsibility to ensure that the payload contains valid UTF-8 data. If the peer strictly enforces the WebSocket specification, it may kill the connection upon receiving invalid UTF-8 data.

See also:

ws_owire_code()

ws_owire_feed()