fileserver/lib/restbed-4.8/documentation/API.md

Overview

This document is intended to accurately communicate the Application Programming Interface (API) exposed by the Restbed framework for public consumption.

A description of the frameworks software architecture is provided by the Design Overview 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.

Table of Contents

1. Overview
2. Interpretation
3. Byte/Bytes
4. HTTP
5. Logger
6. Logger::Level
7. Request
8. Response
9. Resource
10. Rule
11. Service
12. Session
13. SessionManager
14. Settings
15. SSLSettings
16. StatusCode
17. String
18. String::Option
19. URI
20. WebSocket
21. WebSocketMessage
22. WebSocketMessage::OpCode
23. Further Reading

Byte/Bytes

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 (STL) vector collection semantics.

See std::uint8_t and std::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
• close
• is_open
• is_closed
• sync
• async
• fetch

Http::to_bytes

static Bytes to_bytes( const std::shared_ptr< Request >& value );

static Bytes to_bytes( const std::shared_ptr< Response >& value );

Convert a HTTP request/response object to a sequence of bytes.

Parameters

parameter	type	default value	direction
value	restbed::Request	n/a	input
value	restbed::Response	n/a	input

Return Value

Collection of bytes representing the raw request representation.

Exceptions

No exceptions allowed specification: noexcept.

Http::close

static void close( const std::shared_ptr< Request >& value );

Shutdown an active HTTP request object, causing its underlying socket to be disconnected. Invoking this method on a inactive request has no effect.

Parameters

parameter	type	default value	direction
value	restbed::Request	n/a	input

Return Value

n/a

Exceptions

No exceptions allowed specification: noexcept.

Http::is_open

static bool is_open( const std::shared_ptr< Request >& value );

Determine if the HTTP request object is active, that is say, it has a connected socket to a remote endpoint. Invoking this method on a inactive request has no effect.

Parameters

parameter	type	default value	direction
value	restbed::Request	n/a	input

Return Value

Boolean true if the underlying socket is connected, else false.

Exceptions

No exceptions allowed specification: noexcept.

Http::is_closed

static bool is_closed( const std::shared_ptr< Request >& value );

Determine if the HTTP request object is inactive, that is say, it has a disconnected socket. Invoking this method on a inactive request has no effect.

Parameters

parameter	type	default value	direction
value	restbed::Request	n/a	input

Return Value

Boolean true if the underlying socket is disconnected, else false.

Exceptions

No exceptions allowed specification: noexcept.

Http::sync

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. If an error occurs the response will contain details of the error, indicated by a status code of zero (0).

Settings may be specified via the second parameter.

Parameters

parameter	type	default value	direction
request	restbed::Request	n/a	input
settings	restbed::Settings	n/a	input

Return Value

The HTTP response returned from the endpoint specified in the request object, otherwise an error condition.

Exceptions

No exceptions allowed specification: noexcept.

Http::async

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. If an error occurs the 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.

Settings may be specified via the third parameter.

Parameters

parameter	type	default value	direction
request	restbed::Request	n/a	input
callback	std::function	n/a	input
settings	restbed::Settings	n/a	input

Return Value

std::future holding the pending restbed::Response.

Exceptions

No exceptions allowed specification: noexcept.

Http::fetch

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	n/a	input
length	std::size_t	n/a	input
delimiter	std::string	n/a	input

Return Value

Sequence of restbed::Bytes representing a portion or a complete response body determined by length or delimiter parameter options.

Exceptions

No exceptions allowed specification: noexcept.

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
• stop
• log
• log_if
• level

Logger::start

virtual void start( const std::shared_ptr< const restbed::Settings >& settings ) = 0;

Initialise a logger instance; see also stop.

The Settings passed are the same as those given to Exchange::start.

After this method has returned the instance MUST be ready to start receiving log and log_if invocations.

Parameters

name	type	default value	direction
value	restbed::Settings	n/a	input

Return Value

n/a

Exceptions

Any exceptions raised will result in the service failing to start.

Logger::stop

virtual void stop( void ) = 0;

Halt/Clean-up logger resources; see also start.

Parameters

n/a

Return Value

n/a

Exceptions

Exceptions raised will result in a dirty service teardown.

Logger::log

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.

See printf 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	n/a	input
format	char*	n/a	input
...	variadic argument list	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).

Logger::log_if

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.

Parameters

parameter	type	default value	direction
expresssion	bool	n/a	input
level	restbed::Logger::Level	n/a	input
format	char*	n/a	input
...	variadic argument list	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).

Logger::Level

class Logger
{
    enum Level : int
    {
        INFO = 0000,
        DEBUG = 1000,
        FATAL = 2000,
        ERROR = 3000,
        WARNING = 4000,
        SECURITY = 5000
    };
}

Enumeration used in conjunction with the Logger interface 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
• destructor
• has_header
• has_path_parameter
• has_query_parameter
• get_port
• get_version
• get_body
• get_response
• get_host
• get_path
• get_method
• get_protocol
• get_header
• get_headers
• get_query_parameter
• get_query_parameters
• get_path_parameter
• get_path_parameters
• set_body
• set_port
• set_version
• set_path
• set_host
• set_method
• set_protocol
• add_header
• set_header
• set_headers
• set_query_parameter
• set_query_parameters

Request::constructor

Request( void );
Request( const Uri& value );

Initialises a new class instance, if a Uri is supplied it will be used to override the default class property values; see also destructor.

Parameters

name	type	default value	direction
value	Uri	n/a	input

Return Value

n/a

Exceptions

n/a

Request::destructor

virtual ~Request( void );

Clean-up class instance; see also constructor.

Parameters

n/a

Return Value

n/a

Exceptions

No exceptions allowed specification: noexcept.

Request::has_header

bool has_header( const std::string& name ) const;

Case insensitive check to confirm if the request contains a header with the supplied name.

Parameters

name	type	default value	direction
name	std::string	n/a	input

Return Value

Boolean true if the request holds a header with a matching name, else false.

Exceptions

No exceptions allowed specification: noexcept.

Request::has_path_parameter

bool has_path_parameter( const std::string& name ) const;

Case insensitive check to confirm if the request contains a path parameter with the supplied name.

Parameters

name	type	default value	direction
name	std::string	n/a	input

Return Value

Boolean true if the request holds a path parameter with a matching name, else false.

