handling of requests

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

Enumerations
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 }

Functions
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)
const char *	MHD_lookup_connection_value (struct MHD_Connection *connection, enum MHD_ValueKind kind, 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)

Detailed Description

MHD API used to access information about requests.

Typedef Documentation

typedef int(* MHD_KeyValueIterator)(void *cls, enum MHD_ValueKind kind, const char *key, const char *value)

Iterator over key-value pairs. This iterator can be used to iterate over all of the cookies, headers, or POST-data fields of a request, and also to iterate over the headers that have been added to a response.

Returns

MHD_YES to continue iterating, MHD_NO to abort the iteration

Definition at line 1172 of file microhttpd.h.

typedef void(* MHD_RequestCompletedCallback)(void *cls, struct MHD_Connection *connection, void **con_cls, enum MHD_RequestTerminationCode toe)

Signature of the callback used by MHD to notify the application about completed requests.

Parameters

cls	client-defined closure
connection	connection handle
con_cls	value as set by the last call to the MHD_AccessHandlerCallback
toe	reason for request termination

See Also

MHD_OPTION_NOTIFY_COMPLETED

Definition at line 1154 of file microhttpd.h.

Enumeration Type Documentation

enum MHD_ConnectionInfoType

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

Enumerator
MHD_CONNECTION_INFO_CIPHER_ALGO	What cipher algorithm is being used. Takes no extra arguments.
MHD_CONNECTION_INFO_PROTOCOL	Takes no extra arguments.
MHD_CONNECTION_INFO_CLIENT_ADDRESS	Obtain IP address of the client. Takes no extra arguments. Returns essentially a struct sockaddr ** (since the API returns a union MHD_ConnectionInfo * and that union contains a struct sockaddr *).
MHD_CONNECTION_INFO_GNUTLS_SESSION	Get the gnuTLS session handle.
MHD_CONNECTION_INFO_GNUTLS_CLIENT_CERT	Get the gnuTLS client certificate handle. Dysfunctional (never implemented, deprecated). Use MHD_CONNECTION_INFO_GNUTLS_SESSION to get the gnutls_session_t and then call gnutls_certificate_get_peers().
MHD_CONNECTION_INFO_DAEMON	Get the struct MHD_Daemon * responsible for managing this connection.
MHD_CONNECTION_INFO_CONNECTION_FD	Request the file descriptor for the listening socket. No extra arguments should be passed.

Definition at line 977 of file microhttpd.h.

enum MHD_RequestTerminationCode

The enum MHD_RequestTerminationCode specifies reasons why a request has been terminated (or completed).

Enumerator
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.
MHD_REQUEST_TERMINATED_READ_ERROR	We tried to read additional data, but the other side closed the connection. This error is similar to MHD_REQUEST_TERMINATED_WITH_ERROR, but specific to the case where the connection died because the other side did not send expected data.
MHD_REQUEST_TERMINATED_CLIENT_ABORT	The client terminated the connection by closing the socket for writing (TCP half-closed); MHD aborted sending the response according to RFC 2616, section 8.1.4.

Definition at line 875 of file microhttpd.h.

Function Documentation

struct MHD_PostProcessor * MHD_create_post_processor	(	struct MHD_Connection *	connection,
		size_t	buffer_size,
		MHD_PostDataIterator	iter,
		void *	iter_cls
	)

Create a struct MHD_PostProcessor.

A struct MHD_PostProcessor can be used to (incrementally) parse the data portion of a POST request. Note that some buggy browsers fail to set the encoding type. If you want to support those, you may have to call MHD_set_connection_value with the proper encoding type before creating a post processor (if no supported encoding type is set, this function will fail).

Parameters

connection	the connection on which the POST is happening (used to determine the POST format)
buffer_size	maximum number of bytes to use for internal buffering (used only for the parsing, specifically the parsing of the keys). A tiny value (256-1024) should be sufficient. Do NOT use a value smaller than 256. For good performance, use 32 or 64k (i.e. 65536).
iter	iterator to be called with the parsed data, Must NOT be NULL.
iter_cls	first argument to iter

Returns

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

Definition at line 272 of file postprocessor.c.

References MHD_HEADER_KIND, MHD_HTTP_HEADER_CONTENT_TYPE, MHD_HTTP_POST_ENCODING_FORM_URLENCODED, MHD_HTTP_POST_ENCODING_MULTIPART_FORMDATA, MHD_lookup_connection_value(), mhd_panic, mhd_panic_cls, NULL, PP_Init, and RN_Inactive.

Here is the call graph for this function:

int MHD_destroy_post_processor

