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

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.

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 
) [read]

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:


Generated on 15 Oct 2014 for GNU libmicrohttpd by  doxygen 1.6.1