Exceptions

No exceptions allowed specification: noexcept.

Request::has_query_parameter

bool has_query_parameter( const std::string& name ) const;

Case insensitive check to confirm if the request contains a query parameter with the supplied name.

Parameters

name	type	default value	direction
name	std::string	n/a	input

Return Value

Boolean true if the request holds a query parameter with a matching name, else false.

Exceptions

No exceptions allowed specification: noexcept.

Request::get_port

uint16_t get_port( void ) const;

Retrieves the network port number of the server endpoint; see also set_port.

Parameters

n/a

Return Value

uint16_t representing the network port number.

Exceptions

n/a

Request::get_version

double get_version( void ) const;

Retrieves the HTTP version number; see also set_version.

Parameters

n/a

Return Value

double representing the HTTP version.

Exceptions

n/a

Request::get_body

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; see also set_body.

2. Alters the request body with the transform operation and returns the result as a std::string; see also set_body.

Parameters

name	type	default value	direction
body	std::string	n/a	output
transform	std::function	n/a	input

Return Value

Bytes representing the request body.

Exceptions

n/a

Request::get_response

const std::shared_ptr< const Response > get_response( void ) const;

Retrieves the associated HTTP response for this request, if any.

Parameters

n/a

Return Value

std::shared_ptr representing the response, else nullptr.

Exceptions

n/a

Request::get_host

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	n/a	input

Return Value

std::string representing the host.

Exceptions

n/a

Request::get_path

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	n/a	input

Return Value

std::string representing the path.

Exceptions

n/a

Request::get_method

std::string get_method( const std::function< std::string ( const std::string& ) >& transform = nullptr ) const;

Retrieves the HTTP method for this request, optionally applying a text transformation.

Parameters

name	type	default value	direction
transform	std::function	n/a	input

Return Value

std::string representing the HTTP method.

Exceptions

n/a

Request::get_protocol

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	n/a	input

Return Value

std::string representing the protocol.

Exceptions

n/a

Request::get_header

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. if not found return default_value.

3. Retrieve the first header with a matching name as a std::string, optionally applying a transformation.

Parameters

name	type	default value	direction
transform	std::function	n/a	input
default_value	std::string or arithmetic	n/a	input

Return Value

std::string or arithmetic value representing the header.

Exceptions

n/a

Request::get_headers

std::multimap< std::string, std::string > get_headers( const std::string& name = "" ) const;

Retrieves all headers as a std::multimap. if a name is supplied only matching headers will be returned.

Parameters

name	type	default value	direction
transform	std::function	n/a	input

Return Value

std::multimap representing a collection of headers.

Exceptions

n/a

Request::get_query_parameter

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. if not found return default_value.

3. Retrieve the first query parameter with a matching name as a std::string, optionally applying a transformation.

Parameters

name	type	default value	direction
transform	std::function	n/a	input
default_value	std::string or arithmetic	n/a	input

Return Value

std::string or arithmetic value representing the query parameter.

Exceptions

n/a

Request::get_query_parameters

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. if a name is supplied only matching parameters will be returned.

Parameters

name	type	default value	direction
transform	std::function	n/a	input
option	String::Option	n/a	input

Return Value

std::multimap representing a collection of parameters.

Exceptions

n/a

Request::get_path_parameter

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. if not found return default_value.

3. Retrieve the first parameter with a matching name as a std::string, optionally applying a transformation.

Parameters

name	type	default value	direction
transform	std::function	n/a	input
default_value	std::string or arithmetic	n/a	input

Return Value

std::string or arithmetic value representing the path parameter.

Exceptions

n/a

Request::get_path_parameters

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. if a name is supplied only matching parameters will be returned.

Parameters

name	type	default value	direction
transform	std::function	n/a	input
option	String::Option	n/a	input

Return Value

std::multimap representing a collection of parameters.

Exceptions

n/a

Request::set_body

void set_body( const Bytes& value );

void set_body( const std::string& value );

Replace request body; see also get_body.

Parameters

name	type	default value	direction
value	std::string or Bytes	n/a	input

Return Value

n/a

Exceptions

n/a

Request::set_port

void set_port( const uint16_t value );

Replace request network port; see also get_port.

Parameters

name	type	default value	direction
value	std::uint16_t	n/a	input

Return Value

n/a

Exceptions

n/a

Request::set_version

void set_version( const double value );

Replace request version; see also get_version.

Parameters

name	type	default value	direction
value	double	n/a	input

Return Value

n/a

Exceptions

n/a

Request::set_path

void set_path( const std::string& value );

Replace request path; see also get_path.

Parameters

name	type	default value	direction
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Request::set_host

void set_host( const std::string& value );

Replace request host; see also get_host.

Parameters

name	type	default value	direction
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Request::set_method

void set_method( const std::string& value );

Replace request method; see also get_method.

Parameters

name	type	default value	direction
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Request::set_protocol

void set_protocol( const std::string& value );

Replace request protocol; see also get_protocol.

Parameters

name	type	default value	direction
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Request::add_header

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	n/a	input
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Request::set_header

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	n/a	input
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Request::set_headers

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	n/a	input

Return Value

n/a

Exceptions

n/a

Request::set_query_parameter

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	n/a	input
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Request::set_query_parameters

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	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
• destructor
• has_header
• get_body
• get_version
• get_status_code
• get_protocol
• get_status_message
• get_header
• get_headers
• set_body
• set_version
• set_status_code
• set_protocol
• set_status_message
• add_header
• set_header
• set_headers

Response::constructor

Response( void );

Initialises a new class instance; see also destructor.

Parameters

n/a

Return Value

n/a

Exceptions

n/a

Response::destructor

virtual ~Response( void );

Clean-up class instance; see also constructor.

Parameters

n/a

Return Value

n/a

Exceptions

No exceptions allowed specification: noexcept.

Response::has_header

bool has_header( const std::string& name ) const;

Case insensitive check to confirm if the response contains a header with the supplied name.

Parameters

name	type	default value	direction
name	std::string	n/a	input

Return Value

Boolean true if the response holds a header with a matching name, else false.

Exceptions

No exceptions allowed specification: noexcept.

Response::get_body

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; see also set_body.

2. Alters the response body with the transform operation and returns the result as a std::string; see also set_body.

Parameters

