Next: , Previous: microhttpd-intro, Up: Top


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.
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 only works in conjunction with MHD_USE_THREAD_PER_CONNECTION (at this point). If you specify MHD_USE_POLL and the local platform does not support it, MHD_start_daemon will return NULL.
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.

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

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.

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

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