root/fileserver
1
0
Fork 0
Code Issues 11 Actions Wiki Activity
023ef2ec49
fileserver/lib/restbed-4.8/documentation/API.md

6038 lines
154 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Overview
--------
This document is intended to accurately communicate the [Application Programming Interface (API)](https://en.wikipedia.org/wiki/Application_programming_interface) exposed by the Restbed framework for public consumption.
A description of the frameworks software architecture is provided by the [Design Overview](#DESIGN.md) documentation.
Interpretation
--------------
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](http://tools.ietf.org/pdf/rfc2119.pdf).
Table of Contents
-----------------
1. [Overview](#overview)
2. [Interpretation](#interpretation)
3. [Byte/Bytes](#bytebytes)
4. [HTTP](#http)
5. [Logger](#logger)
6. [Logger::Level](#loggerlevel)
7. [Request](#request)
8. [Response](#response)
9. [Resource](#resource)
10. [Rule](#rule)
11. [Service](#service)
12. [Session](#session)
13. [SessionManager](#sessionmanager)
14. [Settings](#settings)
15. [SSLSettings](#sslsettings)
16. [StatusCode](#statuscode)
17. [String](#string)
18. [String::Option](#stringoption)
19. [URI](#uri)
20. [WebSocket](#websocket)
21. [WebSocketMessage](#websocketmessage)
22. [WebSocketMessage::OpCode](#websocketmessageopcode)
23. [Further Reading](#further-reading)
### Byte/Bytes
```C++
typedef uint8_t Byte;
typedef std::vector< Byte > Bytes;
```
Byte represents an unsigned 8-bit wide data-type, Bytes provides container functionality with [Standard Template Library](http://en.cppreference.com/w/cpp) (STL) [vector](http://en.cppreference.com/w/cpp/container/vector) collection semantics.
See [std::uint8_t](http://en.cppreference.com/w/cpp/types/integer) and [std::vector](http://en.cppreference.com/w/cpp/container/vector) for further details.
### Http
The static HTTP class offers limited client capabilities for consuming RESTful services. This will be removed in future version and replaced with the Restless client framework.
#### Methods
- [to_bytes](#httpto_bytes)
- [close](#httpclose)
- [is_open](#httpis_open)
- [is_closed](#httpis_closed)
- [sync](#httpsync)
- [async](#httpasync)
- [fetch](#httpfetch)
#### Http::to_bytes
```C++
static Bytes to_bytes( const std::shared_ptr< Request >& value );
static Bytes to_bytes( const std::shared_ptr< Response >& value );
```
Convert a HTTP [request](#request)/[response](#response) object to a sequence of [bytes](#bytebytes).
##### Parameters
| parameter | type | default value | direction |
|:---------:|--------------------------------|:-------------:|:---------:|
| value | [restbed::Request](#request) | n/a | input |
| value | [restbed::Response](#response) | n/a | input |
##### Return Value
Collection of [bytes](#bytebytes) representing the raw request representation.
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Http::close
```C++
static void close( const std::shared_ptr< Request >& value );
```
Shutdown an active HTTP [request](#request) object, causing its underlying socket to be disconnected. Invoking this method on a inactive [request](#request) has no effect.
##### Parameters
| parameter | type | default value | direction |
|:---------:|------------------------------|:-------------:|:---------:|
| value | [restbed::Request](#request) | n/a | input |
##### Return Value
n/a
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Http::is_open
```C++
static bool is_open( const std::shared_ptr< Request >& value );
```
Determine if the HTTP [request](#request) object is active, that is say, it has a connected socket to a remote endpoint. Invoking this method on a inactive [request](#request) has no effect.
##### Parameters
| parameter | type | default value | direction |
|:---------:|------------------------------|:-------------:|:---------:|
| value | [restbed::Request](#request) | n/a | input |
##### Return Value
Boolean true if the underlying socket is connected, else false.
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Http::is_closed
```C++
static bool is_closed( const std::shared_ptr< Request >& value );
```
Determine if the HTTP [request](#request) object is inactive, that is say, it has a disconnected socket. Invoking this method on a inactive [request](#request) has no effect.
##### Parameters
| parameter | type | default value | direction |
|:---------:|------------------------------|:-------------:|:---------:|
| value | [restbed::Request](#request) | n/a | input |
##### Return Value
Boolean true if the underlying socket is disconnected, else false.
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Http::sync
```C++
static const std::shared_ptr< Response > sync( const std::shared_ptr< Request > request, const std::shared_ptr< const Settings >& settings = std::make_shared< Settings >( ) );
```
Perform a synchronous, read: wait for the result, HTTP [request](#request). If an error occurs the [response](#response) will contain details of the error, indicated by a status code of zero (0).
[Settings](#settings) may be specified via the second parameter.
##### Parameters
| parameter | type | default value | direction |
|:---------:|--------------------------------|:-------------:|:---------:|
| request | [restbed::Request](#request) | n/a | input |
| settings | [restbed::Settings](#settings) | n/a | input |
##### Return Value
The HTTP [response](#response) returned from the endpoint specified in the [request](#request) object, otherwise an error condition.
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Http::async
```C++
static std::future< std::shared_ptr< Response > > async( const std::shared_ptr< Request > request, const std::function< void ( const std::shared_ptr< Request >, const std::shared_ptr< Response > ) >& callback, const std::shared_ptr< const Settings >& settings = std::make_shared< Settings >( ) );
```
Perform an asynchronous, read: don't wait for the result, HTTP [request](#request). If an error occurs the [response](#response) will contain details of the error, indicated by a status code of zero (0).
The second callback parameter will be invoked when the service has finished responding to the [request](#request).
[Settings](#settings) may be specified via the third parameter.
##### Parameters
| parameter | type | default value | direction |
|:---------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| request | [restbed::Request](#request) | n/a | input |
| callback | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
| settings | [restbed::Settings](#settings) | n/a | input |
##### Return Value
[std::future](http://en.cppreference.com/w/cpp/thread/future) holding the pending [restbed::Response](#response).
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Http::fetch
```C++
static Bytes fetch( const std::size_t length, const std::shared_ptr< Response >& response );
static Bytes fetch( const std::string& delimiter, const std::shared_ptr< Response >& response );
```
Fetch the contents of a response body by either length or delimiter value.
##### Parameters
| parameter | type | default value | direction |
|:---------:|---------------------------------------------------------------------|:-------------:|:---------:|
| response | [restbed::Response](#response) | n/a | input |
| length | [std::size_t](http://en.cppreference.com/w/cpp/types/size_t) | n/a | input |
| delimiter | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
Sequence of [restbed::Bytes](#bytebytes) representing a portion or a complete response body determined by length or delimiter parameter options.
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
### Logger
Interface detailing the required contract for logger extensions.
No default logger is supplied with the codebase and it is the responsibility of third-party developers to implement the desired behaviour.
#### Methods
- [start](#loggerstart)
- [stop](#loggerstop)
- [log](#loggerlog)
- [log_if](#loggerlog_if)
- [level](#loggerlevel)
#### Logger::start
```C++
virtual void start( const std::shared_ptr< const restbed::Settings >& settings ) = 0;
```
Initialise a logger instance; see also [stop](#loggerstop).
The [Settings](#settings) passed are the same as those given to [Exchange::start](#exchangestart).
After this method has returned the instance **MUST** be ready to start receiving [log](#loggerlog) and [log_if](#loggerlog_if) invocations.
##### Parameters
| name | type | default value | direction |
|:-----:|--------------------------------|:-------------:|:---------:|
| value | [restbed::Settings](#settings) | n/a | input |
##### Return Value
n/a
##### Exceptions
Any exceptions raised will result in the service failing to start.
#### Logger::stop
```C++
virtual void stop( void ) = 0;
```
Halt/Clean-up logger resources; see also [start](#loggerstart).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
Exceptions raised will result in a dirty service teardown.
#### Logger::log
```C++
virtual void log( const Level level, const char* format, ... ) = 0;
```
Commit the message specified under the control of a format string, with the specified level of severity into the log; see also [log_if](#loggerlog_if).
See [printf](http://en.cppreference.com/w/cpp/io/c/fprintf) family of functions for format directives.
> The format string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is >introduced by the % character.
##### Parameters
| name | type | default value | direction |
|:------:|-----------------------------------------------------------------------------|:-------------:|:---------:|
| level | [restbed::Logger::Level](#loggerlevel) | n/a | input |
| format | [char\*](http://en.cppreference.com/w/cpp/language/types) | n/a | input |
| ... | [variadic argument list](http://en.cppreference.com/w/cpp/utility/variadic) | n/a | input |
##### Return Value
n/a
##### Exceptions
Any exceptions raised will result in the service ignoring the fault and printing directly to [Standard Error (stderr)](http://en.cppreference.com/w/cpp/io/c).
#### Logger::log_if
```C++
virtual void log_if( bool expression, const Level level, const char* format, ... ) = 0;
```
Commit the message specified under the control of a format string, with the specified level of severity into the log, under the condition that the expression is equal to boolean true; see also [log](#loggerlog).
##### Parameters
| parameter | type | default value | direction |
|:-----------:|-----------------------------------------------------------------------------|:-------------:|:---------:|
| expresssion | [bool](http://en.cppreference.com/w/cpp/language/types) | n/a | input |
| level | [restbed::Logger::Level](#loggerlevel) | n/a | input |
| format | [char\*](http://en.cppreference.com/w/cpp/language/types) | n/a | input |
| ... | [variadic argument list](http://en.cppreference.com/w/cpp/utility/variadic) | n/a | input |
##### Return Value
n/a
##### Exceptions
Any exceptions raised will result in the service ignoring the fault and printing directly to [Standard Error (stderr)](http://en.cppreference.com/w/cpp/io/c).
#### Logger::Level
```C++
class Logger
{
enum Level : int
{
INFO = 0000,
DEBUG = 1000,
FATAL = 2000,
ERROR = 3000,
WARNING = 4000,
SECURITY = 5000
};
}
```
[Enumeration](http://en.cppreference.com/w/cpp/language/enum) used in conjunction with the [Logger interface](#logger) to detail the level of severity towards a particular log entry.
### Request
Represents a HTTP request with additional helper methods for manipulating data, and improving code readability.
#### Methods
- [constructor](#requestconstructor)
- [destructor](#requestdestructor)
- [has_header](#requesthas_header)
- [has_path_parameter](#requesthas_path_parameter)
- [has_query_parameter](#requesthas_query_parameter)
- [get_port](#requestget_port)
- [get_version](#requestget_version)
- [get_body](#requestget_body)
- [get_response](#requestget_response)
- [get_host](#requestget_host)
- [get_path](#requestget_path)
- [get_method](#requestget_method)
- [get_protocol](#requestget_protocol)
- [get_header](#requestget_header)
- [get_headers](#requestget_headers)
- [get_query_parameter](#requestget_query_parameter)
- [get_query_parameters](#requestget_query_parameters)
- [get_path_parameter](#requestget_path_parameter)
- [get_path_parameters](#requestget_path_parameters)
- [set_body](#requestset_body)
- [set_port](#requestset_port)
- [set_version](#requestset_version)
- [set_path](#requestset_path)
- [set_host](#requestset_host)
- [set_method](#requestset_method)
- [set_protocol](#requestset_protocol)
- [add_header](#requestadd_header)
- [set_header](#requestset_header)
- [set_headers](#requestset_headers)
- [set_query_parameter](#requestset_query_parameter)
- [set_query_parameters](#requestset_query_parameters)
#### Request::constructor
```C++
Request( void );
Request( const Uri& value );
```
Initialises a new class instance, if a [Uri](#uri) is supplied it will be used to override the default class property values; see also [destructor](#requestdestructor).
##### Parameters
| name | type | default value | direction |
|:-----:|-------------|:-------------:|:---------:|
| value | [Uri](#uri) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Request::destructor
```C++
virtual ~Request( void );
```
Clean-up class instance; see also [constructor](#requestconstructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Request::has_header
```C++
bool has_header( const std::string& name ) const;
```
Case insensitive check to confirm if the [request](#request) contains a header with the supplied name.
##### Parameters
| name | type | default value | direction |
|:----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
Boolean true if the [request](#request) holds a header with a matching name, else false.
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Request::has_path_parameter
```C++
bool has_path_parameter( const std::string& name ) const;
```
Case insensitive check to confirm if the [request](#request) contains a path parameter with the supplied name.
##### Parameters
| name | type | default value | direction |
|:----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
Boolean true if the [request](#request) holds a path parameter with a matching name, else false.
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Request::has_query_parameter
```C++
bool has_query_parameter( const std::string& name ) const;
```
Case insensitive check to confirm if the [request](#request) contains a query parameter with the supplied name.
##### Parameters
| name | type | default value | direction |
|:----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
Boolean true if the [request](#request) holds a query parameter with a matching name, else false.
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Request::get_port
```C++
uint16_t get_port( void ) const;
```
Retrieves the network port number of the server endpoint; see also [set_port](#requestset_port).
##### Parameters
n/a
##### Return Value
[uint16_t](http://en.cppreference.com/w/cpp/types/integer) representing the network port number.
##### Exceptions
n/a
#### Request::get_version
```C++
double get_version( void ) const;
```
Retrieves the [HTTP version](https://tools.ietf.org/html/rfc2145) number; see also [set_version](#requestset_version).
##### Parameters
n/a
##### Return Value
[double](http://en.cppreference.com/w/cpp/language/types%23Floating_point_types) representing the [HTTP version](https://tools.ietf.org/html/rfc2145).
##### Exceptions
n/a
#### Request::get_body
```C++
Bytes get_body( void ) const;
void get_body( std::string& body, const std::function< std::string ( const Bytes& ) >& transform = nullptr ) const;
```
1) Retrieves the contents of the request body as [Bytes](#bytebytes); see also [set_body](#requestset_body).
2) Alters the request body with the transform operation and returns the result as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string); see also [set_body](#requestset_body).
##### Parameters
| name | type | default value | direction |
|:---------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| body | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | output |
| transform | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
[Bytes](#bytebytes) representing the request body.
##### Exceptions
n/a
#### Request::get_response
```C++
const std::shared_ptr< const Response > get_response( void ) const;
```
Retrieves the associated HTTP [response](#response) for this request, if any.
##### Parameters
n/a
##### Return Value
[std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) representing the response, else nullptr.
##### Exceptions
n/a
#### Request::get_host
```C++
std::string get_host( const std::function< std::string ( const std::string& ) >& transform = nullptr ) const;
```
Retrieves the a host for this request, optionally applying a text transformation.
##### Parameters
| name | type | default value | direction |
|:---------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| transform | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) representing the host.
##### Exceptions
n/a
#### Request::get_path
```C++
std::string get_path( const std::function< std::string ( const std::string& ) >& transform = nullptr ) const;
```
Retrieves the path for this request, optionally applying a text transformation.
##### Parameters
| name | type | default value | direction |
|:---------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| transform | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) representing the path.
##### Exceptions
n/a
#### Request::get_method
```C++
std::string get_method( const std::function< std::string ( const std::string& ) >& transform = nullptr ) const;
```
Retrieves the [HTTP method](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html) for this request, optionally applying a text transformation.
##### Parameters
| name | type | default value | direction |
|:---------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| transform | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) representing the [HTTP method](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html).
##### Exceptions
n/a
#### Request::get_protocol
```C++
std::string get_protocol( const std::function< std::string ( const std::string& ) >& transform = nullptr ) const;
```
Retrieves the protocol for this request, optionally applying a text transformation.
##### Parameters
| name | type | default value | direction |
|:---------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| transform | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) representing the protocol.
##### Exceptions
n/a
#### Request::get_header
```C++
template< typename Type, typename std::enable_if< std::is_arithmetic< Type >::value, Type >::type = 0 >
Type get_header( const std::string& name, const Type default_value ) const
std::string get_header( const std::string& name, const std::string& default_value ) const;
std::string get_header( const std::string& name, const std::function< std::string ( const std::string& ) >& transform = nullptr ) const;
```
1) Retrieve the first header with a matching name parsing to a an arithmetic value. if not found return default_value.
2) Retrieve the first header with a matching name as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string). if not found return default_value.
3) Retrieve the first header with a matching name as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string), optionally applying a transformation.
##### Parameters
| name | type | default value | direction |
|:-------------:|-----------------------------------------------------------------------------------|:-------------:|:---------:|
| transform | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
| default_value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic | n/a | input |
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic value representing the header.
##### Exceptions
n/a
#### Request::get_headers
```C++
std::multimap< std::string, std::string > get_headers( const std::string& name = "" ) const;
```
Retrieves all headers as a [std::multimap](http://en.cppreference.com/w/cpp/container/multimap). if a name is supplied only matching headers will be returned.
##### Parameters
| name | type | default value | direction |
|:---------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| transform | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
[std::multimap](http://en.cppreference.com/w/cpp/container/multimap) representing a collection of headers.
##### Exceptions
n/a
#### Request::get_query_parameter
```C++
template< typename Type, typename std::enable_if< std::is_arithmetic< Type >::value, Type >::type = 0 >
Type get_query_parameter( const std::string& name, const Type default_value ) const
std::string get_query_parameter( const std::string& name, const std::string& default_value ) const;
std::string get_query_parameter( const std::string& name, const std::function< std::string ( const std::string& ) >& transform = nullptr ) const;
```
1) Retrieve the first query parameter with a matching name parsing to a an arithmetic value. if not found return default_value.
2) Retrieve the first query parameter with a matching name as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string). if not found return default_value.
3) Retrieve the first query parameter with a matching name as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string), optionally applying a transformation.
##### Parameters
| name | type | default value | direction |
|:-------------:|-----------------------------------------------------------------------------------|:-------------:|:---------:|
| transform | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
| default_value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic | n/a | input |
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic value representing the query parameter.
##### Exceptions
n/a
#### Request::get_query_parameters
```C++
std::multimap< std::string, std::string > get_query_parameters( const std::string& name = "", const String::Option option = String::CASE_INSENSITIVE ) const;
```
Retrieves all query parameters as a [std::multimap](http://en.cppreference.com/w/cpp/container/multimap). if a name is supplied only matching parameters will be returned.
##### Parameters
| name | type | default value | direction |
|:---------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| transform | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
| option | [String::Option](#stringoption) | n/a | input |
##### Return Value
[std::multimap](http://en.cppreference.com/w/cpp/container/multimap) representing a collection of parameters.
##### Exceptions
n/a
#### Request::get_path_parameter
```C++
template< typename Type, typename std::enable_if< std::is_arithmetic< Type >::value, Type >::type = 0 >
Type get_path_parameter( const std::string& name, const Type default_value ) const
std::string get_path_parameter( const std::string& name, const std::string& default_value ) const;
std::string get_path_parameter( const std::string& name, const std::function< std::string ( const std::string& ) >& transform = nullptr ) const;
```
1) Retrieve the first parameter with a matching name parsing to a an arithmetic value. if not found return default_value.
2) Retrieve the first parameter with a matching name as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string). if not found return default_value.
3) Retrieve the first parameter with a matching name as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string), optionally applying a transformation.
##### Parameters
| name | type | default value | direction |
|:-------------:|-----------------------------------------------------------------------------------|:-------------:|:---------:|
| transform | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
| default_value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic | n/a | input |
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic value representing the path parameter.
##### Exceptions
n/a
#### Request::get_path_parameters
```C++
std::map< std::string, std::string > get_path_parameters( const std::string& name = "", const String::Option option = String::CASE_INSENSITIVE ) const;
```
Retrieves all query parameters as a [std::multimap](http://en.cppreference.com/w/cpp/container/multimap). if a name is supplied only matching parameters will be returned.
##### Parameters
| name | type | default value | direction |
|:---------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| transform | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
| option | [String::Option](#stringoption) | n/a | input |
##### Return Value
[std::multimap](http://en.cppreference.com/w/cpp/container/multimap) representing a collection of parameters.
##### Exceptions
n/a
#### Request::set_body
```C++
void set_body( const Bytes& value );
void set_body( const std::string& value );
```
Replace request body; see also [get_body](#requestget_body).
##### Parameters
| name | type | default value | direction |
|:-----:|--------------------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or [Bytes](#bytebytes) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Request::set_port
```C++
void set_port( const uint16_t value );
```
Replace request network port; see also [get_port](#requestget_port).
##### Parameters
| name | type | default value | direction |
|:-----:|-----------------------------------------------------------------|:-------------:|:---------:|
| value | [std::uint16_t](http://en.cppreference.com/w/cpp/types/integer) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Request::set_version
```C++
void set_version( const double value );
```
Replace request version; see also [get_version](#requestget_version).
##### Parameters
| name | type | default value | direction |
|:-----:|-----------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [double](hhttp://en.cppreference.com/w/cpp/language/types%23Floating_point_types) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Request::set_path
```C++
void set_path( const std::string& value );
```
Replace request path; see also [get_path](#requestget_path).
##### Parameters
| name | type | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Request::set_host
```C++
void set_host( const std::string& value );
```
Replace request host; see also [get_host](#requestget_host).
##### Parameters
| name | type | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Request::set_method
```C++
void set_method( const std::string& value );
```
Replace request method; see also [get_method](#requestget_method).
##### Parameters
| name | type | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Request::set_protocol
```C++
void set_protocol( const std::string& value );
```
Replace request protocol; see also [get_protocol](#requestget_protocol).
##### Parameters
| name | type | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Request::add_header
```C++
void add_header( const std::string& name, const std::string& value );
```
Add a HTTP header to the request, existing headers that share the same name will not be altered.
##### Parameters
| name | type | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Request::set_header
```C++
void set_header( const std::string& name, const std::string& value );
```
Set a HTTP header, existing headers that share the same name will be erased.
##### Parameters
| name | type | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Request::set_headers
```C++
void set_header( const std::string& name, const std::string& value );
```
Set HTTP headers, existing headers will be erased.
##### Parameters
| name | type | default value | direction |
|:------:|----------------------------------------------------------------------|:-------------:|:---------:|
| values | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Request::set_query_parameter
```C++
void set_query_parameter( const std::string& name, const std::string& value );
```
Set a HTTP query parameter, existing parameters that share the same name will be erased.
##### Parameters
| name | type | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Request::set_query_parameters
```C++
void set_query_parameters( const std::multimap< std::string, std::string >& values );
```
Set HTTP query parameters, existing parameters will be erased.
##### Parameters
| name | type | default value | direction |
|:------:|----------------------------------------------------------------------|:-------------:|:---------:|
| values | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
### Response
Represents a HTTP response with additional helper methods for manipulating data, and improving code readability.
#### Methods
- [constructor](#responseconstructor)
- [destructor](#responsedestructor)
- [has_header](#responsehas_header)
- [get_body](#responseget_body)
- [get_version](#responseget_host)
- [get_status_code](#responseget_path)
- [get_protocol](#responseget_method)
- [get_status_message](#responseget_protocol)
- [get_header](#responseget_header)
- [get_headers](#responseget_headers)
- [set_body](#responseset_body)
- [set_version](#responseset_version)
- [set_status_code](#responseset_path)
- [set_protocol](#responseset_host)
- [set_status_message](#responseset_method)
- [add_header](#responseadd_header)
- [set_header](#responseset_header)
- [set_headers](#responseset_headers)
#### Response::constructor
```C++
Response( void );
```
Initialises a new class instance; see also [destructor](#responsedestructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
n/a
#### Response::destructor
```C++
virtual ~Response( void );
```
Clean-up class instance; see also [constructor](#responseconstructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Response::has_header
```C++
bool has_header( const std::string& name ) const;
```
Case insensitive check to confirm if the [response](#response) contains a header with the supplied name.
##### Parameters
| name | type | default value | direction |
|:----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
Boolean true if the [response](#response) holds a header with a matching name, else false.
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Response::get_body
```C++
Bytes get_body( void ) const;
void get_body( std::string& body, const std::function< std::string ( const Bytes& ) >& transform = nullptr ) const;
```
1) Retrieves the contents of the response body as [Bytes](#bytebytes); see also [set_body](#responseset_body).
2) Alters the response body with the transform operation and returns the result as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string); see also [set_body](#responseset_body).
##### Parameters
| name | type | default value | direction |
|:---------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| body | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | output |
| transform | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
[Bytes](#bytebytes) representing the response body.
##### Exceptions
n/a
#### Response::get_version
```C++
double get_version( void ) const;
```
Retrieves the [HTTP version](https://tools.ietf.org/html/rfc2145) number; see also [set_version](#responseset_version).
##### Parameters
n/a
##### Return Value
[double](http://en.cppreference.com/w/cpp/language/types%23Floating_point_types) representing the [HTTP version](https://tools.ietf.org/html/rfc2145).
##### Exceptions
n/a
#### Response::get_status_code
```C++
int get_status_code( void ) const;
```
Retrieves the [HTTP status code](https://tools.ietf.org/html/rfc7231#section-6.1); see also [set_status_code](#responseset_status_code).
##### Parameters
n/a
##### Return Value
Integer representing the [HTTP status code](https://tools.ietf.org/html/rfc7231#section-6.1).
##### Exceptions
n/a
#### Response::get_protocol
```C++
std::string get_protocol( void ) const;
```
Retrieve the protocol.
##### Parameters
n/a
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) representing the protocol.
##### Exceptions
n/a
#### Response::get_status_message
```C++
std::string get_status_message( void ) const;
```
Retrieves the [HTTP status message](https://tools.ietf.org/html/rfc7231#section-6.1); see also [set_status_message](#responseset_status_message).
##### Parameters
n/a
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) representing the [HTTP status message](https://tools.ietf.org/html/rfc7231#section-6.1).
##### Exceptions
n/a
#### Response::get_header
```C++
template< typename Type, typename std::enable_if< std::is_arithmetic< Type >::value, Type >::type = 0 >
Type get_header( const std::string& name, const Type default_value ) const
std::string get_header( const std::string& name, const std::string& default_value ) const;
std::string get_header( const std::string& name, const std::function< std::string ( const std::string& ) >& transform = nullptr ) const;
```
1) Retrieve the first header with a matching name parsing to a an arithmetic value. if not found return default_value.
2) Retrieve the first header with a matching name as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string). if not found return default_value.
3) Retrieve the first header with a matching name as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string), optionally applying a transformation.
##### Parameters
| name | type | default value | direction |
|:-------------:|-----------------------------------------------------------------------------------|:-------------:|:---------:|
| transform | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
| default_value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic | n/a | input |
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) or arithmetic value representing the header.
##### Exceptions
n/a
#### Response::get_headers
```C++
std::multimap< std::string, std::string > get_headers( const std::string& name = "" ) const;
```
Retrieves all headers as a [std::multimap](http://en.cppreference.com/w/cpp/container/multimap). if a name is supplied only matching headers will be returned.
##### Parameters
| name | type | default value | direction |
|:---------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| transform | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
[std::multimap](http://en.cppreference.com/w/cpp/container/multimap) representing a collection of headers.
##### Exceptions
n/a
#### Response::set_body
```C++
void set_body( const Bytes& value );
void set_body( const std::string& value );
```
Replace response body; see also [get_body](#responseget_body).
##### Parameters
| name | type | default value | direction |
|:-----:|--------------------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) or [Bytes](#bytebytes) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Response::set_version
```C++
void set_version( const double value );
```
Replace response version; see also [get_version](#responseget_version).
##### Parameters
| name | type | default value | direction |
|:-----:|-----------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [double](hhttp://en.cppreference.com/w/cpp/language/types%23Floating_point_types) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Response::set_status_code
```C++
void set_status_code( const int value );
```
Replace response status code; see also [get_status_code](#responseget_status_code).
##### Parameters
| name | type | default value | direction |
|:-----:|----------------------------------------------------------------------|:-------------:|:---------:|
| value | [int](http://en.cppreference.com/w/cpp/types/integer) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Response::set_protocol
```C++
void set_protocol( const std::string& value );
```
Replace response protocol; see also [get_protocol](#responseget_protocol).
##### Parameters
| name | type | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Response::set_status_message
```C++
void set_status_message( const std::string& value );
```
Replace response status message; see also [get_status_message](#responseget_status_message).
##### Parameters
| name | type | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Response::add_header
```C++
void add_header( const std::string& name, const std::string& value );
```
Add a HTTP header to the response, existing headers that share the same name will not be altered.
##### Parameters
| name | type | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Response::set_header
```C++
void set_header( const std::string& name, const std::string& value );
```
Set a HTTP header, existing headers that share the same name will be erased; see also [get_header](#responseget_header).
##### Parameters
| name | type | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Response::set_headers
```C++
void set_headers( const std::multimap< std::string, std::string >& values );
```
Set HTTP headers, existing headers will be erased; see also [get_headers](#responseget_headers).
##### Parameters
| name | type | default value | direction |
|:------:|----------------------------------------------------------------------|:-------------:|:---------:|
| values | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
### Resource
Resource represents an network communication endpoint. This is the primary data-structure used throughout to represent RESTful resources. All resource specific filteration, request processing rules, and authentication must be placed on this entity.
#### Methods
- [constructor](#resourceconstructor)
- [destructor](#resourcedestructor)
- [add_rule](#resourceadd_rule)
- [set_path](#resourceset_path)
- [set_paths](#resourceset_paths)
- [set_default_header](#resourceset_default_header)
- [set_default_headers](#resourceset_default_headers)
- [set_failed_filter_validation_handler](#resourceset_failed_filter_validation_handler)
- [set_error_handler](#resourceset_error_handler)
- [set_authentication_handler](#resourceset_authentication_handler)
- [set_method_handler](#resourceset_method_handler)
#### Resource::constructor
```C++
Resource( void );
```
Initialises a new class instance; see also [destructor](#resourcedestructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
n/a
#### Resource::destructor
```C++
virtual ~Resource( void );
```
Clean-up class instance; see also [constructor](#resourceconstructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Resource::add_rule
```C++
void add_rule( const std::shared_ptr< Rule >& rule );
void add_rule( const std::shared_ptr< Rule >& rule, const int priority );
```
Add incoming request processing rule; see also [Rule](#rule).
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------|:-------------:|:---------:|
| rule | [Rule](#rule) | n/a | input |
| priority | [int](http://en.cppreference.com/w/cpp/types/integer) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Resource::set_path
```C++
void set_path( const std::string& value );
```
Set the path with which this resource should be accessible. [Settings::set_root](settingsset_root) will be perpended to this value.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Resource::set_paths
```C++
void set_paths( const std::set< std::string >& values );
```
Set the paths with which this resource should be accessible. [Settings::set_root](settingsset_root) will be perpended to all values.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| values | [std::set](http://en.cppreference.com/w/cpp/container/set) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Resource::set_default_header
```C++
void set_default_header( const std::string& name, const std::string& value );
```
Set a default header that should be sent on every HTTP response, overriding any existing value with the same name.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Resource::set_default_headers
```C++
void set_default_headers( const std::multimap< std::string, std::string >& values );
```
Set default headers that should be sent on every HTTP response, overriding any existing values.
##### Parameters
| name | type | default value | direction |
|:----------:|----------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Resource::set_failed_filter_validation_handler
```C++
void set_failed_filter_validation_handler( const std::function< void ( const std::shared_ptr< Session > ) >& value );
```
Set failed filter validation handler. If an incoming request fails to match the resources filters this method will be invoked offering an opportunity to return a custom HTTP response.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Resource::set_error_handler
```C++
void set_error_handler( const std::function< void ( const int, const std::exception&, const std::shared_ptr< Session > ) >& value );
```
Set error handler. If during processing a failure occurs this method will be invoked for reporting and HTTP response handling.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Resource::set_authentication_handler
```C++
void set_authentication_handler( const std::function< void ( const std::shared_ptr< Session >, const std::function< void ( const std::shared_ptr< Session > ) >& ) >& value );
```
Set authentication handler, this method will be invoked after the service authentication handler.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Resource::set_method_handler
```C++
void set_method_handler( const std::string& method, const std::function< void ( const std::shared_ptr< Session > ) >& callback );
void set_method_handler( const std::string& method, const std::multimap< std::string, std::string >& filters, const std::function< void ( const std::shared_ptr< Session > ) >& callback );
```
Set method handler with optional header filters.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| method | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| filters | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap) | n/a | input |
| callback | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
### Rule
Interface representing an incoming processing rule.
#### Methods
- [condition](#rulecondition)
- [action](#ruleaction)
- [get_priority](#ruleget_priority)
- [set_priority](#ruleset_priority)
#### Rule::condition
```C++
virtual bool condition( const std::shared_ptr< Session > session );
```
The condition that decides if this rules action should be invoked; see also [action](#ruleaction).
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| session | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) | n/a | input |
##### Return Value
True if the condition has been satisfied.
##### Exceptions
n/a
#### Rule::action
```C++
virtual void action( const std::shared_ptr< Session > session, const std::function< void ( const std::shared_ptr< Session > ) >& callback ) = 0;
```
The action to be invoked if the rules condition returns true; see also [condition](#rulecondition).
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| session | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) | n/a | input |
| callback | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Rule::get_priority
```C++
int get_priority( void ) const;
```
Retrieve rule processing priority.
##### Parameters
n/a
##### Return Value
[int](http://en.cppreference.com/w/cpp/language/types) representing rule processing priority.
##### Exceptions
n/a
#### Rule::set_priority
```C++
void set_priority( const int value );
```
Alter rule's processing priority.
##### Parameters
| name | type | default value | direction |
|:----------:|----------------------------------------------------------------|:-------------:|:---------:|
| value | [int](http://en.cppreference.com/w/cpp/language/types) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
### Service
The service is responsible for managing the publicly available RESTful resources, HTTP compliance, scheduling of the socket data and insuring incoming requests are processed in a timely fashion.
#### Methods
- [constructor](#serviceconstructor)
- [destructor](#servicedestructor)
- [is_up](#serviceis_up)
- [is_down](#serviceis_down)
- [stop](#servicestop)
- [start](#servicestart)
- [restart](#servicerestart)
- [add_rule](#serviceadd_rule)
- [publish](#servicepublish)
- [suppress](#servicesuppress)
- [schedule](#serviceschedule)
- [get_uptime](#serviceget_uptime)
- [get_http_uri](#serviceget_http_uri)
- [get_https_uri](#serviceget_https_uri)
- [set_logger](#serviceset_logger)
- [set_session_manager](#serviceset_session_manager)
- [set_ready_handler](#serviceset_ready_handler)
- [set_signal_handler](#serviceset_signal_handler)
- [set_not_found_handler](#serviceset_not_found_handler)
- [set_method_not_allowed_handler](#serviceset_method_not_allowed_handler)
- [set_method_not_implemented_handler](#serviceset_method_not_implemented_handler)
- [set_failed_filter_validation_handler](#serviceset_failed_filter_validation_handler)
- [set_error_handler](#serviceset_error_handler)
- [set_authentication_handler](#serviceset_authentication_handler)
#### Service::constructor
```C++
Resource( void );
```
Initialises a new class instance; see also [destructor](#servicedestructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
n/a
#### Service::destructor
```C++
virtual ~Service( void );
```
Clean-up class instance; see also [constructor](#serviceconstructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Service::is_up
```C++
bool is_up( void ) const;
```
Return boolean value indicating if the service is currently online and serving incoming requests.
##### Parameters
n/a
##### Return Value
Boolean true if the service is online, else false.
##### Exceptions
n/a
#### Service::is_down
```C++
bool is_down( void ) const;
```
Return boolean value indicating if the service is currently offline and serving incoming requests.
##### Parameters
n/a
##### Return Value
Boolean true if the service is offline, else false.
##### Exceptions
n/a
#### Service::stop
```C++
void stop( void ) const;
```
Shut the service down, closing open sessions and terminating threads that may be running.
##### Parameters
n/a
##### Return Value
Boolean true if the service is offline, else false.
##### Exceptions
n/a
#### Service::start
```C++
void start( const std::shared_ptr< const Settings >& settings = nullptr );
```
Start the service with the supplied settings, otherwise default values will be set.
##### Parameters
| name | type | default value | direction |
|:----------:|-----------------------------------------------------------------------|:-------------:|:---------:|
| settings | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Service::restart
```C++
void restart( const std::shared_ptr< const Settings >& settings = nullptr );
```
Restart the service with the supplied settings, otherwise default values will be set.
##### Parameters
| name | type | default value | direction |
|:----------:|-----------------------------------------------------------------------|:-------------:|:---------:|
| settings | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Service::add_rule
```C++
void add_rule( const std::shared_ptr< Rule >& rule );
void add_rule( const std::shared_ptr< Rule >& rule, const int priority );
```
Add incoming request processing rule; see also [Rule](#rule).
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------|:-------------:|:---------:|
| rule | [Rule](#rule) | n/a | input |
| priority | [int](http://en.cppreference.com/w/cpp/types/integer) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Service::publish
```C++
void publish( const std::shared_ptr< const Resource >& resource );
```
Publish a RESTful resource for public consumption; see also [Resource](#resource).
##### Parameters
| name | type | default value | direction |
|:----------:|-----------------------------------------------------------------------|:-------------:|:---------:|
| resource | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Service::suppress
```C++
void suppress( const std::shared_ptr< const Resource >& resource );
```
Suppress an already published RESTful resource; see also [Resource](#resource).
##### Parameters
| name | type | default value | direction |
|:----------:|-----------------------------------------------------------------------|:-------------:|:---------:|
| resource | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Service::schedule
```C++
void schedule( const std::function< void ( void ) >& task, const std::chrono::milliseconds& interval = std::chrono::milliseconds::zero( ) );
```
Place a task on the services event loop for future processing. If an interval is supplied the task will be continual queued with the specified delay.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| task | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
| interval | [std::chrono::milliseconds](http://en.cppreference.com/w/cpp/chrono/duration) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Service::get_uptime
```C++
const std::chrono::seconds get_uptime( void ) const;
```
Return the number of seconds that have passed since the service was brought online.
##### Parameters
n/a
##### Return Value
Number of seconds since calling [start](#servicestart).
##### Exceptions
n/a
#### Service::get_http_uri
```C++
const std::shared_ptr< const Uri > get_http_uri( void ) const;
```
Return a URI representing the HTTP endpoint; see also [URI](#uri).
##### Parameters
n/a
##### Return Value
URI representing HTTP endpoint.
##### Exceptions
n/a
#### Service::get_https_uri
```C++
const std::shared_ptr< const Uri > get_https_uri( void ) const;
```
Return a URI representing the HTTPS endpoint; see also [URI](#uri).
##### Parameters
n/a
##### Return Value
URI representing HTTPS endpoint.
##### Exceptions
n/a
#### Service::set_logger
```C++
void set_logger( const std::shared_ptr< Logger >& value );
```
Set the logger instance to be used; see also [Logger](#logger).
##### Parameters
| name | type | default value | direction |
|:----------:|-----------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Service::set_session_manager
```C++
void set_session_manager( const std::shared_ptr< SessionManager >& value );
```
Set the manager to use for the creation, loading, and purging of HTTP sessions; see also [Session Manager](#sessionmanager).
##### Parameters
| name | type | default value | direction |
|:----------:|-----------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Service::set_ready_handler
```C++
void set_ready_handler( const std::function< void ( Service& ) >& value );
```
Set a handler to be invoked once the service is up and ready to serve incoming HTTP requests.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Service::set_signal_handler
```C++
void set_signal_handler( const int signal, const std::function< void ( const int ) >& value );
```
Set a handler for the specified system signal number.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| signal | [int](http://en.cppreference.com/w/cpp/types/integer) | n/a | input |
| value | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Service::set_not_found_handler
```C++
void set_not_found_handler( const std::function< void ( const std::shared_ptr< Session > ) >& value );
```
If an incoming HTTP request cannot be matched a known resource its session will be handed over to the resource not found handler.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Service::set_method_not_allowed_handler
```C++
void set_method_not_allowed_handler( const std::function< void ( const std::shared_ptr< Session > ) >& value );
```
If an incoming HTTP request cannot be matched a known resource method handler its session will be routed over to the method not found handler.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Service::set_method_not_implemented_handler
```C++
void set_method_not_implemented_handler( const std::function< void ( const std::shared_ptr< Session > ) >& value );
```
If none of the service resources have a handler for an incoming HTTP request method its session shall be routed to the method not implemented handler.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Service::set_failed_filter_validation_handler
```C++
void set_failed_filter_validation_handler( const std::function< void ( const std::shared_ptr< Session > ) >& value );
```
If a resource has filters applied to one or more of it's endpoints but has no specific failed filter validation handler, the global service handler will be invoked if set.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Service::set_error_handler
```C++
void set_error_handler( const std::function< void ( const int, const std::exception&, const std::shared_ptr< Session > ) >& value );
```
If an error occurs during processing and no resource specific error handler can be obtained, the global service error handler will be invoked if set.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Service::set_authentication_handler
```C++
void set_authentication_handler( const std::function< void ( const std::shared_ptr< Session >, const std::function< void ( const std::shared_ptr< Session > ) >& ) >& value );
```
Set a service wide authentication handler before invoking resource specific authentication handlers.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
### Session
Represents a conversation between a client and the service. Internally this class holds the network state and exposes public functionality to interact with the service event-loop for asynchronous data acquisition and/or sleep states.
#### Methods
- [constructor](#sessionconstructor)
- [destructor](#sessiondestructor)
- [has](#sessionhas)
- [erase](#sessionerase)
- [keys](#sessionkeys)
- [is_open](#sessionis_open)
- [is_closed](#sessionis_closed)
- [close](#sessionclose)
- [yield](#sessionyield)
- [fetch](#sessionfetch)
- [upgrade](#sessionupgrade)
- [sleep_for](#sessionsleep_for)
- [get_id](#sessionget_id)
- [get_origin](#sessionget_origin)
- [get_destination](#sessionget_destination)
- [get_request](#sessionget_request)
- [get_resource](#sessionget_resource)
- [get_headers](#sessionget_headers)
- [get](#sessionget)
- [set_id](#sessionset_id)
- [set](#sessionset)
- [add_header](#sessionadd_header)
- [set_header](#sessionset_header)
- [set_headers](#sessionset_headers)
#### Session::constructor
```C++
Session( const std::string& id );
```
Initialises a new class instance; see also [destructor](#sessiondestructor).
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Session::destructor
```C++
virtual ~Session( void );
```
Clean-up class instance; see also [constructor](#sessionconstructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Session::has
```C++
bool has( const std::string& name ) const;
```
Test if a session has session-data under the supplied name.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
Boolean true if the data is available.
##### Exceptions
n/a
#### Session::erase
```C++
void erase( const std::string& name = "" );
```
If session-data is available under the supplied name it is removed. If name is empty all data is erased.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Session::keys
```C++
const std::set< std::string > keys( void ) const;
```
Return a collection of session-data keys.
##### Parameters
n/a
##### Return Value
Collection of valid session-data keys.
##### Exceptions
n/a
#### Session::is_open
```C++
bool is_open( void ) const;
```
Return the status of the underlying Session socket.
##### Parameters
n/a
##### Return Value
Boolean true if the session is active.
##### Exceptions
n/a
#### Session::is_closed
```C++
bool is_closed( void ) const;
```
Return the status of the underlying Session socket.
##### Parameters
n/a
##### Return Value
Boolean true if the session is inactive.
##### Exceptions
n/a
#### Session::close
```C++
void close( const Bytes& body );
void close( const Response& response );
void close( const std::string& body = "" );
void close( const int status, const Bytes& body );
void close( const int status, const std::string& body = "" );
void close( const int status, const std::multimap< std::string, std::string >& headers );
void close( const int status, const std::string& body, const std::multimap< std::string, std::string >& headers );
void close( const int status, const Bytes& body, const std::multimap< std::string, std::string >& headers );
```
Close an active session returning a tailored HTTP response based on the supplied parameters.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| status | [int](http://en.cppreference.com/w/cpp/types/integer) | n/a | input |
| body | [Bytes](#bytebytes) | n/a | input |
| body | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| headers | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap)| n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Session::yield
```C++
void yield( const Bytes& data, const std::function< void ( const std::shared_ptr< Session > ) >& callback = nullptr );
void yield( const std::string& data, const std::function< void ( const std::shared_ptr< Session > ) >& callback = nullptr );
void yield( const Response& response, const std::function< void ( const std::shared_ptr< Session > ) >& callback = nullptr );
void yield( const int status, const std::string& body, const std::function< void ( const std::shared_ptr< Session > ) >& callback = nullptr );
void yield( const int status, const Bytes& body = { }, const std::function< void ( const std::shared_ptr< Session > ) >& callback = nullptr );
void yield( const int status, const std::multimap< std::string, std::string >& headers, const std::function< void ( const std::shared_ptr< Session > ) >& callback = nullptr );
void yield( const int status, const Bytes& body, const std::multimap< std::string, std::string >& headers, const std::function< void ( const std::shared_ptr< Session > ) >& callback = nullptr );
void yield( const int status, const std::string& body, const std::multimap< std::string, std::string >& headers, const std::function< void ( const std::shared_ptr< Session > ) >& callback = nullptr );
```
Return a tailored HTTP response based on the supplied parameters without closing the underlying socket connection; On completion invoke the callback.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| status | [int](http://en.cppreference.com/w/cpp/types/integer) | n/a | input |
| body | [Bytes](#bytebytes) | n/a | input |
| body | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| headers | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap) | n/a | input |
| callback | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Session::fetch
```C++
void fetch( const std::size_t length, const std::function< void ( const std::shared_ptr< Session >, const Bytes& ) >& callback );
void fetch( const std::string& delimiter, const std::function< void ( const std::shared_ptr< Session >, const Bytes& ) >& callback );
```
1) Fetch length bytes from the underlying socket connection.
2) Fetch bytes from the underlying socket connection until encountering the delimiter.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| length | [std::size_t](http://en.cppreference.com/w/cpp/types/size_t) | n/a | input |
| delimiter | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| callback | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Session::upgrade
```C++
void upgrade( const int status, const std::function< void ( const std::shared_ptr< WebSocket > ) >& callback );
void upgrade( const int status, const Bytes& body, const std::function< void ( const std::shared_ptr< WebSocket > ) >& callback );
void upgrade( const int status, const std::string& body, const std::function< void ( const std::shared_ptr< WebSocket > ) >& callback );
void upgrade( const int status, const std::multimap< std::string, std::string >& headers, const std::function< void ( const std::shared_ptr< WebSocket > ) >& callback );
void upgrade( const int status, const Bytes& body, const std::multimap< std::string, std::string >& headers, const std::function< void ( const std::shared_ptr< WebSocket > ) >& callback );
void upgrade( const int status, const std::string& body, const std::multimap< std::string, std::string >& headers, const std::function< void ( const std::shared_ptr< WebSocket > ) >& callback );
```
Return a tailored HTTP response based on the supplied parameters and upgrade to the WebSocket protocol; On completion invoke the callback.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| status | [int](http://en.cppreference.com/w/cpp/types/integer) | n/a | input |
| body | [Bytes](#bytebytes) | n/a | input |
| body | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| headers | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap) | n/a | input |
| callback | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Session::sleep_for
```C++
void sleep_for( const std::chrono::milliseconds& delay, const std::function< void ( const std::shared_ptr< Session > ) >& callback );
```
Place a task on the [Service](#service) event loop to be run in delay milliseconds.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| delay | [std::chrono::milliseconds](http://en.cppreference.com/w/cpp/chrono/duration) | n/a | input |
| callback | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Session::get_id
```C++
const std::string& get_id( void ) const;
```
Return a string uniquely identifying this session instance.
##### Parameters
n/a
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/utility/functional/function) representing a unique session identifier.
##### Exceptions
n/a
#### Session::get_origin
```C++
const std::string get_origin( void ) const;
```
Return a string representing an Internet Protocol address and port number identifying the source of the current HTTP request.
##### Parameters
n/a
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/utility/functional/function) representing the source network endpoint.
##### Exceptions
n/a
#### Session::get_destination
```C++
const std::string get_destination( void ) const;
```
Return a string representing an Internet Protocol address and port number identifying the original destination of the current HTTP request.
##### Parameters
n/a
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/utility/functional/function) representing a destination network endpoint.
##### Exceptions
n/a
#### Session::get_request
```C++
const std::shared_ptr< const Request > get_request( void ) const;
```
Return the currently active HTTP request.
##### Parameters
n/a
##### Return Value
[std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) representing a HTTP request.
##### Exceptions
n/a
#### Session::get_resource
```C++
const std::shared_ptr< const Resource > get_resource( void ) const;
```
Return the currently active RESTful resource.
##### Parameters
n/a
##### Return Value
[std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) representing a HTTP request.
##### Exceptions
n/a
#### Session::get_headers
```C++
const std::multimap< std::string, std::string >& get_headers( void ) const;
```
Return the default session header that must be present on each HTTP response.
##### Parameters
n/a
##### Return Value
[std::multimap](http://en.cppreference.com/w/cpp/container/multimap) representing a collection of HTTP headers.
##### Exceptions
n/a
#### Session::get
```C++
const ContextValue& get( const std::string& name ) const;
const ContextValue& get( const std::string& name, const ContextValue& default_value ) const;
```
Return the session data identified by name.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| value | [std::any](http://en.cppreference.com/w/cpp/utility/any) | n/a | input |
##### Return Value
[std::any](http://en.cppreference.com/w/cpp/utility/any) session data item.
##### Exceptions
n/a
#### Session::set_id
```C++
void set_id( const std::string& value );
```
Set a unique session identifier.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
[std::any](http://en.cppreference.com/w/cpp/utility/any) session data item.
##### Exceptions
n/a
#### Session::set
```C++
void set( const std::string& name, const ContextValue& value );
```
Set a unique session identifier.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| value | [std::any](http://en.cppreference.com/w/cpp/utility/any) | n/a | input |
##### Return Value
[std::any](http://en.cppreference.com/w/cpp/utility/any) session data item.
##### Exceptions
n/a
#### Session::add_header
```C++
void add_header( const std::string& name, const std::string& value );
```
Add a default HTTP header to the session, existing headers that share the same name will not be altered.
##### Parameters
| name | type | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Session::set_header
```C++
void set_header( const std::string& name, const std::string& value );
```
Set a default HTTP header for the session, existing headers that share the same name will be erased.
##### Parameters
| name | type | default value | direction |
|:-----:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Session::set_headers
```C++
void set_headers( const std::multimap< std::string, std::string >& values );
```
Set default HTTP headers for the session, existing headers will be erased; see also [get_headers](#sessionget_headers).
##### Parameters
| name | type | default value | direction |
|:------:|----------------------------------------------------------------------|:-------------:|:---------:|
| values | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
### SessionManager
Abstract Class detailing the required contract for SessionManager extensions. No default implementation is supplied with the codebase and it is the responsibility of third-party developers to implement desired characteristics.
#### Methods
- [constructor](#sessionmanagerconstructor)
- [destructor](#sessionmanagerdestructor)
- [stop](#sessionmanagerstop)
- [start](#sessionmanagerstart)
- [create](#sessionmanagercreate)
- [load](#sessionmanagerload)
- [save](#sessionmanagersave)
#### SessionManager::constructor
```C++
SessionManager( void );
```
Initialises a new class instance; see also [destructor](#sessionmanagerdestructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
n/a
#### SessionManager::destructor
```C++
virtual ~SessionManager( void );
```
Clean-up class instance; see also [constructor](#sessionmanagerconstructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### SessionManager::stop
```C++
virtual void stop( void );
```
Shutdown an active SessionManager.
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
n/a
#### SessionManager::start
```C++
virtual void start( const std::shared_ptr< const Settings >& settings );
```
Start the Session Manager, the settings supplied are identical to those given to [Service::start](servicestart).
##### Parameters
| name | type | default value | direction |
|:------:|-------------------------------------------------------------------------|:-------------:|:---------:|
| settings | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SessionManager::create
```C++
virtual void create( const std::function< void ( const std::shared_ptr< Session > ) >& callback );
```
Create a new [Session](#session) instance passing it into callback.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| callback | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SessionManager::load
```C++
virtual void load( const std::shared_ptr< Session > session, const std::function< void ( const std::shared_ptr< Session > ) >& callback );
```
Load previous session data into the supplied session before passing it to callback.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| session | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) | n/a | input |
| callback | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SessionManager::save
```C++
virtual void save( const std::shared_ptr< Session > session, const std::function< void ( const std::shared_ptr< Session > ) >& callback );
```
Save session for later retrieval.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| session | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) | n/a | input |
| callback | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
### Settings
Represents service configuration.
#### Methods
- [constructor](#settingsconstructor)
- [destructor](#settingsdestructor)
- [get_port](#settingsget_port)
- [get_root](#settingsget_root)
- [get_worker_limit](#settingsget_worker_limit)
- [get_connection_limit](#settingsget_connection_limit)
- [get_bind_address](#settingsget_bind_address)
- [get_case_insensitive_uris](#settingsget_case_insensitive_uris)
- [get_connection_timeout](#settingsget_connection_timeout)
- [get_status_message](#settingsget_status_message)
- [get_status_messages](#settingsget_status_messages)
- [get_property](#settingsget_property)
- [get_properties](#settingsget_properties)
- [get_ssl_settings](#settingsget_ssl_settings)
- [get_default_headers](#settingsget_default_headers)
- [set_port](#settingsset_port)
- [set_root](#settingsset_root)
- [set_worker_limit](#settingsset_worker_limit)
- [set_connection_limit](#settingsset_connection_limit)
- [set_bind_address](#settingsset_bind_address)
- [set_case_insensitive_uris](#settingsset_case_insensitive_uris)
- [set_connection_timeout](#settingsset_connection_timeout)
- [set_status_message](#settingsset_status_message)
- [set_status_messages](#settingsset_status_messages)
- [set_property](#settingsset_property)
- [set_properties](#settingsset_properties)
- [set_ssl_settings](#settingsset_ssl_settings)
- [set_default_header](#settingsset_default_header)
- [set_default_headers](#settingsset_default_headers)
#### Settings::constructor
```C++
Settings( void );
```
Initialises a new class instance; see also [destructor](#settingsdestructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
n/a
#### Settings::destructor
```C++
virtual ~Settings( void );
```
Clean-up class instance; see also [constructor](#settingsconstructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Settings::get_port
```C++
uint16_t get_port( void ) const;
```
Retrieves the network port number which the service will listen on.
##### Parameters
n/a
##### Return Value
[uint16_t](http://en.cppreference.com/w/cpp/types/integer) representing the network port number.
##### Exceptions
n/a
#### Settings::get_root
```C++
std::string get_root( void ) const;
```
Retrieves the base path for all resource paths.
##### Parameters
n/a
##### Return Value
[uint16_t](http://en.cppreference.com/w/cpp/types/integer) representing the base resource path.
##### Exceptions
n/a
#### Settings::get_worker_limit
```C++
unsigned int get_worker_limit( void ) const;
```
Retrieves the number to workers (threads) used for processing incoming requests.
##### Parameters
n/a
##### Return Value
[unsigned integer](http://en.cppreference.com/w/cpp/language/types) detailing the number of service workers.
##### Exceptions
n/a
#### Settings::get_connection_limit
```C++
unsigned int get_connection_limit( void ) const;
```
Retrieves the number of allowed pending socket connections.
##### Parameters
n/a
##### Return Value
[unsigned integer](http://en.cppreference.com/w/cpp/language/types) detailing the number of allowed pending socket connections.
##### Exceptions
n/a
#### Settings::get_bind_address
```C++
std::string get_bind_address( void ) const;
```
Retrieves the local network interface card address to attach the service.
##### Parameters
n/a
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) detailing the service bind address.
##### Exceptions
n/a
#### Settings::get_case_insensitive_uris
```C++
bool get_case_insensitive_uris( void ) const;
```
Retrieves a boolean value indicating if the service should use case insensitive Uris.
##### Parameters
n/a
##### Return Value
[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating case insensitive Uri processing.
##### Exceptions
n/a
#### Settings::get_connection_timeout
```C++
std::chrono::milliseconds get_connection_timeout( void ) const;
```
Retrieves the number of milliseconds before an inactive socket is forcefully closed.
##### Parameters
n/a
##### Return Value
[Milliseconds](http://en.cppreference.com/w/cpp/chrono/duration) detailing when to close an inactive socket.
##### Exceptions
n/a
#### Settings::get_status_message
```C++
std::string get_status_message( const int code ) const;
```
Retrieves the HTTP status message associated with the supplied status code.
##### Parameters
| name | type | default value | direction |
|:----------:|--------------------------------------------------------|:-------------:|:---------:|
| code | [int](http://en.cppreference.com/w/cpp/language/types) | n/a | input |
##### Return Value
HTTP status message as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string).
##### Exceptions
n/a
#### Settings::get_status_messages
```C++
std::map< int, std::string > get_status_messages( void ) const;
```
Retrieves the HTTP status messages.
##### Parameters
n/a
##### Return Value
[std::map](http://en.cppreference.com/w/cpp/container/map) containing the known HTTP status messages.
##### Exceptions
n/a
#### Settings::get_property
```C++
std::string get_property( const std::string& name ) const;
```
Retrieves a string property with the supplied name if it exists, otherwise an empty string will be returned.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) property value.
##### Exceptions
n/a
#### Settings::get_properties
```C++
std::map< std::string, std::string > get_properties( void ) const;
```
Retrieves all setting properties.
##### Parameters
n/a
##### Return Value
[std::map](http://en.cppreference.com/w/cpp/container/map) containing the known settings.
##### Exceptions
n/a
#### Settings::get_ssl_settings
```C++
std::shared_ptr< const SSLSettings > get_ssl_settings( void ) const;
```
Retrieves Secure Socket Layer settings.
##### Parameters
n/a
##### Return Value
[SSLSettings](#sslsettings) detailing SSL configuration.
##### Exceptions
n/a
#### Settings::get_default_headers
```C++
std::multimap< std::string, std::string > get_default_headers( void ) const;
```
Retrieves all known default response headers.
##### Parameters
n/a
##### Return Value
[std::multimap](http://en.cppreference.com/w/cpp/container/multimap) containing all known default response headers.
##### Exceptions
n/a
#### Settings::set_port
```C++
void set_port( const uint16_t value );
```
Set the network port which the service should listen for incoming HTTP requests.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [uint16_t](http://en.cppreference.com/w/cpp/types/integer) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Settings::set_root
```C++
void set_root( const std::string& value );
```
Set the base resource path, this value is prepended to all resource paths.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Settings::set_worker_limit
```C++
void set_worker_limit( const unsigned int value );
```
Set the number of threads available for incoming HTTP request processing.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [unsigned integer](http://en.cppreference.com/w/cpp/language/types) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Settings::set_connection_limit
```C++
void set_connection_limit( const unsigned int value );
```
Set the number of allowed pending connections.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [unsigned integer](http://en.cppreference.com/w/cpp/language/types) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Settings::set_bind_address
```C++
void set_bind_address( const std::string& value );
```
Set network interface card address with which the service should attach itself.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Settings::set_case_insensitive_uris
```C++
void set_case_insensitive_uris( const bool value );
```
Set true for case insensitive Uri handling.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [bool](http://en.cppreference.com/w/c/types/boolean) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Settings::set_connection_timeout
```C++
void set_connection_timeout( const std::chrono::seconds& value );
void set_connection_timeout( const std::chrono::milliseconds& value );
```
Set the duration before forcefully closing inactive socket connections.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [seconds](http://en.cppreference.com/w/cpp/chrono/duration) | n/a | input |
| value | [milliseconds](http://en.cppreference.com/w/cpp/chrono/duration) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Settings::set_status_message
```C++
void set_status_message( const int code, const std::string& message );
```
Associate a HTTP status message with a HTTP status code.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| code | [integer](http://en.cppreference.com/w/cpp/language/types) | n/a | input |
| message | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Settings::set_status_messages
```C++
void set_status_messages( const std::map< int, std::string >& values );
```
Set HTTP status message/status code mappings.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| values | [std::map](http://en.cppreference.com/w/cpp/container/map) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Settings::set_property
```C++
void set_property( const std::string& name, const std::string& value );
```
Set a string property value with the associated name.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Settings::set_properties
```C++
void set_properties( const std::map< std::string, std::string >& values );
```
Set multiple property values.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| values | [std::map](http://en.cppreference.com/w/cpp/container/map) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Settings::set_ssl_settings
```C++
void set_ssl_settings( const std::shared_ptr< const SSLSettings >& value );
```
Set Secure Socket Layer configuration.
##### Parameters
| name | type | default value | direction |
|:----------:|--------------------------------------|:-------------:|:---------:|
| value | [SSLSettings](#sslsettings) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Settings::set_default_header
```C++
void set_default_header( const std::string& name, const std::string& value );
```
Set a default header value that must be returned for each HTTP request response.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### Settings::set_default_headers
```C++
void set_default_headers( const std::multimap< std::string, std::string >& values );
```
Set multiple default header values that must be returned for each HTTP request response.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| name | [std::multimap](http://en.cppreference.com/w/cpp/container/multimap)| n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
### SSLSettings
Represents Secure Socket Layer configuration.
#### Methods
- [constructor](#sslsettingsconstructor)
- [destructor](#sslsettingsdestructor)
- [has_disabled_http](#sslsettingshas_disabled_http)
- [has_enabled_sslv2](#sslsettingshas_enabled_sslv2)
- [has_enabled_sslv3](#sslsettingshas_enabled_sslv3)
- [has_enabled_tlsv1](#sslsettingshas_enabled_tlsv1)
- [has_enabled_tlsv11](#sslsettingshas_enabled_tlsv11)
- [has_enabled_tlsv12](#sslsettingshas_enabled_tlsv12)
- [has_enabled_compression](#sslsettingshas_enabled_compression)
- [has_enabled_default_workarounds](#sslsettingshas_enabled_default_workarounds)
- [has_enabled_single_diffie_hellman_use](#sslsettingshas_enabled_single_diffie_hellman_use)
- [get_port](#sslsettingsget_port)
- [get_bind_address](#sslsettingsget_bind_address)
- [get_certificate](#sslsettingsget_certificate)
- [get_passphrase](#sslsettingsget_passphrase)
- [get_private_key](#sslsettingsget_private_key)
- [get_private_rsa_key](#sslsettingsget_private_rsa_key)
- [get_certificate_chain](#sslsettingsget_certificate_chain)
- [get_temporary_diffie_hellman](#sslsettingsget_temporary_diffie_hellman)
- [get_certificate_authority_pool](#sslsettingsget_certificate_authority_pool)
- [set_port](#sslsettingsset_port)
- [set_bind_address](#sslsettingsset_bind_address)
- [set_http_disabled](#sslsettingsset_http_disabled)
- [set_sslv2_enabled](#sslsettingsset_sslv2_enabled)
- [set_sslv3_enabled](#sslsettingsset_sslv3_enabled)
- [set_tlsv1_enabled](#sslsettingsset_tlsv1_enabled)
- [set_tlsv11_enabled](#sslsettingsset_tlsv11_enabled)
- [set_tlsv12_enabled](#sslsettingsset_tlsv12_enabled)
- [set_compression_enabled](#sslsettingsset_compression_enabled)
- [set_default_workarounds_enabled](#sslsettingsset_default_workarounds_enabled)
- [set_certificate](#sslsettingsset_certificate)
- [set_certificate_authority_pool](#sslsettingsset_certificate_authority_pool)
- [set_passphrase](#sslsettingsset_passphrase)
- [set_private_key](#sslsettingsset_private_key)
- [set_private_rsa_key](#sslsettingsset_private_rsa_key)
- [set_temporary_diffie_hellman](#sslsettingsset_temporary_diffie_hellman)
#### SSLSettings::constructor
```C++
SSLSettings( void );
```
Initialises a new class instance; see also [destructor](#sslsettingsdestructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::destructor
```C++
virtual ~SSLSettings( void );
```
Clean-up class instance; see also [constructor](#sslsettingsconstructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### SSLSettings::has_disabled_http
```C++
bool has_disabled_http( void ) const;
```
Determine if HTTP has been disabled and that the service should only listen for incoming HTTPS requests.
##### Parameters
n/a
##### Return Value
[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating that HTTP has been disabled.
##### Exceptions
n/a
#### SSLSettings::has_enabled_sslv2
```C++
bool has_enabled_sslv2( void ) const;
```
Determine if SSLv2 has been enabled.
##### Parameters
n/a
##### Return Value
[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating SSLv2 is enabled.
##### Exceptions
n/a
#### SSLSettings::has_enabled_sslv3
```C++
bool has_enabled_sslv3( void ) const;
```
Determine if SSLv3 has been enabled.
##### Parameters
n/a
##### Return Value
[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating SSLv3 is enabled.
##### Exceptions
n/a
#### SSLSettings::has_enabled_tlsv1
```C++
bool has_enabled_tlsv1( void ) const;
```
Determine if TLSv1 has been enabled.
##### Parameters
n/a
##### Return Value
[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating TLSv1 is enabled.
##### Exceptions
n/a
#### SSLSettings::has_enabled_tlsv11
```C++
bool has_enabled_tlsv11( void ) const;
```
Determine if TLSv1.1 has been enabled.
##### Parameters
n/a
##### Return Value
[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating TLSv1.1 is enabled.
##### Exceptions
n/a
#### SSLSettings::has_enabled_tlsv12
```C++
bool has_enabled_tlsv12( void ) const;
```
Determine if TLSv1.2 has been enabled.
##### Parameters
n/a
##### Return Value
[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating TLSv1.2 is enabled.
##### Exceptions
n/a
#### SSLSettings::has_enabled_compression
```C++
bool has_enabled_compression( void ) const;
```
Determine if compression has been enabled.
##### Parameters
n/a
##### Return Value
[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating compression is enabled.
##### Exceptions
n/a
#### SSLSettings::has_enabled_default_workarounds
```C++
bool has_enabled_default_workarounds( void ) const;
```
Determine if default workarounds is enabled.
##### Parameters
n/a
##### Return Value
[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating default workaround enabled.
##### Exceptions
n/a
#### SSLSettings::has_enabled_single_diffie_hellman_use
```C++
bool has_enabled_single_diffie_hellman_use( void ) const;
```
Determine if single diffie hellman use is enabled.
##### Parameters
n/a
##### Return Value
[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating single diffie hellman use.
##### Exceptions
n/a
#### SSLSettings::get_port
```C++
uint16_t get_port( void ) const;
```
Retrieves the network port number which the service will listen on.
##### Parameters
n/a
##### Return Value
[uint16_t](http://en.cppreference.com/w/cpp/types/integer) representing the network port number.
##### Exceptions
n/a
#### SSLSettings::get_bind_address
```C++
std::string get_bind_address( void ) const;
```
Retrieves the local network interface card address to attach the service.
##### Parameters
n/a
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) detailing the service bind address.
##### Exceptions
n/a
#### SSLSettings::get_certificate
```C++
std::string get_certificate( void ) const;
```
Retrieves filename of SSL certificate.
##### Parameters
n/a
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) certificate filename.
##### Exceptions
n/a
#### SSLSettings::get_passphrase
```C++
std::string get_passphrase( void ) const;
```
Retrieves SSL certificate passphrase.
##### Parameters
n/a
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) certificate passphrase.
##### Exceptions
n/a
#### SSLSettings::get_private_key
```C++
std::string get_private_key( void ) const;
```
Retrieves filename to private key.
##### Parameters
n/a
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) private key filename.
##### Exceptions
n/a
#### SSLSettings::get_private_rsa_key
```C++
std::string get_private_rsa_key( void ) const;
```
Retrieves filename to RSA private key.
##### Parameters
n/a
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) certificate filename.
##### Exceptions
n/a
#### SSLSettings::get_certificate_chain
```C++
std::string get_certificate_chain( void ) const;
```
Retrieves filename to certificate chain.
##### Parameters
n/a
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) certificate chain filename.
##### Exceptions
n/a
#### SSLSettings::get_temporary_diffie_hellman
```C++
std::string get_temporary_diffie_hellman( void ) const;
```
Retrieves filename to temporary diffie hellman.
##### Parameters
n/a
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) diffie hellman filename.
##### Exceptions
n/a
#### SSLSettings::get_certificate_authority_pool
```C++
std::string get_certificate_authority_pool( void ) const;
```
Retrieves filename to certificate authority pool.
##### Parameters
n/a
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) diffie hellman filename.
##### Exceptions
n/a
#### SSLSettings::set_port
```C++
void set_port( const uint16_t value );
```
Set the network port which the service should listen for incoming HTTPS requests.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [uint16_t](http://en.cppreference.com/w/cpp/types/integer) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_bind_address
```C++
void set_bind_address( const std::string& value );
```
Set network interface card address with which the service should attach itself.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_http_disabled
```C++
void set_http_disabled( const bool value );
```
Set true to disable unencrypted HTTP service access.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [bool](http://en.cppreference.com/w/c/types/boolean) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_sslv2_enabled
```C++
void set_sslv2_enabled( const bool value );
```
Set true to enabled SSLv2.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [bool](http://en.cppreference.com/w/c/types/boolean) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_sslv3_enabled
```C++
void set_sslv3_enabled( const bool value );
```
Set true to enabled SSLv3.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [bool](http://en.cppreference.com/w/c/types/boolean) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_tlsv1_enabled
```C++
void set_tlsv1_enabled( const bool value );
```
Set true to enabled TLSv1.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [bool](http://en.cppreference.com/w/c/types/boolean) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_tlsv11_enabled
```C++
void set_tlsv11_enabled( const bool value );
```
Set true to enabled TLSv1.1.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [bool](http://en.cppreference.com/w/c/types/boolean) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_tlsv12_enabled
```C++
void set_tlsv12_enabled( const bool value );
```
Set true to enabled TLSv1.2.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [bool](http://en.cppreference.com/w/c/types/boolean) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_compression_enabled
```C++
void set_compression_enabled( const bool value );
```
Set true to enabled compression.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [bool](http://en.cppreference.com/w/c/types/boolean) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_default_workarounds_enabled
```C++
void set_default_workarounds_enabled( const bool value );
```
Set true to enabled default workarounds.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [bool](http://en.cppreference.com/w/c/types/boolean) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_single_diffie_hellman_use_enabled
```C++
void set_single_diffie_hellman_use_enabled( const bool value );
```
Set true to enabled single diffie hellman use.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [bool](http://en.cppreference.com/w/c/types/boolean) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_certificate
```C++
void set_certificate( const Uri& value );
```
Set filename to SSL certificate.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------|:-------------:|:---------:|
| value | [Uri](#uri) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_certificate_chain
```C++
void set_certificate_chain( const Uri& value );
```
Set filename to SSL certificate chain.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------|:-------------:|:---------:|
| value | [Uri](#uri) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_certificate_authority_pool
```C++
void set_certificate_authority_pool( const Uri& value );
```
Set filename to SSL certificate authority pool.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------|:-------------:|:---------:|
| value | [Uri](#uri) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_passphrase
```C++
void set_passphrase( const std::string& value );
```
Set filename to SSL certificate passphrase.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_private_key
```C++
void set_private_key( const Uri& value );
```
Set filename to SSL private key.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------|:-------------:|:---------:|
| value | [Uri](#uri) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_private_rsa_key
```C++
void set_private_rsa_key( const Uri& value );
```
Set filename to SSL private RSA key.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------|:-------------:|:---------:|
| value | [Uri](#uri) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### SSLSettings::set_temporary_diffie_hellman
```C++
void set_temporary_diffie_hellman( const Uri& value );
```
Set filename to temporary diffie hellman.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------|:-------------:|:---------:|
| value | [Uri](#uri) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
### StatusCode
[Enumeration](http://en.cppreference.com/w/cpp/language/enum) of HTTP response status codes as outlined in [RFC 7231 sub-section 6.1](https://tools.ietf.org/html/rfc7231#section-6.1).
### Uri
Represents a Uniform Resource Identifier as specified in RFC 3986.
#### Methods
- [constructor](#uriconstructor)
- [destructor](#uridestructor)
- [is_relative](#uriis_relative)
- [is_absolute](#uriis_absolute)
- [to_string](#urito_string)
- [is_valid](#uriis_valid)
- [parse](#uriparse)
- [decode](#uridecode)
- [decode_parameter](#uridecode_parameter)
- [encode](#uriencode)
- [encode_parameter](#uriencode_parameter)
- [get_port](#uriget_port)
- [get_path](#uriget_path)
- [get_query](#uriget_query)
- [get_scheme](#uriget_scheme)
- [get_fragment](#uriget_fragment)
- [get_username](#uriget_username)
- [get_password](#uriget_password)
- [get_authority](#uriget_authority)
- [get_query_parameters](#uriget_query_parameters)
#### Uri::constructor
```C++
explicit Uri( const std::string& value, bool relative = false );
Uri( const Uri& original );
```
Initialises a new class instance; see also [destructor](#uridestructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
n/a
#### Uri::destructor
```C++
virtual ~Uri( void );
```
Clean-up class instance; see also [constructor](#uriconstructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### Uri::is_relative
```C++
bool is_relative( void ) const;
```
Determines if the Uri is a relative path.
##### Parameters
n/a
##### Return Value
Boolean true if relative, else false.
##### Exceptions
n/a
#### Uri::is_absolute
```C++
bool is_absolute( void ) const;
```
Determines if the Uri is an absolute path.
##### Parameters
n/a
##### Return Value
Boolean true if relative, else false.
##### Exceptions
n/a
#### Uri::to_string
```C++
std::string to_string( void ) const;
```
Convert the Uri instance to a string representation.
##### Parameters
n/a
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) representing the Uri's contents.
##### Exceptions
n/a
#### Uri::is_valid
```C++
static bool is_valid( const std::string& value );
```
Determines if the supplied string is a valid Uri.
##### Parameters
n/a
##### Return Value
Boolean true if valid, else false.
##### Exceptions
n/a
#### Uri::parse
```C++
static Uri parse( const std::string& value );
```
Parse string to Uri instance.
##### Parameters
| name | type | default value | direction |
|:----------:|---------------------------------------------------------------------|:-------------:|:---------:|
| session | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
Uri instance.
##### Exceptions
n/a
#### Uri::decode
```C++
static std::string decode( const Bytes& value );
static std::string decode( const std::string& value );
```
Percent decoding functionality.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [Bytes](#bytebytes) | n/a | input |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
Decoded [std::string](http://en.cppreference.com/w/cpp/string/basic_string) value.
##### Exceptions
n/a
#### Uri::decode_parameter
```C++
static std::string decode_parameter( const std::string& value );
```
Parameter percent decoding functionality.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
Decoded [std::string](http://en.cppreference.com/w/cpp/string/basic_string) value.
##### Exceptions
n/a
#### Uri::encode
```C++
static std::string encode( const Bytes& value );
static std::string encode( const std::string& value );
```
Percent encoding functionality.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [Bytes](#bytebytes) | n/a | input |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
Encoded [std::string](http://en.cppreference.com/w/cpp/string/basic_string) value.
##### Exceptions
n/a
#### Uri::encode_parameter
```C++
static std::string encode_parameter( const std::string& value );
```
Parameter percent encoding functionality.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
Encoded [std::string](http://en.cppreference.com/w/cpp/string/basic_string) value.
##### Exceptions
n/a
#### Uri::get_port
```C++
uint16_t get_port( void ) const;
```
Retrieves the network port number.
##### Parameters
n/a
##### Return Value
[uint16_t](http://en.cppreference.com/w/cpp/types/integer) representing the network port number.
##### Exceptions
n/a
#### Uri::get_path
```C++
std::string get_path( void ) const;
```
Retrieves the path segment.
##### Parameters
n/a
##### Return Value
Path segment as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string).
##### Exceptions
n/a
#### Uri::get_query
```C++
std::string get_query( void ) const;
```
Retrieves the query segment.
##### Parameters
n/a
##### Return Value
Query segment as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string).
##### Exceptions
n/a
#### Uri::get_scheme
```C++
std::string get_scheme( void ) const;
```
Retrieves the scheme segment.
##### Parameters
n/a
##### Return Value
Scheme segment as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string).
##### Exceptions
n/a
#### Uri::get_fragment
```C++
std::string get_fragment( void ) const;
```
Retrieves the fragment segment.
##### Parameters
n/a
##### Return Value
Scheme segment as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string).
##### Exceptions
n/a
#### Uri::get_username
```C++
std::string get_username( void ) const;
```
Retrieves the username segment.
##### Parameters
n/a
##### Return Value
Username segment as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string).
##### Exceptions
n/a
#### Uri::get_password
```C++
std::string get_password( void ) const;
```
Retrieves the password segment.
##### Parameters
n/a
##### Return Value
Password segment as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string).
##### Exceptions
n/a
#### Uri::get_authority
```C++
std::string get_authority( void ) const;
```
Retrieves the authority segment.
##### Parameters
n/a
##### Return Value
Authority segment as a [std::string](http://en.cppreference.com/w/cpp/string/basic_string).
##### Exceptions
n/a
#### Uri::get_query_parameters
```C++
std::multimap< std::string, std::string > get_query_parameters( void ) const;
```
Retrieves parsed query parameters.
##### Parameters
n/a
##### Return Value
[std::multimap](http://en.cppreference.com/w/cpp/container/multimap) of decoded query parameters.
##### Exceptions
n/a
### WebSocket
Represents a WebSocket.
#### Methods
- [constructor](#websocketconstructor)
- [destructor](#websocketdestructor)
- [is_open](#websocketis_open)
- [is_closed](#websocketis_closed)
- [close](#websocketclose)
- [send](#websocketsend)
- [get_key](#websocketget_key)
- [get_logger](#websocketget_logger)
- [get_socket](#websocketget_socket)
- [get_open_handler](#websocketget_open_handler)
- [get_close_handler](#websocketget_close_handler)
- [get_error_handler](#websocketget_error_handler)
- [get_message_handler](#websocketget_message_handler)
- [set_key](#websocketset_key)
- [set_logger](#websocketset_logger)
- [set_open_handler](#websocketset_open_handler)
- [set_close_handler](#websocketset_close_handler)
- [set_error_handler](#websocketset_error_handler)
- [set_message_handler](#websocketset_message_handler)
#### WebSocket::constructor
```C++
WebSocket( void );
```
Initialises a new class instance; see also [destructor](#websocketdestructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocket::destructor
```C++
virtual ~WebSocket( void );
```
Clean-up class instance; see also [constructor](#websocketconstructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### WebSocket::is_open
```C++
bool is_open( void ) const;
```
Determine if the underlying socket is active.
##### Parameters
n/a
##### Return Value
[Boolean](http://en.cppreference.com/w/c/types/boolean) value indicating socket is active.
##### Exceptions
n/a
#### WebSocket::is_open
```C++
bool is_closed( void ) const;
```
Determine if the underlying socket is inactive.
##### Parameters
n/a
##### Return Value
[Boolean](http://en.cppreference.com/w/c/types/boolean) value indicating socket is inactive.
##### Exceptions
n/a
#### WebSocket::close
```C++
void close( void );
```
Close socket.
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocket::send
```C++
void send( const Bytes& body, const std::function< void ( const std::shared_ptr< WebSocket > ) > callback = nullptr );
void send( const std::string& body, const std::function< void ( const std::shared_ptr< WebSocket > ) > callback = nullptr );
void send( const WebSocketMessage::OpCode opcode, const std::function< void ( const std::shared_ptr< WebSocket > ) > callback = nullptr );
void send( const std::shared_ptr< WebSocketMessage > message, const std::function< void ( const std::shared_ptr< WebSocket > ) > callback = nullptr );
```
Transmit a WebSocket message.
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocket::get_key
```C++
std::string get_key( void ) const;
```
Retrieve unique key identifying this instance.
##### Parameters
n/a
##### Return Value
[std::string](http://en.cppreference.com/w/cpp/string/basic_string) unique identifier.
##### Exceptions
n/a
#### WebSocket::get_logger
```C++
std::shared_ptr< Logger > get_logger( void ) const;
```
Retrieve the logging instance used by this WebSocket.
##### Parameters
n/a
##### Return Value
[std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) referencing [Logger](#logger) used.
##### Exceptions
n/a
#### WebSocket::get_open_handler
```C++
std::function< void ( const std::shared_ptr< WebSocket > ) > get_open_handler( void ) const;
```
Retrieve socket open handler.
##### Parameters
n/a
##### Return Value
[std::function](http://en.cppreference.com/w/cpp/utility/functional/function) holding socket open handler.
##### Exceptions
n/a
#### WebSocket::get_close_handler
```C++
std::function< void ( const std::shared_ptr< WebSocket > ) > get_close_handler( void ) const;
```
Retrieve socket closed handler.
##### Parameters
n/a
##### Return Value
[std::function](http://en.cppreference.com/w/cpp/utility/functional/function) holding socket close handler.
##### Exceptions
n/a
#### WebSocket::get_error_handler
```C++
std::function< void ( const std::shared_ptr< WebSocket >, const std::error_code ) > get_error_handler( void ) const;
```
Retrieve socket error handler.
##### Parameters
n/a
##### Return Value
[std::function](http://en.cppreference.com/w/cpp/utility/functional/function) holding socket error handler.
##### Exceptions
n/a
#### WebSocket::get_message_handler
```C++
std::function< void ( const std::shared_ptr< WebSocket >, const std::shared_ptr< WebSocketMessage > ) > get_message_handler( void ) const;
```
Retrieve socket message handler.
##### Parameters
n/a
##### Return Value
[std::function](http://en.cppreference.com/w/cpp/utility/functional/function) holding socket message handler.
##### Exceptions
n/a
#### WebSocket::set_key
```C++
void set_key( const std::string& value );
```
Set WebSocket unique key.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocket::set_logger
```C++
void set_logger( const std::shared_ptr< Logger >& value );
```
Set [Logger](#logger) instance to use internally by the instance.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocket::set_open_handler
```C++
void set_open_handler( const std::function< void ( const std::shared_ptr< WebSocket > ) >& value );
```
Set a callback to be invoked once the socket connection has been established to a remote endpoint.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocket::set_close_handler
```C++
void set_close_handler( const std::function< void ( const std::shared_ptr< WebSocket > ) >& value );
```
Set a callback to be invoked once the socket connection has been terminated.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocket::set_error_handler
```C++
void set_error_handler( const std::function< void ( const std::shared_ptr< WebSocket >, const std::error_code ) >& value );
```
Set a callback to be invoked if the socket encounters an error.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocket::set_message_handler
```C++
void set_message_handler( const std::function< void ( const std::shared_ptr< WebSocket >, const std::shared_ptr< WebSocketMessage > ) >& value );
```
Set a callback to be invoked when a message is received.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::function](http://en.cppreference.com/w/cpp/utility/functional/function) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
### WebSocketMessage
Class to abstract the over engineered WebSocket packet format.
#### Methods
- [constructor](#websocketmessageconstructor)
- [destructor](#websocketmessagedestructor)
- [to_bytes](#websocketmessageto_bytes)
- [get_data](#websocketmessageget_data)
- [get_opcode](#websocketmessageget_opcode)
- [get_mask](#websocketmessageget_mask)
- [get_length](#websocketmessageget_length)
- [get_extended_length](#websocketmessageget_extended_length)
- [get_mask_flag](#websocketmessageget_mask_flag)
- [get_final_frame_flag](#websocketmessageget_final_frame_flag)
- [get_reserved_flags](#websocketmessageget_resserved_flags)
- [set_data](#websocketmessageset_data)
- [set_opcode](#websocketmessageset_opcode)
- [set_mask](#websocketmessageset_mask)
- [set_length](#websocketmessageset_length)
- [set_extended_length](#websocketmessageset_extended_length)
- [set_mask_flag](#websocketmessageset_mask_flag)
- [set_final_frame_flag](#websocketmessageset_final_frame_flag)
- [set_reserved_flags](#websocketmessageset_reserved_flags)
#### WebSocketMessage::constructor
```C++
WebSocketMessage( void );
WebSocketMessage( const WebSocketMessage& original );
WebSocketMessage( const OpCode code, const Bytes& data = { } );
WebSocketMessage( const OpCode code, const std::string& data );
WebSocketMessage( const OpCode code, const Bytes& data, const std::uint32_t mask );
WebSocketMessage( const OpCode code, const std::string& data, const std::uint32_t mask );
```
Initialises a new class instance; see also [destructor](#websocketmessagedestructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocketMessage::destructor
```C++
virtual ~WebSocketMessage( void );
```
Clean-up class instance; see also [constructor](#websocketmessageconstructor).
##### Parameters
n/a
##### Return Value
n/a
##### Exceptions
No exceptions allowed specification: [noexcept](http://en.cppreference.com/w/cpp/language/noexcept_spec).
#### WebSocketMessage::to_bytes
```C++
Bytes to_bytes( void ) const;
```
Convert instance to a collection of [Bytes](#bytebytes)
##### Parameters
n/a
##### Return Value
[Bytes](#bytebytes) containing a representation of the current WebSocketMessage state.
##### Exceptions
n/a
#### WebSocketMessage::get_data
```C++
Bytes get_data( void ) const;
```
Get data segment.
##### Parameters
n/a
##### Return Value
[Bytes](#bytebytes) containing message data.
##### Exceptions
n/a
#### WebSocketMessage::get_opcode
```C++
OpCode get_opcode( void ) const;
```
Get operation code.
##### Parameters
n/a
##### Return Value
[WebSocketMessage::OpCode](#websocketmessageopcode) detailing operation code in use.
##### Exceptions
n/a
#### WebSocketMessage::get_mask
```C++
std::uint32_t get_mask( void ) const;
```
Get message mask.
##### Parameters
n/a
##### Return Value
[std::uint32_t](http://en.cppreference.com/w/cpp/types/integer) detailing message length.
##### Exceptions
n/a
#### WebSocketMessage::get_length
```C++
std::uint8_t get_length( void ) const;
```
Get message data length.
##### Parameters
n/a
##### Return Value
[std::uint8_t](http://en.cppreference.com/w/cpp/types/integer) detailing mask to use on message data.
##### Exceptions
n/a
#### WebSocketMessage::get_extended_length
```C++
std::uint64_t get_extended_length( void ) const;
```
Get message data extended length.
##### Parameters
n/a
##### Return Value
[std::uint64_t](http://en.cppreference.com/w/cpp/types/integer) detailing message extended length.
##### Exceptions
n/a
#### WebSocketMessage::get_mask_flag
```C++
bool get_mask_flag( void ) const;
```
Get flag indicating if a mask is in use.
##### Parameters
n/a
##### Return Value
[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating a mask is in use.
##### Exceptions
n/a
#### WebSocketMessage::get_mask_flag
```C++
bool get_final_frame_flag( void ) const;
```
Get flag indicating if this message is the final frame.
##### Parameters
n/a
##### Return Value
[Boolean](http://en.cppreference.com/w/c/types/boolean) indicating a final frame.
##### Exceptions
n/a
#### WebSocketMessage::get_reserved_flags
```C++
std::tuple< bool, bool, bool > get_reserved_flags( void ) const;
```
Get reserved flags
##### Parameters
n/a
##### Return Value
[std::tuple](http://en.cppreference.com/w/cpp/utility/tuple) of reserved flags.
##### Exceptions
n/a
#### WebSocketMessage::set_data
```C++
void set_data( const Bytes& value );
void set_data( const std::string& value );
```
Set a callback to be invoked when a message is received.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [Bytes](#bytebytes) | n/a | input |
| value | [std::string](http://en.cppreference.com/w/cpp/string/basic_string) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocketMessage::set_opcode
```C++
void set_opcode( const OpCode value );
```
Set message operation code.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [WebSocketMessage::OpCode](#websocketmessageopcode) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocketMessage::set_mask
```C++
void set_mask( const std::uint32_t value );
```
Set message mask, this will also set the mask flag equal to true.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::uint32_t](http://en.cppreference.com/w/cpp/types/integer) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocketMessage::set_length
```C++
void set_length( const std::uint8_t value );
```
Set message length.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::uint8_t](http://en.cppreference.com/w/cpp/types/integer) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocketMessage::set_extended_length
```C++
void set_extended_length( const std::uint64_t value );
```
Set message extended length.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [std::uint64_t](http://en.cppreference.com/w/cpp/types/integer) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocketMessage::set_extended_length
```C++
void set_mask_flag( const bool value );
```
Setting true indicates a message mask is in place.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [Boolean](http://en.cppreference.com/w/c/types/boolean) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocketMessage::set_final_frame_flag
```C++
void set_final_frame_flag( const bool value );
```
Setting true indicates this is the final frame in a sequence of messages.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| value | [Boolean](http://en.cppreference.com/w/c/types/boolean) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocketMessage::set_reserved_flags
```C++
void set_reserved_flags( const bool rsv1, const bool rsv2, const bool rsv3 );
```
Set reserved flags.
##### Parameters
| name | type | default value | direction |
|:----------:|-------------------------------------------------------------------------------|:-------------:|:---------:|
| rsv1 | [Boolean](http://en.cppreference.com/w/c/types/boolean) | n/a | input |
| rsv2 | [Boolean](http://en.cppreference.com/w/c/types/boolean) | n/a | input |
| rsv3 | [Boolean](http://en.cppreference.com/w/c/types/boolean) | n/a | input |
##### Return Value
n/a
##### Exceptions
n/a
#### WebSocketMessage::OpCode
```C++
class WebSocketMessage
{
enum OpCode : uint8_t
{
CONTINUATION_FRAME = 0x00,
TEXT_FRAME = 0x01,
BINARY_FRAME = 0x02,
CONNECTION_CLOSE_FRAME = 0x08,
PING_FRAME = 0x09,
PONG_FRAME = 0x0A
};
}
```
[Enumeration](http://en.cppreference.com/w/cpp/language/enum) detailing WebSocket message operation codes.
### Further Reading
[C++ Standard](https://isocpp.org/std/the-standard) - The current ISO C++ standard is officially known as ISO International Standard ISO/IEC 14882:2014(E) – Programming Language C++. Want to read the ISO C++ standard, or working drafts of the standard? You have several options, most of them free.
[C++ Reference](http://en.cppreference.com/) - Comprehensive C++ and Standard Template Library (STL) reference.
[Effective STL](https://www.amazon.com/Effective-STL-Specific-Standard-Template/dp/0201749629) - Written for the intermediate or advanced C++ programmer, renowned C++ expert Scott Meyers provides essential techniques for getting more out of the Standard Template Library in Effective STL, a tutorial for doing more with this powerful library.
[Effective C++](https://www.amazon.com/Effective-Specific-Improve-Programs-Designs/dp/0321334876) - “Every C++ professional needs a copy of Effective C++. It is an absolute must-read for anyone thinking of doing serious C++ development. If you’ve never read Effective C++ and you think you know everything about C++, think again.” — Steve Schirripa, Software Engineer, Google
Reference in New Issue View Git Blame Copy Permalink