Embedded HTTP Server
Typedefs | Enumerations | Functions | Variables
http Namespace Reference

Namespace with scope for all Embedded HTTP Server definitions. More...

Typedefs

typedef std::function< void(std::ostream &, connection_event)> connection_callback_type
 
typedef std::function< void(std::ostream &, const std::string &, const std::string &)> get_action_type
 
typedef std::function< void(std::ostream &, const std::string &, const std::string &, std::istream &, std::size_t, const std::string &)> post_action_type
 
typedef std::unordered_map< std::string, std::string > params_map_type
 Type of map {key->value,...} for decoding URL and form parameters.
 

Enumerations

enum  connection_event { just_connected, to_be_closed }
 Type defining possible connection events, used to notify the connection callback. More...
 

Functions

void server_start (int port_number, const char *base_directory)
 Start the embedded HTTP server. More...
 
void register_connection_callback (connection_callback_type callback)
 
void register_generic_get_action (const char *name, get_action_type f)
 
void register_html_get_action (const char *name, get_action_type f)
 
void register_text_get_action (const char *name, get_action_type f)
 
void register_generic_post_action (const char *name, post_action_type f)
 
void register_html_post_action (const char *name, post_action_type f)
 
void register_text_post_action (const char *name, post_action_type f)
 
std::string html_encode (const std::string &s)
 
std::string url_encode (const std::string &s)
 
std::string url_decode (const std::string &s)
 
params_map_type decode_params (const std::string &params, bool decode)
 
std::string header (const std::string &mime_type, std::size_t content_length=0, bool cache=false)
 

Variables

const unsigned int log_connections = 0x01
 Bit masks for various categories of diagnostic log messages.
 

Detailed Description

Namespace with scope for all Embedded HTTP Server definitions.

Typedef Documentation

◆ connection_callback_type

typedef std::function<void(std::ostream &, connection_event)> http::connection_callback_type

Type of function callback for connection event notifications.

Parameters
outstream object that is the subject of the current event.
eventthe name of current event.

◆ get_action_type

typedef std::function<void(std::ostream &, const std::string &, const std::string &)> http::get_action_type

Type of function callback for handling GET requests.

Parameters
outstream object handling the requesting client connection
pathname of the requested resource (up to the '?' sign, if any)
paramsthe URL parameters (from the '?' sign to the end of URL)

◆ post_action_type

typedef std::function<void(std::ostream &, const std::string &, const std::string &, std::istream &, std::size_t, const std::string &)> http::post_action_type

Type of function callback for handling POST requests.

Parameters
outstream object handling the output part of the requesting client connection
pathname of the requested resource (up to the '?' sign, if any)
paramsthe URL parameters (from the '?' sign to the end of URL)
instream object handling the input part of the requesting connection
content_lengthnumber of bytes to be consumed from the in stream
mime_typeMIME type declared for the POST request by the client

Enumeration Type Documentation

◆ connection_event

Type defining possible connection events, used to notify the connection callback.

Enumerator
just_connected 

The given stream (client connection) was just created.

to_be_closed 

The given stream is to be closed and destroyed.

Function Documentation

◆ decode_params()

params_map_type http::decode_params ( const std::string &  params,
bool  decode 
)

Decode URL or form parameters.

Decode URL or form parameters into map. The encoded parameters are expected to have the "key1=value1&key2=value2&..." format.

Parameters
paramsparameters, stored as a single string, to be decoded.
Returns
decoded parameter map.

◆ header()

std::string http::header ( const std::string &  mime_type,
std::size_t  content_length = 0,
bool  cache = false 
)

Generate basic HTTP header.

Generate basic HTTP header, typically for the generic resource handler, of the form: HTTP/1.1 200 OK Content-Type: mime_type Content-Length: content_length Cache-Control: ...

Parameters
mime_typeMIME type declaration.
content_lengthnumber of bytes in the response body.
cachewhether the given response is supposed to be cached
Returns
generated HTTP header.

◆ html_encode()

std::string http::html_encode ( const std::string &  s)

Encode basic HTML entities.

Encode basic HTML entities - '<', '>', '&'. Those special characters are replaced with "&lt;", "&gt;" and "&amp;".

Parameters
sstring to be encoded.
Returns
encoded string.

◆ register_connection_callback()

