diff options
Diffstat (limited to 'doc/libmicrohttpd.texi')
| -rw-r--r-- | doc/libmicrohttpd.texi | 2824 |
1 files changed, 2824 insertions, 0 deletions
diff --git a/doc/libmicrohttpd.texi b/doc/libmicrohttpd.texi new file mode 100644 index 00000000..7e13a27a --- /dev/null +++ b/doc/libmicrohttpd.texi @@ -0,0 +1,2824 @@ +\input texinfo +@setfilename libmicrohttpd.info +@include version.texi +@settitle The GNU libmicrohttpd Reference Manual +@c Unify all the indices into concept index. +@syncodeindex vr cp +@syncodeindex ky cp +@syncodeindex pg cp +@copying +This manual is for GNU libmicrohttpd +(version @value{VERSION}, @value{UPDATED}), a library for embedding +an HTTP(S) server into C applications. + +Copyright @copyright{} 2007--2013 Christian Grothoff + +@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 +* libmicrohttpd: (libmicrohttpd). Embedded HTTP server library. +@end direntry + +@c +@c Titlepage +@c +@titlepage +@title The GNU libmicrohttpd Reference Manual +@subtitle Version @value{VERSION} +@subtitle @value{UPDATED} +@author Marco Maggi (@email{marco.maggi-ipsu@@poste.it}) +@author Christian Grothoff (@email{christian@@grothoff.org}) +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@summarycontents +@contents + +@c ------------------------------------------------------------ +@ifnottex +@node Top +@top The GNU libmicrohttpd Library +@insertcopying +@end ifnottex + +@menu +* microhttpd-intro:: Introduction. +* microhttpd-const:: Constants. +* microhttpd-struct:: Structures type definition. +* microhttpd-cb:: Callback functions definition. +* microhttpd-init:: Starting and stopping the server. +* microhttpd-inspect:: Implementing external @code{select}. +* microhttpd-requests:: Handling requests. +* microhttpd-responses:: Building responses to requests. +* microhttpd-flow:: Flow control. +* microhttpd-dauth:: Utilizing Authentication. +* microhttpd-post:: Adding a @code{POST} processor. +* microhttpd-info:: Obtaining and modifying status information. +* microhttpd-util:: Utilities. + +Appendices + +* GNU-LGPL:: The GNU Lesser General Public License says how you + can copy and share almost all of `libmicrohttpd'. +* GNU GPL with eCos Extension:: The GNU General Public License with eCos extension says how you + can copy and share some parts of `libmicrohttpd'. +* GNU-FDL:: The GNU Free Documentation License says how you + can copy and share the documentation of `libmicrohttpd'. + +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 microhttpd-intro +@chapter Introduction + + +@noindent +All symbols defined in the public API start with @code{MHD_}. MHD +is a small HTTP daemon library. As such, it does not have any API +for logging errors (you can only enable or disable logging to stderr). +Also, it may not support all of the HTTP features directly, where +applicable, portions of HTTP may have to be handled by clients of the +library. + +The library is supposed to handle everything that it must handle +(because the API would not allow clients to do this), such as basic +connection management; however, detailed interpretations of headers --- +such as range requests --- and HTTP methods are left to clients. The +library does understand @code{HEAD} and will only send the headers of +the response and not the body, even if the client supplied a body. The +library also understands headers that control connection management +(specifically, @code{Connection: close} and @code{Expect: 100 continue} +are understood and handled automatically). + +MHD understands @code{POST} data and is able to decode certain +formats (at the moment only @code{application/x-www-form-urlencoded} +and @code{multipart/form-data}) using the post processor API. The +data stream of a POST is also provided directly to the main +application, so unsupported encodings could still be processed, just +not conveniently by MHD. + +The header file defines various constants used by the HTTP protocol. +This does not mean that MHD actually interprets all of these values. +The provided constants are exported as a convenience for users of the +library. MHD does not verify that transmitted HTTP headers are +part of the standard specification; users of the library are free to +define their own extensions of the HTTP standard and use those with +MHD. + +All functions are guaranteed to be completely reentrant and +thread-safe. MHD checks for allocation failures and tries to +recover gracefully (for example, by closing the connection). +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 Scope + +MHD is currently used in a wide range of implementations. +Examples based on reports we've received from developers include: +@itemize +@item Embedded HTTP server on a cortex M3 (128 KB code space) +@item Large-scale multimedia server (reportedly serving at the + simulator limit of 7.5 GB/s) +@item Administrative console (via HTTP/HTTPS) for network appliances +@c If you have other interesting examples, please let us know +@end itemize + +@section Thread modes and event loops +@cindex poll +@cindex epoll +@cindex select + +MHD supports four basic thread modes and up to three event loop +styes. + +The four basic thread modes are external (MHD creates no threads, +event loop is fully managed by the application), internal (MHD creates +one thread for all connections), thread pool (MHD creates a thread +pool which is used to process all connections) and +thread-per-connection (MHD creates one listen thread and then one +thread per accepted connection). + +These thread modes are then combined with the event loop styles. +MHD support select, poll and epoll. epoll is only available on +Linux, poll may not be available on some platforms. Note that +it is possible to combine MHD using epoll with an external +select-based event loop. + +The default (if no other option is passed) is ``external select''. +The highest performance can typically be obtained with a thread pool +using @code{epoll}. Apache Benchmark (ab) was used to compare the +performance of @code{select} and @code{epoll} when using a thread pool +and a large number of connections. @ref{fig:performance} shows the +resulting plot from the @code{benchmark.c} example, which measures the +latency between an incoming request and the completion of the +transmission of the response. In this setting, the @code{epoll} +thread pool with four threads was able to handle more than 45,000 +connections per second on loopback (with Apache Benchmark running +three processes on the same machine). +@cindex performance + + +@float Figure,fig:performance +@image{performance_data,400pt,300pt,Data,.png} +@caption{Performance measurements for select vs. epoll (with thread-pool).} +@end float + + +Not all combinations of thread modes and event loop styles are +supported. This is partially to keep the API simple, and partially +because some combinations simply make no sense as others are strictly +superior. Note that the choice of style depends fist of all on the +application logic, and then on the performance requirements. +Applications that perform a blocking operation while handling a +request within the callbacks from MHD must use a thread per +connection. This is typically rather costly. Applications that do +not support threads or that must run on embedded devices without +thread-support must use the external mode. Using @code{epoll} is only +supported on Linux, thus portable applications must at least have a +fallback option available. @ref{tbl:supported} lists the sane +combinations. + +@float Table,tbl:supported +@multitable {@b{thread-per-connection}} {@b{select}} {@b{poll}} {@b{epoll}} +@item @tab @b{select} @tab @b{poll} @tab @b{epoll} +@item @b{external} @tab yes @tab no @tab yes +@item @b{internal} @tab yes @tab yes @tab yes +@item @b{thread pool} @tab yes @tab yes @tab yes +@item @b{thread-per-connection} @tab yes @tab yes @tab no +@end multitable +@caption{Supported combinations of event styles and thread modes.} +@end float + + +@section Compiling GNU libmicrohttpd +@cindex compilation +@cindex embedded systems +@cindex portability + +MHD uses the standard GNU system where the usual build process +involves running +@verbatim +$ ./configure +$ make +$ make install +@end verbatim + +MHD supports various options to be given to configure to tailor the +binary to a specific situation. Note that some of these options will +remove portions of the MHD code that are required for +binary-compatibility. They should only be used on embedded systems +with tight resource constraints and no concerns about library +versioning. Standard distributions including MHD are expected to +always ship with all features enabled, otherwise unexpected +incompatibilities can arise! + +Here is a list of MHD-specific options that can be given to configure +(canonical configure options such as ``--prefix'' are also supported, for a +full list of options run ``./configure --help''): + +@table @code +@item ``--disable-curl'' +disable running testcases using libcurl + +@item ``--disable-largefile'' +disable support for 64-bit files + +@item ``--disable-messages'' +disable logging of error messages (smaller binary size, not so much fun for debugging) + +@item ``--disable-https'' +disable HTTPS support, even if GNUtls is found; this option must be used if eCOS license is desired as an option (in all cases the resulting binary falls under a GNU LGPL-only license) + +@item ``--disable-postprocessor'' +do not include the post processor API (results in binary incompatibility) + +@item ``--disable-dauth'' +do not include the authentication APIs (results in binary incompatibility) + +@item ``--disable-epoll +do not include epoll support, even on Linux (minimally smaller binary size, good for testing portability to non-Linux systems) + +@item ``--enable-coverage'' +set flags for analysis of code-coverage with gcc/gcov (results in slow, large binaries) + +@item ``--with-gcrypt=PATH'' +specifies path to libgcrypt installation + +@item ``--with-gnutls=PATH'' +specifies path to libgnutls installation + + +@end table + +@section Validity of pointers + +MHD will give applications access to its internal data structures +via pointers via arguments and return values from its API. This +creates the question as to how long those pointers are assured to +stay valid. + +Most MHD data structures are associated with the connection of an +HTTP client. Thus, pointers associated with a connection are +typically valid until the connection is finished, at which point +MHD will call the @code{MHD_RequestCompletedCallback} if one is +registered. Applications that have such a callback registered +may assume that keys and values from the +@code{MHD_KeyValueIterator}, return values from +@code{MHD_lookup_connection_value} and the @code{url}, +@code{method} and @code{version} arguments to the +@code{MHD_AccessHandlerCallback} will remain valid until the +respective @code{MHD_RequestCompletedCallback} is invoked. + +In contrast, the @code{upload_data} argument of +@code{MHD_RequestCompletedCallback} as well as all pointers +from the @code{MHD_PostDataIterator} are only valid for the +duration of the callback. + +Pointers returned from @code{MHD_get_response_header} are +valid as long as the response itself is valid. + + +@section Including the microhttpd.h header +@cindex portability +@cindex microhttpd.h + +Ideally, before including "microhttpd.h" you should add the necessary +includes to define the @code{uint64_t}, @code{size_t}, @code{fd_set}, +@code{socklen_t} and @code{struct sockaddr} data types. Which +specific headers are needed may depend on your platform and your build +system might include some tests to provide you with the necessary +conditional operations. For possible suggestions consult +@code{platform.h} and @code{configure.ac} in the MHD distribution. + +Once you have ensured that you manually (!) included the right headers +for your platform before "microhttpd.h", you should also add a line +with @code{#define MHD_PLATFORM_H} which will prevent the +"microhttpd.h" header from trying (and, depending on your platform, +failing) to include the right headers. + +If you do not define MHD_PLATFORM_H, the "microhttpd.h" header will +automatically include headers needed on GNU/Linux systems (possibly +causing problems when porting to other platforms). + +@section SIGPIPE +@cindex signals +MHD does not install a signal handler for SIGPIPE. On platforms +where this is possible (such as GNU/Linux), it disables SIGPIPE for +its I/O operations (by passing MSG_NOSIGNAL). On other platforms, +SIGPIPE signals may be generated from network operations by +MHD and will cause the process to die unless the developer +explicitly installs a signal handler for SIGPIPE. + +Hence portable code using MHD must install a SIGPIPE handler or +explicitly block the SIGPIPE signal. MHD does not do so in order +to avoid messing with other parts of the application that may +need to handle SIGPIPE in a particular way. You can make your application handle SIGPIPE by calling the following function in @code{main}: + +@verbatim +static void +catcher (int sig) +{ +} + +static void +ignore_sigpipe () +{ + struct sigaction oldsig; + struct sigaction sig; + + sig.sa_handler = &catcher; + sigemptyset (&sig.sa_mask); +#ifdef SA_INTERRUPT + sig.sa_flags = SA_INTERRUPT; /* SunOS */ +#else + sig.sa_flags = SA_RESTART; +#endif + if (0 != sigaction (SIGPIPE, &sig, &oldsig)) + fprintf (stderr, + "Failed to install SIGPIPE handler: %s\n", strerror (errno)); +} +@end verbatim + +@section MHD_UNSIGNED_LONG_LONG +@cindex long long +@cindex MHD_LONG_LONG +@cindex IAR +@cindex ARM +@cindex cortex m3 +@cindex embedded systems + +Some platforms do not support @code{long long}. Hence MHD defines a +macro @code{MHD_UNSIGNED LONG_LONG} which will default to +@code{unsigned long long}. For standard desktop operating systems, +this is all you need to know. + +However, if your platform does not support @code{unsigned long long}, +you should change "platform.h" to define @code{MHD_LONG_LONG} and +@code{MHD_UNSIGNED_LONG_LONG} to an appropriate alternative type and +also define @code{MHD_LONG_LONG_PRINTF} and +@code{MHD_UNSIGNED_LONG_LONG_PRINTF} to the corresponding format +string for printing such a data type. Note that the ``signed'' +versions are deprecated. Also, for historical reasons, +@code{MHD_LONG_LONG_PRINTF} is without the percent sign, whereas +@code{MHD_UNSIGNED_LONG_LONG_PRINTF} is with the percent sign. Newly +written code should only use the unsigned versions. However, you need +to define both in "platform.h" if you need to change the definition +for the specific platform. + + +@section Portability to W32 + +libmicrohttpd in general ported well to W32. Most libmicrohttpd features +are supported. W32 do not support some functions, like epoll and +corresponding MHD features are not available on W32. + + +@section Portability to z/OS + +To compile MHD on z/OS, extract the archive and run + +@verbatim +iconv -f UTF-8 -t IBM-1047 contrib/ascebc > /tmp/ascebc.sh +chmod +x /tmp/ascebc.sh +for n in `find * -type f` +do + /tmp/ascebc.sh $n +done +@end verbatim +to convert all source files to EBCDIC. Note that you must run +@code{configure} from the directory where the configure script is +located. Otherwise, configure will fail to find the +@code{contrib/xcc} script (which is a wrapper around the z/OS c89 +compiler). + + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-const +@chapter Constants + + +@deftp {Enumeration} MHD_FLAG +Options for the MHD daemon. + +Note that if neither @code{MHD_USE_THREAD_PER_CONNECTION} nor +@code{MHD_USE_SELECT_INTERNALLY} is used, the client wants control over +the process and will call the appropriate microhttpd callbacks. + +Starting the daemon may also fail if a particular option is not +implemented or not supported on the target platform (i.e. no support for +@acronym{SSL}, threads or IPv6). SSL support generally depends on +options given during MHD compilation. Threaded operations +(including @code{MHD_USE_SELECT_INTERNALLY}) are not supported on +Symbian. + +@table @code +@item MHD_NO_FLAG +No options selected. + +@item MHD_USE_DEBUG +@cindex debugging +Run in debug mode. If this flag is used, the library should print error +messages and warnings to stderr. Note that for this +run-time option to have any effect, MHD needs to be +compiled with messages enabled. This is done by default except you ran +configure with the @code{--disable-messages} flag set. + +@item MHD_USE_SSL +@cindex TLS +@cindex SSL +Run in HTTPS-mode. If you specify @code{MHD_USE_SSL} and MHD was +compiled without SSL support, @code{MHD_start_daemon} will return +NULL. + +@item MHD_USE_THREAD_PER_CONNECTION +Run using one thread per connection. + +@item MHD_USE_SELECT_INTERNALLY +Run using an internal thread doing @code{SELECT}. + +@item MHD_USE_IPv6 +@cindex IPv6 +Run using the IPv6 protocol (otherwise, MHD will just support IPv4). +If you specify @code{MHD_USE_IPV6} and the local platform does not +support it, @code{MHD_start_daemon} will return NULL. + +If you want MHD to support IPv4 and IPv6 using a single socket, pass +MHD_USE_DUAL_STACK, otherwise, if you only pass this option, MHD will +try to bind to IPv6-only (resulting in no IPv4 support). + +@item MHD_USE_DUAL_STACK +@cindex IPv6 +Use a single socket for IPv4 and IPv6. Note that this will mean +that IPv4 addresses are returned by MHD in the IPv6-mapped format +(the 'struct sockaddr_in6' format will be used for IPv4 and IPv6). + +@item MHD_USE_PEDANTIC_CHECKS +Be pedantic about the protocol (as opposed to as tolerant as possible). +Specifically, at the moment, this flag causes MHD to reject HTTP +1.1 connections without a @code{Host} header. This is required by the +standard, but of course in violation of the ``be as liberal as possible +in what you accept'' norm. It is recommended to turn this @strong{ON} +if you are testing clients against MHD, and @strong{OFF} in +production. + +@item MHD_USE_POLL +@cindex FD_SETSIZE +@cindex poll +@cindex select +Use poll instead of select. This allows sockets with descriptors +@code{>= FD_SETSIZE}. This option currently only works in conjunction +with @code{MHD_USE_THREAD_PER_CONNECTION} or +@code{MHD_USE_INTERNAL_SELECT} (at this point). If you specify +@code{MHD_USE_POLL} and the local platform does not support it, +@code{MHD_start_daemon} will return NULL. + +@item MHD_USE_EPOLL_LINUX_ONLY +@cindex FD_SETSIZE +@cindex epoll +@cindex select +Use epoll instead of poll or select. This allows sockets with +descriptors @code{>= FD_SETSIZE}. This option is only available on +Linux systems and only works in conjunction with +@code{MHD_USE_THREAD_PER_CONNECTION} (at this point). If you specify +@code{MHD_USE_EPOLL_LINUX_ONLY} and the local platform does not +support it, @code{MHD_start_daemon} will return NULL. Using epoll +instead of select or poll can in some situations result in significantly +higher performance as the system call has fundamentally lower complexity +(O(1) for epoll vs. O(n) for select/poll where n is the number of +open connections). + +@item MHD_SUPPRESS_DATE_NO_CLOCK +@cindex date +@cindex clock +@cindex embedded systems +Suppress (automatically) adding the 'Date:' header to HTTP responses. +This option should ONLY be used on systems that do not have a clock +and that DO provide other mechanisms for cache control. See also +RFC 2616, section 14.18 (exception 3). + + +@item MHD_USE_NO_LISTEN_SOCKET +@cindex listen +@cindex proxy +@cindex embedded systems +Run the HTTP server without any listen socket. This option only makes +sense if @code{MHD_add_connection} is going to be used exclusively to +connect HTTP clients to the HTTP server. This option is incompatible +with using a thread pool; if it is used, +@code{MHD_OPTION_THREAD_POOL_SIZE} is ignored. + +@item MHD_USE_PIPE_FOR_SHUTDOWN +@cindex quiesce +Force MHD to use a signal pipe to notify the event loop (of threads) +of our shutdown. This is required if an appliction uses +@code{MHD_USE_INTERNAL_SELECT} or @code{MHD_USE_THREAD_PER_CONNECTION} +and then performs @code{MHD_quiesce_daemon} (which eliminates our +ability to signal termination via the listen socket). In these modes, +@code{MHD_quiesce_daemon} will fail if this option was not set. Also, +use of this option is automatic (as in, you do not even have to +specify it), if @code{MHD_USE_NO_LISTEN_SOCKET} is specified. In +"external" select mode, this option is always simply ignored. + +@item MHD_USE_SUSPEND_RESUME +Enables using @code{MHD_suspend_connection} and +@code{MHD_resume_connection}, as performing these calls requires some +additional pipes to be created, and code not using these calls should +not pay the cost. + +@item MHD_USE_TCP_FASTOPEN +@cindex listen +Enable TCP_FASTOPEN on the listen socket. TCP_FASTOPEN is currently +supported on Linux >= 3.6. On other systems using this option with +cause @code{MHD_start_daemon} to fail. + +@end table +@end deftp + + +@deftp {Enumeration} MHD_OPTION +MHD options. Passed in the varargs portion of +@code{MHD_start_daemon()}. + +@table @code +@item MHD_OPTION_END +No more options / last option. This is used to terminate the VARARGs +list. + +@item MHD_OPTION_CONNECTION_MEMORY_LIMIT +@cindex memory, limiting memory utilization +Maximum memory size per connection (followed by a @code{size_t}). The +default is 32 kB (32*1024 bytes) as defined by the internal constant +@code{MHD_POOL_SIZE_DEFAULT}. Values above 128k are unlikely to +result in much benefit, as half of the memory will be typically used +for IO, and TCP buffers are unlikely to support window sizes above 64k +on most systems. + +@item MHD_OPTION_CONNECTION_MEMORY_INCREMENT +@cindex memory +Increment to use for growing the read buffer (followed by a +@code{size_t}). The default is 1024 (bytes). Increasing this value +will make MHD use memory for reading more aggressively, which can +reduce the number of @code{recvfrom} calls but may increase the number +of @code{sendto} calls. The given value must fit within +MHD_OPTION_CONNECTION_MEMORY_LIMIT. + +@item MHD_OPTION_CONNECTION_LIMIT +@cindex connection, limiting number of connections +Maximum number of concurrent connections to accept (followed by an +@code{unsigned int}). The default is @code{FD_SETSIZE - 4} (the +maximum number of file descriptors supported by @code{select} minus +four for @code{stdin}, @code{stdout}, @code{stderr} and the server +socket). In other words, the default is as large as possible. + +Note that if you set a low connection limit, you can easily get into +trouble with browsers doing request pipelining. For example, if your +connection limit is ``1'', a browser may open a first connection to +access your ``index.html'' file, keep it open but use a second +connection to retrieve CSS files, images and the like. In fact, modern +browsers are typically by default configured for up to 15 parallel +connections to a single server. If this happens, MHD will refuse to +even accept the second connection until the first connection is +closed --- which does not happen until timeout. As a result, the +browser will fail to render the page and seem to hang. If you expect +your server to operate close to the connection limit, you should +first consider using a lower timeout value and also possibly add +a ``Connection: close'' header to your response to ensure that +request pipelining is not used and connections are closed immediately +after the request has completed: +@example +MHD_add_response_header (response, + MHD_HTTP_HEADER_CONNECTION, + "close"); +@end example + +@item MHD_OPTION_CONNECTION_TIMEOUT +@cindex timeout +After how many seconds of inactivity should a connection automatically +be timed out? (followed by an @code{unsigned int}; use zero for no +timeout). The default is zero (no timeout). + +@item MHD_OPTION_NOTIFY_COMPLETED +Register a function that should be called whenever a request has been +completed (this can be used for application-specific clean up). +Requests that have never been presented to the application (via +@code{MHD_AccessHandlerCallback()}) will not result in +notifications. + +This option should be followed by @strong{TWO} pointers. First a +pointer to a function of type @code{MHD_RequestCompletedCallback()} +and second a pointer to a closure to pass to the request completed +callback. The second pointer maybe @code{NULL}. + +@item MHD_OPTION_NOTIFY_CONNECTION +Register a function that should be called when the TCP connection to a +client is opened or closed. Note that +@code{MHD_OPTION_NOTIFY_COMPLETED} and the @code{con_cls} argument to +the @code{MHD_AccessHandlerCallback} are per HTTP request (and there +can be multiple HTTP requests per TCP connection). The registered +callback is called twice per TCP connection, with +@code{MHD_CONNECTION_NOTIFY_STARTED} and +@code{MHD_CONNECTION_NOTIFY_CLOSED} respectively. An additional +argument can be used to store TCP connection specific information, +which can be retrieved using @code{MHD_CONNECTION_INFO_SOCKET_CONTEXT} +during the lifetime of the TCP connection. The respective location is +not the same as the HTTP-request-specific @code{con_cls} from the +@code{MHD_AccessHandlerCallback}. + +This option should be followed by @strong{TWO} pointers. First a +pointer to a function of type @code{MHD_NotifyConnectionCallback()} +and second a pointer to a closure to pass to the request completed +callback. The second pointer maybe @code{NULL}. + +@item MHD_OPTION_PER_IP_CONNECTION_LIMIT +Limit on the number of (concurrent) connections made to the +server from the same IP address. Can be used to prevent one +IP from taking over all of the allowed connections. If the +same IP tries to establish more than the specified number of +connections, they will be immediately rejected. The option +should be followed by an @code{unsigned int}. The default is +zero, which means no limit on the number of connections +from the same IP address. + +@item MHD_OPTION_SOCK_ADDR +@cindex bind, restricting bind +Bind daemon to the supplied socket address. This option should be followed by a +@code{struct sockaddr *}. If @code{MHD_USE_IPv6} is specified, +the @code{struct sockaddr*} should point to a @code{struct sockaddr_in6}, +otherwise to a @code{struct sockaddr_in}. If this option is not specified, +the daemon will listen to incoming connections from anywhere. If you use this +option, the 'port' argument from @code{MHD_start_daemon} is ignored and the port +from the given @code{struct sockaddr *} will be used instead. + +@item MHD_OPTION_URI_LOG_CALLBACK +@cindex debugging +@cindex logging +@cindex query string +Specify a function that should be called before parsing the URI from +the client. The specified callback function can be used for processing +the URI (including the options) before it is parsed. The URI after +parsing will no longer contain the options, which maybe inconvenient for +logging. This option should be followed by two arguments, the first +one must be of the form +@example + void * my_logger(void * cls, const char * uri, struct MHD_Connection *con) +@end example +where the return value will be passed as +@code{*con_cls} in calls to the @code{MHD_AccessHandlerCallback} +when this request is processed later; returning a +value of @code{NULL} has no special significance; (however, +note that if you return non-@code{NULL}, you can no longer +rely on the first call to the access handler having +@code{NULL == *con_cls} on entry) +@code{cls} will be set to the second argument following +MHD_OPTION_URI_LOG_CALLBACK. Finally, @code{uri} will +be the 0-terminated URI of the request. + +Note that during the time of this call, most of the connection's state +is not initialized (as we have not yet parsed he headers). However, +information about the connecting client (IP, socket) is available. + +@item MHD_OPTION_HTTPS_MEM_KEY +@cindex SSL +@cindex TLS +Memory pointer to the private key to be used by the +HTTPS daemon. This option should be followed by an +"const char*" argument. +This should be used in conjunction with 'MHD_OPTION_HTTPS_MEM_CERT'. + +@item MHD_OPTION_HTTPS_KEY_PASSWORD +@cindex SSL +@cindex TLS +Memory pointer to the password that decrypts the +private key to be used by the HTTPS daemon. +This option should be followed by an +"const char*" argument. +This should be used in conjunction with 'MHD_OPTION_HTTPS_MEM_KEY'. + +The password (or passphrase) is only used immediately during +@code{MHD_start_daemon()}. Thus, the application may want to +erase it from memory afterwards for additional security. + +@item MHD_OPTION_HTTPS_MEM_CERT +@cindex SSL +@cindex TLS +Memory pointer to the certificate to be used by the +HTTPS daemon. This option should be followed by an +"const char*" argument. +This should be used in conjunction with 'MHD_OPTION_HTTPS_MEM_KEY'. + +@item MHD_OPTION_HTTPS_MEM_TRUST +@cindex SSL +@cindex TLS +Memory pointer to the CA certificate to be used by the +HTTPS daemon to authenticate and trust clients certificates. +This option should be followed by an "const char*" argument. +The presence of this option activates the request of certificate +to the client. The request to the client is marked optional, and +it is the responsibility of the server to check the presence +of the certificate if needed. +Note that most browsers will only present a client certificate +only if they have one matching the specified CA, not sending +any certificate otherwise. + +@item MHD_OPTION_HTTPS_CRED_TYPE +@cindex SSL +@cindex TLS +Daemon credentials type. Either certificate or anonymous, +this option should be followed by one of the values listed in +"enum gnutls_credentials_type_t". + +@item MHD_OPTION_HTTPS_PRIORITIES +@cindex SSL +@cindex TLS +@cindex cipher +SSL/TLS protocol version and ciphers. +This option must be followed by an "const char *" argument +specifying the SSL/TLS protocol versions and ciphers that +are acceptable for the application. The string is passed +unchanged to gnutls_priority_init. If this option is not +specified, ``NORMAL'' is used. + +@item MHD_OPTION_HTTPS_CERT_CALLBACK +@cindex SSL +@cindex TLS +@cindex SNI +Use a callback to determine which X.509 certificate should be used for +a given HTTPS connection. This option should be followed by a +argument of type "gnutls_certificate_retrieve_function2 *". This +option provides an alternative to MHD_OPTION_HTTPS_MEM_KEY and +MHD_OPTION_HTTPS_MEM_CERT. You must use this version if multiple +domains are to be hosted at the same IP address using TLS's Server +Name Indication (SNI) extension. In this case, the callback is +expected to select the correct certificate based on the SNI +information provided. The callback is expected to access the SNI data +using gnutls_server_name_get(). Using this option requires GnuTLS 3.0 +or higher. + +@item MHD_OPTION_DIGEST_AUTH_RANDOM +@cindex digest auth +@cindex random +Digest Authentication nonce's seed. + +This option should be followed by two arguments. First an integer of +type "size_t" which specifies the size of the buffer pointed to by the +second argument in bytes. Note that the application must ensure that +the buffer of the second argument remains allocated and unmodified +while the daemon is running. For security, you SHOULD provide a fresh +random nonce when using MHD with Digest Authentication. + +@item MHD_OPTION_NONCE_NC_SIZE +@cindex digest auth +@cindex replay attack + +Size of an array of nonce and nonce counter map. This option must be +followed by an "unsigned int" argument that have the size (number of +elements) of a map of a nonce and a nonce-counter. If this option +is not specified, a default value of 4 will be used (which might be +too small for servers handling many requests). If you do not use +digest authentication at all, you can specify a value of zero to +save some memory. + +You should calculate the value of NC_SIZE based on the number of +connections per second multiplied by your expected session duration +plus a factor of about two for hash table collisions. For example, if +you expect 100 digest-authenticated connections per second and the +average user to stay on your site for 5 minutes, then you likely need +a value of about 60000. On the other hand, if you can only expect +only 10 digest-authenticated connections per second, tolerate browsers +getting a fresh nonce for each request and expect a HTTP request +latency of 250 ms, then a value of about 5 should be fine. + + +@item MHD_OPTION_LISTEN_SOCKET +@cindex systemd +Listen socket to use. Pass a listen socket for MHD to use +(systemd-style). If this option is used, MHD will not open its own +listen socket(s). The argument passed must be of type "int" and refer +to an existing socket that has been bound to a port and is listening. + +@item MHD_OPTION_EXTERNAL_LOGGER +@cindex logging +Use the given function for logging error messages. +This option must be followed by two arguments; the +first must be a pointer to a function +of type 'void fun(void * arg, const char * fmt, va_list ap)' +and the second a pointer of type 'void*' which will +be passed as the "arg" argument to "fun". + +Note that MHD will not generate any log messages without +the MHD_USE_DEBUG flag set and if MHD was compiled +with the "--disable-messages" flag. + +@item MHD_OPTION_THREAD_POOL_SIZE +@cindex performance +Number (unsigned int) of threads in thread pool. Enable +thread pooling by setting this value to to something +greater than 1. Currently, thread model must be +MHD_USE_SELECT_INTERNALLY if thread pooling is enabled +(@code{MHD_start_daemon} returns @code{NULL} for an unsupported thread +model). + +@item MHD_OPTION_ARRAY +@cindex options +@cindex foreign-function interface +This option can be used for initializing MHD using options from an +array. A common use for this is writing an FFI for MHD. The actual +options given are in an array of 'struct MHD_OptionItem', so this +option requires a single argument of type 'struct MHD_OptionItem'. +The array must be terminated with an entry @code{MHD_OPTION_END}. + +An example for code using MHD_OPTION_ARRAY is: +@example +struct MHD_OptionItem ops[] = @{ + @{ MHD_OPTION_CONNECTION_LIMIT, 100, NULL @}, + @{ MHD_OPTION_CONNECTION_TIMEOUT, 10, NULL @}, + @{ MHD_OPTION_END, 0, NULL @} +@}; +d = MHD_start_daemon(0, 8080, NULL, NULL, dh, NULL, + MHD_OPTION_ARRAY, ops, + MHD_OPTION_END); +@end example +For options that expect a single pointer argument, the +second member of the @code{struct MHD_OptionItem} is ignored. +For options that expect two pointer arguments, the first +argument must be cast to @code{intptr_t}. + +@item MHD_OPTION_UNESCAPE_CALLBACK +@cindex internationalization +@cindex escaping + +Specify a function that should be called for unescaping escape +sequences in URIs and URI arguments. Note that this function will NOT +be used by the MHD_PostProcessor. If this option is not specified, +the default method will be used which decodes escape sequences of the +form "%HH". This option should be followed by two arguments, the +first one must be of the form + +@example + size_t my_unescaper(void * cls, struct MHD_Connection *c, char *s) +@end example + +where the return value must be @code{strlen(s)} and @code{s} should be +updated. Note that the unescape function must not lengthen @code{s} +(the result must be shorter than the input and still be 0-terminated). +@code{cls} will be set to the second argument following +MHD_OPTION_UNESCAPE_CALLBACK. + + +@item MHD_OPTION_THREAD_STACK_SIZE +@cindex stack +@cindex thread +@cindex pthread +@cindex embedded systems +Maximum stack size for threads created by MHD. This option must be +followed by a @code{size_t}). Not specifying this option or using +a value of zero means using the system default (which is likely to +differ based on your platform). + +@item MHD_OPTION_TCP_FASTQUEUE_QUEUE_SIZE +@cindex listen +When the flag @code{MHD_USE_TCP_FASTOPEN} is used, this option sets the +connection handshake queue size for the TCP FASTOPEN connections. Note +that a TCP FASTOPEN connection handshake occupies more resources than a +TCP handshake as the SYN packets also contain DATA which is kept in the +associate state until handshake is completed. If this option is not +given the queue size is set to a default value of 10. This option must +be followed by a @code{unsigned int}. + +@item MHD_OPTION_HTTPS_MEM_DHPARAMS +@cindex TLS +@cindex SSL +@cindex DH +Memory pointer for the Diffie-Hellman parameters (dh.pem) to be used +by the HTTPS daemon for key exchange. This option must be followed by +a @code{const char *} argument. The argument would be a zero-terminated +string with a PEM encoded PKCS3 DH parameters structure suitable +for passing to @code{gnutls_dh_parms_import_pkcs3}. + +@item MHD_OPTION_LISTENING_ADDRESS_REUSE +@cindex bind, restricting bind +@cindex reusing listening address +This option must be followed by a @code{unsigned int} argument. +If this option is present and true (nonzero) parameter is given, allow reusing +the address:port of the listening socket (using @code{SO_REUSEPORT} on most +platforms, and @code{SO_REUSEADDR} on Windows). If a false (zero) parameter is +given, disallow reusing the the address:port of the listening socket (this +usually requires no special action, but @code{SO_EXCLUSIVEADDRUSE} is needed on +Windows). If this option is not present, default behaviour is undefined +(currently, @code{SO_REUSEADDR} is used on all platforms, which disallows +address:port reusing with the exception of Windows). + +@end table +@end deftp + + +@deftp {C Struct} MHD_OptionItem +Entry in an MHD_OPTION_ARRAY. See the @code{MHD_OPTION_ARRAY} option +argument for its use. + +The @code{option} member is used to specify which option is specified +in the array. The other members specify the respective argument. + +Note that for options taking only a single pointer, the +@code{ptr_value} member should be set. For options taking two pointer +arguments, the first pointer must be cast to @code{intptr_t} and both +the @code{value} and the @code{ptr_value} members should be used to +pass the two pointers. +@end deftp + + +@deftp {Enumeration} MHD_ValueKind +The @code{MHD_ValueKind} specifies the source of the key-value pairs in +the HTTP protocol. + +@table @code +@item MHD_RESPONSE_HEADER_KIND +Response header. + +@item MHD_HEADER_KIND +HTTP header. + +@item MHD_COOKIE_KIND +@cindex cookie +Cookies. Note that the original HTTP header containing the cookie(s) +will still be available and intact. + +@item MHD_POSTDATA_KIND +@cindex POST method +@code{POST} data. This is available only if a content encoding +supported by MHD is used (currently only @acronym{URL} encoding), and +only if the posted content fits within the available memory pool. Note +that in that case, the upload data given to the +@code{MHD_AccessHandlerCallback()} will be empty (since it has +already been processed). + +@item MHD_GET_ARGUMENT_KIND +@code{GET} (URI) arguments. + +@item MHD_FOOTER_KIND +HTTP footer (only for http 1.1 chunked encodings). + +@end table +@end deftp + + +@deftp {Enumeration} MHD_RequestTerminationCode +The @code{MHD_RequestTerminationCode} specifies reasons why a request +has been terminated (or completed). + +@table @code +@item MHD_REQUEST_TERMINATED_COMPLETED_OK +We finished sending the response. + +@item MHD_REQUEST_TERMINATED_WITH_ERROR +Error handling the connection (resources exhausted, other side closed +connection, application error accepting request, etc.) + +@item MHD_REQUEST_TERMINATED_TIMEOUT_REACHED +No activity on the connection for the number of seconds specified using +@code{MHD_OPTION_CONNECTION_TIMEOUT}. + +@item MHD_REQUEST_TERMINATED_DAEMON_SHUTDOWN +We had to close the session since MHD was being shut down. +@end table +@end deftp + + +@deftp {Enumeration} MHD_ResponseMemoryMode +The @code{MHD_ResponeMemoryMode} specifies how MHD should treat +the memory buffer given for the response in +@code{MHD_create_response_from_buffer}. + +@table @code +@item MHD_RESPMEM_PERSISTENT +Buffer is a persistent (static/global) buffer that won't change +for at least the lifetime of the response, MHD should just use +it, not free it, not copy it, just keep an alias to it. + +@item MHD_RESPMEM_MUST_FREE +Buffer is heap-allocated with @code{malloc} (or equivalent) and +should be freed by MHD after processing the response has +concluded (response reference counter reaches zero). + +@item MHD_RESPMEM_MUST_COPY +Buffer is in transient memory, but not on the heap (for example, +on the stack or non-malloc allocated) and only valid during the +call to @code{MHD_create_response_from_buffer}. MHD must make its +own private copy of the data for processing. + +@end table +@end deftp + + +@deftp {Enumeration} MHD_ResponseFlags +Response-specific flags. Passed as an argument to +@code{MHD_set_response_options()}. + +@table @code +@item MHD_RF_NONE +No special handling. + +@item MHD_RF_HTTP_VERSION_1_0_ONLY +Only respond in conservative HTTP 1.0-mode. In particular, +do not (automatically) sent "Connection" headers and always +close the connection after generating the response. + +@end table +@end deftp + + +@deftp {Enumeration} MHD_ResponseOptions +Response-specific options. Passed in the varargs portion of +@code{MHD_set_response_options()}. + +@table @code +@item MHD_RO_END +No more options / last option. This is used to terminate the VARARGs +list. +@end table +@end deftp + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-struct +@chapter Structures type definition + + +@deftp {C Struct} MHD_Daemon +Handle for the daemon (listening on a socket for HTTP traffic). +@end deftp + + +@deftp {C Struct} MHD_Connection +Handle for a connection / HTTP request. With HTTP/1.1, multiple +requests can be run over the same connection. However, MHD will only +show one request per TCP connection to the client at any given time. +@end deftp + + +@deftp {C Struct} MHD_Response +Handle for a response. +@end deftp + + +@deftp {C Struct} MHD_PostProcessor +@cindex POST method +Handle for @code{POST} processing. +@end deftp + + +@deftp {C Union} MHD_ConnectionInfo +Information about a connection. +@end deftp + + +@deftp {C Union} MHD_DaemonInfo +Information about an MHD daemon. +@end deftp + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-cb +@chapter Callback functions definition + + +@deftypefn {Function Pointer} int {*MHD_AcceptPolicyCallback} (void *cls, const struct sockaddr * addr, socklen_t addrlen) +Invoked in the context of a connection to allow or deny a client to +connect. This callback return @code{MHD_YES} if connection is allowed, +@code{MHD_NO} if not. + +@table @var +@item cls +custom value selected at callback registration time; +@item addr +address information from the client; +@item addrlen +length of the address information. +@end table +@end deftypefn + + +@deftypefn {Function Pointer} int {*MHD_AccessHandlerCallback} (void *cls, struct MHD_Connection * connection, const char *url, const char *method, const char *version, const char *upload_data, size_t *upload_data_size, void **con_cls) +Invoked in the context of a connection to answer a request from the +client. This callback must call MHD functions (example: the +@code{MHD_Response} ones) to provide content to give back to the client +and return an HTTP status code (i.e. @code{200} for OK, @code{404}, +etc.). + +@ref{microhttpd-post}, for details on how to code this callback. + +Must return @code{MHD_YES} if the connection was handled successfully, +@code{MHD_NO} if the socket must be closed due to a serious error while +handling the request + +@table @var +@item cls +custom value selected at callback registration time; + +@item url +the URL requested by the client; + +@item method +the HTTP method used by the client (@code{GET}, @code{PUT}, +@code{DELETE}, @code{POST}, etc.); + +@item version +the HTTP version string (i.e. @code{HTTP/1.1}); + +@item upload_data +the data being uploaded (excluding headers): +@cindex POST method +@cindex PUT method + +@code{POST} data @strong{will} be made available +incrementally in @var{upload_data}; even if @code{POST} +data is available, the first time the callback is +invoked there won't be upload data, as this is done +just after MHD parses the headers. If supported by +the client and the HTTP version, the application can +at this point queue an error response to possibly +avoid the upload entirely. If no response is generated, +MHD will (if required) automatically send a 100 CONTINUE +reply to the client. + +Afterwards, POST data will be passed to the callback +to be processed incrementally by the application. The +application may return @code{MHD_NO} to forcefully +terminate the TCP connection without generating a +proper HTTP response. Once all of the upload data has +been provided to the application, the application +will be called again with 0 bytes of upload data. +At this point, a response should be queued to complete +the handling of the request. + +@item upload_data_size +set initially to the size of the @var{upload_data} provided; this +callback must update this value to the number of bytes @strong{NOT} +processed; unless external select is used, the callback maybe +required to process at least some data. If the callback fails to +process data in multi-threaded or internal-select mode and if the +read-buffer is already at the maximum size that MHD is willing to +use for reading (about half of the maximum amount of memory allowed +for the connection), then MHD will abort handling the connection +and return an internal server error to the client. In order to +avoid this, clients must be able to process upload data incrementally +and reduce the value of @code{upload_data_size}. + +@item con_cls +reference to a pointer, initially set to @code{NULL}, that this callback can +set to some address and that will be preserved by MHD for future +calls for this request; + +since the access handler may be called many times (i.e., for a +@code{PUT}/@code{POST} operation with plenty of upload data) this allows +the application to easily associate some request-specific state; + +if necessary, this state can be cleaned up in the global +@code{MHD_RequestCompletedCallback} (which can be set with the +@code{MHD_OPTION_NOTIFY_COMPLETED}). +@end table +@end deftypefn + + +@deftypefn {Function Pointer} void {*MHD_RequestCompletedCallback} (void *cls, struct MHD_Connectionconnection, void **con_cls, enum MHD_RequestTerminationCode toe) +Signature of the callback used by MHD to notify the application about +completed requests. + +@table @var +@item cls +custom value selected at callback registration time; + +@item connection +connection handle; + +@item con_cls +value as set by the last call to the +@code{MHD_AccessHandlerCallback}; + +@item toe +reason for request termination see @code{MHD_OPTION_NOTIFY_COMPLETED}. +@end table +@end deftypefn + + +@deftypefn {Function Pointer} int {*MHD_KeyValueIterator} (void *cls, enum MHD_ValueKind kind, const char *key, const char *value) +Iterator over key-value pairs. This iterator can be used to iterate +over all of the cookies, headers, or @code{POST}-data fields of a +request, and also to iterate over the headers that have been added to a +response. + +@table @var +@item cls +custom value specified when iteration was triggered; + +@item kind +kind of the header we are looking at + +@item key +key for the value, can be an empty string + +@item value +value corresponding value, can be NULL + +@end table + +Return @code{MHD_YES} to continue iterating, @code{MHD_NO} to abort the +iteration. +@end deftypefn + + +@deftypefn {Function Pointer} int {*MHD_ContentReaderCallback} (void *cls, uint64_t pos, char *buf, size_t max) +Callback used by MHD in order to obtain content. The callback has to +copy at most @var{max} bytes of content into @var{buf}. The total +number of bytes that has been placed into @var{buf} should be returned. + +Note that returning zero will cause MHD to try again. +Thus, returning zero should only be used in conjunction +with @code{MHD_suspend_connection()} to avoid busy waiting. + +While usually the callback simply returns the number of bytes written +into @var{buf}, there are two special return value: + +@code{MHD_CONTENT_READER_END_OF_STREAM} (-1) should be returned +for the regular end of transmission (with chunked encoding, MHD will then +terminate the chunk and send any HTTP footers that might be +present; without chunked encoding and given an unknown +response size, MHD will simply close the connection; note +that while returning @code{MHD_CONTENT_READER_END_OF_STREAM} is not technically +legal if a response size was specified, MHD accepts this +and treats it just as @code{MHD_CONTENT_READER_END_WITH_ERROR}. + +@code{MHD_CONTENT_READER_END_WITH_ERROR} (-2) is used to indicate a server +error generating the response; this will cause MHD to simply +close the connection immediately. If a response size was +given or if chunked encoding is in use, this will indicate +an error to the client. Note, however, that if the client +does not know a response size and chunked encoding is not in +use, then clients will not be able to tell the difference between +@code{MHD_CONTENT_READER_END_WITH_ERROR} and +@code{MHD_CONTENT_READER_END_OF_STREAM}. +This is not a limitation of MHD but rather of the HTTP protocol. + +@table @var +@item cls +custom value selected at callback registration time; + +@item pos +position in the datastream to access; note that if an +@code{MHD_Response} object is re-used, it is possible for the same +content reader to be queried multiple times for the same data; however, +if an @code{MHD_Response} is not re-used, MHD guarantees that +@var{pos} will be the sum of all non-negative return values obtained +from the content reader so far. +@end table + +Return @code{-1} on error (MHD will no longer try to read content and +instead close the connection with the client). +@end deftypefn + + +@deftypefn {Function Pointer} void {*MHD_ContentReaderFreeCallback} (void *cls) +This method is called by MHD if we are done with a content reader. +It should be used to free resources associated with the content reader. +@end deftypefn + + +@deftypefn {Function Pointer} int {*MHD_PostDataIterator} (void *cls, enum MHD_ValueKind kind, const char *key, const char *filename, const char *content_type, const char *transfer_encoding, const char *data, uint64_t off, size_t size) +Iterator over key-value pairs where the value maybe made available in +increments and/or may not be zero-terminated. Used for processing +@code{POST} data. + +@table @var +@item cls +custom value selected at callback registration time; + +@item kind +type of the value; + +@item key +zero-terminated key for the value; + +@item filename +name of the uploaded file, @code{NULL} if not known; + +@item content_type +mime-type of the data, @code{NULL} if not known; + +@item transfer_encoding +encoding of the data, @code{NULL} if not known; + +@item data +pointer to size bytes of data at the specified offset; + +@item off +offset of data in the overall value; + +@item size +number of bytes in data available. +@end table + +Return @code{MHD_YES} to continue iterating, @code{MHD_NO} to abort the +iteration. +@end deftypefn + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-init +@chapter Starting and stopping the server + +@deftypefun {void} MHD_set_panic_func (MHD_PanicCallback cb, void *cls) +Set a handler for fatal errors. + +@table @var +@item cb +function to call if MHD encounters a fatal internal error. If no handler was set explicitly, MHD will call @code{abort}. + +@item cls +closure argument for cb; the other arguments are the name of the source file, line number and a string describing the nature of the fatal error (which can be @code{NULL}) +@end table +@end deftypefun + +@deftypefun {struct MHD_Daemon *} MHD_start_daemon (unsigned int flags, unsigned short port, MHD_AcceptPolicyCallback apc, void *apc_cls, MHD_AccessHandlerCallback dh, void *dh_cls, ...) +Start a webserver on the given port. + +@table @var +@item flags +OR-ed combination of @code{MHD_FLAG} values; + +@item port +port to bind to; + +@item apc +callback to call to check which clients will be allowed to connect; you +can pass @code{NULL} in which case connections from any @acronym{IP} will be +accepted; + +@item apc_cls +extra argument to @var{apc}; + +@item dh +default handler for all URIs; + +@item dh_cls +extra argument to @var{dh}. +@end table + +Additional arguments are a list of options (type-value pairs, +terminated with @code{MHD_OPTION_END}). It is mandatory to use +@code{MHD_OPTION_END} as last argument, even when there are no +additional arguments. + +Return @code{NULL} on error, handle to daemon on success. +@end deftypefun + + +@deftypefun int MHD_quiesce_daemon (struct MHD_Daemon *daemon) +@cindex quiesce +Stop accepting connections from the listening socket. Allows clients +to continue processing, but stops accepting new connections. Note +that the caller is responsible for closing the returned socket; +however, if MHD is run using threads (anything but external select +mode), it must not be closed until AFTER @code{MHD_stop_daemon} has +been called (as it is theoretically possible that an existing thread +is still using it). + +This function is useful in the special case that a listen socket +is to be migrated to another process (i.e. a newer version of the +HTTP server) while existing connections should continue to be +processed until they are finished. + +Return @code{-1} on error (daemon not listening), the handle to the +listen socket otherwise. + +@end deftypefun + + +@deftypefun void MHD_stop_daemon (struct MHD_Daemon *daemon) +Shutdown an HTTP daemon. +@end deftypefun + + +@deftypefun int MHD_run (struct MHD_Daemon *daemon) +Run webserver operations (without blocking unless in client callbacks). +This method should be called by clients in combination with +@code{MHD_get_fdset()} if the client-controlled @code{select}-method is used. +@cindex select +@cindex poll + +This function will work for external @code{poll} and @code{select} mode. +However, if using external @code{select} mode, you may want to +instead use @code{MHD_run_from_select}, as it is more efficient. + +@table @var +@item daemon +daemon to process connections of +@end table + +Return @code{MHD_YES} on success, @code{MHD_NO} if this daemon was not +started with the right options for this call. +@end deftypefun + + +@deftypefun int MHD_run_from_select (struct MHD_Daemon *daemon, const fd_set *read_fd_set, const fd_set *write_fd_set, const fd_set *except_fd_set) +Run webserver operations given sets of ready socket handles. +@cindex select + +This method should be called by clients in combination with +@code{MHD_get_fdset} if the client-controlled (external) +select method is used. + +You can use this function instead of @code{MHD_run} if you called +@code{select} on the result from @code{MHD_get_fdset}. File descriptors in +the sets that are not controlled by MHD will be ignored. Calling +this function instead of @code{MHD_run} is more efficient as MHD will +not have to call @code{select} again to determine which operations are +ready. + +@table @var +@item daemon +daemon to process connections of +@item read_fd_set +set of descriptors that must be ready for reading without blocking +@item write_fd_set +set of descriptors that must be ready for writing without blocking +@item except_fd_set +ignored, can be NULL +@end table + +Return @code{MHD_YES} on success, @code{MHD_NO} on serious internal +errors. + +@end deftypefun + + + +@deftypefun void MHD_add_connection (struct MHD_Daemon *daemon, int client_socket, const struct sockaddr *addr, socklen_t addrlen) +Add another client connection to the set of connections +managed by MHD. This API is usually not needed (since +MHD will accept inbound connections on the server socket). +Use this API in special cases, for example if your HTTP +server is behind NAT and needs to connect out to the +HTTP client, or if you are building a proxy. + +If you use this API in conjunction with a internal select or a thread +pool, you must set the option @code{MHD_USE_PIPE_FOR_SHUTDOWN} to +ensure that the freshly added connection is immediately processed by +MHD. + +The given client socket will be managed (and closed!) by MHD after +this call and must no longer be used directly by the application +afterwards. + +@table @var +@item daemon +daemon that manages the connection +@item client_socket +socket to manage (MHD will expect to receive an HTTP request from this socket next). +@item addr +IP address of the client +@item addrlen +number of bytes in addr +@end table + +This function will return @code{MHD_YES} on success, +@code{MHD_NO} if this daemon could +not handle the connection (i.e. malloc failed, etc). +The socket will be closed in any case; 'errno' is set +to indicate further details about the error. +@end deftypefun + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ----------------------------------------------------------- +@node microhttpd-inspect +@chapter Implementing external @code{select} + + +@deftypefun int MHD_get_fdset (struct MHD_Daemon *daemon, fd_set * read_fd_set, fd_set * write_fd_set, fd_set * except_fd_set, int *max_fd) +Obtain the @code{select()} sets for this daemon. The daemon's socket +is added to @var{read_fd_set}. The list of currently existent +connections is scanned and their file descriptors added to the correct +set. + +After the call completed successfully: the variable referenced by +@var{max_fd} references the file descriptor with highest integer +identifier. The variable must be set to zero before invoking this +function. + +Return @code{MHD_YES} on success, @code{MHD_NO} if: the arguments are +invalid (example: @code{NULL} pointers); this daemon was not started with +the right options for this call. +@end deftypefun + + +@deftypefun int MHD_get_timeout (struct MHD_Daemon *daemon, unsigned long long *timeout) +@cindex timeout +Obtain timeout value for select for this daemon (only needed if +connection timeout is used). The returned value is how many +milliseconds @code{select} should at most block, not the timeout value +set for connections. This function must not be called if the +@code{MHD_USE_THREAD_PER_CONNECTION} mode is in use (since then it is +not meaningful to ask for a timeout, after all, there is concurrenct +activity). The function must also not be called by user-code if +@code{MHD_USE_INTERNAL_SELECT} is in use. In the latter case, the +behavior is undefined. + +@table @var +@item daemon +which daemon to obtain the timeout from. +@item timeout +will be set to the timeout (in milliseconds). +@end table + +Return @code{MHD_YES} on success, @code{MHD_NO} if timeouts are not used +(or no connections exist that would necessiate the use of a timeout +right now). +@end deftypefun + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ----------------------------------------------------------- +@node microhttpd-requests +@chapter Handling requests + + +@deftypefun int MHD_get_connection_values (struct MHD_Connection *connection, enum MHD_ValueKind kind, MHD_KeyValueIterator iterator, void *iterator_cls) +Get all the headers matching @var{kind} from the request. + +The @var{iterator} callback is invoked once for each header, with +@var{iterator_cls} as first argument. After version 0.9.19, the +headers are iterated in the same order as they were received from +the network; previous versions iterated over the headers in reverse +order. + +@code{MHD_get_connection_values} returns the number of entries +iterated over; this can be less than the number of headers if, while +iterating, @var{iterator} returns @code{MHD_NO}. + +@var{iterator} can be @code{NULL}: in this case this function just counts +and returns the number of headers. + +In the case of @code{MHD_GET_ARGUMENT_KIND}, the @var{value} argument +will be @code{NULL} if the URL contained a key without an equals operator. +For example, for a HTTP request to the URL ``http://foo/bar?key'', the +@var{value} argument is @code{NULL}; in contrast, a HTTP request to the URL +``http://foo/bar?key='', the @var{value} argument is the empty string. +The normal case is that the URL contains ``http://foo/bar?key=value'' +in which case @var{value} would be the string ``value'' and @var{key} +would contain the string ``key''. +@end deftypefun + + +@deftypefun int MHD_set_connection_value (struct MHD_Connection *connection, enum MHD_ValueKind kind, const char * key, const char * value) +This function can be used to append an entry to +the list of HTTP headers of a connection (so that the +@code{MHD_get_connection_values function} will return +them -- and the MHD PostProcessor will also +see them). This maybe required in certain +situations (see Mantis #1399) where (broken) +HTTP implementations fail to supply values needed +by the post processor (or other parts of the +application). + +This function MUST only be called from within +the MHD_AccessHandlerCallback (otherwise, access +maybe improperly synchronized). Furthermore, +the client must guarantee that the key and +value arguments are 0-terminated strings that +are NOT freed until the connection is closed. +(The easiest way to do this is by passing only +arguments to permanently allocated strings.). + +@var{connection} is the connection for which +the entry for @var{key} of the given @var{kind} +should be set to the given @var{value}. + +The function returns @code{MHD_NO} if the operation +could not be performed due to insufficient memory +and @code{MHD_YES} on success. +@end deftypefun + + +@deftypefun {const char *} MHD_lookup_connection_value (struct MHD_Connection *connection, enum MHD_ValueKind kind, const char *key) +Get a particular header value. If multiple values match the +@var{kind}, return one of them (the ``first'', whatever that means). +@var{key} must reference a zero-terminated ASCII-coded string +representing the header to look for: it is compared against the +headers using @code{strcasecmp()}, so case is ignored. A value of +@code{NULL} for @var{key} can be used to lookup 'trailing' values without a +key, for example if a URI is of the form +``http://example.com/?trailer'', a @var{key} of @code{NULL} can be used to +access ``tailer" The function returns @code{NULL} if no matching item +was found. +@end deftypefun + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-responses +@chapter Building responses to requests + + +@noindent +Response objects handling by MHD is asynchronous with respect to the +application execution flow. Instances of the @code{MHD_Response} +structure are not associated to a daemon and neither to a client +connection: they are managed with reference counting. + +In the simplest case: we allocate a new @code{MHD_Response} structure +for each response, we use it once and finally we destroy it. + +MHD allows more efficient resources usages. + +Example: we allocate a new @code{MHD_Response} structure for each +response @strong{kind}, we use it every time we have to give that +response and we finally destroy it only when the daemon shuts down. + +@menu +* microhttpd-response enqueue:: Enqueuing a response. +* microhttpd-response create:: Creating a response object. +* microhttpd-response headers:: Adding headers to a response. +* microhttpd-response options:: Setting response options. +* microhttpd-response inspect:: Inspecting a response object. +@end menu + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-response enqueue +@section Enqueuing a response + + +@deftypefun int MHD_queue_response (struct MHD_Connection *connection, unsigned int status_code, struct MHD_Response *response) +Queue a response to be transmitted to the client as soon as possible +but only after MHD_AccessHandlerCallback returns. This function +checks that it is legal to queue a response at this time for the +given connection. It also increments the internal reference +counter for the response object (the counter will be decremented +automatically once the response has been transmitted). + +@table @var +@item connection +the connection identifying the client; + +@item status_code +HTTP status code (i.e. @code{200} for OK); + +@item response +response to transmit. +@end table + +Return @code{MHD_YES} on success or if message has been queued. Return +@code{MHD_NO}: if arguments are invalid (example: @code{NULL} pointer); on +error (i.e. reply already sent). +@end deftypefun + + +@deftypefun void MHD_destroy_response (struct MHD_Response *response) +Destroy a response object and associated resources (decrement the +reference counter). Note that MHD may keep some of the resources +around if the response is still in the queue for some clients, so the +memory may not necessarily be freed immediately. +@end deftypefun + + +An explanation of reference counting@footnote{Note to readers acquainted +to the Tcl API: reference counting on @code{MHD_Connection} +structures is handled in the same way as Tcl handles @code{Tcl_Obj} +structures through @code{Tcl_IncrRefCount()} and +@code{Tcl_DecrRefCount()}.}: + +@enumerate +@item +a @code{MHD_Response} object is allocated: + +@example +struct MHD_Response * response = MHD_create_response_from_buffer(...); +/* here: reference counter = 1 */ +@end example + +@item +the @code{MHD_Response} object is enqueued in a @code{MHD_Connection}: + +@example +MHD_queue_response(connection, , response); +/* here: reference counter = 2 */ +@end example + +@item +the creator of the response object discharges responsibility for it: + +@example +MHD_destroy_response(response); +/* here: reference counter = 1 */ +@end example + +@item +the daemon handles the connection sending the response's data to the +client then decrements the reference counter by calling +@code{MHD_destroy_response()}: the counter's value drops to zero and +the @code{MHD_Response} object is released. +@end enumerate + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-response create +@section Creating a response object + + +@deftypefun {struct MHD_Response *} MHD_create_response_from_callback (uint64_t size, size_t block_size, MHD_ContentReaderCallback crc, void *crc_cls, MHD_ContentReaderFreeCallback crfc) +Create a response object. The response object can be extended with +header information and then it can be used any number of times. + +@table @var +@item size +size of the data portion of the response, @code{-1} for unknown; + +@item block_size +preferred block size for querying @var{crc} (advisory only, MHD may +still call @var{crc} using smaller chunks); this is essentially the +buffer size used for @acronym{IO}, clients should pick a value that is +appropriate for @acronym{IO} and memory performance requirements; + +@item crc +callback to use to obtain response data; + +@item crc_cls +extra argument to @var{crc}; + +@item crfc +callback to call to free @var{crc_cls} resources. +@end table + +Return @code{NULL} on error (i.e. invalid arguments, out of memory). +@end deftypefun + + + +@deftypefun {struct MHD_Response *} MHD_create_response_from_fd (uint64_t size, int fd) +Create a response object. The response object can be extended with +header information and then it can be used any number of times. + +@table @var +@item size +size of the data portion of the response (should be smaller or equal to the +size of the file) + +@item fd +file descriptor referring to a file on disk with the data; will be +closed when response is destroyed; note that 'fd' must be an actual +file descriptor (not a pipe or socket) since MHD might use 'sendfile' +or 'seek' on it. The descriptor should be in blocking-IO mode. +@end table + +Return @code{NULL} on error (i.e. invalid arguments, out of memory). +@end deftypefun + + +@deftypefun {struct MHD_Response *} MHD_create_response_from_fd_at_offset (size_t size, int fd, off_t offset) +Create a response object. The response object can be extended with +header information and then it can be used any number of times. +Note that you need to be a bit careful about @code{off_t} when +writing this code. Depending on your platform, MHD is likely +to have been compiled with support for 64-bit files. When you +compile your own application, you must make sure that @code{off_t} +is also a 64-bit value. If not, your compiler may pass a 32-bit +value as @code{off_t}, which will result in 32-bits of garbage. + +If you use the autotools, use the @code{AC_SYS_LARGEFILE} autoconf +macro and make sure to include the generated @file{config.h} file +before @file{microhttpd.h} to avoid problems. If you do not have a +build system and only want to run on a GNU/Linux system, you could +also use +@verbatim +#define _FILE_OFFSET_BITS 64 +#include <sys/types.h> +#include <sys/stat.h> +#include <fcntl.h> +#include <microhttpd.h> +@end verbatim +to ensure 64-bit @code{off_t}. Note that if your operating system +does not support 64-bit files, MHD will be compiled with a 32-bit +@code{off_t} (in which case the above would be wrong). + +@table @var +@item size +size of the data portion of the response (number of bytes to transmit from the +file starting at offset). + +@item fd +file descriptor referring to a file on disk with the data; will be +closed when response is destroyed; note that 'fd' must be an actual +file descriptor (not a pipe or socket) since MHD might use 'sendfile' +or 'seek' on it. The descriptor should be in blocking-IO mode. + +@item offset +offset to start reading from in the file +@end table + +Return @code{NULL} on error (i.e. invalid arguments, out of memory). +@end deftypefun + + +@deftypefun {struct MHD_Response *} MHD_create_response_from_buffer (size_t size, void *data, enum MHD_ResponseMemoryMode mode) +Create a response object. The response object can be extended with +header information and then it can be used any number of times. + +@table @var +@item size +size of the data portion of the response; + +@item buffer +the data itself; + +@item mode +memory management options for buffer; use +MHD_RESPMEM_PERSISTENT if the buffer is static/global memory, +use MHD_RESPMEM_MUST_FREE if the buffer is heap-allocated and +should be freed by MHD and MHD_RESPMEM_MUST_COPY if the +buffer is in transient memory (i.e. on the stack) and must +be copied by MHD; +@end table + +Return @code{NULL} on error (i.e. invalid arguments, out of memory). +@end deftypefun + + +@deftypefun {struct MHD_Response *} MHD_create_response_from_data (size_t size, void *data, int must_free, int must_copy) +Create a response object. The response object can be extended with +header information and then it can be used any number of times. +This function is deprecated, use @code{MHD_create_response_from_buffer} instead. + +@table @var +@item size +size of the data portion of the response; + +@item data +the data itself; + +@item must_free +if true: MHD should free data when done; + +@item must_copy +if true: MHD allocates a block of memory and use it to make a copy of +@var{data} embedded in the returned @code{MHD_Response} structure; +handling of the embedded memory is responsibility of MHD; @var{data} +can be released anytime after this call returns. +@end table + +Return @code{NULL} on error (i.e. invalid arguments, out of memory). +@end deftypefun + + +Example: create a response from a statically allocated string: + +@example +const char * data = "<html><body><p>Error!</p></body></html>"; + +struct MHD_Connection * connection = ...; +struct MHD_Response * response; + +response = MHD_create_response_from_buffer (strlen(data), data, + MHD_RESPMEM_PERSISTENT); +MHD_queue_response(connection, 404, response); +MHD_destroy_response(response); +@end example + + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-response headers +@section Adding headers to a response + + +@deftypefun int MHD_add_response_header (struct MHD_Response *response, const char *header, const char *content) +Add a header line to the response. The strings referenced by +@var{header} and @var{content} must be zero-terminated and they are +duplicated into memory blocks embedded in @var{response}. + +Notice that the strings must not hold newlines, carriage returns or tab +chars. + +Return @code{MHD_NO} on error (i.e. invalid header or content format or +memory allocation error). +@end deftypefun + + +@deftypefun int MHD_add_response_footer (struct MHD_Response *response, const char *footer, const char *content) +Add a footer line to the response. The strings referenced by +@var{footer} and @var{content} must be zero-terminated and they are +duplicated into memory blocks embedded in @var{response}. + +Notice that the strings must not hold newlines, carriage returns or tab +chars. You can add response footers at any time before signalling the +end of the response to MHD (not just before calling 'MHD_queue_response'). +Footers are useful for adding cryptographic checksums to the reply or to +signal errors encountered during data generation. This call was introduced +in MHD 0.9.3. + +Return @code{MHD_NO} on error (i.e. invalid header or content format or +memory allocation error). +@end deftypefun + + + +@deftypefun int MHD_del_response_header (struct MHD_Response *response, const char *header, const char *content) +Delete a header (or footer) line from the response. Return @code{MHD_NO} on error +(arguments are invalid or no such header known). +@end deftypefun + + +@c ------------------------------------------------------------ +@node microhttpd-response options +@section Setting response options + + +@deftypefun int MHD_set_response_options (struct MHD_Response *response, enum MHD_ResponseFlags flags, ...) +Set special flags and options for a response. + +Calling this functions sets the given flags and options for the response. + +@table @var +@item response +which response should be modified; + +@item flags +flags to set for the response; + +@end table + +Additional arguments are a list of options (type-value pairs, +terminated with @code{MHD_RO_END}). It is mandatory to use +@code{MHD_RO_END} as last argument, even when there are no +additional arguments. + +Return @code{MHD_NO} on error, @code{MHD_YES} on success. +@end deftypefun + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-response inspect +@section Inspecting a response object + + +@deftypefun int MHD_get_response_headers (struct MHD_Response *response, MHD_KeyValueIterator iterator, void *iterator_cls) +Get all of the headers added to a response. + +Invoke the @var{iterator} callback for each header in the response, +using @var{iterator_cls} as first argument. Return number of entries +iterated over. @var{iterator} can be @code{NULL}: in this case the function +just counts headers. + +@var{iterator} should not modify the its key and value arguments, unless +we know what we are doing. +@end deftypefun + + +@deftypefun {const char *} MHD_get_response_header (struct MHD_Response *response, const char *key) +Find and return a pointer to the value of a particular header from the +response. @var{key} must reference a zero-terminated string +representing the header to look for. The search is case sensitive. +Return @code{NULL} if header does not exist or @var{key} is @code{NULL}. + +We should not modify the value, unless we know what we are doing. +@end deftypefun + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-flow +@chapter Flow control. + +@noindent +Sometimes it may be possible that clients upload data faster +than an application can process it, or that an application +needs an extended period of time to generate a response. +If @code{MHD_USE_THREAD_PER_CONNECTION} is used, applications +can simply deal with this by performing their logic within the +thread and thus effectively blocking connection processing +by MHD. In all other modes, blocking logic must not be +placed within the callbacks invoked by MHD as this would also +block processing of other requests, as a single thread may be +responsible for tens of thousands of connections. + +Instead, applications using thread modes other than +@code{MHD_USE_THREAD_PER_CONNECTION} should use the +following functions to perform flow control. + +@deftypefun int MHD_suspend_connection (struct MHD_Connection *connection) +Suspend handling of network data for a given connection. This can +be used to dequeue a connection from MHD's event loop (external +select, internal select or thread pool; not applicable to +thread-per-connection!) for a while. + +If you use this API in conjunction with a internal select or a +thread pool, you must set the option @code{MHD_USE_SUSPEND_RESUME} to +ensure that a resumed connection is immediately processed by MHD. + +Suspended connections continue to count against the total number of +connections allowed (per daemon, as well as per IP, if such limits +are set). Suspended connections will NOT time out; timeouts will +restart when the connection handling is resumed. While a +connection is suspended, MHD will not detect disconnects by the +client. + +The only safe time to suspend a connection is from the +@code{MHD_AccessHandlerCallback}. + +Finally, it is an API violation to call @code{MHD_stop_daemon} while +having suspended connections (this will at least create memory and +socket leaks or lead to undefined behavior). You must explicitly +resume all connections before stopping the daemon. + +@table @var +@item connection +the connection to suspend +@end table +@end deftypefun + +@deftypefun int MHD_resume_connection (struct MHD_Connection *connection) +Resume handling of network data for suspended connection. It is safe +to resume a suspended connection at any time. Calling this function +on a connection that was not previously suspended will result in +undefined behavior. + +@table @var +@item connection +the connection to resume +@end table +@end deftypefun + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-dauth +@chapter Utilizing Authentication + +@noindent +MHD support three types of client authentication. + +Basic authentication uses a simple authentication method based +on BASE64 algorithm. Username and password are exchanged in clear +between the client and the server, so this method must only be used +for non-sensitive content or when the session is protected with https. +When using basic authentication MHD will have access to the clear +password, possibly allowing to create a chained authentication +toward an external authentication server. + +Digest authentication uses a one-way authentication method based +on MD5 hash algorithm. Only the hash will transit over the network, +hence protecting the user password. The nonce will prevent replay +attacks. This method is appropriate for general use, especially +when https is not used to encrypt the session. + +Client certificate authentication uses a X.509 certificate from +the client. This is the strongest authentication mechanism but it +requires the use of HTTPS. Client certificate authentication can +be used simultaneously with Basic or Digest Authentication in order +to provide a two levels authentication (like for instance separate +machine and user authentication). A code example for using +client certificates is presented in the MHD tutorial. + +@menu +* microhttpd-dauth basic:: Using Basic Authentication. +* microhttpd-dauth digest:: Using Digest Authentication. +@end menu + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-dauth basic +@section Using Basic Authentication + +@deftypefun {char *} MHD_basic_auth_get_username_password (struct MHD_Connection *connection, char** password) +Get the username and password from the basic authorization header sent by the client. +Return @code{NULL} if no username could be found, a pointer to the username if found. +If returned value is not @code{NULL}, the value must be @code{free()}'ed. + +@var{password} reference a buffer to store the password. It can be @code{NULL}. +If returned value is not @code{NULL}, the value must be @code{free()}'ed. +@end deftypefun + +@deftypefun {int} MHD_queue_basic_auth_fail_response (struct MHD_Connection *connection, const char *realm, struct MHD_Response *response) +Queues a response to request basic authentication from the client. +Return @code{MHD_YES} if successful, otherwise @code{MHD_NO}. + +@var{realm} must reference to a zero-terminated string representing the realm. + +@var{response} a response structure to specify what shall be presented to the +client with a 401 HTTP status. +@end deftypefun + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-dauth digest +@section Using Digest Authentication + +@deftypefun {char *} MHD_digest_auth_get_username (struct MHD_Connection *connection) +Find and return a pointer to the username value from the request header. +Return @code{NULL} if the value is not found or header does not exist. +If returned value is not @code{NULL}, the value must be @code{free()}'ed. +@end deftypefun + +@deftypefun int MHD_digest_auth_check (struct MHD_Connection *connection, const char *realm, const char *username, const char *password, unsigned int nonce_timeout) +Checks if the provided values in the WWW-Authenticate header are valid +and sound according to RFC2716. If valid return @code{MHD_YES}, otherwise return @code{MHD_NO}. + +@var{realm} must reference to a zero-terminated string representing the realm. + +@var{username} must reference to a zero-terminated string representing the username, +it is usually the returned value from MHD_digest_auth_get_username. + +@var{password} must reference to a zero-terminated string representing the password, +most probably it will be the result of a lookup of the username against a local database. + +@var{nonce_timeout} is the amount of time in seconds for a nonce to be invalid. +Most of the time it is sound to specify 300 seconds as its values. +@end deftypefun + +@deftypefun int MHD_queue_auth_fail_response (struct MHD_Connection *connection, const char *realm, const char *opaque, struct MHD_Response *response, int signal_stale) +Queues a response to request authentication from the client, +return @code{MHD_YES} if successful, otherwise @code{MHD_NO}. + +@var{realm} must reference to a zero-terminated string representing the realm. + +@var{opaque} must reference to a zero-terminated string representing a value +that gets passed to the client and expected to be passed again to the server +as-is. This value can be a hexadecimal or base64 string. + +@var{response} a response structure to specify what shall be presented to the +client with a 401 HTTP status. + +@var{signal_stale} a value that signals "stale=true" in the response header to +indicate the invalidity of the nonce and no need to ask for authentication +parameters and only a new nonce gets generated. @code{MHD_YES} to generate a new +nonce, @code{MHD_NO} to ask for authentication parameters. +@end deftypefun + +Example: handling digest authentication requests and responses. + +@example +#define PAGE "<html><head><title>libmicrohttpd demo</title></head><body>Access granted</body></html>" +#define DENIED "<html><head><title>libmicrohttpd demo</title></head><body>Access denied</body></html>" +#define OPAQUE "11733b200778ce33060f31c9af70a870ba96ddd4" + +static int +ahc_echo (void *cls, + struct MHD_Connection *connection, + const char *url, + const char *method, + const char *version, + const char *upload_data, size_t *upload_data_size, void **ptr) +@{ + struct MHD_Response *response; + char *username; + const char *password = "testpass"; + const char *realm = "test@@example.com"; + int ret; + + username = MHD_digest_auth_get_username(connection); + if (username == NULL) + @{ + response = MHD_create_response_from_buffer(strlen (DENIED), + DENIED, + MHD_RESPMEM_PERSISTENT); + ret = MHD_queue_auth_fail_response(connection, realm, + OPAQUE, + response, + MHD_NO); + MHD_destroy_response(response); + return ret; + @} + ret = MHD_digest_auth_check(connection, realm, + username, + password, + 300); + free(username); + if ( (ret == MHD_INVALID_NONCE) || + (ret == MHD_NO) ) + @{ + response = MHD_create_response_from_buffer(strlen (DENIED), + DENIED, + MHD_RESPMEM_PERSISTENT); + if (NULL == response) + return MHD_NO; + ret = MHD_queue_auth_fail_response(connection, realm, + OPAQUE, + response, + (ret == MHD_INVALID_NONCE) ? MHD_YES : MHD_NO); + MHD_destroy_response(response); + return ret; + @} + response = MHD_create_response_from_buffer (strlen(PAGE), PAGE, + MHD_RESPMEM_PERSISTENT); + ret = MHD_queue_response(connection, MHD_HTTP_OK, response); + MHD_destroy_response(response); + return ret; +@} +@end example + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-post +@chapter Adding a @code{POST} processor +@cindex POST method + +@menu +* microhttpd-post api:: Programming interface for the + @code{POST} processor. +@end menu + + +@noindent +MHD provides the post processor API to make it easier for applications to +parse the data of a client's @code{POST} request: the +@code{MHD_AccessHandlerCallback} will be invoked multiple times to +process data as it arrives; at each invocation a new chunk of data must +be processed. The arguments @var{upload_data} and @var{upload_data_size} +are used to reference the chunk of data. + +When @code{MHD_AccessHandlerCallback} is invoked for a new connection: +its @code{*@var{con_cls}} argument is set to @code{NULL}. When @code{POST} +data comes in the upload buffer it is @strong{mandatory} to use the +@var{con_cls} to store a reference to per-connection data. The fact +that the pointer was initially @code{NULL} can be used to detect that +this is a new request. + +One method to detect that a new connection was established is +to set @code{*con_cls} to an unused integer: + +@example +int +access_handler (void *cls, + struct MHD_Connection * connection, + const char *url, + const char *method, const char *version, + const char *upload_data, size_t *upload_data_size, + void **con_cls) +@{ + static int old_connection_marker; + int new_connection = (NULL == *con_cls); + + if (new_connection) + @{ + /* new connection with POST */ + *con_cls = &old_connection_marker; + @} + + ... +@} +@end example + +@noindent +In contrast to the previous example, for @code{POST} requests in particular, +it is more common to use the value of @code{*con_cls} to keep track of +actual state used during processing, such as the post processor (or a +struct containing a post processor): + +@example +int +access_handler (void *cls, + struct MHD_Connection * connection, + const char *url, + const char *method, const char *version, + const char *upload_data, size_t *upload_data_size, + void **con_cls) +@{ + struct MHD_PostProcessor * pp = *con_cls; + + if (pp == NULL) + @{ + pp = MHD_create_post_processor(connection, ...); + *con_cls = pp; + return MHD_YES; + @} + if (*upload_data_size) + @{ + MHD_post_process(pp, upload_data, *upload_data_size); + *upload_data_size = 0; + return MHD_YES; + @} + else + @{ + MHD_destroy_post_processor(pp); + return MHD_queue_response(...); + @} +@} +@end example + +Note that the callback from @code{MHD_OPTION_NOTIFY_COMPLETED} +should be used to destroy the post processor. This cannot be +done inside of the access handler since the connection may not +always terminate normally. + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-post api +@section Programming interface for the @code{POST} processor +@cindex POST method + +@deftypefun {struct MHD_PostProcessor *} MHD_create_post_processor (struct MHD_Connection *connection, size_t buffer_size, MHD_PostDataIterator iterator, void *iterator_cls) +Create a PostProcessor. A PostProcessor can be used to (incrementally) +parse the data portion of a @code{POST} request. + +@table @var +@item connection +the connection on which the @code{POST} is happening (used to determine +the @code{POST} format); + +@item buffer_size +maximum number of bytes to use for internal buffering (used only for the +parsing, specifically the parsing of the keys). A tiny value (256-1024) +should be sufficient; do @strong{NOT} use a value smaller than 256; +for good performance, use 32k or 64k (i.e. 65536). + +@item iterator +iterator to be called with the parsed data; must @strong{NOT} be +@code{NULL}; + +@item iterator_cls +custom value to be used as first argument to @var{iterator}. +@end table + +Return @code{NULL} on error (out of memory, unsupported encoding), otherwise +a PP handle. +@end deftypefun + + +@deftypefun int MHD_post_process (struct MHD_PostProcessor *pp, const char *post_data, size_t post_data_len) +Parse and process @code{POST} data. Call this function when @code{POST} +data is available (usually during an @code{MHD_AccessHandlerCallback}) +with the @var{upload_data} and @var{upload_data_size}. Whenever +possible, this will then cause calls to the +@code{MHD_IncrementalKeyValueIterator}. + +@table @var +@item pp +the post processor; + +@item post_data +@var{post_data_len} bytes of @code{POST} data; + +@item post_data_len +length of @var{post_data}. +@end table + +Return @code{MHD_YES} on success, @code{MHD_NO} on error +(out-of-memory, iterator aborted, parse error). +@end deftypefun + + +@deftypefun int MHD_destroy_post_processor (struct MHD_PostProcessor *pp) +Release PostProcessor resources. After this function is being called, +the PostProcessor is guaranteed to no longer call its iterator. There +is no special call to the iterator to indicate the end of the post processing +stream. After destroying the PostProcessor, the programmer should +perform any necessary work to complete the processing of the iterator. + +Return @code{MHD_YES} if processing completed nicely, @code{MHD_NO} +if there were spurious characters or formatting problems with +the post request. It is common to ignore the return value +of this function. + + +@end deftypefun + + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-info +@chapter Obtaining and modifying status information. + + +@menu +* microhttpd-info daemon:: State information about an MHD daemon +* microhttpd-info conn:: State information about a connection +* microhttpd-option conn:: Modify per-connection options +@end menu + + +@c ------------------------------------------------------------ +@node microhttpd-info daemon +@section Obtaining state information about an MHD daemon + +@deftypefun {const union MHD_DaemonInfo *} MHD_get_daemon_info (struct MHD_Daemon *daemon, enum MHD_DaemonInfoType infoType, ...) +Obtain information about the given daemon. This function +is currently not fully implemented. + +@table @var +@item daemon +the daemon about which information is desired; + +@item infoType +type of information that is desired + +@item ... +additional arguments about the desired information (depending on +infoType) +@end table + +Returns a union with the respective member (depending on +infoType) set to the desired information), or @code{NULL} +in case the desired information is not available or +applicable. +@end deftypefun + + +@deftp {Enumeration} MHD_DaemonInfoType +Values of this enum are used to specify what +information about a daemon is desired. +@table @code +@item MHD_DAEMON_INFO_KEY_SIZE +Request information about the key size for a particular cipher +algorithm. The cipher algorithm should be passed as an extra argument +(of type 'enum MHD_GNUTLS_CipherAlgorithm'). No longer supported, +using this value will cause @code{MHD_get_daemon_info} to return NULL. + +@item MHD_DAEMON_INFO_MAC_KEY_SIZE +Request information about the key size for a particular cipher +algorithm. The cipher algorithm should be passed as an extra argument +(of type 'enum MHD_GNUTLS_HashAlgorithm'). No longer supported, +using this value will cause @code{MHD_get_daemon_info} to return NULL. + +@item MHD_DAEMON_INFO_LISTEN_FD +@cindex listen +Request the file-descriptor number that MHD is using to listen to the +server socket. This can be useful if no port +was specified and a client needs to learn what port +is actually being used by MHD. +No extra arguments should be passed. + +@item MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY +@cindex epoll +Request the file-descriptor number that MHD is using for epoll. If +the build is not supporting epoll, NULL is returned; if we are using a +thread pool or this daemon was not started with +@code{MHD_USE_EPOLL_LINUX_ONLY}, (a pointer to) -1 is returned. If we are +using @code{MHD_USE_SELECT_INTERNALLY} or are in 'external' select mode, the +internal epoll FD is returned. This function must be used in external +select mode with epoll to obtain the FD to call epoll on. No extra +arguments should be passed. + +@item MHD_DAEMON_INFO_CURRENT_CONNECTIONS +@cindex connection, limiting number of connections +Request the number of current connections handled by the daemon. No +extra arguments should be passed and a pointer to a @code{union +MHD_DaemonInfo} value is returned, with the @code{num_connections} +member of type @code{unsigned int} set to the number of active +connections. + +Note that in multi-threaded or internal-select mode, the real number of current +connections may already be different when @code{MHD_get_daemon_info} returns. +The number of current connections can be used (even in multi-threaded and +internal-select mode) after @code{MHD_quiesce_daemon} to detect whether all +connections have been handled. + +@end table +@end deftp + + + +@c ------------------------------------------------------------ +@node microhttpd-info conn +@section Obtaining state information about a connection + + +@deftypefun {const union MHD_ConnectionInfo *} MHD_get_connection_info (struct MHD_Connection *daemon, enum MHD_ConnectionInfoType infoType, ...) +Obtain information about the given connection. + +@table @var +@item connection +the connection about which information is desired; + +@item infoType +type of information that is desired + +@item ... +additional arguments about the desired information (depending on +infoType) +@end table + +Returns a union with the respective member (depending on +infoType) set to the desired information), or @code{NULL} +in case the desired information is not available or +applicable. +@end deftypefun + +@deftp {Enumeration} MHD_ConnectionInfoType +Values of this enum are used to specify what information about a +connection is desired. + +@table @code + +@item MHD_CONNECTION_INFO_CIPHER_ALGO +What cipher algorithm is being used (HTTPS connections only). +Takes no extra arguments. +@code{NULL} is returned for non-HTTPS connections. + +@item MHD_CONNECTION_INFO_PROTOCOL, +Takes no extra arguments. Allows finding out the TLS/SSL protocol used +(HTTPS connections only). +@code{NULL} is returned for non-HTTPS connections. + +@item MHD_CONNECTION_INFO_CLIENT_ADDRESS +Returns information about the address of the client. Returns +essentially a @code{struct sockaddr **} (since the API returns +a @code{union MHD_ConnectionInfo *} and that union contains +a @code{struct sockaddr *}). + +@item MHD_CONNECTION_INFO_GNUTLS_SESSION, +Takes no extra arguments. Allows access to the underlying GNUtls session, +including access to the underlying GNUtls client certificate +(HTTPS connections only). Takes no extra arguments. +@code{NULL} is returned for non-HTTPS connections. + +@item MHD_CONNECTION_INFO_GNUTLS_CLIENT_CERT, +Dysfunctional (never implemented, deprecated). Use +MHD_CONNECTION_INFO_GNUTLS_SESSION to get the @code{gnutls_session_t} +and then call @code{gnutls_certificate_get_peers()}. + +@item MHD_CONNECTION_INFO_DAEMON +Returns information about @code{struct MHD_Daemon} which manages +this connection. + +@item MHD_CONNECTION_INFO_CONNECTION_FD +Returns the file descriptor (usually a TCP socket) associated with +this connection (in the ``connect-fd'' member of the returned struct). +Note that manipulating the descriptor directly can have problematic +consequences (as in, break HTTP). Applications might use this access +to manipulate TCP options, for example to set the ``TCP-NODELAY'' +option for COMET-like applications. Note that MHD will set TCP-CORK +after sending the HTTP header and clear it after finishing the footers +automatically (if the platform supports it). As the connection +callbacks are invoked in between, those might be used to set different +values for TCP-CORK and TCP-NODELAY in the meantime. + +@item MHD_CONNECTION_INFO_SOCKET_CONTEXT +Returns the client-specific pointer to a @code{void *} that was +(possibly) set during a @code{MHD_NotifyConnectionCallback} when the +socket was first accepted. Note that this is NOT the same as the +@code{con_cls} argument of the @code{MHD_AccessHandlerCallback}. The +@code{con_cls} is fresh for each HTTP request, while the +@code{socket_context} is fresh for each socket. + +@end table +@end deftp + + + +@c ------------------------------------------------------------ +@node microhttpd-option conn +@section Setting custom options for an individual connection +@cindex timeout + + + +@deftypefun {int} MHD_set_connection_option (struct MHD_Connection *daemon, enum MHD_CONNECTION_OPTION option, ...) +Set a custom option for the given connection. + +@table @var +@item connection +the connection for which an option should be set or modified; + +@item option +option to set + +@item ... +additional arguments for the option (depending on option) +@end table + +Returns @code{MHD_YES} on success, @code{MHD_NO} for errors +(i.e. option argument invalid or option unknown). +@end deftypefun + + +@deftp {Enumeration} MHD_CONNECTION_OPTION +Values of this enum are used to specify which option for a +connection should be changed. + +@table @code + +@item MHD_CONNECTION_OPTION_TIMEOUT +Set a custom timeout for the given connection. Specified +as the number of seconds, given as an @code{unsigned int}. Use +zero for no timeout. + +@end table +@end deftp + + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +@c ------------------------------------------------------------ +@node microhttpd-util +@chapter Utility functions. + + +@menu +* microhttpd-util feature:: Test supported MHD features +* microhttpd-util unescape:: Unescape strings +@end menu + + +@c ------------------------------------------------------------ +@node microhttpd-util feature +@section Testing for supported MHD features + + +@deftp {Enumeration} MHD_FEATURE +Values of this enum are used to specify what +information about a daemon is desired. +@table @code +@item MHD_FEATURE_MESSAGES +Get whether messages are supported. If supported then in debug +mode messages can be printed to stderr or to external logger. + +@item MHD_FEATURE_SSL +Get whether HTTPS is supported. If supported then flag +MHD_USE_SSL and options MHD_OPTION_HTTPS_MEM_KEY, +MHD_OPTION_HTTPS_MEM_CERT, MHD_OPTION_HTTPS_MEM_TRUST, +MHD_OPTION_HTTPS_MEM_DHPARAMS, MHD_OPTION_HTTPS_CRED_TYPE, +MHD_OPTION_HTTPS_PRIORITIES can be used. + +@item MHD_FEATURE_HTTPS_CERT_CALLBACK +Get whether option #MHD_OPTION_HTTPS_CERT_CALLBACK is +supported. + +@item MHD_FEATURE_IPv6 +Get whether IPv6 is supported. If supported then flag +MHD_USE_IPv6 can be used. + +@item MHD_FEATURE_IPv6_ONLY +Get whether IPv6 without IPv4 is supported. If not supported +then IPv4 is always enabled in IPv6 sockets and +flag MHD_USE_DUAL_STACK if always used when MHD_USE_IPv6 is +specified. + +@item MHD_FEATURE_POLL +Get whether @code{poll()} is supported. If supported then flag +MHD_USE_POLL can be used. + +@item MHD_FEATURE_EPOLL +Get whether @code{epoll()} is supported. If supported then Flags +MHD_USE_EPOLL_LINUX_ONLY and +MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY can be used. + +@item MHD_FEATURE_SHUTDOWN_LISTEN_SOCKET +Get whether shutdown on listen socket to signal other +threads is supported. If not supported flag +MHD_USE_PIPE_FOR_SHUTDOWN is automatically forced. + +@item MHD_FEATURE_SOCKETPAIR +Get whether a @code{socketpair()} is used internally instead of +a @code{pipe()} to signal other threads. + +@item MHD_FEATURE_TCP_FASTOPEN +Get whether TCP Fast Open is supported. If supported then +flag MHD_USE_TCP_FASTOPEN and option +MHD_OPTION_TCP_FASTOPEN_QUEUE_SIZE can be used. + +@item MHD_FEATURE_BASIC_AUTH +Get whether HTTP Basic authorization is supported. If supported +then functions @code{MHD_basic_auth_get_username_password()} and +@code{MHD_queue_basic_auth_fail_response()} can be used. + +@item MHD_FEATURE_DIGEST_AUTH +Get whether HTTP Digest authorization is supported. If +supported then options MHD_OPTION_DIGEST_AUTH_RANDOM, +MHD_OPTION_NONCE_NC_SIZE and functions @code{MHD_digest_auth_check()}, +can be used. + +@item MHD_FEATURE_POSTPROCESSOR +Get whether postprocessor is supported. If supported then +functions @code{MHD_create_post_processor()}, +@code{MHD_post_process()}, @code{MHD_destroy_post_processor()} +can be used. + +@end table +@end deftp + + + +@deftypefun {int} MHD_is_feature_supported (enum MHD_FEATURE feature) +Get information about supported MHD features. Indicate that MHD was +compiled with or without support for particular feature. Some features +require additional support by the kernel. However, kernel support is not +checked by this function. + +@table @var +@item feature +type of requested information +@end table + +Returns @code{MHD_YES} if the feature is supported, +and @code{MHD_NO} if not. +@end deftypefun + + +@c ------------------------------------------------------------ +@node microhttpd-util unescape +@section Unescape strings + +@deftypefun {size_t} MHD_http_unescape (char *val) +Process escape sequences ('%HH') Updates val in place; the result +should be UTF-8 encoded and cannot be larger than the input. The +result must also still be 0-terminated. + +@table @var +@item val +value to unescape (modified in the process), must be +a 0-terminated UTF-8 string. +@end table + +Returns length of the resulting val (@code{strlen(val)} may be +shorter afterwards due to elimination of escape sequences). + +@end deftypefun + + + + +@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + +@c ********************************************************** +@c ******************* Appendices ************************* +@c ********************************************************** + +@node GNU-LGPL +@unnumbered GNU-LGPL +@cindex license +@include lgpl.texi + +@node GNU GPL with eCos Extension +@unnumbered GNU GPL with eCos Extension +@cindex license +@include ecos.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 |