applyin Karl Berry's suggestions for GNU libextractor also to MHD

1 files changed, 2140 insertions, 0 deletions

diff --git a/doc/libmicrohttpd.texi b/doc/libmicrohttpd.texi
new file mode 100644
index 00000000..f9b99bea
--- /dev/null
+++ b/doc/libmicrohttpd.texi
@@ -0,0 +1,2140 @@
+\input texinfo
+@setfilename libmicrohttpd.info
+@include version.texi
+@settitle The GNU libmicrohttpd Reference Manual
+@c Unify all the indices into concept index.
+@syncodeindex fn cp
+@syncodeindex vr cp
+@syncodeindex ky cp
+@syncodeindex pg cp
+@syncodeindex tp cp
+@copying
+This manual is for GNU libmicrohttpd
+(version @value{VERSION}, @value{UPDATED}), a library for embedding
+an HTTP(S) server into C applications.
+
+Copyright @copyright{} 2007--2012 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-dauth::            Utilizing Authentication.
+* microhttpd-post::             Adding a @code{POST} processor.
+* microhttpd-info::             Obtaining and modifying status information.
+
+Appendices
+
+* GNU-LGPL::                     The GNU Lesser General Public License says how you
+                                 can copy and share almost all of `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 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 ``--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 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_LONG_LONG
+@cindex 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_LONG_LONG} which will default to @code{long long}.
+If your platform does not support @code{long long}, you should
+change "platform.h" to define @code{MHD_LONG_LONG} to an appropriate
+alternative type and also define @code{MHD_LONG_LONG_PRINTF} to the
+corresponding format string for printing such a data type (without
+the percent sign).
+
+@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
+Run in https mode (this option may not work with all threading modes yet).
+
+@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).
+
+
+@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 only works in conjunction with
+@code{MHD_USE_THREAD_PER_CONNECTION} (at this point).
+
+@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.
+
+@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}.
+
+@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_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)
+@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.
+
+@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_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_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
+(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).
+
+@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
+
+
+
+
+@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
+
+@itemize
+@item
+for a @code{POST} that fits into memory and that is encoded with a
+supported encoding, the @code{POST} data will @strong{NOT} be given in
+@var{upload_data} and is instead available as part of
+@code{MHD_get_connection_values()};
+
+@item
+very large @code{POST} data @strong{will} be made available
+incrementally in @var{upload_data};
+@end itemize
+
+@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.
+
+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, either
+``immediately'' if in multi-threaded mode (in which case the callback
+may want to do blocking operations to avoid busy waiting) or in the
+next round if @code{MHD_run} is used.  Returning zero for a daemon
+that runs in internal @code{select}-mode is an error (since it
+would result in busy waiting) and cause the program to be aborted
+(@code{abort()}).
+
+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 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.
+
+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 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.
+
+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.
+@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 long
+@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
+@cindex timeout
+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 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 (uint64_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 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+@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-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;
+
+@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').
+
+@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').
+
+@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.
+
+@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.
+
+@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 **********************************************************
+@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