Loading...
Searching...
No Matches
websocketpp::extensions::permessage_deflate::enabled< config > Class Template Reference

## Public Member Functions

lib::error_code | init (bool is_server)
| Initialize zlib state.
bool | is_implemented () const
| Test if this object implements the permessage-deflate specification.
bool | is_enabled () const
| Test if the extension was negotiated for this connection.
void | enable_server_no_context_takeover ()
| Reset server's outgoing LZ77 sliding window for each new message.
void | enable_client_no_context_takeover ()
| Reset client's outgoing LZ77 sliding window for each new message.
lib::error_code | set_server_max_window_bits (uint8_t bits, mode::value mode)
| Limit server LZ77 sliding window size.
lib::error_code | set_client_max_window_bits (uint8_t bits, mode::value mode)
| Limit client LZ77 sliding window size.
std::string | generate_offer () const
| Generate extension offer.
lib::error_code | validate_offer (http::attribute_list const &)
| Validate extension response.
err_str_pair | negotiate (http::attribute_list const &offer)
| Negotiate extension.
lib::error_code | compress (std::string const &in, std::string &out)
| Compress bytes.
lib::error_code | decompress (uint8_t const *buf, size_t len, std::string &out)
| Decompress bytes.

## Detailed Description

template<typename config>
class websocketpp::extensions::permessage_deflate::enabled< config >

Definition at line 218 of file enabled.hpp.

## Constructor & Destructor Documentation

## enabled()

template<typename config>

websocketpp::extensions::permessage_deflate::enabled< config >::enabled | ( |  | ) |

inline

Definition at line 220 of file enabled.hpp.

## ~enabled()

template<typename config>

websocketpp::extensions::permessage_deflate::enabled< config >::~enabled | ( |  | ) |

inline

Definition at line 242 of file enabled.hpp.

## Member Function Documentation

## compress()

template<typename config>

lib::error_code websocketpp::extensions::permessage_deflate::enabled< config >::compress | ( | std::string const & | in,
|  | std::string & | out )

inline

Compress bytes.

Todo
  : avail_in/out is 32 bit, need to fix for cases of >32 bit frames on 64 bit machines.

Parameters

  [in] | in | String to compress
  [out] | out | String to append compressed bytes to

Returns
  Error or status code

Definition at line 548 of file enabled.hpp.

## decompress()

template<typename config>

lib::error_code websocketpp::extensions::permessage_deflate::enabled< config >::decompress | ( | uint8_t const * | buf,
|  | size_t | len,
|  | std::string & | out )

inline

Decompress bytes.

Parameters

  buf | Byte buffer to decompress
  len | Length of buf
  out | String to append decompressed bytes to

Returns
  Error or status code

Definition at line 586 of file enabled.hpp.

## enable_client_no_context_takeover()

template<typename config>

void websocketpp::extensions::permessage_deflate::enabled< config >::enable_client_no_context_takeover | ( |  | ) |

inline

Reset client's outgoing LZ77 sliding window for each new message.

Enabling this setting will cause the client's compressor to reset the compression state (the LZ77 sliding window) for every message. This means that the compressor will not look back to patterns in previous messages to improve compression. This will reduce the compression efficiency for large messages somewhat and small messages drastically.

This option may reduce client compressor memory usage and server decompressor memory usage.

Todo
  Document to what extent memory usage will be reduced

This option is supported by all compliant clients and servers. Enabling it via either endpoint should be sufficient to ensure it is used.

Definition at line 381 of file enabled.hpp.

## enable_server_no_context_takeover()

template<typename config>

void websocketpp::extensions::permessage_deflate::enabled< config >::enable_server_no_context_takeover | ( |  | ) |

inline

Reset server's outgoing LZ77 sliding window for each new message.

Enabling this setting will cause the server's compressor to reset the compression state (the LZ77 sliding window) for every message. This means that the compressor will not look back to patterns in previous messages to improve compression. This will reduce the compression efficiency for large messages somewhat and small messages drastically.

This option may reduce server compressor memory usage and client decompressor memory usage.

Todo
  Document to what extent memory usage will be reduced

For clients, this option is dependent on server support. Enabling it via this method does not guarantee that it will be successfully negotiated, only that it will be requested.

For servers, no client support is required. Enabling this option on a server will result in its use. The server will signal to clients that the option will be in use so they can optimize resource usage if they are able.

Definition at line 362 of file enabled.hpp.

## generate_offer()

template<typename config>

std::string websocketpp::extensions::permessage_deflate::enabled< config >::generate_offer | ( |  | ) | const

inline

Generate extension offer.

Creates an offer string to include in the Sec-WebSocket-Extensions header of outgoing client requests.

Returns
  A WebSocket extension offer string for this extension

Definition at line 483 of file enabled.hpp.

## init()

template<typename config>

lib::error_code websocketpp::extensions::permessage_deflate::enabled< config >::init | ( | bool | is_server | ) |

inline

Initialize zlib state.

