     [file version.texi not included]

The GNU libmicrohttpd Library
*****************************

This manual documents GNU libmicrohttpd version VERSION, last updated UPDATED. It is built upon the documentation in the header file microhttpd.h.

Copyright © 2007, 2008 Christian Grothoff

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 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".

GNU libmicrohttpd is a GNU package.

Introduction
************

All symbols defined in the public API start with 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 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, Connection: close and Expect: 100 continue are understood and handled automatically).

MHD understands POST data and is able to decode certain formats (at the moment only application/x-www-form-urlencoded and 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.

Constants
*********

 -- Enumeration: MHD_FLAG
     Options for the MHD daemon.

     Note that if neither MHD_USER_THREAD_PER_CONNECTION nor MHD_USE_SELECT_INTERNALLY are 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 SSL, threads or IPv6).

     MHD_NO_FLAG
          No options selected.

     MHD_USE_DEBUG
          Run in debug mode.  If this flag is used, the library should print error messages and warnings to stderr.  Note that MHD also needs to be compiled with the configure option --enable-messages for this run-time option to have any effect.

     MHD_USE_SSL
          Run in https mode (this is not yet supported).

     MHD_USE_THREAD_PER_CONNECTION
          Run using one thread per connection.

     MHD_USE_SELECT_INTERNALLY
          Run using an internal thread doing SELECT.

     MHD_USE_IPv6
          Run using the IPv6 protocol (otherwise, MHD will just support IPv4).

     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 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 ON if you are testing clients against MHD, and OFF in production.

 -- Enumeration: MHD_OPTION
     MHD options.  Passed in the varargs portion of MHD_start_daemon().

     MHD_OPTION_END
          No more options / last option.  This is used to terminate the VARARGs list.

     MHD_OPTION_CONNECTION_MEMORY_LIMIT
          Maximum memory size per connection (followed by an unsigned int).

     MHD_OPTION_CONNECTION_LIMIT
          Maximum number of concurrenct connections to accept (followed by an unsigned int).

     MHD_OPTION_CONNECTION_TIMEOUT
          After how many seconds of inactivity should a connection automatically be timed out? (followed by an unsigned int; use zero for no timeout).

     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 MHD_AccessHandlerCallback()) will not result in notifications.

          This option should be followed by TWO pointers.  First a pointer to a function of type MHD_RequestCompletedCallback() and second a pointer to a closure to pass to the request completed callback.  The second pointer maybe NULL.

     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 unsigned int.  The default is zero, which means no limit on the number of connections from the same IP address.

 -- Enumeration: MHD_ValueKind
     The MHD_ValueKind specifies the source of the key-value pairs in the HTTP protocol.

     MHD_RESPONSE_HEADER_KIND
          Response header.

     MHD_HEADER_KIND
          HTTP header.

     MHD_COOKIE_KIND
          Cookies.  Note that the original HTTP header containing the cookie(s) will still be available and intact.

     MHD_POSTDATA_KIND
          POST data.  This is available only if a content encoding supported by MHD is used (currently only 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 MHD_AccessHandlerCallback() will be empty (since it has already been processed).

     MHD_GET_ARGUMENT_KIND
          GET (URI) arguments.

     MHD_HEADER_KIND
          HTTP footer (only for http 1.1 chunked encodings).

 -- Enumeration: MHD_RequestTerminationCode
     The MHD_RequestTerminationCode specifies reasons why a request has been terminated (or completed).

     MHD_REQUEST_TERMINATED_COMPLETED_OK
          We finished sending the response.

     MHD_REQUEST_TERMINATED_WITH_ERROR
          Error handling the connection (resources exhausted, other side closed connection, application error accepting request, etc.)

     MHD_REQUEST_TERMINATED_TIMEOUT_REACHED
          No activity on the connection for the number of seconds specified using MHD_OPTION_CONNECTION_TIMEOUT.

     MHD_REQUEST_TERMINATED_DAEMON_SHUTDOWN
          We had to close the session since MHD was being shut down.

Structures type definition
**************************

 -- C Struct: MHD_Daemon
     Handle for the daemon (listening on a socket for HTTP traffic).

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

 -- C Struct: MHD_Response
     Handle for a response.

 -- C Struct: MHD_PostProcessor
     Handle for POST processing.

Callback functions definition
*****************************

 -- 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 MHD_YES if connection is allowed, MHD_NO if not.

     cls
          custom value selected at callback registration time;

     addr
          address information from the client;

     addrlen
          length of the address information.

 -- Function Pointer: int *MHD_AccessHandlerCallback (void *cls, struct MHD_Connection * connection, const char *url, const char *method, const char *version, const char *upload_data, unsigned int *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 MHD_Response ones) to provide content to give back to the client and return an HTTP status code (i.e. 200 for OK, 404, etc.).

     microhttpd-post, for details on how to code this callback.

     Must return MHD_YES if the connection was handled successfully, MHD_NO if the socket must be closed due to a serious error while handling the request

     cls
          custom value selected at callback registration time;

     url
          the URL requested by the client;

     method
          the HTTP method used by the client (GET, PUT, DELETE, POST, etc.);

     version
          the HTTP version string (i.e. HTTP/1.1);

     upload_data
          the data being uploaded (excluding headers):

            * for a POST that fits into memory and that is encoded with a supported encoding, the POST data will NOT be given in UPLOAD_DATA and is instead available as part of MHD_get_connection_values();

            * very large POST data will be made available incrementally in UPLOAD_DATA;

     upload_data_size
          set initially to the size of the UPLOAD_DATA provided; this callback must update this value to the number of bytes 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 upload_data_size.

     con_cls
          reference to a pointer, initially set to 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 PUT/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 MHD_RequestCompletedCallback (which can be set with the MHD_OPTION_NOTIFY_COMPLETED).

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

     cls
          custom value selected at callback registration time;

     connection
          connection handle;

     con_cls
          value as set by the last call to the MHD_AccessHandlerCallback;

     toe
          reason for request termination see MHD_OPTION_NOTIFY_COMPLETED.

 -- 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 POST-data fields of a request, and also to iterate over the headers that have been added to a response.

     Return MHD_YES to continue iterating, MHD_NO to abort the iteration.

 -- Function Pointer: int *MHD_ContentReaderCallback (void *cls, size_t pos, char *buf, int max)
     Callback used by MHD in order to obtain content.  The callback has to copy at most MAX bytes of content into BUF.  The total number of bytes that has been placed into 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) or in the next round if MHD_run is used.  Returning zero for a daemon that runs in internal select() mode is an error (since it would result in busy waiting) and will cause the program to be aborted (abort()).

     cls
          custom value selected at callback registration time;

     pos
          position in the datastream to access; note that if an 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 MHD_Response is not re-used, MHD guarantees that POS will be the sum of all non-negative return values obtained from the content reader so far.

     Return -1 on error (MHD will no longer try to read content and instead close the connection with the client).

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

 -- 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, size_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 POST data.

     cls
          custom value selected at callback registration time;

     kind
          type of the value;

     key
          zero-terminated key for the value;

     filename
          name of the uploaded file, NULL if not known;

     content_type
          mime-type of the data, NULL if not known;

     transfer_encoding
          encoding of the data, NULL if not known;

     data
          pointer to size bytes of data at the specified offset;

     off
          offset of data in the overall value;

     size
          number of bytes in data available.

     Return MHD_YES to continue iterating, MHD_NO to abort the iteration.