name	type	default value	direction
body	std::string	n/a	output
transform	std::function	n/a	input

Return Value

Bytes representing the response body.

Exceptions

n/a

Response::get_version

double get_version( void ) const;

Retrieves the HTTP version number; see also set_version.

Parameters

n/a

Return Value

double representing the HTTP version.

Exceptions

n/a

Response::get_status_code

int get_status_code( void ) const;

Retrieves the HTTP status code; see also set_status_code.

Parameters

n/a

Return Value

Integer representing the HTTP status code.

Exceptions

n/a

Response::get_protocol

std::string get_protocol( void ) const;

Retrieve the protocol.

Parameters

n/a

Return Value

std::string representing the protocol.

Exceptions

n/a

Response::get_status_message

std::string get_status_message( void ) const;

Retrieves the HTTP status message; see also set_status_message.

Parameters

n/a

Return Value

std::string representing the HTTP status message.

Exceptions

n/a

Response::get_header

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. if not found return default_value.

3. Retrieve the first header with a matching name as a std::string, optionally applying a transformation.

Parameters

name	type	default value	direction
transform	std::function	n/a	input
default_value	std::string or arithmetic	n/a	input

Return Value

std::string or arithmetic value representing the header.

Exceptions

n/a

Response::get_headers

std::multimap< std::string, std::string > get_headers( const std::string& name = "" ) const;

Retrieves all headers as a std::multimap. if a name is supplied only matching headers will be returned.

Parameters

name	type	default value	direction
transform	std::function	n/a	input

Return Value

std::multimap representing a collection of headers.

Exceptions

n/a

Response::set_body

void set_body( const Bytes& value );

void set_body( const std::string& value );

Replace response body; see also get_body.

Parameters

name	type	default value	direction
value	std::string or Bytes	n/a	input

Return Value

n/a

Exceptions

n/a

Response::set_version

void set_version( const double value );

Replace response version; see also get_version.

Parameters

name	type	default value	direction
value	double	n/a	input

Return Value

n/a

Exceptions

n/a

Response::set_status_code

void set_status_code( const int value );

Replace response status code; see also get_status_code.

Parameters

name	type	default value	direction
value	int	n/a	input

Return Value

n/a

Exceptions

n/a

Response::set_protocol

void set_protocol( const std::string& value );

Replace response protocol; see also get_protocol.

Parameters

name	type	default value	direction
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Response::set_status_message

void set_status_message( const std::string& value );

Replace response status message; see also get_status_message.

Parameters

name	type	default value	direction
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Response::add_header

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	n/a	input
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Response::set_header

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.

Parameters

name	type	default value	direction
name	std::string	n/a	input
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Response::set_headers

void set_headers( const std::multimap< std::string, std::string >& values );

Set HTTP headers, existing headers will be erased; see also get_headers.

Parameters

name	type	default value	direction
values	std::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
• destructor
• add_rule
• set_path
• set_paths
• set_default_header
• set_default_headers
• set_failed_filter_validation_handler
• set_error_handler
• set_authentication_handler
• set_method_handler

Resource::constructor

Resource( void );

Initialises a new class instance; see also destructor.

Parameters

n/a

Return Value

n/a

Exceptions

n/a

Resource::destructor

virtual ~Resource( void );

Clean-up class instance; see also constructor.

Parameters

n/a

Return Value

n/a

Exceptions

No exceptions allowed specification: noexcept.

Resource::add_rule

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.

Parameters

name	type	default value	direction
rule	Rule	n/a	input
priority	int	n/a	input

Return Value

n/a

Exceptions

n/a

Resource::set_path

void set_path( const std::string& value );

Set the path with which this resource should be accessible. Settings::set_root will be perpended to this value.

Parameters

name	type	default value	direction
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Resource::set_paths

void set_paths( const std::set< std::string >& values );

Set the paths with which this resource should be accessible. Settings::set_root will be perpended to all values.

Parameters

name	type	default value	direction
values	std::set	n/a	input

Return Value

n/a

Exceptions

n/a

Resource::set_default_header

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	n/a	input
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Resource::set_default_headers

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	n/a	input

Return Value

n/a

Exceptions

n/a

Resource::set_failed_filter_validation_handler

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	n/a	input

Return Value

n/a

Exceptions

n/a

Resource::set_error_handler

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	n/a	input

Return Value

n/a

Exceptions

n/a

Resource::set_authentication_handler

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	n/a	input

Return Value

n/a

Exceptions

n/a

Resource::set_method_handler

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	n/a	input
filters	std::multimap	n/a	input
callback	std::function	n/a	input

Return Value

n/a

Exceptions

n/a

Rule

Interface representing an incoming processing rule.

Methods

• condition
• action
• get_priority
• set_priority

Rule::condition

virtual bool condition( const std::shared_ptr< Session > session );

The condition that decides if this rules action should be invoked; see also action.

Parameters

name	type	default value	direction
session	std::shared_ptr	n/a	input

Return Value

True if the condition has been satisfied.

Exceptions

n/a

Rule::action

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.

Parameters

name	type	default value	direction
session	std::shared_ptr	n/a	input
callback	std::function	n/a	input

Return Value

n/a

Exceptions

n/a

Rule::get_priority

int get_priority( void ) const;

Retrieve rule processing priority.

Parameters

n/a

Return Value

int representing rule processing priority.

Exceptions

n/a

Rule::set_priority

void set_priority( const int value );

Alter rule's processing priority.

Parameters

name	type	default value	direction
value	int	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
• destructor
• is_up
• is_down
• stop
• start
• restart
• add_rule
• publish
• suppress
• schedule
• get_uptime
• get_http_uri
• get_https_uri
• set_logger
• set_session_manager
• set_ready_handler
• set_signal_handler
• set_not_found_handler
• set_method_not_allowed_handler
• set_method_not_implemented_handler
• set_failed_filter_validation_handler
• set_error_handler
• set_authentication_handler

Service::constructor

Resource( void );

Initialises a new class instance; see also destructor.

Parameters

n/a

Return Value

n/a

Exceptions

n/a

Service::destructor

virtual ~Service( void );

Clean-up class instance; see also constructor.

Parameters

n/a

Return Value

n/a

Exceptions

No exceptions allowed specification: noexcept.

Service::is_up

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

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

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

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	n/a	input

