\input texinfo
@setfilename libhttpserver.info
@include version.texi
@settitle The libhttpserver Reference Manual
@c Unify all the indices into concept index.
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp
@copying
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
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled "GNU
Free Documentation License".
@end quotation
@end copying
@dircategory Software libraries
@direntry
* libhttpserver: (libhttpserver). C++ library for creating an
embedded Rest HTTP server (and more).
@end direntry
@c
@c Titlepage
@c
@titlepage
@title The libhttpserver Reference Manual
@subtitle Version @value{VERSION}
@subtitle @value{UPDATED}
@author Sebastiano Merlino (@email{electrictwister2000@@gmail.com})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@ifnottex
@node Top
@top The libhttpserver Library
@insertcopying
@end ifnottex
@c @summarycontents
@c @contents
@c ------------------------------------------------------------
@menu
* httpserver-intro:: Introduction.
* httpserver-const:: Constants.
* httpserver-struct:: Structures and classes type definition.
* httpserver-cb:: Callback functions definition.
* httpserver-init:: Create and work with server.
* httpserver-resources:: Registering resources.
* httpserver-responses:: Building responses to requests.
* httpserver-bans:: Whitelists and Blacklists.
* httpserver-comet:: Simple comet semantics.
* httpserver-dauth:: Utilizing Authentication.
* httpserver-info:: Obtaining and modifying status information.
Appendices
* GNU-LGPL:: The GNU Lesser General Public License says how you
can copy and share almost all of `libhttpserver'.
* GNU-FDL:: The GNU Free Documentation License says how you
can copy and share the documentation of `libhttpserver'.
Indices
* Concept Index:: Index of concepts and programs.
* Function and Data Index:: Index of functions, variables and data types.
* Type Index:: Index of data types.
@end menu
@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@c ------------------------------------------------------------
@node httpserver-intro
@chapter Introduction
@noindent
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.
@section Compiling libhttpserver
@cindex compilation
@cindex embedded systems
@cindex portability
libhttpserver uses the standard system where the usual build process
involves running
@verbatim
$ ./bootstrap
$ mkdir build
$ cd build
$ ./configure
$ make
$ make install
@end verbatim
@c ------------------------------------------------------------
@node httpserver-const
@chapter Constants
@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@c ------------------------------------------------------------
@node httpserver-struct
@chapter Structures and classes type definition
@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
@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@c ------------------------------------------------------------
@node httpserver-cb
@chapter Callback functions definition
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 table
@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 table
@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 table
@end deftypefn
@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@c ------------------------------------------------------------
@node httpserver-init
@chapter Create and work with server
@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
@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@c -----------------------------------------------------------
@node httpserver-resources
@chapter Registering resources
@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@c ------------------------------------------------------------
@node httpserver-responses
@chapter Building responses to requests
@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@c ------------------------------------------------------------
@c @node httpserver-response create
@c @section Creating a response object
@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@c ------------------------------------------------------------
@c @node httpserver-response headers
@c @section Adding headers to a response
@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@c ------------------------------------------------------------
@c @node httpserver-response inspect
@c @section Inspecting a response object
@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@c ------------------------------------------------------------
@node httpserver-dauth
@chapter Utilizing Authentication
@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@c ------------------------------------------------------------
@node httpserver-info
@chapter Obtaining and modifying status information.
@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@c ------------------------------------------------------------
@node httpserver-bans
@chapter AAAA
@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@c ------------------------------------------------------------
@node httpserver-comet
@chapter AAAA
@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@c **********************************************************
@c ******************* Appendices *************************
@c **********************************************************
@node GNU-LGPL
@unnumbered GNU-LGPL
@cindex license
@include lgpl.texi
@node GNU-FDL
@unnumbered GNU-FDL
@cindex license
@include fdl-1.3.texi
@node Concept Index
@unnumbered Concept Index
@printindex cp
@node Function and Data Index
@unnumbered Function and Data Index
@printindex fn
@node Type Index
@unnumbered Type Index
@printindex tp
@bye