Starting and stopping the server
********************************

 -- Function: 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.

     flags
          OR-ed combination of MHD_FLAG values;

     port
          port to bind to;

     apc
          callback to call to check which clients will be allowed to connect; you can pass NULL in which case connections from any IP will be accepted;

     apc_cls
          extra argument to APC;

     dh
          default handler for all URIs;

     dh_cls
          extra argument to DH.

     Additional arguments are a list of options (type-value pairs, terminated with MHD_OPTION_END). It is mandatory to use MHD_OPTION_END as last argument, even when there are no additional arguments.

     Return NULL on error, handle to daemon on success.

 -- Function: void MHD_stop_daemon (struct MHD_Daemon *daemon)
     Shutdown an HTTP daemon.

 -- Function: 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 MHD_get_fdset() if the client-controlled select() method is used.

     Return MHD_YES on success, MHD_NO if this daemon was not started with the right options for this call.

Implementing external select
****************************

 -- Function: 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 select() sets for this daemon. The daemon's socket is added to READ_FD_SET. The list of currently existent connections is scanned and their file descriptors added to the correct set.

     see Waiting for I/O (libc), for details on file descriptor sets.

     After the call completed successfully: the variable referenced by MAX_FD references the file descriptor with highest integer identifier. The variable must be set to zero before invoking this function.

     Return MHD_YES on success, MHD_NO if: the arguments are invalid (example: NULL pointers); this daemon was not started with the right options for this call.

 -- Function: int MHD_get_timeout (struct MHD_Daemon *daemon, unsigned long long *timeout)
     Obtain timeout value for select for this daemon (only needed if connection timeout is used).  The returned value is how long select() should at most block, not the timeout value set for connections.

     timeout
          set to the timeout (in milliseconds).

     Return MHD_YES on success, MHD_NO if timeouts are not used (or no connections exist that would necessiate the use of a timeout right now).

