websocketpp::frame Namespace Reference

Data structures and utility functions for manipulating WebSocket frames. More...

Namespaces
namespace	limits
	Constants related to frame and payload limits.
namespace	opcode
	Constants and utility functions related to WebSocket opcodes.

Classes
struct	basic_header
	The constant size component of a WebSocket frame header. More...
struct	extended_header
	The variable size component of a WebSocket frame header. More...
union	uint16_converter
	Two byte conversion union. More...
union	uint32_converter
	Four byte conversion union. More...
union	uint64_converter
	Eight byte conversion union. More...

Typedefs
typedef uint32_converter	masking_key_type

Functions
bool	get_fin (basic_header const &h)
	Check whether the frame's FIN bit is set.
void	set_fin (basic_header &h, bool value)
	Set the frame's FIN bit.
bool	get_rsv1 (const basic_header &h)
	check whether the frame's RSV1 bit is set
void	set_rsv1 (basic_header &h, bool value)
	Set the frame's RSV1 bit.
bool	get_rsv2 (const basic_header &h)
	check whether the frame's RSV2 bit is set
void	set_rsv2 (basic_header &h, bool value)
	Set the frame's RSV2 bit.
bool	get_rsv3 (const basic_header &h)
	check whether the frame's RSV3 bit is set
void	set_rsv3 (basic_header &h, bool value)
	Set the frame's RSV3 bit.
opcode::value	get_opcode (const basic_header &h)
	Extract opcode from basic header.
bool	get_masked (basic_header const &h)
	check whether the frame is masked
void	set_masked (basic_header &h, bool value)
	Set the frame's MASK bit.
uint8_t	get_basic_size (const basic_header &h)
	Extracts the raw payload length specified in the basic header.
size_t	get_header_len (basic_header const &h)
	Calculates the full length of the header based on the first bytes.
unsigned int	get_masking_key_offset (const basic_header &h)
	Calculate the offset location of the masking key within the extended header.
std::string	write_header (basic_header const &, extended_header const &)
masking_key_type	get_masking_key (const basic_header &h, const extended_header &e)
	Extract the masking key from a frame header.
uint16_t	get_extended_size (const extended_header &e)
	Extract the extended size field from an extended header.
uint64_t	get_jumbo_size (const extended_header &e)
	Extract the jumbo size field from an extended header.
uint64_t	get_payload_size (const basic_header &h, const extended_header &e)
	Extract the full payload size field from a WebSocket header.
size_t	prepare_masking_key (const masking_key_type &key)
	Extract a masking key into a value the size of a machine word.
size_t	circshift_prepared_key (size_t prepared_key, size_t offset)
	circularly shifts the supplied prepared masking key by offset bytes
template<typename input_iter , typename output_iter >
void	byte_mask (input_iter first, input_iter last, output_iter result, masking_key_type const &key, size_t key_offset)
	Byte by byte mask/unmask.
template<typename iter_type >
void	byte_mask (iter_type b, iter_type e, masking_key_type const &key, size_t key_offset)
	Byte by byte mask/unmask (in place)
void	word_mask_exact (uint8_t *input, uint8_t *output, size_t length, const masking_key_type &key)
	Exact word aligned mask/unmask.
void	word_mask_exact (uint8_t *data, size_t length, const masking_key_type &key)
	Exact word aligned mask/unmask (in place)
size_t	word_mask_circ (uint8_t *input, uint8_t *output, size_t length, size_t prepared_key)
	Circular word aligned mask/unmask.
size_t	word_mask_circ (uint8_t *data, size_t length, size_t prepared_key)
	Circular word aligned mask/unmask (in place)
std::string	prepare_header (const basic_header &h, const extended_header &e)
	Generate a properly sized contiguous string that encodes a full frame header.
size_t	byte_mask_circ (uint8_t *input, uint8_t *output, size_t length, size_t prepared_key)
	Circular byte aligned mask/unmask.
size_t	byte_mask_circ (uint8_t *data, size_t length, size_t prepared_key)
	Circular byte aligned mask/unmask (in place)

Detailed Description

namespace frame provides a number of data structures and utility functions for reading, writing, and manipulating binary encoded WebSocket frames.

Typedef Documentation

masking_key_type

typedef uint32_converter websocketpp::frame::masking_key_type

Definition at line 186 of file frame.hpp.

Function Documentation

byte_mask() [1/2]

template<typename input_iter , typename output_iter >

void websocketpp::frame::byte_mask	(	input_iter	first,
		input_iter	last,
		output_iter	result,
		masking_key_type const &	key,
		size_t	key_offset )

