\input texinfo

This manual is for libhttpserver

(version @value{VERSION}, @value{UPDATED}), C++ library for creating an

embedded Rest HTTP server (and more).

Copyright @copyright{} 2011--2013 Sebastiano Merlino

libhttpserver is meant to constitute an easy system to build HTTP

servers with REST fashion.

libhttpserver is based on libmicrohttpd and, like this, it is a

daemon library.

The mission of this library is to support all possible HTTP features

directly and with a simple semantic allowing then the user to concentrate

only on his application and not on HTTP request handling details.

The library is supposed to work transparently for the client Implementing

the business logic and using the library itself to realize an interface.

If the user wants it must be able to change every behavior of the library

itself through the registration of callbacks.

Like the api is based on (libmicrohttpd), libhttpserver is able to decode

certain body format a and automatically format them in object oriented

fashion. This is true for query arguments and for @code{POST} and @code{PUT}

requests bodies if @code{application/x-www-form-urlencoded} or

@code{multipart/form-data} header are passed.

The header reproduce all the constants defined by libhttpserver.

These maps various constant used by the HTTP protocol that are exported

as a convenience for users of the library. Is is possible for the user

to define their own extensions of the HTTP standard and use those with

libhttpserver.

All functions are guaranteed to be completely reentrant and

thread-safe.

Additionally, clients can specify resource limits on the overall

number of connections, number of connections per IP address and memory

used per connection to avoid resource exhaustion.

libhttpserver uses the standard system where the usual build process

involves running

@deftp {CPP Class} http_resource

Represents the resource corresponding to a specific endpoint.

@end deftp

@deftp {CPP Class} http_request

Represents the request received by the resource that process it.

@end deftp

@deftp {CPP Class} http_response

Represents the response sent by the server once the resource

finished its work.

@end deftp

@deftp {CPP Class} webserver

Represents the daemon listening on a socket for HTTP traffic.

@end deftp

Callbacks are functions defined by the client and then used by the library. This way

it is possible to extend the library itself.

@deftypefn {Function Pointer} void {*log_access_ptr} (const std::string& uri)

Invoked by the library when a new connection is opened by the client.

@table @var

@item uri

A string containing the uri called by the client and the method it used.

@end deftypefn

@deftypefn {Function Pointer} void {*log_error_ptr} (const std::string& message)

Invoked by the library to send error messages.

@table @var

@item message

A string containing the message to log.

@end deftypefn

@deftypefn {Function Pointer} void {*unescaper_ptr} (char* uri)

Invoked by the library to unescape the uri requested by the client.

If no unescaper_ptr is passed to the webserver it uses the internal defined

unescaper function.

@table @var

@item uri

A c-style string containing the uri to unescape.

@end deftypefn

@deftypemethod {webserver}{} webserver (int port, const http_utils::start_method_T& start_method, int max_threads, int max_connections, int memory_limit, int connection_timeout, int per_IP_connection_limit, log_access_ptr log_access, log_error_ptr log_error, validator_ptr validator, unescaper_ptr unescaper, const struct sockaddr* bind_address, int bind_socket, int max_thread_stack_size, bool use_ssl, bool use_ipv6, bool debug, bool pedantic, const std::string& https_mem_key, const std::string& https_mem_cert, const std::string& https_mem_trust, const std::string& https_mem_priorities, const http_utils::cred_type_T& cred_type, const std::string digest_auth_random, int nonce_nc_size, const http_utils::policy_T& default_policy, bool basic_auth_enabled, bool digest_auth_enabled, bool regex_checking, bool ban_system_enabled, bool post_process_enabled, render_ptr single_resource, render_ptr not_found_resource, render_ptr method_not_allowed_resource, render_ptr method_not_acceptable_resource, render_ptr internal_error_resource)

@end deftypemethod