Return Value

n/a

Exceptions

n/a

Service::restart

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	n/a	input

Return Value

n/a

Exceptions

n/a

Service::add_rule

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.

Parameters

name	type	default value	direction
rule	Rule	n/a	input
priority	int	n/a	input

Return Value

n/a

Exceptions

n/a

Service::publish

void publish( const std::shared_ptr< const Resource >& resource );

Publish a RESTful resource for public consumption; see also Resource.

Parameters

name	type	default value	direction
resource	std::shared_ptr	n/a	input

Return Value

n/a

Exceptions

n/a

Service::suppress

void suppress( const std::shared_ptr< const Resource >& resource );

Suppress an already published RESTful resource; see also Resource.

Parameters

name	type	default value	direction
resource	std::shared_ptr	n/a	input

Return Value

n/a

Exceptions

n/a

Service::schedule

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	n/a	input
interval	std::chrono::milliseconds	n/a	input

Return Value

n/a

Exceptions

n/a

Service::get_uptime

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.

Exceptions

n/a

Service::get_http_uri

const std::shared_ptr< const Uri > get_http_uri( void ) const;

Return a URI representing the HTTP endpoint; see also URI.

Parameters

n/a

Return Value

URI representing HTTP endpoint.

Exceptions

n/a

Service::get_https_uri

const std::shared_ptr< const Uri > get_https_uri( void ) const;

Return a URI representing the HTTPS endpoint; see also URI.

Parameters

n/a

Return Value

URI representing HTTPS endpoint.

Exceptions

n/a

Service::set_logger

void set_logger( const std::shared_ptr< Logger >& value );

Set the logger instance to be used; see also Logger.

Parameters

name	type	default value	direction
value	std::shared_ptr	n/a	input

Return Value

n/a

Exceptions

n/a

Service::set_session_manager

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.

Parameters

name	type	default value	direction
value	std::shared_ptr	n/a	input

Return Value

n/a

Exceptions

n/a

Service::set_ready_handler

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	n/a	input

Return Value

n/a

Exceptions

n/a

Service::set_signal_handler

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	n/a	input
value	std::function	n/a	input

Return Value

n/a

Exceptions

n/a

Service::set_not_found_handler

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	n/a	input

Return Value

n/a

Exceptions

n/a

Service::set_method_not_allowed_handler

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	n/a	input

Return Value

n/a

Exceptions

n/a

Service::set_method_not_implemented_handler

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	n/a	input

Return Value

n/a

Exceptions

n/a

Service::set_failed_filter_validation_handler

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	n/a	input

Return Value

n/a

Exceptions

n/a

Service::set_error_handler

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	n/a	input

Return Value

n/a

Exceptions

n/a

Service::set_authentication_handler

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	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
• destructor
• has
• erase
• keys
• is_open
• is_closed
• close
• yield
• fetch
• upgrade
• sleep_for
• get_id
• get_origin
• get_destination
• get_request
• get_resource
• get_headers
• get
• set_id
• set
• add_header
• set_header
• set_headers

Session::constructor

Session( const std::string& id );

Initialises a new class instance; see also destructor.

Parameters

name	type	default value	direction
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Session::destructor

virtual ~Session( void );

Clean-up class instance; see also constructor.

Parameters

n/a

Return Value

n/a

Exceptions

No exceptions allowed specification: noexcept.

Session::has

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	n/a	input

Return Value

Boolean true if the data is available.

Exceptions

n/a

Session::erase

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	n/a	input

Return Value

n/a

Exceptions

n/a

Session::keys

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

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

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

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	n/a	input
body	Bytes	n/a	input
body	std::string	n/a	input
headers	std::multimap	n/a	input

Return Value

n/a

Exceptions

n/a

Session::yield

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	n/a	input
body	Bytes	n/a	input
body	std::string	n/a	input
headers	std::multimap	n/a	input
callback	std::function	n/a	input

Return Value

n/a

Exceptions

n/a

Session::fetch

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	n/a	input
delimiter	std::string	n/a	input
callback	std::function	n/a	input

Return Value

n/a

Exceptions

n/a

Session::upgrade

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	n/a	input
body	Bytes	n/a	input
body	std::string	n/a	input
headers	std::multimap	n/a	input
callback	std::function	n/a	input

Return Value

n/a

Exceptions

n/a

Session::sleep_for

void sleep_for( const std::chrono::milliseconds& delay, const std::function< void ( const std::shared_ptr< Session > ) >& callback );

Place a task on the Service event loop to be run in delay milliseconds.

Parameters

name	type	default value	direction
delay	std::chrono::milliseconds	n/a	input
callback	std::function	n/a	input

Return Value

n/a

Exceptions

n/a

Session::get_id

const std::string& get_id( void ) const;

Return a string uniquely identifying this session instance.

Parameters

n/a

Return Value

std::string representing a unique session identifier.

Exceptions

n/a

Session::get_origin

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 representing the source network endpoint.

Exceptions

n/a

Session::get_destination

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 representing a destination network endpoint.

Exceptions

n/a

Session::get_request

const std::shared_ptr< const Request > get_request(  void ) const;

Return the currently active HTTP request.

Parameters

n/a

Return Value

std::shared_ptr representing a HTTP request.

Exceptions

n/a

Session::get_resource

const std::shared_ptr< const Resource > get_resource( void ) const;

Return the currently active RESTful resource.

Parameters

n/a

Return Value

std::shared_ptr representing a HTTP request.

Exceptions

n/a

Session::get_headers

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 representing a collection of HTTP headers.

Exceptions

n/a

Session::get

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	n/a	input
value	std::any	n/a	input

Return Value

std::any session data item.

Exceptions

n/a

Session::set_id

void set_id( const std::string& value );

Set a unique session identifier.

Parameters

name	type	default value	direction
value	std::string	n/a	input

Return Value

std::any session data item.

Exceptions

n/a

Session::set

void set( const std::string& name, const ContextValue& value );

Set a unique session identifier.

Parameters

name	type	default value	direction
name	std::string	n/a	input
value	std::any	n/a	input

Return Value

std::any session data item.

Exceptions

n/a

Session::add_header

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	n/a	input
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Session::set_header

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	n/a	input
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Session::set_headers

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.

Parameters

name	type	default value	direction
values	std::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
• destructor
• stop
• start
• create
• load
• save