void http::register_connection_callback ( connection_callback_type  callback)

Register the connection callback.

Register the connection callback. The callback function will be notified whenever the client connection is created to is about to be destroyed. The previous callback registration (if any) is replaced.

Parameters
callbackthe callback function to register.

◆ register_generic_get_action()

void http::register_generic_get_action ( const char *  name,
get_action_type  f 
)

Register generic GET handler.

Register generic GET handler. The generic handler is responsible for producing the whole response, including HTTP headers, and for flushing the output stream.

Note: generic actions are called in the context of the thread that is dedicated for the given connection and the stream object retains state between invocations (it directly represents the connection stream).

Parameters
namename of the "resource" to be handled by the callback.
ffunction callback that will handle the GET request.

◆ register_generic_post_action()

void http::register_generic_post_action ( const char *  name,
post_action_type  f 
)

Register generic POST handler.

Register generic POST handler. The generic handler is responsible for producing the whole response, including HTTP headers.

Note: generic actions are called in the context of the thread that is dedicated for the given connection and the stream object retains state between invocations (it directly represents the connection stream).

Parameters
namename of the "resource" to be handled by the callback.
ffunction callback that will handle the POST request.

◆ register_html_get_action()

void http::register_html_get_action ( const char *  name,
get_action_type  f 
)

Register text/html GET handler.

Register text/html GET handler. The text/html handler is responsible for producing only the response data, the HTTP headers are taken care of automatically.

Note: the text/html action is called in the context of the thread that is dedicated for the given connection, but the stream object is temporary and does not retain state between invocations. The collected output is automatically flushed to the actual connection stream.

Parameters
namename of the "resource" to be handled by the callback.
ffunction callback that will handle the GET request.

◆ register_html_post_action()

void http::register_html_post_action ( const char *  name,
post_action_type  f 
)

Register text/html POST handler.

Register text/html POST handler. The text/html handler is responsible for producing only the response data, the HTTP headers are taken care of automatically.

Note: the text/html action is called in the context of the thread that is dedicated for the given connection, but the stream object is temporary and does not retain state between invocations. The collected output is automatically flushed to the actual connection stream.

Parameters
namename of the "resource" to be handled by the callback.
ffunction callback that will handle the POST request.

◆ register_text_get_action()

void http::register_text_get_action ( const char *  name,
get_action_type  f 
)

Register text/plain GET handler.

Register text/plain GET handler. The text/plain handler is responsible for producing only the response data, the HTTP headers are taken care of automatically.

Note: the text/plain action is called in the context of the thread that is dedicated for the given connection, but the stream object is temporary and does not retain state between invocations. The collected output is automatically flushed to the actual connection stream.

Parameters
namename of the "resource" to be handled by the callback.
ffunction callback that will handle the GET request.

◆ register_text_post_action()

void http::register_text_post_action ( const char *  name,
post_action_type  f 
)

Register text/plain POST handler.

Register text/plain POST handler. The text/plain handler is responsible for producing only the response data, the HTTP headers are taken care of automatically.

Note: the text/plain action is called in the context of the thread that is dedicated for the given connection, but the stream object is temporary and does not retain state between invocations. The collected output is automatically flushed to the actual connection stream.

Parameters
namename of the "resource" to be handled by the callback.
ffunction callback that will handle the POST request.

◆ server_start()

void http::server_start ( int  port_number,
const char *  base_directory 
)

Start the embedded HTTP server.

Start the singleton embedded HTTP server. The server creates the listener socket and operates it in the context of the calling thread.

Parameters
port_numberport number for the listening socket
base_directorydirectory containing static files.
error_logoptional output stream for diagnostic logs
log_events_maskbit mask for selecting active categories of log messages
Returns
This function does not return as long as the server functions properly.

◆ url_decode()

std::string http::url_decode ( const std::string &  s)

Decode part of the URL (used for parameters).

Decode part of the URL, using reverse logic of url_encode.

Parameters
sstring to be decoded.
Returns
decoded string.

◆ url_encode()

std::string http::url_encode ( const std::string &  s)

Encode string for safe use within URL.

Encode string for safe use within URL. Alpha-numeric characters, with '-', '_', '.' and '~' are left unchanged, other characters are encoded as hh hex code (space is replaced with '+').

Parameters
sstring to be encoded.
Returns
encoded string.