Iterator based byte by byte masking and unmasking for WebSocket payloads. Performs masking in place using the supplied key offset by the supplied offset number of bytes.

This function is simple and can be done in place on input with arbitrary lengths and does not vary based on machine word size. It is slow.

Parameters

b	Beginning iterator to start masking
e	Ending iterator to end masking
o	Beginning iterator to store masked results
key	32 bit key to mask with.
key_offset	offset value to start masking at.

Definition at line 642 of file frame.hpp.

{
    size_t key_index = key_offset%4;
    while (first != last) {
        *result = *first ^ key.c[key_index++];
        key_index %= 4;
        ++result;
        ++first;
    }
}

Here is the caller graph for this function:

byte_mask() [2/2]

template<typename iter_type >

void websocketpp::frame::byte_mask	(	iter_type	b,
		iter_type	e,
		masking_key_type const &	key,
		size_t	key_offset )

Iterator based byte by byte masking and unmasking for WebSocket payloads. Performs masking in place using the supplied key offset by the supplied offset number of bytes.

This function is simple and can be done in place on input with arbitrary lengths and does not vary based on machine word size. It is slow.

Parameters

b	Beginning iterator to start masking
e	Ending iterator to end masking
key	32 bit key to mask with.
key_offset	offset value to start masking at.

Definition at line 672 of file frame.hpp.

{
    byte_mask(b,e,b,key,key_offset);
}

Here is the call graph for this function:

byte_mask_circ() [1/2]

size_t websocketpp::frame::byte_mask_circ ( uint8_t * data, size_t length, size_t prepared_key )

inline

In place version of byte_mask_circ

See also

byte_mask_circ

Parameters

data	Character buffer to read from and write to
length	Length of data
prepared_key	Prepared key to use.

Returns

the prepared_key shifted to account for the input length

Definition at line 854 of file frame.hpp.

                                                                               {
    return byte_mask_circ(data,data,length,prepared_key);
}

Here is the call graph for this function:

byte_mask_circ() [2/2]

size_t websocketpp::frame::byte_mask_circ ( uint8_t * input, uint8_t * output, size_t length, size_t prepared_key )

inline

Performs a circular mask/unmask in byte sized chunks using pre-prepared keys that store state between calls. Best for providing streaming masking or unmasking of small chunks at a time of a larger message. Requires that the underlying allocated size of the data buffer be a multiple of the word size. Data in the buffer after length will be overwritten only with the same values that were originally present.

word_mask returns a copy of prepared_key circularly shifted based on the length value. The returned value may be fed back into byte_mask when more data is available.

Parameters

data	Character buffer to mask
length	Length of data
prepared_key	Prepared key to use.

Returns

the prepared_key shifted to account for the input length

Definition at line 827 of file frame.hpp.

{
    uint32_converter key;
    key.i = prepared_key;
 
    for (size_t i = 0; i < length; ++i) {
        output[i] = input[i] ^ key.c[i % 4];
    }
 
    return circshift_prepared_key(prepared_key,length % 4);
}

Here is the call graph for this function:

Here is the caller graph for this function:

circshift_prepared_key()

size_t websocketpp::frame::circshift_prepared_key ( size_t prepared_key, size_t offset )

inline

Prepared_key must be the output of prepare_masking_key with the associated restrictions on the machine word size. offset must be greater than or equal to zero and less than sizeof(size_t).

