\input texinfo

@setfilename libmicrohttpd.info

@documentencoding UTF-8

@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--2017 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, are left to the main application.  In

particular, if an application developer wants to support range

requests, he needs to explicitly indicate support in responses and

also explicitly parse the range header and generate a response (for

example, using the @code{MHD_create_response_from_fd_at_offset} call

to serve ranges from a file).  MHD does understands headers that

control connection management (specifically, @code{Connection: close}

and @code{Expect: 100 continue} are understood and handled

automatically).  @code{Connection: upgrade} is supported by passing

control over the socket (or something that behaves like the real

socket in the case of TLS) to the application (after sending the

desired HTTP response header).

MHD largely ignores the semantics of the different HTTP methods,

so clients are left to handle those.  One exception is that MHD does

understand @code{HEAD} and will only send the headers of the response

and not the body, even if the client supplied a body.  (In fact,

clients do need to construct a response with the correct length, even

for @code{HEAD} request.)

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

styles.

The four basic thread modes are external sockets polling (MHD creates

no threads, event loop is fully managed by the application), internal

polling (MHD creates one thread for all connections), polling in

thread pool (MHD creates a thread pool which is used to process all

connections) and thread-per-connection (MHD creates one thread for

listen sockets and then one thread per accepted connection).

These thread modes are then combined with the evet loop styles

(polling function type).  MHD support select, poll and epoll. select

is available on all platforms, epoll and 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{libmicrohttpd_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 first 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 some platform, 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-httpupgrade''

do not build code for HTTP ``Upgrade'' (smaller binary size, binary incompatible library)

@item ``--disable-epoll''

do not include epoll support, even if it supported (minimally smaller binary size, good for portability testing)

@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 or similar).  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 MHD will run automatically in background thread(s) only if

@code{MHD_USE_INTERNAL_POLLING_THREAD} is used. Otherwise caller

(application) must use @code{MHD_run} or @code{MHD_run_from_select} to

have MHD processed network connections and data.

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{TLS}, threads or IPv6). TLS support generally depends on

options given during MHD compilation.

@table @code

@item MHD_NO_FLAG

No options selected.

@item MHD_USE_ERROR_LOG

If this flag is used, the library should print error messages and

warnings to stderr (or to custom error printer if it's specified by

options).  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_DEBUG

@cindex debugging

Currently the same as @code{MHD_USE_ERROR_LOG}.

@item MHD_USE_TLS

@cindex TLS

@cindex SSL

Run in HTTPS-mode.  If you specify @code{MHD_USE_TLS} 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_INTERNAL_POLLING_THREAD

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

@cindex deprecated

Deprecated (use @code{MHD_OPTION_STRICT_FOR_CLIENT}).

Be pedantic about the protocol.

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 @code{poll()} instead of @code{select()}. This allows sockets with

descriptors @code{>= FD_SETSIZE}.  This option currently only works in

conjunction with @code{MHD_USE_INTERNAL_POLLING_THREAD} (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

@cindex FD_SETSIZE

@cindex epoll

@cindex select

Use @code{epoll()} instead of @code{poll()} or @code{select()}. This

allows sockets with descriptors @code{>= FD_SETSIZE}.  This option is

only available on some systems and does not work in conjunction with

@code{MHD_USE_THREAD_PER_CONNECTION} (at this point).  If you specify

@code{MHD_USE_EPOLL} and the local platform does not support it,

@code{MHD_start_daemon} will return NULL.  Using @code{epoll()}

instead of @code{select()} or @code{poll()} can in some situations

result in significantly higher performance as the system call has

fundamentally lower complexity (O(1) for @code{epoll()} vs. O(n) for

@code{select()}/@code{poll()} where n is the number of open

connections).

@item MHD_USE_TURBO

@cindex performance

Enable optimizations to aggressively improve performance.

Currently, the optimizations this option enables are based on

opportunistic reads and writes.  Bascially, MHD will simply try to

read or write or accept on a socket before checking that the socket is

ready for IO using the event loop mechanism.  As the sockets are

non-blocking, this may fail (at a loss of performance), but generally

MHD does this in situations where the operation is likely to succeed,

in which case performance is improved.  Setting the flag should generally

be safe (even though the code is slightly more experimental).  You may

want to benchmark your application to see if this makes any difference

for you.

@item MHD_USE_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_ITC

@cindex quiesce

Force MHD to use a signal inter-thread communication channel to notify

the event loop (of threads) of our shutdown and other events.  This is

required if an application uses @code{MHD_USE_INTERNAL_POLLING_THREAD}

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.

Using this option also guarantees that MHD will not call

@code{shutdown()} on the listen socket, which means a parent

process can continue to use the socket.

@item MHD_ALLOW_SUSPEND_RESUME

Enables using @code{MHD_suspend_connection} and

@code{MHD_resume_connection}, as performing these calls requires some

additional inter-thred communication channels 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.

@item MHD_ALLOW_UPGRADE

@cindex upgrade

This option must be set if you want to upgrade connections

(via ``101 Switching Protocols'' responses).  This requires MHD to

allocate additional resources, and hence we require this

special flag so we only use the resources that are really needed.

@item MHD_USE_AUTO

Automatically select best event loop style (polling function)

depending on requested mode by other MHD flags and functions available

on platform.  If application doesn't have requirements for any

specific polling function, it's recommended to use this flag.  This

flag is very convenient for multiplatform applications.

@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.

If the connection limit is reached, MHD's behavior depends a bit on

other options.  If @code{MHD_USE_ITC} was given, MHD

will stop accepting connections on the listen socket.  This will cause

the operating system to queue connections (up to the @code{listen()}

limit) above the connection limit.  Those connections will be held

until MHD is done processing at least one of the active connections.

If @code{MHD_USE_ITC} is not set, then MHD will continue

to @code{accept()} and immediately @code{close()} these connections.

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_LISTEN_BACKLOG_SIZE

Set the size of the @code{listen()} back log queue of the TCP socket.

Takes an @code{unsigned int} as the argument.  Default is the

platform-specific value of @code{SOMAXCONN}.

@item MHD_OPTION_STRICT_FOR_CLIENT

Specify how strict we should enforce the HTTP protocol.

Takes an @code{int} as the argument.  Default is zero.

If set to 1, MHD will be strict about the protocol.  Specifically, at

the moment, this flag uses MHD to reject HTTP 1.1 connections without

a "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 set this to 1 if you are testing clients against

MHD, and 0 in production.

If set to -1 MHD will be permissive about the protocol, allowing

slight deviations that are technically not allowed by the

RFC. Specifically, at the moment, this flag causes MHD to allow spaces

in header field names. This is disallowed by the standard.

It is not recommended to set it to -1 on publicly available servers as

it may potentially lower level of protection.

@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