Note: this should be called after the negotiation methods. It will use information from the negotiation to determine how to initialize the zlib data structures.

Todo
  memory level, strategy, etc are hardcoded

Parameters

  is_server | True to initialize as a server, false for a client.

Returns
  A code representing the error that occurred, if any

Definition at line 273 of file enabled.hpp.

## is_enabled()

template<typename config>

bool websocketpp::extensions::permessage_deflate::enabled< config >::is_enabled | ( |  | ) | const

inline

Test if the extension was negotiated for this connection.

Retrieves whether or not this extension is in use based on the initial handshake extension negotiations.

Returns
  Whether or not the extension is in use

Definition at line 337 of file enabled.hpp.

## is_implemented()

template<typename config>

bool websocketpp::extensions::permessage_deflate::enabled< config >::is_implemented | ( |  | ) | const

inline

Test if this object implements the permessage-deflate specification.

Because this object does implieent it, it will always return true.

Returns
  Whether or not this object implements permessage-deflate

Definition at line 326 of file enabled.hpp.

## negotiate()

template<typename config>

err_str_pair websocketpp::extensions::permessage_deflate::enabled< config >::negotiate | ( | http::attribute_list const & | offer | ) |

inline

Negotiate extension.

Confirm that the client's extension negotiation offer has settings compatible with local policy. If so, generate a reply and apply those settings to the extension state.

Parameters

  offer | Attribute from client's offer

Returns
  Status code and value to return to remote endpoint

Definition at line 509 of file enabled.hpp.

## set_client_max_window_bits()

template<typename config>

lib::error_code websocketpp::extensions::permessage_deflate::enabled< config >::set_client_max_window_bits | ( | uint8_t | bits,
|  | mode::value | mode )

inline

Limit client LZ77 sliding window size.

The bits setting is the base 2 logarithm of the window size that the client must use to compress outgoing messages. The permitted range is 9 to 15 inclusive. 9 represents a 512 byte window and 15 a 32KiB window. The default setting is 15.

Mode Options:

- accept: Accept whatever the remote endpoint offers.
- decline: Decline any offers to deviate from the defaults
- largest: Accept largest window size acceptable to both endpoints
- smallest: Accept smallest window size acceptiable to both endpoints

This setting is dependent on client support. A client may limit its own outgoing window size unilaterally. A server may only limit the client's window size if the remote client supports that feature.

NOTE: The permessage-deflate spec specifies that a value of 8 is allowed. Prior to version 0.8.0 a value of 8 was also allowed by this library. zlib, the deflate compression library that WebSocket++ uses has always silently adjusted a value of 8 to 9. In recent versions of zlib (1.2.9 and greater) a value of 8 is now explicitly rejected. WebSocket++ 0.8.0 continues to perform the 8->9 conversion for backwards compatibility purposes but this should be considered deprecated functionality.

Parameters

  bits | The size to request for the outgoing window size
  mode | The mode to use for negotiating this parameter

Returns
  A status code

Definition at line 460 of file enabled.hpp.

## set_server_max_window_bits()

template<typename config>

lib::error_code websocketpp::extensions::permessage_deflate::enabled< config >::set_server_max_window_bits | ( | uint8_t | bits,
|  | mode::value | mode )

inline

Limit server LZ77 sliding window size.

The bits setting is the base 2 logarithm of the maximum window size that the server must use to compress outgoing messages. The permitted range is 9 to 15 inclusive. 9 represents a 512 byte window and 15 a 32KiB window. The default setting is 15.

Mode Options:

- accept: Accept whatever the remote endpoint offers.
- decline: Decline any offers to deviate from the defaults
- largest: Accept largest window size acceptable to both endpoints
- smallest: Accept smallest window size acceptiable to both endpoints

This setting is dependent on server support. A client requesting this setting may be rejected by the server or have the exact value used adjusted by the server. A server may unilaterally set this value without client support.

NOTE: The permessage-deflate spec specifies that a value of 8 is allowed. Prior to version 0.8.0 a value of 8 was also allowed by this library. zlib, the deflate compression library that WebSocket++ uses has always silently adjusted a value of 8 to 9. In recent versions of zlib (1.2.9 and greater) a value of 8 is now explicitly rejected. WebSocket++ 0.8.0 continues to perform the 8->9 conversion for backwards compatibility purposes but this should be considered deprecated functionality.

Parameters

  bits | The size to request for the outgoing window size
  mode | The mode to use for negotiating this parameter

Returns
  A status code

Definition at line 415 of file enabled.hpp.

## validate_offer()

template<typename config>

lib::error_code websocketpp::extensions::permessage_deflate::enabled< config >::validate_offer | ( | http::attribute_list const & |  | ) |

inline

Validate extension response.

Confirm that the server has negotiated settings compatible with our original offer and apply those settings to the extension state.

Parameters

  response | The server response attribute list to validate

Returns
  Validation error or 0 on success

Definition at line 496 of file enabled.hpp.

The documentation for this class was generated from the following file:

- websocketpp/extensions/permessage_deflate/enabled.hpp