src/include/microhttpd.h File Reference

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>
Include dependency graph for microhttpd.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  MHD_OptionItem
union  MHD_ConnectionInfo
union  MHD_DaemonInfo

Defines

#define MHD_VERSION   0x00093300
#define MHD_YES   1
#define MHD_NO   0
#define MHD_INVALID_NONCE   -1
#define MHD_SIZE_UNKNOWN   ((uint64_t) -1LL)
#define MHD_CONTENT_READER_END_OF_STREAM   ((size_t) -1LL)
#define MHD_CONTENT_READER_END_WITH_ERROR   (((size_t) -1LL) - 1)
#define MHD_LONG_LONG   long long
#define MHD_UNSIGNED_LONG_LONG   unsigned long long
#define MHD_LONG_LONG_PRINTF   "ll"
#define MHD_UNSIGNED_LONG_LONG_PRINTF   "%llu"
#define MHD_HTTP_CONTINUE   100
#define MHD_HTTP_SWITCHING_PROTOCOLS   101
#define MHD_HTTP_PROCESSING   102
#define MHD_HTTP_OK   200
#define MHD_HTTP_CREATED   201
#define MHD_HTTP_ACCEPTED   202
#define MHD_HTTP_NON_AUTHORITATIVE_INFORMATION   203
#define MHD_HTTP_NO_CONTENT   204
#define MHD_HTTP_RESET_CONTENT   205
#define MHD_HTTP_PARTIAL_CONTENT   206
#define MHD_HTTP_MULTI_STATUS   207
#define MHD_HTTP_MULTIPLE_CHOICES   300
#define MHD_HTTP_MOVED_PERMANENTLY   301
#define MHD_HTTP_FOUND   302
#define MHD_HTTP_SEE_OTHER   303
#define MHD_HTTP_NOT_MODIFIED   304
#define MHD_HTTP_USE_PROXY   305
#define MHD_HTTP_SWITCH_PROXY   306
#define MHD_HTTP_TEMPORARY_REDIRECT   307
#define MHD_HTTP_BAD_REQUEST   400
#define MHD_HTTP_UNAUTHORIZED   401
#define MHD_HTTP_PAYMENT_REQUIRED   402
#define MHD_HTTP_FORBIDDEN   403
#define MHD_HTTP_NOT_FOUND   404
#define MHD_HTTP_METHOD_NOT_ALLOWED   405
#define MHD_HTTP_METHOD_NOT_ACCEPTABLE   406
#define MHD_HTTP_PROXY_AUTHENTICATION_REQUIRED   407
#define MHD_HTTP_REQUEST_TIMEOUT   408
#define MHD_HTTP_CONFLICT   409
#define MHD_HTTP_GONE   410
#define MHD_HTTP_LENGTH_REQUIRED   411
#define MHD_HTTP_PRECONDITION_FAILED   412
#define MHD_HTTP_REQUEST_ENTITY_TOO_LARGE   413
#define MHD_HTTP_REQUEST_URI_TOO_LONG   414
#define MHD_HTTP_UNSUPPORTED_MEDIA_TYPE   415
#define MHD_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE   416
#define MHD_HTTP_EXPECTATION_FAILED   417
#define MHD_HTTP_UNPROCESSABLE_ENTITY   422
#define MHD_HTTP_LOCKED   423
#define MHD_HTTP_FAILED_DEPENDENCY   424
#define MHD_HTTP_UNORDERED_COLLECTION   425
#define MHD_HTTP_UPGRADE_REQUIRED   426
#define MHD_HTTP_NO_RESPONSE   444
#define MHD_HTTP_RETRY_WITH   449
#define MHD_HTTP_BLOCKED_BY_WINDOWS_PARENTAL_CONTROLS   450
#define MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS   451
#define MHD_HTTP_INTERNAL_SERVER_ERROR   500
#define MHD_HTTP_NOT_IMPLEMENTED   501
#define MHD_HTTP_BAD_GATEWAY   502
#define MHD_HTTP_SERVICE_UNAVAILABLE   503
#define MHD_HTTP_GATEWAY_TIMEOUT   504
#define MHD_HTTP_HTTP_VERSION_NOT_SUPPORTED   505
#define MHD_HTTP_VARIANT_ALSO_NEGOTIATES   506
#define MHD_HTTP_INSUFFICIENT_STORAGE   507
#define MHD_HTTP_BANDWIDTH_LIMIT_EXCEEDED   509
#define MHD_HTTP_NOT_EXTENDED   510
#define MHD_ICY_FLAG   ((uint32_t)(1 << 31))
#define MHD_HTTP_HEADER_ACCEPT   "Accept"
#define MHD_HTTP_HEADER_ACCEPT_CHARSET   "Accept-Charset"
#define MHD_HTTP_HEADER_ACCEPT_ENCODING   "Accept-Encoding"
#define MHD_HTTP_HEADER_ACCEPT_LANGUAGE   "Accept-Language"
#define MHD_HTTP_HEADER_ACCEPT_RANGES   "Accept-Ranges"
#define MHD_HTTP_HEADER_AGE   "Age"
#define MHD_HTTP_HEADER_ALLOW   "Allow"
#define MHD_HTTP_HEADER_AUTHORIZATION   "Authorization"
#define MHD_HTTP_HEADER_CACHE_CONTROL   "Cache-Control"
#define MHD_HTTP_HEADER_CONNECTION   "Connection"
#define MHD_HTTP_HEADER_CONTENT_ENCODING   "Content-Encoding"
#define MHD_HTTP_HEADER_CONTENT_LANGUAGE   "Content-Language"
#define MHD_HTTP_HEADER_CONTENT_LENGTH   "Content-Length"
#define MHD_HTTP_HEADER_CONTENT_LOCATION   "Content-Location"
#define MHD_HTTP_HEADER_CONTENT_MD5   "Content-MD5"
#define MHD_HTTP_HEADER_CONTENT_RANGE   "Content-Range"
#define MHD_HTTP_HEADER_CONTENT_TYPE   "Content-Type"
#define MHD_HTTP_HEADER_COOKIE   "Cookie"
#define MHD_HTTP_HEADER_DATE   "Date"
#define MHD_HTTP_HEADER_ETAG   "ETag"
#define MHD_HTTP_HEADER_EXPECT   "Expect"
#define MHD_HTTP_HEADER_EXPIRES   "Expires"
#define MHD_HTTP_HEADER_FROM   "From"
#define MHD_HTTP_HEADER_HOST   "Host"
#define MHD_HTTP_HEADER_IF_MATCH   "If-Match"
#define MHD_HTTP_HEADER_IF_MODIFIED_SINCE   "If-Modified-Since"
#define MHD_HTTP_HEADER_IF_NONE_MATCH   "If-None-Match"
#define MHD_HTTP_HEADER_IF_RANGE   "If-Range"
#define MHD_HTTP_HEADER_IF_UNMODIFIED_SINCE   "If-Unmodified-Since"
#define MHD_HTTP_HEADER_LAST_MODIFIED   "Last-Modified"
#define MHD_HTTP_HEADER_LOCATION   "Location"
#define MHD_HTTP_HEADER_MAX_FORWARDS   "Max-Forwards"
#define MHD_HTTP_HEADER_PRAGMA   "Pragma"
#define MHD_HTTP_HEADER_PROXY_AUTHENTICATE   "Proxy-Authenticate"
#define MHD_HTTP_HEADER_PROXY_AUTHORIZATION   "Proxy-Authorization"
#define MHD_HTTP_HEADER_RANGE   "Range"
#define MHD_HTTP_HEADER_REFERER   "Referer"
#define MHD_HTTP_HEADER_RETRY_AFTER   "Retry-After"
#define MHD_HTTP_HEADER_SERVER   "Server"
#define MHD_HTTP_HEADER_SET_COOKIE   "Set-Cookie"
#define MHD_HTTP_HEADER_SET_COOKIE2   "Set-Cookie2"
#define MHD_HTTP_HEADER_TE   "TE"
#define MHD_HTTP_HEADER_TRAILER   "Trailer"
#define MHD_HTTP_HEADER_TRANSFER_ENCODING   "Transfer-Encoding"
#define MHD_HTTP_HEADER_UPGRADE   "Upgrade"
#define MHD_HTTP_HEADER_USER_AGENT   "User-Agent"
#define MHD_HTTP_HEADER_VARY   "Vary"
#define MHD_HTTP_HEADER_VIA   "Via"
#define MHD_HTTP_HEADER_WARNING   "Warning"
#define MHD_HTTP_HEADER_WWW_AUTHENTICATE   "WWW-Authenticate"
#define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN   "Access-Control-Allow-Origin"
#define MHD_HTTP_VERSION_1_0   "HTTP/1.0"
#define MHD_HTTP_VERSION_1_1   "HTTP/1.1"
#define MHD_HTTP_METHOD_CONNECT   "CONNECT"
#define MHD_HTTP_METHOD_DELETE   "DELETE"
#define MHD_HTTP_METHOD_GET   "GET"
#define MHD_HTTP_METHOD_HEAD   "HEAD"
#define MHD_HTTP_METHOD_OPTIONS   "OPTIONS"
#define MHD_HTTP_METHOD_POST   "POST"
#define MHD_HTTP_METHOD_PUT   "PUT"
#define MHD_HTTP_METHOD_TRACE   "TRACE"
#define MHD_HTTP_POST_ENCODING_FORM_URLENCODED   "application/x-www-form-urlencoded"
#define MHD_HTTP_POST_ENCODING_MULTIPART_FORMDATA   "multipart/form-data"
#define MHD_INVALID_NONCE   -1