SessionManager::constructor

SessionManager( void );

Initialises a new class instance; see also destructor.

Parameters

n/a

Return Value

n/a

Exceptions

n/a

SessionManager::destructor

virtual ~SessionManager( void );

Clean-up class instance; see also constructor.

Parameters

n/a

Return Value

n/a

Exceptions

No exceptions allowed specification: noexcept.

SessionManager::stop

virtual void stop( void );

Shutdown an active SessionManager.

Parameters

n/a

Return Value

n/a

Exceptions

n/a

SessionManager::start

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.

Parameters

name	type	default value	direction
settings	std::shared_ptr	n/a	input

Return Value

n/a

Exceptions

n/a

SessionManager::create

virtual void create( const std::function< void ( const std::shared_ptr< Session > ) >& callback );

Create a new Session instance passing it into callback.

Parameters

name	type	default value	direction
callback	std::function	n/a	input

Return Value

n/a

Exceptions

n/a

SessionManager::load

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	n/a	input
callback	std::function	n/a	input

Return Value

n/a

Exceptions

n/a

SessionManager::save

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	n/a	input
callback	std::function	n/a	input

Return Value

n/a

Exceptions

n/a

Settings

Represents service configuration.

Methods

• constructor
• destructor
• get_port
• get_root
• get_worker_limit
• get_connection_limit
• get_bind_address
• get_case_insensitive_uris
• get_connection_timeout
• get_status_message
• get_status_messages
• get_property
• get_properties
• get_ssl_settings
• get_default_headers
• set_port
• set_root
• set_worker_limit
• set_connection_limit
• set_bind_address
• set_case_insensitive_uris
• set_connection_timeout
• set_status_message
• set_status_messages
• set_property
• set_properties
• set_ssl_settings
• set_default_header
• set_default_headers

Settings::constructor

Settings( void );

Initialises a new class instance; see also destructor.

Parameters

n/a

Return Value

n/a

Exceptions

n/a

Settings::destructor

virtual ~Settings( void );

Clean-up class instance; see also constructor.

Parameters

n/a

Return Value

n/a

Exceptions

No exceptions allowed specification: noexcept.

Settings::get_port

uint16_t get_port( void ) const;

Retrieves the network port number which the service will listen on.

Parameters

n/a

Return Value

uint16_t representing the network port number.

Exceptions

n/a

Settings::get_root

std::string get_root( void ) const;

Retrieves the base path for all resource paths.

Parameters

n/a

Return Value

uint16_t representing the base resource path.

Exceptions

n/a

Settings::get_worker_limit

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 detailing the number of service workers.

Exceptions

n/a

Settings::get_connection_limit

unsigned int get_connection_limit( void ) const;

Retrieves the number of allowed pending socket connections.

Parameters

n/a

Return Value

unsigned integer detailing the number of allowed pending socket connections.

Exceptions

n/a

Settings::get_bind_address

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 detailing the service bind address.

Exceptions

n/a

Settings::get_case_insensitive_uris

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 indicating case insensitive Uri processing.

Exceptions

n/a

Settings::get_connection_timeout

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 detailing when to close an inactive socket.

Exceptions

n/a

Settings::get_status_message

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	n/a	input

Return Value

HTTP status message as a std::string.

Exceptions

n/a

Settings::get_status_messages

std::map< int, std::string > get_status_messages( void ) const;

Retrieves the HTTP status messages.

Parameters

n/a

Return Value

std::map containing the known HTTP status messages.

Exceptions

n/a

Settings::get_property

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	n/a	input

Return Value

std::string property value.

Exceptions

n/a

Settings::get_properties

std::map< std::string, std::string > get_properties( void ) const;

Retrieves all setting properties.

Parameters

n/a

Return Value

std::map containing the known settings.

Exceptions

n/a

Settings::get_ssl_settings

std::shared_ptr< const SSLSettings > get_ssl_settings( void ) const;

Retrieves Secure Socket Layer settings.

Parameters

n/a

Return Value

SSLSettings detailing SSL configuration.

Exceptions

n/a

Settings::get_default_headers

std::multimap< std::string, std::string > get_default_headers( void ) const;

Retrieves all known default response headers.

Parameters

n/a

Return Value

std::multimap containing all known default response headers.

Exceptions

n/a

Settings::set_port

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	n/a	input

Return Value

n/a

Exceptions

n/a

Settings::set_root

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	n/a	input

Return Value

n/a

Exceptions

n/a

Settings::set_worker_limit

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	n/a	input

Return Value

n/a

Exceptions

n/a

Settings::set_connection_limit

void set_connection_limit( const unsigned int value );

Set the number of allowed pending connections.

Parameters

name	type	default value	direction
value	unsigned integer	n/a	input

Return Value

n/a

Exceptions

n/a

Settings::set_bind_address

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	n/a	input

Return Value

n/a

Exceptions

n/a

Settings::set_case_insensitive_uris

void set_case_insensitive_uris( const bool value );

Set true for case insensitive Uri handling.

Parameters

name	type	default value	direction
value	bool	n/a	input

Return Value

n/a

Exceptions

n/a

Settings::set_connection_timeout

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	n/a	input
value	milliseconds	n/a	input

Return Value

n/a

Exceptions

n/a

Settings::set_status_message

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	n/a	input
message	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Settings::set_status_messages

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	n/a	input

Return Value

n/a

Exceptions

n/a

Settings::set_property

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	n/a	input
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Settings::set_properties

void set_properties( const std::map< std::string, std::string >& values );

Set multiple property values.

Parameters

name	type	default value	direction
values	std::map	n/a	input

Return Value

n/a

Exceptions

n/a

Settings::set_ssl_settings

void set_ssl_settings( const std::shared_ptr< const SSLSettings >& value );

Set Secure Socket Layer configuration.

Parameters

name	type	default value	direction
value	SSLSettings	n/a	input

Return Value

n/a

Exceptions

n/a

Settings::set_default_header

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	n/a	input
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

Settings::set_default_headers

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	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings

Represents Secure Socket Layer configuration.

Methods

