public interface to libmicrohttpd More...
#include <unistd.h>
#include <stdarg.h>
#include <stdint.h>
#include <sys/time.h>
#include <sys/types.h>
#include <sys/socket.h>
Go to the source code of this file.
public interface to libmicrohttpd
All symbols defined in this header 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 "mulitpart/formdata"). Unsupported encodings and large POST submissions may require the application to manually process the stream, which is provided to the main application (and thus can 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 (with the exception of MHD_set_connection_value, which must only be used in a particular context).
NEW: Before including "microhttpd.h" you should add the necessary includes to define the `uint64_t`, `size_t`, `fd_set`, `socklen_t` and `struct sockaddr` data types (which headers are needed may depend on your platform; for possible suggestions consult "platform.h" in the MHD distribution). If you have done so, you should also have a line with "#define MHD_PLATFORM_H" which will prevent this header from trying (and, depending on your platform, failing) to include the right headers.
Definition in file microhttpd.h.
#define MHD_CONTENT_READER_END_OF_STREAM ((size_t) -1LL) |
Definition at line 155 of file microhttpd.h.
Referenced by file_reader(), try_ready_chunked_body(), and try_ready_normal_body().
#define MHD_CONTENT_READER_END_WITH_ERROR (((size_t) -1LL) - 1) |
Definition at line 156 of file microhttpd.h.
Referenced by file_reader(), try_ready_chunked_body(), and try_ready_normal_body().
#define MHD_LONG_LONG long long |
Not all architectures and `printf()`'s support the `long long` type. This gives the ability to replace `long long` with just a `long`, standard `int` or a `short`.
Definition at line 168 of file microhttpd.h.
#define MHD_LONG_LONG_PRINTF "ll" |
Format string for printing a variable of type MHD_LONG_LONG. You should only redefine this if you also define MHD_LONG_LONG.
Definition at line 179 of file microhttpd.h.
#define MHD_NO 0 |
MHD-internal return code for "NO".
Definition at line 134 of file microhttpd.h.
Referenced by add_extra_headers(), add_response_entry(), build_header_response(), call_connection_handler(), check_argument_match(), check_nonce_nc(), check_write_done(), cleanup_connection(), connection_add_header(), do_read(), do_write(), find_boundary(), get_next_header_line(), internal_add_connection(), MHD_accept_connection(), MHD_cleanup_connections(), MHD_connection_close(), MHD_connection_handle_idle(), MHD_connection_handle_read(), MHD_connection_update_event_loop_info(), MHD_del_response_header(), MHD_destroy_post_processor(), MHD_digest_auth_check(), MHD_get_fdset(), MHD_get_timeout(), MHD_handle_connection(), MHD_ip_addr_to_key(), MHD_ip_limit_add(), MHD_ip_limit_del(), MHD_poll(), MHD_pool_create(), MHD_pool_destroy(), MHD_post_process(), MHD_queue_auth_fail_response(), MHD_queue_response(), MHD_quiesce_daemon(), MHD_run(), MHD_run_from_select(), MHD_select(), MHD_set_connection_option(), MHD_set_connection_value(), parse_arguments(), parse_cookie_header(), parse_initial_message_line(), parse_options_va(), post_process_multipart(), post_process_urlencoded(), process_broken_line(), process_header_line(), process_multipart_headers(), process_request_body(), process_value_to_boundary(), resume_suspended_connections(), run_tls_handshake(), test_header(), transmit_error_response(), try_grow_read_buffer(), try_match_header(), try_ready_chunked_body(), and try_ready_normal_body().
#define MHD_SIZE_UNKNOWN ((uint64_t) -1LL) |
Constant used to indicate unknown size (use when creating a response).
Definition at line 148 of file microhttpd.h.
Referenced by add_extra_headers(), MHD_connection_handle_idle(), parse_connection_headers(), and process_request_body().
#define MHD_UNSIGNED_LONG_LONG unsigned long long |
Definition at line 169 of file microhttpd.h.
Referenced by add_extra_headers(), MHD_select(), and parse_connection_headers().
#define MHD_UNSIGNED_LONG_LONG_PRINTF "%llu" |
Definition at line 180 of file microhttpd.h.
Referenced by add_extra_headers().
#define MHD_VERSION 0x00093300 |
Current version of the library. 0x01093001 = 1.9.30-1.
Definition at line 124 of file microhttpd.h.
#define MHD_YES 1 |
MHD-internal return code for "YES".
Definition at line 129 of file microhttpd.h.
Referenced by add_extra_headers(), add_response_entry(), build_header_response(), call_connection_handler(), check_argument_match(), check_nonce_nc(), check_write_done(), cleanup_connection(), close_all_connections(), connection_add_header(), do_read(), do_write(), find_boundary(), internal_add_connection(), MHD_accept_connection(), MHD_add_connection(), MHD_connection_close(), MHD_connection_handle_idle(), MHD_connection_handle_read(), MHD_connection_handle_write(), MHD_connection_update_event_loop_info(), MHD_create_response_from_data(), MHD_del_response_header(), MHD_destroy_post_processor(), MHD_digest_auth_check(), MHD_get_connection_values(), MHD_get_fdset(), MHD_get_response_headers(), MHD_get_timeout(), MHD_handle_connection(), MHD_ip_addr_to_key(), MHD_ip_limit_add(), MHD_poll(), MHD_pool_allocate(), MHD_pool_create(), MHD_post_process(), MHD_queue_auth_fail_response(), MHD_queue_basic_auth_fail_response(), MHD_queue_response(), MHD_quiesce_daemon(), MHD_resume_connection(), MHD_run(), MHD_run_from_select(), MHD_select(), MHD_select_thread(), MHD_set_connection_option(), MHD_set_connection_value(), MHD_start_daemon_va(), MHD_stop_daemon(), MHD_suspend_connection(), MHD_tls_connection_handle_idle(), MHD_tls_connection_handle_read(), MHD_tls_connection_handle_write(), parse_arguments(), parse_connection_headers(), parse_cookie_header(), parse_initial_message_line(), parse_options_va(), post_process_multipart(), post_process_urlencoded(), process_broken_line(), process_header_line(), process_multipart_headers(), process_request_body(), process_value_to_boundary(), resume_suspended_connections(), run_tls_handshake(), test_header(), transmit_error_response(), try_grow_read_buffer(), try_match_header(), try_ready_chunked_body(), and try_ready_normal_body().
typedef int(* MHD_AcceptPolicyCallback)(void *cls, const struct sockaddr *addr, socklen_t addrlen) |
Allow or deny a client to connect.
addr | address information from the client | |
addrlen | length of addr |
Definition at line 1086 of file microhttpd.h.
typedef 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) |
A client has requested the given url using the given method (MHD_HTTP_METHOD_GET, MHD_HTTP_METHOD_PUT, MHD_HTTP_METHOD_DELETE, MHD_HTTP_METHOD_POST, etc). The callback must call MHD callbacks to provide content to give back to the client and return an HTTP status code (i.e. MHD_HTTP_OK, MHD_HTTP_NOT_FOUND, etc.).
cls | argument given together with the function pointer when the handler was registered with MHD | |
url | the requested url | |
method | the HTTP method used (MHD_HTTP_METHOD_GET, MHD_HTTP_METHOD_PUT, etc.) | |
version | the HTTP version string (i.e. MHD_HTTP_VERSION_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; the method must update this value to the number of bytes NOT processed; | |
con_cls | pointer that the 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). Initially, `*con_cls` will be NULL. |
Definition at line 1131 of file microhttpd.h.
typedef ssize_t(* MHD_ContentReaderCallback)(void *cls, uint64_t pos, char *buf, size_t max) |
Callback used by libmicrohttpd in order to obtain content. The callback is 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 libmicrohttpd to try again. Thus, returning zero should only be used in conjunction with MHD_suspend_connection() to avoid busy waiting.
cls | extra argument to the callback | |
pos | position in the datastream to access; note that if a `struct 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 a `struct MHD_Response` is not re-used, libmicrohttpd guarantees that "pos" will be the sum of all non-negative return values obtained from the content reader so far. | |
buf | where to copy the data | |
max | maximum number of bytes to copy to buf (size of buf) |
Definition at line 1222 of file microhttpd.h.
typedef 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 POST data.
cls | user-specified closure | |
kind | type of the value, always MHD_POSTDATA_KIND when called from MHD | |
key | 0-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 |
Definition at line 1261 of file microhttpd.h.
MHD connection options. Given to MHD_set_connection_option to set custom options for a particular connection.
MHD_CONNECTION_OPTION_TIMEOUT |
Set a custom timeout for the given connection. Specified as the number of seconds, given as an `unsigned int`. Use zero for no timeout. |
Definition at line 2172 of file microhttpd.h.
enum MHD_DaemonInfoType |
Values of this enum are used to specify what information about a deamon is desired.
Definition at line 1036 of file microhttpd.h.
enum MHD_FLAG |
Flags for the `struct 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).
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`. |
MHD_USE_SSL |
Run in HTTPS mode. |
MHD_USE_THREAD_PER_CONNECTION |
Run using one thread per connection. |
MHD_USE_SELECT_INTERNALLY |
Run using an internal thread (or thread pool) doing `select()`. |
MHD_USE_IPv6 |
Run using the IPv6 protocol (otherwise, MHD will just support IPv4). 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_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 `fd >= FD_SETSIZE`. This option is not compatible with using an 'external' `select()` mode (as there is no API to get the file descriptors for the external select from MHD) and must also not be used in combination with MHD_USE_EPOLL_LINUX_ONLY. |
MHD_USE_POLL_INTERNALLY |
Run using an internal thread (or thread pool) doing `poll()`. |
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 without a listen socket. This option only makes sense if MHD_add_connection is 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_EPOLL_LINUX_ONLY |
Use `epoll()` instead of `select()` or `poll()` for the event loop. This option is only available on Linux; using the option on non-Linux systems will cause MHD_start_daemon to fail. |
MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY |
Run using an internal thread (or thread pool) doing `epoll()`. This option is only available on Linux; using the option on non-Linux systems will cause MHD_start_daemon to fail. |
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_SELECT_INTERNALLY 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. On W32 a pair of sockets is used instead of a pipe. You must also use this option if you use internal select mode or a thread pool in conjunction with MHD_add_connection. |
MHD_USE_DUAL_STACK |
Use a single socket for IPv4 and IPv6. |
MHD_USE_EPOLL_TURBO |
Enable `epoll()` turbo. Disables certain calls to `shutdown()` and enables aggressive non-blocking optimisitc reads. Most effects only happen with MHD_USE_EPOLL_LINUX_ONLY. Enalbed always on W32 as winsock does not properly behave with `shutdown()` and this then fixes potential problems. |
MHD_USE_SUSPEND_RESUME |
Enable suspend/resume functions, which also implies setting up pipes to signal resume. |
Definition at line 399 of file microhttpd.h.
enum 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`). Default is 32 kb (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_LIMIT |
Maximum number of concurrent 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. |
MHD_OPTION_SOCK_ADDR |
Bind daemon to the supplied `struct sockaddr`. 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`. |
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 for the private key (key.pem) to be used by the HTTPS daemon. This option should be followed by a `const char *` argument. This should be used in conjunction with MHD_OPTION_HTTPS_MEM_CERT. |
MHD_OPTION_HTTPS_MEM_CERT |
Memory pointer for the certificate (cert.pem) to be used by the HTTPS daemon. This option should be followed by a `const char *` argument. This should be used in conjunction with MHD_OPTION_HTTPS_MEM_KEY. |
MHD_OPTION_HTTPS_CRED_TYPE |
Daemon credentials type. Followed by an argument of type `gnutls_credentials_type_t`. |
MHD_OPTION_HTTPS_PRIORITIES |
Memory pointer to a `const char *` specifying the cipher algorithm (default: "NORMAL"). |
MHD_OPTION_LISTEN_SOCKET |
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 MHD_LogCallback and the second a pointer `void *` which will be passed as the first argument to the log callback. Note that MHD will not generate any log messages if it was compiled without the "--enable-messages" flag being set. |
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 |
Additional options given in an array of `struct MHD_OptionItem`. The array must be terminated with an entry `{MHD_OPTION_END, 0, NULL}`. 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 `struct 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_DIGEST_AUTH_RANDOM |
Memory pointer for the random values to be used by the Digest Auth module. 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 deamon is running. |
MHD_OPTION_NONCE_NC_SIZE |
Size of the internal array holding the map of the nonce and the nonce counter. This option should be followed by an `unsigend int` argument. |
MHD_OPTION_THREAD_STACK_SIZE |
Desired size of the stack for threads created by MHD. Followed by an argument of type `size_t`. Use 0 for system default. |
MHD_OPTION_HTTPS_MEM_TRUST |
Memory pointer for the certificate (ca.pem) to be used by the HTTPS daemon for client authentification. This option should be followed by a `const char *` argument. |
MHD_OPTION_CONNECTION_MEMORY_INCREMENT |
Increment to use for growing the read buffer (followed by a `size_t`). Must fit within MHD_OPTION_CONNECTION_MEMORY_LIMIT. |
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, 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. |
Definition at line 548 of file microhttpd.h.
enum MHD_ValueKind |
The `enum 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). |
Definition at line 829 of file microhttpd.h.
void MHD_resume_connection | ( | struct MHD_Connection * | connection | ) |
Resume handling of network data for suspended connection. It is safe to resume a suspended connection at any time. Calling this function on a connection that was not previously suspended will result in undefined behavior.
connection | the connection to resume |
Definition at line 1464 of file daemon.c.
References MHD_Daemon::cleanup_connection_mutex, MHD_Connection::daemon, MHD_PANIC, MHD_USE_SUSPEND_RESUME, MHD_USE_THREAD_PER_CONNECTION, MHD_YES, MHD_Daemon::options, MHD_Daemon::resuming, MHD_Connection::resuming, and MHD_Daemon::wpipe.
void MHD_suspend_connection | ( | struct MHD_Connection * | connection | ) |
Suspend handling of network data for a given connection. This can be used to dequeue a connection from MHD's event loop (external select, internal select or thread pool; not applicable to thread-per-connection!) for a while.
If you use this API in conjunction with a internal select or a thread pool, you must set the option MHD_USE_PIPE_FOR_SHUTDOWN to ensure that a resumed connection is immediately processed by MHD.
Suspended connections continue to count against the total number of connections allowed (per daemon, as well as per IP, if such limits are set). Suspended connections will NOT time out; timeouts will restart when the connection handling is resumed. While a connection is suspended, MHD will not detect disconnects by the client.
The only safe time to suspend a connection is from the MHD_AccessHandlerCallback.
Finally, it is an API violation to call MHD_stop_daemon while having suspended connections (this will at least create memory and socket leaks or lead to undefined behavior). You must explicitly resume all connections before stopping the daemon.
connection | the connection to suspend |
Definition at line 1403 of file daemon.c.
References MHD_Daemon::cleanup_connection_mutex, MHD_Daemon::connection_timeout, MHD_Connection::connection_timeout, MHD_Daemon::connections_head, MHD_Daemon::connections_tail, MHD_Connection::daemon, DLL_insert, DLL_remove, EDLL_remove, MHD_Daemon::manual_timeout_head, MHD_Daemon::manual_timeout_tail, MHD_EPOLL_STATE_IN_EPOLL_SET, MHD_EPOLL_STATE_IN_EREADY_EDLL, MHD_EPOLL_STATE_SUSPENDED, MHD_PANIC, MHD_USE_EPOLL_LINUX_ONLY, MHD_USE_SUSPEND_RESUME, MHD_USE_THREAD_PER_CONNECTION, MHD_YES, MHD_Daemon::normal_timeout_head, MHD_Daemon::normal_timeout_tail, NULL, MHD_Daemon::options, MHD_Connection::socket_fd, MHD_Connection::suspended, MHD_Daemon::suspended_connections_head, MHD_Daemon::suspended_connections_tail, and XDLL_remove.