Handling requests
*****************

 -- Function: int MHD_get_connection_values (struct MHD_Connection *connection, enum MHD_ValueKind kind, MHD_KeyValueIterator iterator, void *iterator_cls)
     Get all the headers matching KIND from the request.

     The ITERATOR callback is invoked once for each header, with ITERATOR_CLS as first argument. Return the number of entries iterated over; this can be less than the number of headers if, while iterating, ITERATOR returns MHD_NO.

     ITERATOR can be NULL: in this case this function just counts and returns the number of headers.

 -- Function: 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 KIND, return one of them (the ``first'', whatever that means).  KEY must reference a zero-terminated ASCII-coded string representing the header to look for: it is compared against the headers using strcasecmp(), so case is ignored.  Return NULL if no such item was found.

Building answers to responses
*****************************

Response objects handling by MHD is asynchronous with respect to the application execution flow. Instances of the 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 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 MHD_Response structure for each response kind, we use it every time we have to give that responce and we finally destroy it only when the daemon shuts down.

Enqueuing a response
====================

 -- Function: 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 (increment the reference counter).

     connection
          the connection identifying the client;

     status_code
          HTTP status code (i.e. 200 for OK);

     response
          response to transmit.

     Return MHD_YES on success or if message has been queued.  Return MHD_NO: if arguments are invalid (example: NULL pointer); on error (i.e. reply already sent).

 -- Function: 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 immediatley.

An explanation of reference counting (Note to readers acquainted
to the Tcl API: reference counting on MHD_Connection
structures is handled in the same way as Tcl handles Tcl_Obj
structures through Tcl_IncrRefCount() and
Tcl_DecrRefCount().):

 1. a MHD_Response object is allocated:

          struct MHD_Response * response = MHD_create_response_from_data(...);
          /* here: reference counter = 1 */

 2. the MHD_Response object is enqueued in a MHD_Connection:

          MHD_queue_response(connection, , response);
          /* here: reference counter = 2 */

 3. the creator of the response object discharges responsibility for it:

          MHD_destroy_response(response);
          /* here: reference counter = 1 */

 4. the daemon handles the connection sending the response's data to the client then decrements the reference counter by calling MHD_destroy_response(): the counter's value drops to zero and the MHD_Response object is released.

