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

6038 lines
154 KiB
Markdown
Raw Normal View History

Rewrote the server in cpp with the frontend in svelte
2023-10-20 11:02:21 +00:00
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 Copy Permalink