• constructor
• destructor
• has_disabled_http
• has_enabled_sslv2
• has_enabled_sslv3
• has_enabled_tlsv1
• has_enabled_tlsv11
• has_enabled_tlsv12
• has_enabled_compression
• has_enabled_default_workarounds
• has_enabled_single_diffie_hellman_use
• get_port
• get_bind_address
• get_certificate
• get_passphrase
• get_private_key
• get_private_rsa_key
• get_certificate_chain
• get_temporary_diffie_hellman
• get_certificate_authority_pool
• set_port
• set_bind_address
• set_http_disabled
• set_sslv2_enabled
• set_sslv3_enabled
• set_tlsv1_enabled
• set_tlsv11_enabled
• set_tlsv12_enabled
• set_compression_enabled
• set_default_workarounds_enabled
• set_certificate
• set_certificate_authority_pool
• set_passphrase
• set_private_key
• set_private_rsa_key
• set_temporary_diffie_hellman

SSLSettings::constructor

SSLSettings( void );

Initialises a new class instance; see also destructor.

Parameters

n/a

Return Value

n/a

Exceptions

n/a

SSLSettings::destructor

virtual ~SSLSettings( void );

Clean-up class instance; see also constructor.

Parameters

n/a

Return Value

n/a

Exceptions

No exceptions allowed specification: noexcept.

SSLSettings::has_disabled_http

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 indicating that HTTP has been disabled.

Exceptions

n/a

SSLSettings::has_enabled_sslv2

bool has_enabled_sslv2( void ) const;

Determine if SSLv2 has been enabled.

Parameters

n/a

Return Value

Boolean indicating SSLv2 is enabled.

Exceptions

n/a

SSLSettings::has_enabled_sslv3

bool has_enabled_sslv3( void ) const;

Determine if SSLv3 has been enabled.

Parameters

n/a

Return Value

Boolean indicating SSLv3 is enabled.

Exceptions

n/a

SSLSettings::has_enabled_tlsv1

bool has_enabled_tlsv1( void ) const;

Determine if TLSv1 has been enabled.

Parameters

n/a

Return Value

Boolean indicating TLSv1 is enabled.

Exceptions

n/a

SSLSettings::has_enabled_tlsv11

bool has_enabled_tlsv11( void ) const;

Determine if TLSv1.1 has been enabled.

Parameters

n/a

Return Value

Boolean indicating TLSv1.1 is enabled.

Exceptions

n/a

SSLSettings::has_enabled_tlsv12

bool has_enabled_tlsv12( void ) const;

Determine if TLSv1.2 has been enabled.

Parameters

n/a

Return Value

Boolean indicating TLSv1.2 is enabled.

Exceptions

n/a

SSLSettings::has_enabled_compression

bool has_enabled_compression( void ) const;

Determine if compression has been enabled.

Parameters

n/a

Return Value

Boolean indicating compression is enabled.

Exceptions

n/a

SSLSettings::has_enabled_default_workarounds

bool has_enabled_default_workarounds( void ) const;

Determine if default workarounds is enabled.

Parameters

n/a

Return Value

Boolean indicating default workaround enabled.

Exceptions

n/a

SSLSettings::has_enabled_single_diffie_hellman_use

bool has_enabled_single_diffie_hellman_use( void ) const;

Determine if single diffie hellman use is enabled.

Parameters

n/a

Return Value

Boolean indicating single diffie hellman use.

Exceptions

n/a

SSLSettings::get_port

uint16_t get_port( void ) const;

Retrieves the network port number which the service will listen on.

Parameters

n/a

Return Value

uint16_t representing the network port number.

Exceptions

n/a

SSLSettings::get_bind_address

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 detailing the service bind address.

Exceptions

n/a

SSLSettings::get_certificate

std::string get_certificate( void ) const;

Retrieves filename of SSL certificate.

Parameters

n/a

Return Value

std::string certificate filename.

Exceptions

n/a

SSLSettings::get_passphrase

std::string get_passphrase( void ) const;

Retrieves SSL certificate passphrase.

Parameters

n/a

Return Value

std::string certificate passphrase.

Exceptions

n/a

SSLSettings::get_private_key

std::string get_private_key( void ) const;

Retrieves filename to private key.

Parameters

n/a

Return Value

std::string private key filename.

Exceptions

n/a

SSLSettings::get_private_rsa_key

std::string get_private_rsa_key( void ) const;

Retrieves filename to RSA private key.

Parameters

n/a

Return Value

std::string certificate filename.

Exceptions

n/a

SSLSettings::get_certificate_chain

std::string get_certificate_chain( void ) const;

Retrieves filename to certificate chain.

Parameters

n/a

Return Value

std::string certificate chain filename.

Exceptions

n/a

SSLSettings::get_temporary_diffie_hellman

std::string get_temporary_diffie_hellman( void ) const;

Retrieves filename to temporary diffie hellman.

Parameters

n/a

Return Value

std::string diffie hellman filename.

Exceptions

n/a

SSLSettings::get_certificate_authority_pool

std::string get_certificate_authority_pool( void ) const;

Retrieves filename to certificate authority pool.

Parameters

n/a

Return Value

std::string diffie hellman filename.

Exceptions

n/a

SSLSettings::set_port

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	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_bind_address

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	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_http_disabled

void set_http_disabled( const bool value );

Set true to disable unencrypted HTTP service access.

Parameters

name	type	default value	direction
value	bool	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_sslv2_enabled

void set_sslv2_enabled( const bool value );

Set true to enabled SSLv2.

Parameters

name	type	default value	direction
value	bool	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_sslv3_enabled

void set_sslv3_enabled( const bool value );

Set true to enabled SSLv3.

Parameters

name	type	default value	direction
value	bool	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_tlsv1_enabled

void set_tlsv1_enabled( const bool value );

Set true to enabled TLSv1.

Parameters

name	type	default value	direction
value	bool	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_tlsv11_enabled

void set_tlsv11_enabled( const bool value );

Set true to enabled TLSv1.1.

Parameters

name	type	default value	direction
value	bool	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_tlsv12_enabled

void set_tlsv12_enabled( const bool value );

Set true to enabled TLSv1.2.

Parameters

name	type	default value	direction
value	bool	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_compression_enabled

void set_compression_enabled( const bool value );

Set true to enabled compression.

Parameters

name	type	default value	direction
value	bool	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_default_workarounds_enabled

void set_default_workarounds_enabled( const bool value );

Set true to enabled default workarounds.

Parameters