Typedefs

typedef void(* MHD_LogCallback )(void *cls, const char *fm, va_list ap)
typedef void(* MHD_PanicCallback )(void *cls, const char *file, unsigned int line, const char *reason)
typedef int(* MHD_AcceptPolicyCallback )(void *cls, const struct sockaddr *addr, socklen_t addrlen)
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)
typedef void(* MHD_RequestCompletedCallback )(void *cls, struct MHD_Connection *connection, void **con_cls, enum MHD_RequestTerminationCode toe)
typedef int(* MHD_KeyValueIterator )(void *cls, enum MHD_ValueKind kind, const char *key, const char *value)
typedef ssize_t(* MHD_ContentReaderCallback )(void *cls, uint64_t pos, char *buf, size_t max)
typedef void(* MHD_ContentReaderFreeCallback )(void *cls)
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)

Enumerations

enum  MHD_FLAG {
  MHD_NO_FLAG = 0, MHD_USE_DEBUG = 1, MHD_USE_SSL = 2, MHD_USE_THREAD_PER_CONNECTION = 4,
  MHD_USE_SELECT_INTERNALLY = 8, MHD_USE_IPv6 = 16, MHD_USE_PEDANTIC_CHECKS = 32, MHD_USE_POLL = 64,
  MHD_USE_POLL_INTERNALLY = MHD_USE_SELECT_INTERNALLY | MHD_USE_POLL, MHD_SUPPRESS_DATE_NO_CLOCK = 128, MHD_USE_NO_LISTEN_SOCKET = 256, MHD_USE_EPOLL_LINUX_ONLY = 512,
  MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY = MHD_USE_SELECT_INTERNALLY | MHD_USE_EPOLL_LINUX_ONLY, MHD_USE_PIPE_FOR_SHUTDOWN = 1024, MHD_USE_DUAL_STACK = MHD_USE_IPv6 | 2048, MHD_USE_EPOLL_TURBO = 4096,
  MHD_USE_SUSPEND_RESUME = 8192 | MHD_USE_PIPE_FOR_SHUTDOWN
}
 