Creating response objects
=========================

 -- Function: struct MHD_Response * MHD_create_response_from_callback (size_t size, unsigned int 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.

     size
          size of the data portion of the response, -1 for unknown;

     block_size
          preferred block size for querying CRC (advisory only, MHD may still call CRC using smaller chunks); this is essentially the buffer size used for IO, clients should pick a value that is appropriate for IO and memory performance requirements;

     crc
          callback to use to obtain response data;

     crc_cls
          extra argument to CRC;

     crfc
          callback to call to free CRC_CLS resources.

     Return NULL on error (i.e. invalid arguments, out of memory).

 -- Function: 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.

     size
          size of the data portion of the response;

     data
          the data itself;

     must_free
          if true: MHD should free data when done;

     must_copy
          if true: MHD allocates a block of memory and use it to make a copy of DATA embedded in the returned MHD_Response structure; handling of the embedded memory is responsibility of MHD; DATA can be released anytime after this call returns.

     Return NULL on error (i.e. invalid arguments, out of memory).

Example: create a response from a statically allocated string:

     const char * data = "<html><body><p>Error!</p></body></html>";

     struct MHD_Connection * connection = ...;
     struct MHD_Response *   response;

     response = MHD_create_response_from_data(strlen(data), data,
                                              MHD_NO, MHD_NO);
     MHD_queue_response(connection, 404, response);
     MHD_destroy_response(response);

Adding headers to a response
============================

 -- Function: 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 HEADER and CONTENT must be zero-terminated and they are duplicated into memory blocks embedded in RESPONSE.

     Notice that the strings must not hold newlines, carriage returns or tab chars.

     Return MHD_NO on error (i.e. invalid header or content format or memory allocation error).

 -- Function: int MHD_del_response_header (struct MHD_Response *response, const char *header, const char *content)
     Delete a header line from the response.  Return MHD_NO on error (arguments are invalid or no such header known).

Inspecting a response object
============================

 -- Function: 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 ITERATOR callback for each header in the response, using ITERATOR_CLS as first argument. Return number of entries iterated over.  ITERATOR can be NULL: in this case the function just counts headers.

     ITERATOR should not modify the its key and value arguments, unless we know what we are doing.

 -- Function: 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.  KEY must reference a zero-terminated string representing the header to look for. The search is case sensitive. Return NULL if header does not exist or KEY is NULL.

     We should not modify the value, unless we know what we are doing.

Adding a POST processor
***********************

MHD provides the post procesor API to make it easier for applications to parse the data of a client's POST request: the 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 UPLOAD_DATA and UPLOAD_DATA_SIZE are used to reference the chunk of data.

When MHD_AccessHandlerCallback is invoked for a new connection: its *CON_CLS argument is set to NULL. When POST data comes in the upload buffer it is mandatory to use the CON_CLS to store a reference to per-connection data.  The fact that the pointer was initially 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 *con_cls to anunused integer:

     int
     access_handler (void *cls,
                     struct MHD_Connection * connection,
                     const char *url,
                     const char *method, const char *version,
                     const char *upload_data, unsigned int *upload_data_size,
                     void **con_cls)
     {
       static int old_connection_marker;
       int new_connection = (MYNULL == *con_cls);

       if (new_connection)
         {
           /* new connection with POST */
           *con_cls = &old_connection_marker;
         }

       ...
     }

In contrast to the previous example, for POST requests in particular, it is more common to use the value of *con_cls to keep track of actual state used during processing, such as the post processor (or a struct containing a post processor):

     int
     access_handler (void *cls,
                     struct MHD_Connection * connection,
                     const char *url,
                     const char *method, const char *version,
                     const char *upload_data, unsigned int *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(...);
         }
     }

Note that the callback from 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.

Programming interface for the POST processor
============================================

 -- Function: struct MHD_PostProcessor * MHD_create_post_processor (struct MHD_Connection *connection, unsigned int buffer_size, MHD_PostDataIterator iterator, void *iterator_cls)
     Create a PostProcessor.  A PostProcessor can be used to (incrementally) parse the data portion of a POST request.

     connection
          the connection on which the POST is happening (used to determine the POST format);

     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 NOT use a value smaller than 256;

     iterator
          iterator to be called with the parsed data; must NOT be NULL;

     iterator_cls
          custom value to be used as first argument to ITERATOR.

     Return NULL on error (out of memory, unsupported encoding), otherwise a PP handle.

 -- Function: int MHD_post_process (struct MHD_PostProcessor *pp, const char *post_data, unsigned int post_data_len)
     Parse and process POST data.  Call this function when POST data is available (usually during an MHD_AccessHandlerCallback) with the UPLOAD_DATA and UPLOAD_DATA_SIZE.  Whenever possible, this will then cause calls to the MHD_IncrementalKeyValueIterator.

     pp
          the post processor;

     post_data
          POST_DATA_LEN bytes of POST data;

     post_data_len
          length of POST_DATA.

     Return MHD_YES on success, MHD_NO on error (out-of-memory, iterator aborted, parse error).

 -- Function: 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 MHD_YES if processing completed nicely, 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.

Copying
*******

     [file lgpl.texi not included]

GNU-FDL
*******

     [file fdl-1.2.texi not included]