name	type	default value	direction
value	bool	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_single_diffie_hellman_use_enabled

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	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_certificate

void set_certificate( const Uri& value );

Set filename to SSL certificate.

Parameters

name	type	default value	direction
value	Uri	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_certificate_chain

void set_certificate_chain( const Uri& value );

Set filename to SSL certificate chain.

Parameters

name	type	default value	direction
value	Uri	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_certificate_authority_pool

void set_certificate_authority_pool( const Uri& value );

Set filename to SSL certificate authority pool.

Parameters

name	type	default value	direction
value	Uri	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_passphrase

void set_passphrase( const std::string& value );

Set filename to SSL certificate passphrase.

Parameters

name	type	default value	direction
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_private_key

void set_private_key( const Uri& value );

Set filename to SSL private key.

Parameters

name	type	default value	direction
value	Uri	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_private_rsa_key

void set_private_rsa_key( const Uri& value );

Set filename to SSL private RSA key.

Parameters

name	type	default value	direction
value	Uri	n/a	input

Return Value

n/a

Exceptions

n/a

SSLSettings::set_temporary_diffie_hellman

void set_temporary_diffie_hellman( const Uri& value );

Set filename to temporary diffie hellman.

Parameters

name	type	default value	direction
value	Uri	n/a	input

Return Value

n/a

Exceptions

n/a

StatusCode

Enumeration of HTTP response status codes as outlined in RFC 7231 sub-section 6.1.

Uri

Represents a Uniform Resource Identifier as specified in RFC 3986.

Methods

• constructor
• destructor
• is_relative
• is_absolute
• to_string
• is_valid
• parse
• decode
• decode_parameter
• encode
• encode_parameter
• get_port
• get_path
• get_query
• get_scheme
• get_fragment
• get_username
• get_password
• get_authority
• get_query_parameters

Uri::constructor

explicit Uri( const std::string& value, bool relative = false );

Uri( const Uri& original );

Initialises a new class instance; see also destructor.

Parameters

n/a

Return Value

n/a

Exceptions

n/a

Uri::destructor

virtual ~Uri( void );

Clean-up class instance; see also constructor.

Parameters

n/a

Return Value

n/a

Exceptions

No exceptions allowed specification: noexcept.

Uri::is_relative

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

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

std::string to_string( void ) const;

Convert the Uri instance to a string representation.

Parameters

n/a

Return Value

std::string representing the Uri's contents.

Exceptions

n/a

Uri::is_valid

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

static Uri parse( const std::string& value );

Parse string to Uri instance.

Parameters

name	type	default value	direction
session	std::string	n/a	input

Return Value

Uri instance.

Exceptions

n/a

Uri::decode

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	n/a	input
value	std::string	n/a	input

Return Value

Decoded std::string value.

Exceptions

n/a

Uri::decode_parameter

static std::string decode_parameter( const std::string& value );

Parameter percent decoding functionality.

Parameters

name	type	default value	direction
value	std::string	n/a	input

Return Value

Decoded std::string value.

Exceptions

n/a

Uri::encode

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	n/a	input
value	std::string	n/a	input

Return Value

Encoded std::string value.

Exceptions

n/a

Uri::encode_parameter

static std::string encode_parameter( const std::string& value );

Parameter percent encoding functionality.

Parameters

name	type	default value	direction
value	std::string	n/a	input

Return Value

Encoded std::string value.

Exceptions

n/a

Uri::get_port

uint16_t get_port( void ) const;

Retrieves the network port number.

Parameters

n/a

Return Value

uint16_t representing the network port number.

Exceptions

n/a

Uri::get_path

std::string get_path( void ) const;

Retrieves the path segment.

Parameters

n/a

Return Value

Path segment as a std::string.

Exceptions

n/a

Uri::get_query

std::string get_query( void ) const;

Retrieves the query segment.

Parameters

n/a

Return Value

Query segment as a std::string.

Exceptions

n/a

Uri::get_scheme

std::string get_scheme( void ) const;

Retrieves the scheme segment.

Parameters

n/a

Return Value

Scheme segment as a std::string.

Exceptions

n/a

Uri::get_fragment

std::string get_fragment( void ) const;

Retrieves the fragment segment.

Parameters

n/a

Return Value

Scheme segment as a std::string.

Exceptions

n/a

Uri::get_username

std::string get_username( void ) const;

Retrieves the username segment.

Parameters

n/a

Return Value

Username segment as a std::string.

Exceptions

n/a

Uri::get_password

std::string get_password( void ) const;

Retrieves the password segment.

Parameters

n/a

Return Value

Password segment as a std::string.

Exceptions

n/a

Uri::get_authority

std::string get_authority( void ) const;

Retrieves the authority segment.

Parameters

n/a

Return Value

Authority segment as a std::string.

Exceptions

n/a

Uri::get_query_parameters

std::multimap< std::string, std::string > get_query_parameters( void ) const;

Retrieves parsed query parameters.

Parameters

n/a

Return Value

std::multimap of decoded query parameters.

Exceptions

n/a

WebSocket

Represents a WebSocket.

Methods

• constructor
• destructor
• is_open
• is_closed
• close
• send
• get_key
• get_logger
• get_socket
• get_open_handler
• get_close_handler
• get_error_handler
• get_message_handler
• set_key
• set_logger
• set_open_handler
• set_close_handler
• set_error_handler
• set_message_handler

WebSocket::constructor

WebSocket( void );

Initialises a new class instance; see also destructor.

Parameters

n/a

Return Value

n/a

Exceptions

n/a

WebSocket::destructor

virtual ~WebSocket( void );

Clean-up class instance; see also constructor.

Parameters

n/a

Return Value

n/a

Exceptions

No exceptions allowed specification: noexcept.

WebSocket::is_open

bool is_open( void ) const;

Determine if the underlying socket is active.

Parameters

n/a

Return Value

Boolean value indicating socket is active.

Exceptions

n/a

WebSocket::is_open

bool is_closed( void ) const;

Determine if the underlying socket is inactive.

Parameters

n/a

Return Value

Boolean value indicating socket is inactive.

Exceptions

n/a

WebSocket::close

void close( void );

Close socket.

Parameters

n/a

Return Value

n/a

Exceptions

n/a

WebSocket::send

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

std::string get_key( void ) const;

Retrieve unique key identifying this instance.