Flags for the `struct MHD_Daemon`.

More...
enum  MHD_OPTION {
  MHD_OPTION_END = 0, MHD_OPTION_CONNECTION_MEMORY_LIMIT = 1, MHD_OPTION_CONNECTION_LIMIT = 2, MHD_OPTION_CONNECTION_TIMEOUT = 3,
  MHD_OPTION_NOTIFY_COMPLETED = 4, MHD_OPTION_PER_IP_CONNECTION_LIMIT = 5, MHD_OPTION_SOCK_ADDR = 6, MHD_OPTION_URI_LOG_CALLBACK = 7,
  MHD_OPTION_HTTPS_MEM_KEY = 8, MHD_OPTION_HTTPS_MEM_CERT = 9, MHD_OPTION_HTTPS_CRED_TYPE = 10, MHD_OPTION_HTTPS_PRIORITIES = 11,
  MHD_OPTION_LISTEN_SOCKET = 12, MHD_OPTION_EXTERNAL_LOGGER = 13, MHD_OPTION_THREAD_POOL_SIZE = 14, MHD_OPTION_ARRAY = 15,
  MHD_OPTION_UNESCAPE_CALLBACK = 16, MHD_OPTION_DIGEST_AUTH_RANDOM = 17, MHD_OPTION_NONCE_NC_SIZE = 18, MHD_OPTION_THREAD_STACK_SIZE = 19,
  MHD_OPTION_HTTPS_MEM_TRUST = 20, MHD_OPTION_CONNECTION_MEMORY_INCREMENT = 21, MHD_OPTION_HTTPS_CERT_CALLBACK = 22
}
 

MHD options.

