Data structures and utility functions for manipulating WebSocket frames. More...
Namespaces | |
limits | |
Constants related to frame and payload limits. | |
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. More... | |
void | set_fin (basic_header &h, bool value) |
Set the frame's FIN bit. More... | |
bool | get_rsv1 (const basic_header &h) |
check whether the frame's RSV1 bit is set More... | |
void | set_rsv1 (basic_header &h, bool value) |
Set the frame's RSV1 bit. More... | |
bool | get_rsv2 (const basic_header &h) |
check whether the frame's RSV2 bit is set More... | |
void | set_rsv2 (basic_header &h, bool value) |
Set the frame's RSV2 bit. More... | |
bool | get_rsv3 (const basic_header &h) |
check whether the frame's RSV3 bit is set More... | |
void | set_rsv3 (basic_header &h, bool value) |
Set the frame's RSV3 bit. More... | |
opcode::value | get_opcode (const basic_header &h) |
Extract opcode from basic header. More... | |
bool | get_masked (basic_header const &h) |
check whether the frame is masked More... | |
void | set_masked (basic_header &h, bool value) |
Set the frame's MASK bit. More... | |
uint8_t | get_basic_size (const basic_header &h) |
Extracts the raw payload length specified in the basic header. More... | |
size_t | get_header_len (basic_header const &h) |
Calculates the full length of the header based on the first bytes. More... | |
unsigned int | get_masking_key_offset (const basic_header &h) |
Calculate the offset location of the masking key within the extended header. More... | |
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. More... | |
uint16_t | get_extended_size (const extended_header &e) |
Extract the extended size field from an extended header. More... | |
uint64_t | get_jumbo_size (const extended_header &e) |
Extract the jumbo size field from an extended header. More... | |
uint64_t | get_payload_size (const basic_header &h, const extended_header &e) |
Extract the full payload size field from a WebSocket header. More... | |
size_t | prepare_masking_key (const masking_key_type &key) |
Extract a masking key into a value the size of a machine word. More... | |
size_t | circshift_prepared_key (size_t prepared_key, size_t offset) |
circularly shifts the supplied prepared masking key by offset bytes More... | |
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. More... | |
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) More... | |
void | word_mask_exact (uint8_t *input, uint8_t *output, size_t length, const masking_key_type &key) |
Exact word aligned mask/unmask. More... | |
void | word_mask_exact (uint8_t *data, size_t length, const masking_key_type &key) |
Exact word aligned mask/unmask (in place) More... | |
size_t | word_mask_circ (uint8_t *input, uint8_t *output, size_t length, size_t prepared_key) |
Circular word aligned mask/unmask. More... | |
size_t | word_mask_circ (uint8_t *data, size_t length, size_t prepared_key) |
Circular word aligned mask/unmask (in place) More... | |
std::string | prepare_header (const basic_header &h, const extended_header &e) |
Generate a properly sized contiguous string that encodes a full frame header. More... | |
size_t | byte_mask_circ (uint8_t *input, uint8_t *output, size_t length, size_t prepared_key) |
Circular byte aligned mask/unmask. More... | |
size_t | byte_mask_circ (uint8_t *data, size_t length, size_t prepared_key) |
Circular byte aligned mask/unmask (in place) More... | |
Variables | |
static unsigned int const | BASIC_HEADER_LENGTH = 2 |
Minimum length of a WebSocket frame header. More... | |
static unsigned int const | MAX_HEADER_LENGTH = 14 |
Maximum length of a WebSocket header. More... | |
static unsigned int const | MAX_EXTENDED_HEADER_LENGTH = 12 |
Maximum length of the variable portion of the WebSocket header. More... | |
static uint8_t const | BHB0_OPCODE = 0x0F |
static uint8_t const | BHB0_RSV3 = 0x10 |
static uint8_t const | BHB0_RSV2 = 0x20 |
static uint8_t const | BHB0_RSV1 = 0x40 |
static uint8_t const | BHB0_FIN = 0x80 |
static uint8_t const | BHB1_PAYLOAD = 0x7F |
static uint8_t const | BHB1_MASK = 0x80 |
static uint8_t const | payload_size_code_16bit = 0x7E |
static uint8_t const | payload_size_code_64bit = 0x7F |
Data structures and utility functions for manipulating WebSocket frames.
namespace frame provides a number of data structures and utility functions for reading, writing, and manipulating binary encoded WebSocket frames.
|
inline |
Check whether the frame's FIN bit is set.
[in] | h | The basic header to extract from. |
Definition at line 321 of file frame.hpp.
References websocketpp::frame::basic_header::b0.
Referenced by BOOST_AUTO_TEST_CASE(), websocketpp::processor::hybi13< stub_config >::consume(), and websocketpp::processor::hybi13< stub_config >::validate_incoming_basic_header().
|
inline |
Set the frame's FIN bit.
[out] | h | Header to set. |
[in] | value | Value to set it to. |
Definition at line 330 of file frame.hpp.
References websocketpp::frame::basic_header::b0, and BHB0_FIN.
Referenced by BOOST_AUTO_TEST_CASE().
|
inline |
check whether the frame's RSV1 bit is set
[in] | h | The basic header to extract from. |
Definition at line 339 of file frame.hpp.
References websocketpp::frame::basic_header::b0.
Referenced by BOOST_AUTO_TEST_CASE(), websocketpp::processor::hybi13< stub_config >::consume(), and websocketpp::processor::hybi13< stub_config >::validate_incoming_basic_header().
|
inline |
Set the frame's RSV1 bit.
[out] | h | Header to set. |
[in] | value | Value to set it to. |
Definition at line 348 of file frame.hpp.
References websocketpp::frame::basic_header::b0, and BHB0_RSV1.
Referenced by BOOST_AUTO_TEST_CASE().
|
inline |
check whether the frame's RSV2 bit is set
[in] | h | The basic header to extract from. |
Definition at line 357 of file frame.hpp.
References websocketpp::frame::basic_header::b0.
Referenced by BOOST_AUTO_TEST_CASE(), and websocketpp::processor::hybi13< stub_config >::validate_incoming_basic_header().
|
inline |
Set the frame's RSV2 bit.
[out] | h | Header to set. |
[in] | value | Value to set it to. |
Definition at line 366 of file frame.hpp.
References websocketpp::frame::basic_header::b0, and BHB0_RSV2.
Referenced by BOOST_AUTO_TEST_CASE().
|
inline |
check whether the frame's RSV3 bit is set
[in] | h | The basic header to extract from. |
Definition at line 375 of file frame.hpp.
References websocketpp::frame::basic_header::b0.
Referenced by BOOST_AUTO_TEST_CASE(), and websocketpp::processor::hybi13< stub_config >::validate_incoming_basic_header().
|
inline |
Set the frame's RSV3 bit.
[out] | h | Header to set. |
[in] | value | Value to set it to. |
Definition at line 384 of file frame.hpp.
References websocketpp::frame::basic_header::b0, and BHB0_RSV3.
Referenced by BOOST_AUTO_TEST_CASE().
|
inline |
Extract opcode from basic header.
[in] | h | The basic header to extract from. |
Definition at line 393 of file frame.hpp.
References websocketpp::frame::basic_header::b0.
Referenced by BOOST_AUTO_TEST_CASE(), websocketpp::processor::hybi13< stub_config >::consume(), websocketpp::processor::hybi13< stub_config >::finalize_message(), and websocketpp::processor::hybi13< stub_config >::validate_incoming_basic_header().
|
inline |
check whether the frame is masked
[in] | h | The basic header to extract from. |
Definition at line 402 of file frame.hpp.
References websocketpp::frame::basic_header::b1.
Referenced by BOOST_AUTO_TEST_CASE(), get_header_len(), get_masking_key(), websocketpp::processor::hybi13< stub_config >::process_payload_bytes(), and websocketpp::processor::hybi13< stub_config >::validate_incoming_basic_header().
|
inline |
Set the frame's MASK bit.
[out] | h | Header to set. |
value | Value to set it to. |
Definition at line 411 of file frame.hpp.
References websocketpp::frame::basic_header::b1, and BHB1_MASK.
Referenced by BOOST_AUTO_TEST_CASE().
|
inline |
Extracts the raw payload length specified in the basic header.
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
[in] | h | Basic header to read value from. |
Definition at line 431 of file frame.hpp.
References websocketpp::frame::basic_header::b1, and BHB1_PAYLOAD.
Referenced by BOOST_AUTO_TEST_CASE(), get_masking_key_offset(), get_payload_size(), websocketpp::processor::hybi13< stub_config >::validate_incoming_basic_header(), and websocketpp::processor::hybi13< stub_config >::validate_incoming_extended_header().
|
inline |
Calculates the full length of the header based on the first bytes.
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.
h | Basic frame header to extract size from. |
Definition at line 445 of file frame.hpp.
References get_masked(), get_masking_key_offset(), and nonstd::span_lite::size().
Referenced by BOOST_AUTO_TEST_CASE(), and websocketpp::processor::hybi13< stub_config >::consume().
|
inline |
Calculate the offset location of the masking key within the extended header.
Calculate the offset location of the masking key within the extended header using information from its corresponding basic header
h | Corresponding basic header to calculate from. |
Definition at line 469 of file frame.hpp.
References get_basic_size().
Referenced by BOOST_AUTO_TEST_CASE(), get_header_len(), and get_masking_key().
std::string websocketpp::frame::write_header | ( | basic_header const & | , |
extended_header const & | |||
) |
|
inline |
Extract the masking key from a frame header.
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.
h | The basic header to extract from |
e | The extended header to extract from |
Definition at line 516 of file frame.hpp.
References websocketpp::frame::extended_header::bytes, websocketpp::frame::uint32_converter::c, get_masked(), get_masking_key_offset(), and websocketpp::frame::uint32_converter::i.
Referenced by BOOST_AUTO_TEST_CASE(), and websocketpp::processor::hybi13< stub_config >::consume().
|
inline |
Extract the extended size field from an extended header.
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.
e | The extended header to extract from |
Definition at line 540 of file frame.hpp.
References websocketpp::frame::extended_header::bytes, websocketpp::frame::uint16_converter::c, and websocketpp::frame::uint16_converter::i.
Referenced by BOOST_AUTO_TEST_CASE(), and get_payload_size().
|
inline |
Extract the jumbo size field from an extended header.
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.
e | The extended header to extract from |
Definition at line 555 of file frame.hpp.
References websocketpp::lib::net::_ntohll(), websocketpp::frame::extended_header::bytes, websocketpp::frame::uint64_converter::c, and websocketpp::frame::uint64_converter::i.
Referenced by BOOST_AUTO_TEST_CASE(), and get_payload_size().
|
inline |
Extract the full payload size field from a WebSocket header.
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
h | The basic header to extract from |
e | The extended header to extract from |
Definition at line 573 of file frame.hpp.
References get_basic_size(), get_extended_size(), get_jumbo_size(), and websocketpp::frame::limits::payload_size_basic.
Referenced by BOOST_AUTO_TEST_CASE(), websocketpp::processor::hybi13< stub_config >::consume(), and websocketpp::processor::hybi13< stub_config >::validate_incoming_extended_header().
|
inline |
Extract a masking key into a value the size of a machine word.
Machine word size must be 4 or 8.
key | Masking key to extract from |
Definition at line 595 of file frame.hpp.
References websocketpp::frame::uint32_converter::i.
Referenced by BOOST_AUTO_TEST_CASE(), websocketpp::processor::hybi13< stub_config >::consume(), and word_mask_exact().
|
inline |
circularly shifts the supplied prepared masking key by offset bytes
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.
References websocketpp::lib::net::is_little_endian().
Referenced by BOOST_AUTO_TEST_CASE(), byte_mask_circ(), and word_mask_circ().
void websocketpp::frame::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.
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.
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 645 of file frame.hpp.
References websocketpp::frame::uint32_converter::c.
Referenced by BOOST_AUTO_TEST_CASE(), byte_mask(), main(), and websocketpp::processor::hybi13< stub_config >::masked_copy().
void websocketpp::frame::byte_mask | ( | iter_type | b, |
iter_type | e, | ||
masking_key_type const & | key, | ||
size_t | key_offset | ||
) |
Byte by byte mask/unmask (in place)
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.
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 675 of file frame.hpp.
References byte_mask().
|
inline |
Exact word aligned mask/unmask.
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.
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 702 of file frame.hpp.
References websocketpp::frame::uint32_converter::c, websocketpp::frame::uint16_converter::i, and prepare_masking_key().
Referenced by BOOST_AUTO_TEST_CASE(), main(), and word_mask_exact().
|
inline |
Exact word aligned mask/unmask (in place)
In place version of word_mask_exact
data | buffer to read and write from |
length | length of data buffer |
key | Masking key to use |
Definition at line 731 of file frame.hpp.
References word_mask_exact().
|
inline |
Circular word aligned mask/unmask.
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)
data | Character buffer to mask |
length | Length of data |
prepared_key | Prepared key to use. |
Definition at line 768 of file frame.hpp.
References circshift_prepared_key(), and websocketpp::frame::uint16_converter::i.
Referenced by BOOST_AUTO_TEST_CASE(), and word_mask_circ().
|
inline |
Circular word aligned mask/unmask (in place)
In place version of word_mask_circ
data | Character buffer to read from and write to |
length | Length of data |
prepared_key | Prepared key to use. |
Definition at line 805 of file frame.hpp.
References word_mask_circ().
|
inline |
Generate a properly sized contiguous string that encodes a full frame header.
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.
h | The basic header to include |
e | The extended header to include |
Definition at line 489 of file frame.hpp.
References websocketpp::frame::basic_header::b0, websocketpp::frame::basic_header::b1, and websocketpp::frame::extended_header::bytes.
Referenced by BOOST_AUTO_TEST_CASE(), websocketpp::processor::hybi13< stub_config >::prepare_control(), and websocketpp::processor::hybi13< stub_config >::prepare_data_frame().
|
inline |
Circular byte aligned mask/unmask.
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.
data | Character buffer to mask |
length | Length of data |
prepared_key | Prepared key to use. |
Definition at line 830 of file frame.hpp.
References websocketpp::frame::uint32_converter::c, circshift_prepared_key(), websocketpp::frame::uint16_converter::i, and websocketpp::frame::uint32_converter::i.
Referenced by BOOST_AUTO_TEST_CASE(), byte_mask_circ(), and websocketpp::processor::hybi13< stub_config >::process_payload_bytes().
|
inline |
Circular byte aligned mask/unmask (in place)
In place version of byte_mask_circ
data | Character buffer to read from and write to |
length | Length of data |
prepared_key | Prepared key to use. |
Definition at line 857 of file frame.hpp.
References byte_mask_circ().
|
static |
Minimum length of a WebSocket frame header.
Definition at line 48 of file frame.hpp.
Referenced by websocketpp::processor::hybi13< stub_config >::consume(), and websocketpp::processor::hybi13< stub_config >::reset_headers().
|
static |
|
static |
Maximum length of the variable portion of the WebSocket header.
Definition at line 52 of file frame.hpp.
Referenced by websocketpp::processor::hybi13< stub_config >::reset_headers().
|
static |
Definition at line 174 of file frame.hpp.
Referenced by websocketpp::frame::basic_header::basic_header().
|
static |
Definition at line 175 of file frame.hpp.
Referenced by websocketpp::frame::basic_header::basic_header(), and set_rsv3().
|
static |
Definition at line 176 of file frame.hpp.
Referenced by websocketpp::frame::basic_header::basic_header(), and set_rsv2().
|
static |
Definition at line 177 of file frame.hpp.
Referenced by websocketpp::frame::basic_header::basic_header(), and set_rsv1().
|
static |
Definition at line 178 of file frame.hpp.
Referenced by websocketpp::frame::basic_header::basic_header(), and set_fin().
|
static |
Definition at line 180 of file frame.hpp.
Referenced by get_basic_size().
|
static |
Definition at line 181 of file frame.hpp.
Referenced by websocketpp::frame::basic_header::basic_header(), and set_masked().
|
static |
Definition at line 183 of file frame.hpp.
Referenced by websocketpp::frame::basic_header::basic_header(), and websocketpp::processor::hybi13< stub_config >::validate_incoming_extended_header().
|
static |
Definition at line 184 of file frame.hpp.
Referenced by websocketpp::frame::basic_header::basic_header(), and websocketpp::processor::hybi13< stub_config >::validate_incoming_extended_header().