Definition at line 612 of file frame.hpp.

                                                                         {
    if (lib::net::is_little_endian()) {
        size_t temp = prepared_key << (sizeof(size_t)-offset)*8;
        return (prepared_key >> offset*8) | temp;
    } else {
        size_t temp = prepared_key >> (sizeof(size_t)-offset)*8;
        return (prepared_key << offset*8) | temp;
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

get_basic_size()

uint8_t websocketpp::frame::get_basic_size ( const basic_header & h )

inline

A basic WebSocket frame header contains a 7 bit value that represents the payload size. There are two reserved values that are used to indicate that the actual payload size will not fit in 7 bits and that the full payload size is included in a separate field. The values are as follows:

PAYLOAD_SIZE_CODE_16BIT (0x7E) indicates that the actual payload is less than 16 bit

PAYLOAD_SIZE_CODE_64BIT (0x7F) indicates that the actual payload is less than 63 bit

Parameters

[in]

h

Basic header to read value from.

Returns

The exact size encoded in h.

Definition at line 431 of file frame.hpp.

                                                     {
    return h.b1 & BHB1_PAYLOAD;
}

Here is the caller graph for this function:

get_extended_size()

uint16_t websocketpp::frame::get_extended_size ( const extended_header & e )

inline

It is the responsibility of the caller to verify that e is a valid extended header. This function assumes that e contains an extended payload size.

Parameters

e	The extended header to extract from

Returns

The size encoded in the extended header in host byte order

Definition at line 540 of file frame.hpp.

                                                            {
    uint16_converter temp16;
    std::copy(e.bytes,e.bytes+2,temp16.c);
    return ntohs(temp16.i);
}

Here is the caller graph for this function:

get_fin()

bool websocketpp::frame::get_fin ( basic_header const & h )

inline

Parameters

[in]

h

The basic header to extract from.

Returns

True if the header's fin bit is set.

Definition at line 321 of file frame.hpp.

                                            {
    return ((h.b0 & BHB0_FIN) == BHB0_FIN);
}

Here is the caller graph for this function:

get_header_len()

size_t websocketpp::frame::get_header_len ( basic_header const & h )

inline

A WebSocket frame header always has at least two bytes. Encoded within the first two bytes is all the information necessary to calculate the full (variable) header length. get_header_len() calculates the full header length for the given two byte basic header.

Parameters

h	Basic frame header to extract size from.

Returns

Full length of the extended header.

Definition at line 445 of file frame.hpp.

                                                     {
    // TODO: check extensions?
 
    // masking key offset represents the space used for the extended length
    // fields
    size_t size = BASIC_HEADER_LENGTH + get_masking_key_offset(h);
 
    // If the header is masked there is a 4 byte masking key
    if (get_masked(h)) {
        size += 4;
    }
 
    return size;
}

Here is the call graph for this function:

Here is the caller graph for this function:

get_jumbo_size()

uint64_t websocketpp::frame::get_jumbo_size ( const extended_header & e )

inline

It is the responsibility of the caller to verify that e is a valid extended header. This function assumes that e contains a jumbo payload size.

Parameters

e	The extended header to extract from

Returns

The size encoded in the extended header in host byte order

Definition at line 555 of file frame.hpp.

                                                         {
    uint64_converter temp64;
    std::copy(e.bytes,e.bytes+8,temp64.c);
    return lib::net::_ntohll(temp64.i);
}

Here is the call graph for this function:

Here is the caller graph for this function:

get_masked()

bool websocketpp::frame::get_masked ( basic_header const & h )

inline

Parameters

[in]

h

The basic header to extract from.

Returns

True if the header mask bit is set.

Definition at line 402 of file frame.hpp.

                                               {
    return ((h.b1 & BHB1_MASK) == BHB1_MASK);
}

Here is the caller graph for this function:

get_masking_key()

masking_key_type websocketpp::frame::get_masking_key ( const basic_header & h, const extended_header & e )

inline

Note that while read and written as an integer at times, this value is not an integer and should never be interpreted as one. Big and little endian machines will generate and store masking keys differently without issue as long as the integer values remain irrelivant.

Parameters

h	The basic header to extract from
e	The extended header to extract from

Returns

The masking key as an integer.

Definition at line 516 of file frame.hpp.

{
    masking_key_type temp32;
 
    if (!get_masked(h)) {
        temp32.i = 0;
    } else {
        unsigned int offset = get_masking_key_offset(h);
        std::copy(e.bytes+offset,e.bytes+offset+4,temp32.c);
    }
 
    return temp32;
}

Here is the call graph for this function:

Here is the caller graph for this function:

get_masking_key_offset()

unsigned int websocketpp::frame::get_masking_key_offset ( const basic_header & h )

inline

Calculate the offset location of the masking key within the extended header using information from its corresponding basic header

Parameters

h	Corresponding basic header to calculate from.

Returns

byte offset of the first byte of the masking key

Definition at line 469 of file frame.hpp.

                                                                  {
    if (get_basic_size(h) == payload_size_code_16bit) {
        return 2;
    } else if (get_basic_size(h) == payload_size_code_64bit) {
        return 8;
    } else {
        return 0;
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

get_opcode()

opcode::value websocketpp::frame::get_opcode ( const basic_header & h )

inline

Parameters

[in]

h

The basic header to extract from.

Returns

The opcode value of the header.

Definition at line 393 of file frame.hpp.

                                                     {
    return opcode::value(h.b0 & BHB0_OPCODE);
}

Here is the caller graph for this function:

get_payload_size()

uint64_t websocketpp::frame::get_payload_size ( const basic_header & h, const extended_header & e )

inline

It is the responsibility of the caller to verify that h and e together represent a valid WebSocket frame header. This function assumes only that h and e are valid. It uses information in the basic header to determine where to look for the payload_size

Parameters

h	The basic header to extract from
e	The extended header to extract from

Returns

The size encoded in the combined header in host byte order.

Definition at line 573 of file frame.hpp.

{
    uint8_t val = get_basic_size(h);
 
    if (val <= limits::payload_size_basic) {
        return val;
    } else if (val == payload_size_code_16bit) {
        return get_extended_size(e);
    } else {
        return get_jumbo_size(e);
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

get_rsv1()

bool websocketpp::frame::get_rsv1 ( const basic_header & h )

inline

Parameters

[in]

h

The basic header to extract from.

Returns

True if the header's RSV1 bit is set.

Definition at line 339 of file frame.hpp.

                                            {
    return ((h.b0 & BHB0_RSV1) == BHB0_RSV1);
}

Here is the caller graph for this function:

get_rsv2()

bool websocketpp::frame::get_rsv2 ( const basic_header & h )

inline

Parameters

[in]

h

The basic header to extract from.

Returns

True if the header's RSV2 bit is set.

Definition at line 357 of file frame.hpp.

                                            {
    return ((h.b0 & BHB0_RSV2) == BHB0_RSV2);
}

Here is the caller graph for this function:

get_rsv3()

bool websocketpp::frame::get_rsv3 ( const basic_header & h )

inline

Parameters

[in]

h

The basic header to extract from.

Returns

True if the header's RSV3 bit is set.

Definition at line 375 of file frame.hpp.

                                            {
    return ((h.b0 & BHB0_RSV3) == BHB0_RSV3);
}

Here is the caller graph for this function:

prepare_header()

std::string websocketpp::frame::prepare_header ( const basic_header & h, const extended_header & e )

inline

Copy the basic header h and extended header e into a properly sized contiguous frame header string for the purposes of writing out to the wire.

Parameters

h	The basic header to include
e	The extended header to include

Returns

A contiguous string containing h and e

Definition at line 489 of file frame.hpp.

{
    std::string ret;
 
    ret.push_back(char(h.b0));
    ret.push_back(char(h.b1));
    ret.append(
        reinterpret_cast<const char*>(e.bytes),
        get_header_len(h)-BASIC_HEADER_LENGTH
    );
 
    return ret;
}

Here is the call graph for this function:

Here is the caller graph for this function:

prepare_masking_key()

size_t websocketpp::frame::prepare_masking_key ( const masking_key_type & key )

inline

Machine word size must be 4 or 8.

Parameters

key	Masking key to extract from

Returns

prepared key as a machine word

Definition at line 595 of file frame.hpp.

                                                               {
    size_t low_bits = static_cast<size_t>(key.i);
 
    if (sizeof(size_t) == 8) {
        uint64_t high_bits = static_cast<size_t>(key.i);
        return static_cast<size_t>((high_bits << 32) | low_bits);
    } else {
        return low_bits;
    }
}

Here is the caller graph for this function:

set_fin()

void websocketpp::frame::set_fin ( basic_header & h, bool value )

inline

Parameters

[out]	h	Header to set.
[in]	value	Value to set it to.

Definition at line 330 of file frame.hpp.

                                                  {
    h.b0 = (value ? h.b0 | BHB0_FIN : h.b0 & ~BHB0_FIN);
}

Here is the caller graph for this function:

set_masked()

void websocketpp::frame::set_masked ( basic_header & h, bool value )

inline

Parameters

[out]	h	Header to set.
	value	Value to set it to.

Definition at line 411 of file frame.hpp.

                                                     {
    h.b1 = (value ? h.b1 | BHB1_MASK : h.b1 & ~BHB1_MASK);
}

Here is the caller graph for this function:

set_rsv1()

void websocketpp::frame::set_rsv1 ( basic_header & h, bool value )

inline

Parameters

[out]	h	Header to set.
[in]	value	Value to set it to.

Definition at line 348 of file frame.hpp.

                                                  {
    h.b0 = (value ? h.b0 | BHB0_RSV1 : h.b0 & ~BHB0_RSV1);
}

Here is the caller graph for this function:

set_rsv2()

void websocketpp::frame::set_rsv2 ( basic_header & h, bool value )

inline

Parameters

[out]	h	Header to set.
[in]	value	Value to set it to.

Definition at line 366 of file frame.hpp.

                                                  {
    h.b0 = (value ? h.b0 | BHB0_RSV2 : h.b0 & ~BHB0_RSV2);
}

Here is the caller graph for this function:

set_rsv3()

void websocketpp::frame::set_rsv3 ( basic_header & h, bool value )

inline

Parameters

[out]	h	Header to set.
[in]	value	Value to set it to.

Definition at line 384 of file frame.hpp.

                                                  {
    h.b0 = (value ? h.b0 | BHB0_RSV3 : h.b0 & ~BHB0_RSV3);
}

Here is the caller graph for this function:

word_mask_circ() [1/2]

size_t websocketpp::frame::word_mask_circ ( uint8_t * data, size_t length, size_t prepared_key )

inline

In place version of word_mask_circ

See also

word_mask_circ

Parameters

data	Character buffer to read from and write to
length	Length of data
prepared_key	Prepared key to use.

Returns

the prepared_key shifted to account for the input length

Definition at line 802 of file frame.hpp.

                                                                               {
    return word_mask_circ(data,data,length,prepared_key);
}

Here is the call graph for this function:

word_mask_circ() [2/2]

size_t websocketpp::frame::word_mask_circ ( uint8_t * input, uint8_t * output, size_t length, size_t prepared_key )

inline

Performs a circular mask/unmask in word sized chunks using pre-prepared keys that store state between calls. Best for providing streaming masking or unmasking of small chunks at a time of a larger message. Requires that the underlying allocated size of the data buffer be a multiple of the word size. Data in the buffer after length will be overwritten only with the same values that were originally present.

Buffer based word by word masking and unmasking for WebSocket payloads. Performs masking in place using the supplied key. Casts the data buffer to an array of size_t's and performs masking word by word. The underlying buffer size must be a muliple of the word size.

word_mask returns a copy of prepared_key circularly shifted based on the length value. The returned value may be fed back into word_mask when more data is available.

input and output must both have length at least: ceil(length/sizeof(size_t))*sizeof(size_t) Exactly that many bytes will be written, although only exactly length bytes will be changed (trailing bytes will be replaced without masking)

Parameters

data	Character buffer to mask
length	Length of data
prepared_key	Prepared key to use.

Returns

the prepared_key shifted to account for the input length

Definition at line 765 of file frame.hpp.

{
    size_t n = length / sizeof(size_t); // whole words
    size_t l = length - (n * sizeof(size_t)); // remaining bytes
    size_t * input_word = reinterpret_cast<size_t *>(input);
    size_t * output_word = reinterpret_cast<size_t *>(output);
 
    // mask word by word
    for (size_t i = 0; i < n; i++) {
        output_word[i] = input_word[i] ^ prepared_key;
    }
 
    // mask partial word at the end
    size_t start = length - l;
    uint8_t * byte_key = reinterpret_cast<uint8_t *>(&prepared_key);
    for (size_t i = 0; i < l; ++i) {
        output[start+i] = input[start+i] ^ byte_key[i];
    }
 
    return circshift_prepared_key(prepared_key,l);
}

Here is the call graph for this function:

Here is the caller graph for this function:

word_mask_exact() [1/2]

void websocketpp::frame::word_mask_exact ( uint8_t * data, size_t length, const masking_key_type & key )

inline

In place version of word_mask_exact

See also

word_mask_exact

Parameters

data	buffer to read and write from
length	length of data buffer
key	Masking key to use

Definition at line 728 of file frame.hpp.

{
    word_mask_exact(data,data,length,key);
}

Here is the call graph for this function:

word_mask_exact() [2/2]

void websocketpp::frame::word_mask_exact ( uint8_t * input, uint8_t * output, size_t length, const masking_key_type & key )

inline

Balanced combination of byte by byte and circular word by word masking. Best used to mask complete messages at once. Has much higher setup costs than word_mask_circ but works with exact sized buffers.

Buffer based word by word masking and unmasking for WebSocket payloads. Masking is done in word by word chunks with the remainder not divisible by the word size done byte by byte.

input and output must both be at least length bytes. Exactly length bytes will be written.

Parameters

input	buffer to mask or unmask
output	buffer to store the output. May be the same as input.
length	length of data buffer
key	Masking key to use

Definition at line 699 of file frame.hpp.

{
    size_t prepared_key = prepare_masking_key(key);
    size_t n = length/sizeof(size_t);
    size_t* input_word = reinterpret_cast<size_t*>(input);
    size_t* output_word = reinterpret_cast<size_t*>(output);
 
    for (size_t i = 0; i < n; i++) {
        output_word[i] = input_word[i] ^ prepared_key;
    }
 
    for (size_t i = n*sizeof(size_t); i < length; i++) {
        output[i] = input[i] ^ key.c[i%4];
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

write_header()

std::string websocketpp::frame::write_header	(	basic_header const &	,
		extended_header const &	)