More...
enum  MHD_ValueKind {
  MHD_RESPONSE_HEADER_KIND = 0, MHD_HEADER_KIND = 1, MHD_COOKIE_KIND = 2, MHD_POSTDATA_KIND = 4,
  MHD_GET_ARGUMENT_KIND = 8, MHD_FOOTER_KIND = 16
}
enum  MHD_RequestTerminationCode {
  MHD_REQUEST_TERMINATED_COMPLETED_OK = 0, MHD_REQUEST_TERMINATED_WITH_ERROR = 1, MHD_REQUEST_TERMINATED_TIMEOUT_REACHED = 2, MHD_REQUEST_TERMINATED_DAEMON_SHUTDOWN = 3,
  MHD_REQUEST_TERMINATED_READ_ERROR = 4, MHD_REQUEST_TERMINATED_CLIENT_ABORT = 5
}
enum  MHD_ConnectionInfoType {
  MHD_CONNECTION_INFO_CIPHER_ALGO, MHD_CONNECTION_INFO_PROTOCOL, MHD_CONNECTION_INFO_CLIENT_ADDRESS, MHD_CONNECTION_INFO_GNUTLS_SESSION,
  MHD_CONNECTION_INFO_GNUTLS_CLIENT_CERT, MHD_CONNECTION_INFO_DAEMON, MHD_CONNECTION_INFO_CONNECTION_FD
}
enum  MHD_DaemonInfoType { MHD_DAEMON_INFO_KEY_SIZE, MHD_DAEMON_INFO_MAC_KEY_SIZE, MHD_DAEMON_INFO_LISTEN_FD, MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY }
enum  MHD_ResponseMemoryMode { MHD_RESPMEM_PERSISTENT, MHD_RESPMEM_MUST_FREE, MHD_RESPMEM_MUST_COPY }
enum  MHD_CONNECTION_OPTION { MHD_CONNECTION_OPTION_TIMEOUT }

Functions

struct MHD_DaemonMHD_start_daemon_va (unsigned int flags, uint16_t port, MHD_AcceptPolicyCallback apc, void *apc_cls, MHD_AccessHandlerCallback dh, void *dh_cls, va_list ap)
struct MHD_DaemonMHD_start_daemon (unsigned int flags, uint16_t port, MHD_AcceptPolicyCallback apc, void *apc_cls, MHD_AccessHandlerCallback dh, void *dh_cls,...)
int MHD_quiesce_daemon (struct MHD_Daemon *daemon)
void MHD_stop_daemon (struct MHD_Daemon *daemon)
int MHD_add_connection (struct MHD_Daemon *daemon, int client_socket, const struct sockaddr *addr, socklen_t addrlen)
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)
int MHD_get_timeout (struct MHD_Daemon *daemon, MHD_UNSIGNED_LONG_LONG *timeout)
int MHD_run (struct MHD_Daemon *daemon)
int MHD_run_from_select (struct MHD_Daemon *daemon, const fd_set *read_fd_set, const fd_set *write_fd_set, const fd_set *except_fd_set)
int MHD_get_connection_values (struct MHD_Connection *connection, enum MHD_ValueKind kind, MHD_KeyValueIterator iterator, void *iterator_cls)
int MHD_set_connection_value (struct MHD_Connection *connection, enum MHD_ValueKind kind, const char *key, const char *value)
void MHD_set_panic_func (MHD_PanicCallback cb, void *cls)
const char * MHD_lookup_connection_value (struct MHD_Connection *connection, enum MHD_ValueKind kind, const char *key)
int MHD_queue_response (struct MHD_Connection *connection, unsigned int status_code, struct MHD_Response *response)
void MHD_suspend_connection (struct MHD_Connection *connection)
void MHD_resume_connection (struct MHD_Connection *connection)
struct MHD_ResponseMHD_create_response_from_callback (uint64_t size, size_t block_size, MHD_ContentReaderCallback crc, void *crc_cls, MHD_ContentReaderFreeCallback crfc)
struct MHD_ResponseMHD_create_response_from_data (size_t size, void *data, int must_free, int must_copy)
struct MHD_ResponseMHD_create_response_from_buffer (size_t size, void *buffer, enum MHD_ResponseMemoryMode mode)
struct MHD_ResponseMHD_create_response_from_fd (size_t size, int fd)
struct MHD_ResponseMHD_create_response_from_fd_at_offset (size_t size, int fd, off_t offset)
void MHD_destroy_response (struct MHD_Response *response)
int MHD_add_response_header (struct MHD_Response *response, const char *header, const char *content)
int MHD_add_response_footer (struct MHD_Response *response, const char *footer, const char *content)
int MHD_del_response_header (struct MHD_Response *response, const char *header, const char *content)
int MHD_get_response_headers (struct MHD_Response *response, MHD_KeyValueIterator iterator, void *iterator_cls)
const char * MHD_get_response_header (struct MHD_Response *response, const char *key)
struct MHD_PostProcessor * MHD_create_post_processor (struct MHD_Connection *connection, size_t buffer_size, MHD_PostDataIterator iter, void *iter_cls)
int MHD_post_process (struct MHD_PostProcessor *pp, const char *post_data, size_t post_data_len)
int MHD_destroy_post_processor (struct MHD_PostProcessor *pp)
char * MHD_digest_auth_get_username (struct MHD_Connection *connection)
int MHD_digest_auth_check (struct MHD_Connection *connection, const char *realm, const char *username, const char *password, unsigned int nonce_timeout)
int MHD_queue_auth_fail_response (struct MHD_Connection *connection, const char *realm, const char *opaque, struct MHD_Response *response, int signal_stale)
char * MHD_basic_auth_get_username_password (struct MHD_Connection *connection, char **password)
int MHD_queue_basic_auth_fail_response (struct MHD_Connection *connection, const char *realm, struct MHD_Response *response)
union MHD_ConnectionInfoMHD_get_connection_info (struct MHD_Connection *connection, enum MHD_ConnectionInfoType info_type,...)
int MHD_set_connection_option (struct MHD_Connection *connection, enum MHD_CONNECTION_OPTION option,...)
union MHD_DaemonInfoMHD_get_daemon_info (struct MHD_Daemon *daemon, enum MHD_DaemonInfoType info_type,...)
const char * MHD_get_version (void)

Detailed Description

public interface to libmicrohttpd

Author:
Christian Grothoff
Chris GauthierDickey

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 Documentation

#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
#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 Documentation

typedef int(* MHD_AcceptPolicyCallback)(void *cls, const struct sockaddr *addr, socklen_t addrlen)

Allow or deny a client to connect.

Parameters:
addr address information from the client
addrlen length of addr
Returns:
MHD_YES if connection is allowed, MHD_NO if not

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

Parameters:
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.
Returns:
MHD_YES if the connection was handled successfully, MHD_NO if the socket must be closed due to a serios error while handling the request

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.

Parameters:
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)
Returns:
number of bytes written to buf; 0 is legal unless we are running in internal select mode (since this would cause busy-waiting); 0 in external select mode will cause this function to be called again once the external select calls MHD again; MHD_CONTENT_READER_END_OF_STREAM (-1) for the regular end of transmission (with chunked encoding, MHD will then terminate the chunk and send any HTTP footers that might be present; without chunked encoding and given an unknown response size, MHD will simply close the connection; note that while returning MHD_CONTENT_READER_END_OF_STREAM is not technically legal if a response size was specified, MHD accepts this and treats it just as MHD_CONTENT_READER_END_WITH_ERROR; MHD_CONTENT_READER_END_WITH_ERROR (-2) to indicate a server error generating the response; this will cause MHD to simply close the connection immediately. If a response size was given or if chunked encoding is in use, this will indicate an error to the client. Note, however, that if the client does not know a response size and chunked encoding is not in use, then clients will not be able to tell the difference between MHD_CONTENT_READER_END_WITH_ERROR and MHD_CONTENT_READER_END_OF_STREAM. This is not a limitation of MHD but rather of the HTTP protocol.

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.

Parameters:
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
Returns:
MHD_YES to continue iterating, MHD_NO to abort the iteration

Definition at line 1261 of file microhttpd.h.


Enumeration Type Documentation

MHD connection options. Given to MHD_set_connection_option to set custom options for a particular connection.

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

Values of this enum are used to specify what information about a deamon is desired.

Enumerator:
MHD_DAEMON_INFO_KEY_SIZE 

No longer supported (will return NULL).

MHD_DAEMON_INFO_MAC_KEY_SIZE 

No longer supported (will return NULL).

MHD_DAEMON_INFO_LISTEN_FD 

Request the file descriptor for the listening socket. No extra arguments should be passed.

MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY 

Request the file descriptor for the external epoll. No extra arguments should be passed.

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

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

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

The `enum MHD_ValueKind` specifies the source of the key-value pairs in the HTTP protocol.

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


Function Documentation

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.

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

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


Generated on 14 Oct 2014 for GNU libmicrohttpd by  doxygen 1.6.1