(

struct MHD_PostProcessor *

pp

)

Release PostProcessor resources.

Parameters

pp	the PostProcessor to destroy

Returns

MHD_YES if processing completed nicely, MHD_NO if there were spurious characters / formatting problems; it is common to ignore the return value of this function

Release PostProcessor resources.

Parameters

pp	post processor context to destroy

Returns

MHD_YES if processing completed nicely, MHD_NO if there were spurious characters / formatting problems; it is common to ignore the return value of this function

Definition at line 1161 of file postprocessor.c.

References free_unmarked(), MHD_NO, MHD_YES, NE_none, NULL, post_process_urlencoded(), PP_Done, PP_ExpectNewLine, and PP_ProcessValue.

Here is the call graph for this function:

int MHD_get_connection_values	(	struct MHD_Connection *	connection,
		enum MHD_ValueKind	kind,
		MHD_KeyValueIterator	iterator,
		void *	iterator_cls
	)

Get all of the headers from the request.

Parameters

connection	connection to get values from
kind	types of values to iterate over
iterator	callback to call on each header; maybe NULL (then just count headers)
iterator_cls	extra argument to iterator

Returns

number of entries iterated over

Definition at line 121 of file connection.c.

References MHD_HTTP_Header::header, MHD_Connection::headers_received, MHD_HTTP_Header::kind, MHD_YES, MHD_HTTP_Header::next, NULL, and MHD_HTTP_Header::value.

const char * MHD_lookup_connection_value	(	struct MHD_Connection *	connection,
		enum MHD_ValueKind	kind,
		const char *	key
	)

Get a particular header value. If multiple values match the kind, return any one of them.

Parameters

connection	connection to get values from
kind	what kind of value are we looking for
key	the header to look for, NULL to lookup 'trailing' value without a key

Returns

NULL if no such item was found

Definition at line 210 of file connection.c.

References MHD_HTTP_Header::header, MHD_Connection::headers_received, MHD_HTTP_Header::kind, MHD_HTTP_Header::next, NULL, and MHD_HTTP_Header::value.

Referenced by add_extra_headers(), MHD_basic_auth_get_username_password(), MHD_connection_handle_idle(), MHD_create_post_processor(), MHD_digest_auth_check(), MHD_digest_auth_get_username(), need_100_continue(), parse_connection_headers(), and parse_cookie_header().

Here is the caller graph for this function:

int MHD_post_process	(	struct MHD_PostProcessor *	pp,
		const char *	post_data,
		size_t	post_data_len
	)

Parse and process POST data. Call this function when POST data is available (usually during an MHD_AccessHandlerCallback) with the "upload_data" and "upload_data_size". Whenever possible, this will then cause calls to the MHD_PostDataIterator.

Parameters

pp	the post processor
post_data	post_data_len bytes of POST data
post_data_len	length of post_data

Returns

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

Definition at line 1131 of file postprocessor.c.

References MHD_HTTP_POST_ENCODING_FORM_URLENCODED, MHD_HTTP_POST_ENCODING_MULTIPART_FORMDATA, MHD_NO, MHD_YES, NULL, post_process_multipart(), and post_process_urlencoded().

Here is the call graph for this function:

int MHD_set_connection_value	(	struct MHD_Connection *	connection,
		enum MHD_ValueKind	kind,
		const char *	key,
		const char *	value
	)

This function can be used to add an entry to the HTTP headers of a connection (so that the MHD_get_connection_values function will return them – and the struct MHD_PostProcessor will also see them). This maybe required in certain situations (see Mantis #1399) where (broken) HTTP implementations fail to supply values needed by the post processor (or other parts of the application).

This function MUST only be called from within the MHD_AccessHandlerCallback (otherwise, access maybe improperly synchronized). Furthermore, the client must guarantee that the key and value arguments are 0-terminated strings that are NOT freed until the connection is closed. (The easiest way to do this is by passing only arguments to permanently allocated strings.).

Parameters

connection	the connection for which a value should be set
kind	kind of the value
key	key for the value
value	the value itself

Returns

MHD_NO if the operation could not be performed due to insufficient memory; MHD_YES on success

Definition at line 170 of file connection.c.

References MHD_HTTP_Header::header, MHD_Connection::headers_received, MHD_Connection::headers_received_tail, MHD_HTTP_Header::kind, MHD_NO, MHD_pool_allocate(), MHD_YES, MHD_HTTP_Header::next, NULL, MHD_Connection::pool, and MHD_HTTP_Header::value.

Referenced by connection_add_header().

Here is the call graph for this function:

Here is the caller graph for this function: