2 Constants

Enumeration: MHD_FLAG

Options for the MHD daemon.

Note that if neither MHD_USE_THREAD_PER_CONNECTION nor 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 SSL, threads or IPv6). SSL support generally depends on options given during MHD compilation. Threaded operations (including MHD_USE_SELECT_INTERNALLY) are not supported on Symbian.

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 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 --disable-messages flag set.

MHD_USE_SSL

Run in HTTPS-mode. If you specify MHD_USE_SSL and MHD was compiled without SSL support, MHD_start_daemon will return NULL.

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). If you specify MHD_USE_IPV6 and the local platform does not support it, MHD_start_daemon will return NULL.

If you want MHD to support IPv4 and IPv6 using a single socket, pass MHD_USE_DUAL_STACK, otherwise, if you only pass this option, MHD will try to bind to IPv6-only (resulting in no IPv4 support).

MHD_USE_DUAL_STACK

Use a single socket for IPv4 and IPv6. Note that this will mean that IPv4 addresses are returned by MHD in the IPv6-mapped format (the ’struct sockaddr_in6’ format will be used for IPv4 and IPv6).

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.

MHD_USE_POLL

Use poll() instead of select(). This allows sockets with descriptors >= FD_SETSIZE. This option currently only works in conjunction with MHD_USE_THREAD_PER_CONNECTION or MHD_USE_INTERNAL_SELECT (at this point). If you specify MHD_USE_POLL and the local platform does not support it, MHD_start_daemon will return NULL.

MHD_USE_EPOLL_LINUX_ONLY

Use epoll() instead of poll() or select(). This allows sockets with descriptors >= FD_SETSIZE. This option is only available on Linux systems and does not work in conjunction with MHD_USE_THREAD_PER_CONNECTION (at this point). If you specify MHD_USE_EPOLL_LINUX_ONLY and the local platform does not support it, MHD_start_daemon will return NULL. Using epoll() instead of select() or poll() can in some situations result in significantly higher performance as the system call has fundamentally lower complexity (O(1) for epoll() vs. O(n) for select()/poll() where n is the number of open connections).

MHD_SUPPRESS_DATE_NO_CLOCK

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

MHD_USE_NO_LISTEN_SOCKET

Run the HTTP server without any listen socket. This option only makes sense if 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, MHD_OPTION_THREAD_POOL_SIZE is ignored.

MHD_USE_PIPE_FOR_SHUTDOWN

Force MHD to use a signal pipe to notify the event loop (of threads) of our shutdown. This is required if an appliction uses MHD_USE_INTERNAL_SELECT or MHD_USE_THREAD_PER_CONNECTION and then performs MHD_quiesce_daemon (which eliminates our ability to signal termination via the listen socket). In these modes, MHD_quiesce_daemon will fail if this option was not set. Also, use of this option is automatic (as in, you do not even have to specify it), if MHD_USE_NO_LISTEN_SOCKET is specified. In "external" select mode, this option is always simply ignored.

Using this option also guarantees that MHD will not call shutdown() on the listen socket, which means a parent process can continue to use the socket.

MHD_USE_SUSPEND_RESUME

Enables using MHD_suspend_connection and MHD_resume_connection, as performing these calls requires some additional pipes to be created, and code not using these calls should not pay the cost.

MHD_USE_TCP_FASTOPEN

Enable TCP_FASTOPEN on the listen socket. TCP_FASTOPEN is currently supported on Linux >= 3.6. On other systems using this option with cause MHD_start_daemon to fail.

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 a size_t). The default is 32 kB (32*1024 bytes) as defined by the internal constant MHD_POOL_SIZE_DEFAULT. Values above 128k are unlikely to result in much benefit, as half of the memory will be typically used for IO, and TCP buffers are unlikely to support window sizes above 64k on most systems.

MHD_OPTION_CONNECTION_MEMORY_INCREMENT

Increment to use for growing the read buffer (followed by a size_t). The default is 1024 (bytes). Increasing this value will make MHD use memory for reading more aggressively, which can reduce the number of recvfrom calls but may increase the number of sendto calls. The given value must fit within MHD_OPTION_CONNECTION_MEMORY_LIMIT.

MHD_OPTION_CONNECTION_LIMIT

Maximum number of concurrent connections to accept (followed by an unsigned int). The default is FD_SETSIZE - 4 (the maximum number of file descriptors supported by select minus four for stdin, stdout, 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:

MHD_add_response_header (response,
                         MHD_HTTP_HEADER_CONNECTION,
                         "close");

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). The default is zero (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_NOTIFY_CONNECTION

Register a function that should be called when the TCP connection to a client is opened or closed. Note that MHD_OPTION_NOTIFY_COMPLETED and the con_cls argument to the MHD_AccessHandlerCallback are per HTTP request (and there can be multiple HTTP requests per TCP connection). The registered callback is called twice per TCP connection, with MHD_CONNECTION_NOTIFY_STARTED and MHD_CONNECTION_NOTIFY_CLOSED respectively. An additional argument can be used to store TCP connection specific information, which can be retrieved using MHD_CONNECTION_INFO_SOCKET_CONTEXT during the lifetime of the TCP connection. The respective location is not the same as the HTTP-request-specific con_cls from the MHD_AccessHandlerCallback.

This option should be followed by TWO pointers. First a pointer to a function of type MHD_NotifyConnectionCallback() 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.

MHD_OPTION_SOCK_ADDR

Bind daemon to the supplied socket address. This option should be followed by a struct sockaddr *. If MHD_USE_IPv6 is specified, the struct sockaddr* should point to a struct sockaddr_in6, otherwise to a 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 MHD_start_daemon is ignored and the port from the given struct sockaddr * will be used instead.

MHD_OPTION_URI_LOG_CALLBACK

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

 void * my_logger(void * cls, const char * uri, struct MHD_Connection *con)

where the return value will be passed as *con_cls in calls to the MHD_AccessHandlerCallback when this request is processed later; returning a value of NULL has no special significance; (however, note that if you return non-NULL, you can no longer rely on the first call to the access handler having NULL == *con_cls on entry) cls will be set to the second argument following MHD_OPTION_URI_LOG_CALLBACK. Finally, uri will be the 0-terminated URI of the request.

Note that during the time of this call, most of the connection’s state is not initialized (as we have not yet parsed he headers). However, information about the connecting client (IP, socket) is available.

MHD_OPTION_HTTPS_MEM_KEY

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

MHD_OPTION_HTTPS_KEY_PASSWORD

Memory pointer to the password that decrypts the private key to be used by the HTTPS daemon. This option should be followed by an "const char*" argument. This should be used in conjunction with ’MHD_OPTION_HTTPS_MEM_KEY’.

The password (or passphrase) is only used immediately during MHD_start_daemon(). Thus, the application may want to erase it from memory afterwards for additional security.

MHD_OPTION_HTTPS_MEM_CERT

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

MHD_OPTION_HTTPS_MEM_TRUST

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.

MHD_OPTION_HTTPS_CRED_TYPE

Daemon credentials type. Either certificate or anonymous, this option should be followed by one of the values listed in "enum gnutls_credentials_type_t".

MHD_OPTION_HTTPS_PRIORITIES

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.

MHD_OPTION_HTTPS_CERT_CALLBACK

Use a callback to determine which X.509 certificate should be used for a given HTTPS connection. This option should be followed by a argument of type "gnutls_certificate_retrieve_function2 *". This option provides an alternative to MHD_OPTION_HTTPS_MEM_KEY and MHD_OPTION_HTTPS_MEM_CERT. You must use this version if multiple domains are to be hosted at the same IP address using TLS’s Server Name Indication (SNI) extension. In this case, the callback is expected to select the correct certificate based on the SNI information provided. The callback is expected to access the SNI data using gnutls_server_name_get(). Using this option requires GnuTLS 3.0 or higher.

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

MHD_OPTION_NONCE_NC_SIZE

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.

MHD_OPTION_LISTEN_SOCKET

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.

MHD_OPTION_EXTERNAL_LOGGER

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.

MHD_OPTION_THREAD_POOL_SIZE

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 NULL for an unsupported thread model).

MHD_OPTION_ARRAY

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

An example for code using MHD_OPTION_ARRAY is:

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);

For options that expect a single pointer argument, the second member of the struct MHD_OptionItem is ignored. For options that expect two pointer arguments, the first argument must be cast to intptr_t.

MHD_OPTION_UNESCAPE_CALLBACK

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

  size_t my_unescaper(void * cls, struct MHD_Connection *c, char *s)

where the return value must be strlen(s) and s should be updated. Note that the unescape function must not lengthen s (the result must be shorter than the input and still be 0-terminated). cls will be set to the second argument following MHD_OPTION_UNESCAPE_CALLBACK.

MHD_OPTION_THREAD_STACK_SIZE

Maximum stack size for threads created by MHD. This option must be followed by a 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).

MHD_OPTION_TCP_FASTQUEUE_QUEUE_SIZE

When the flag MHD_USE_TCP_FASTOPEN is used, this option sets the connection handshake queue size for the TCP FASTOPEN connections. Note that a TCP FASTOPEN connection handshake occupies more resources than a TCP handshake as the SYN packets also contain DATA which is kept in the associate state until handshake is completed. If this option is not given the queue size is set to a default value of 10. This option must be followed by a unsigned int.

MHD_OPTION_HTTPS_MEM_DHPARAMS

Memory pointer for the Diffie-Hellman parameters (dh.pem) to be used by the HTTPS daemon for key exchange. This option must be followed by a const char * argument. The argument would be a zero-terminated string with a PEM encoded PKCS3 DH parameters structure suitable for passing to gnutls_dh_parms_import_pkcs3.

MHD_OPTION_LISTENING_ADDRESS_REUSE

This option must be followed by a unsigned int argument. If this option is present and true (nonzero) parameter is given, allow reusing the address:port of the listening socket (using SO_REUSEPORT on most platforms, and SO_REUSEADDR on Windows). If a false (zero) parameter is given, disallow reusing the the address:port of the listening socket (this usually requires no special action, but SO_EXCLUSIVEADDRUSE is needed on Windows). If this option is not present, default behaviour is undefined (currently, SO_REUSEADDR is used on all platforms, which disallows address:port reusing with the exception of Windows).

C Struct: MHD_OptionItem

Entry in an MHD_OPTION_ARRAY. See the MHD_OPTION_ARRAY option argument for its use.

The 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 ptr_value member should be set. For options taking two pointer arguments, the first pointer must be cast to intptr_t and both the value and the ptr_value members should be used to pass the two pointers.

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

Enumeration: MHD_ResponseMemoryMode

The MHD_ResponeMemoryMode specifies how MHD should treat the memory buffer given for the response in MHD_create_response_from_buffer.

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.

MHD_RESPMEM_MUST_FREE

Buffer is heap-allocated with malloc (or equivalent) and should be freed by MHD after processing the response has concluded (response reference counter reaches zero).

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 MHD_create_response_from_buffer. MHD must make its own private copy of the data for processing.

Enumeration: MHD_ResponseFlags

Response-specific flags. Passed as an argument to MHD_set_response_options().

MHD_RF_NONE

No special handling.

MHD_RF_HTTP_VERSION_1_0_ONLY

Only respond in conservative HTTP 1.0-mode. In particular, do not (automatically) sent "Connection" headers and always close the connection after generating the response.

Enumeration: MHD_ResponseOptions

Response-specific options. Passed in the varargs portion of MHD_set_response_options().

MHD_RO_END

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