Parameters

n/a

Return Value

std::string unique identifier.

Exceptions

n/a

WebSocket::get_logger

std::shared_ptr< Logger > get_logger( void ) const;

Retrieve the logging instance used by this WebSocket.

Parameters

n/a

Return Value

std::shared_ptr referencing Logger used.

Exceptions

n/a

WebSocket::get_open_handler

std::function< void ( const std::shared_ptr< WebSocket > ) > get_open_handler( void ) const;

Retrieve socket open handler.

Parameters

n/a

Return Value

std::function holding socket open handler.

Exceptions

n/a

WebSocket::get_close_handler

std::function< void ( const std::shared_ptr< WebSocket > ) > get_close_handler( void ) const;

Retrieve socket closed handler.

Parameters

n/a

Return Value

std::function holding socket close handler.

Exceptions

n/a

WebSocket::get_error_handler

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 holding socket error handler.

Exceptions

n/a

WebSocket::get_message_handler

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 holding socket message handler.

Exceptions

n/a

WebSocket::set_key

void set_key( const std::string& value );

Set WebSocket unique key.

Parameters

name	type	default value	direction
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

WebSocket::set_logger

void set_logger( const std::shared_ptr< Logger >& value );

Set Logger instance to use internally by the instance.

Parameters

name	type	default value	direction
value	std::shared_ptr	n/a	input

Return Value

n/a

Exceptions

n/a

WebSocket::set_open_handler

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	n/a	input

Return Value

n/a

Exceptions

n/a

WebSocket::set_close_handler

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	n/a	input

Return Value

n/a

Exceptions

n/a

WebSocket::set_error_handler

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	n/a	input

Return Value

n/a

Exceptions

n/a

WebSocket::set_message_handler

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	n/a	input

Return Value

n/a

Exceptions

n/a

WebSocketMessage

Class to abstract the over engineered WebSocket packet format.

Methods

• constructor
• destructor
• to_bytes
• get_data
• get_opcode
• get_mask
• get_length
• get_extended_length
• get_mask_flag
• get_final_frame_flag
• get_reserved_flags
• set_data
• set_opcode
• set_mask
• set_length
• set_extended_length
• set_mask_flag
• set_final_frame_flag
• set_reserved_flags

WebSocketMessage::constructor

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.

Parameters

n/a

Return Value

n/a

Exceptions

n/a

WebSocketMessage::destructor

virtual ~WebSocketMessage( void );

Clean-up class instance; see also constructor.

Parameters

n/a

Return Value

n/a

Exceptions

No exceptions allowed specification: noexcept.

WebSocketMessage::to_bytes

Bytes to_bytes( void ) const;

Convert instance to a collection of Bytes

Parameters

n/a

Return Value

Bytes containing a representation of the current WebSocketMessage state.

Exceptions

n/a

WebSocketMessage::get_data

Bytes get_data( void ) const;

Get data segment.

Parameters

n/a

Return Value

Bytes containing message data.

Exceptions

n/a

WebSocketMessage::get_opcode

OpCode get_opcode( void ) const;

Get operation code.

Parameters

n/a

Return Value

WebSocketMessage::OpCode detailing operation code in use.

Exceptions

n/a

WebSocketMessage::get_mask

std::uint32_t get_mask( void ) const;

Get message mask.

Parameters

n/a

Return Value

std::uint32_t detailing message length.

Exceptions

n/a

WebSocketMessage::get_length

std::uint8_t get_length( void ) const;

Get message data length.

Parameters

n/a

Return Value

std::uint8_t detailing mask to use on message data.

Exceptions

n/a

WebSocketMessage::get_extended_length

std::uint64_t get_extended_length( void ) const;

Get message data extended length.

Parameters

n/a

Return Value

std::uint64_t detailing message extended length.

Exceptions

n/a

WebSocketMessage::get_mask_flag

bool get_mask_flag( void ) const;

Get flag indicating if a mask is in use.

Parameters

n/a

Return Value

Boolean indicating a mask is in use.

Exceptions

n/a

WebSocketMessage::get_mask_flag

bool get_final_frame_flag( void ) const;

Get flag indicating if this message is the final frame.

Parameters

n/a

Return Value

Boolean indicating a final frame.

Exceptions

n/a

WebSocketMessage::get_reserved_flags

std::tuple< bool, bool, bool > get_reserved_flags( void ) const;

Get reserved flags

Parameters

n/a

Return Value

std::tuple of reserved flags.

Exceptions

n/a

WebSocketMessage::set_data

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	n/a	input
value	std::string	n/a	input

Return Value

n/a

Exceptions

n/a

WebSocketMessage::set_opcode

void set_opcode( const OpCode value );

Set message operation code.

Parameters

name	type	default value	direction
value	WebSocketMessage::OpCode	n/a	input

Return Value

n/a

Exceptions

n/a

WebSocketMessage::set_mask

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	n/a	input

Return Value

n/a

Exceptions

n/a

WebSocketMessage::set_length

void set_length( const std::uint8_t value );

Set message length.

Parameters

name	type	default value	direction
value	std::uint8_t	n/a	input

Return Value

n/a

Exceptions

n/a

WebSocketMessage::set_extended_length

void set_extended_length( const std::uint64_t value );

Set message extended length.

Parameters

name	type	default value	direction
value	std::uint64_t	n/a	input

Return Value

n/a

Exceptions

n/a

WebSocketMessage::set_extended_length

void set_mask_flag( const bool value );

Setting true indicates a message mask is in place.

Parameters

name	type	default value	direction
value	Boolean	n/a	input

Return Value

n/a

Exceptions

n/a

WebSocketMessage::set_final_frame_flag

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	n/a	input

Return Value

n/a

Exceptions

n/a

WebSocketMessage::set_reserved_flags

void set_reserved_flags( const bool rsv1, const bool rsv2, const bool rsv3 );

Set reserved flags.

Parameters

name	type	default value	direction
rsv1	Boolean	n/a	input
rsv2	Boolean	n/a	input
rsv3	Boolean	n/a	input

Return Value

n/a

Exceptions

n/a

WebSocketMessage::OpCode

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 detailing WebSocket message operation codes.

### Further Reading

C++ 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 - Comprehensive C++ and Standard Template Library (STL) reference.

Effective STL - 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++ - “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