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
