4. Callback functions definition

Function Pointer: int *MHD_AcceptPolicyCallback (void *cls, const struct sockaddr * addr, socklen_t addrlen)

Invoked in the context of a connection to allow or deny a client to connect. This callback return MHD_YES if connection is allowed, MHD_NO if not.

cls

custom value selected at callback registration time;

addr

address information from the client;

addrlen

length of the address information.

Function Pointer: int *MHD_AccessHandlerCallback (void *cls, struct MHD_Connection * connection, const char *url, const char *method, const char *version, const char *upload_data, unsigned int *upload_data_size, void **con_cls)

Invoked in the context of a connection to answer a request from the client. This callback must call MHD functions (example: the MHD_Response ones) to provide content to give back to the client and return an HTTP status code (i.e. 200 for OK, 404, etc.).

Adding a POST processor, for details on how to code this callback.

Must return MHD_YES if the connection was handled successfully, MHD_NO if the socket must be closed due to a serious error while handling the request

cls

custom value selected at callback registration time;

url

the URL requested by the client;

method

the HTTP method used by the client (GET, PUT, DELETE, POST, etc.);

version

the HTTP version string (i.e. HTTP/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; this callback must update this value to the number of bytes NOT processed; unless external select is used, the callback maybe required to process at least some data. If the callback fails to process data in multi-threaded or internal-select mode and if the read-buffer is already at the maximum size that MHD is willing to use for reading (about half of the maximum amount of memory allowed for the connection), then MHD will abort handling the connection and return an internal server error to the client. In order to avoid this, clients must be able to process upload data incrementally and reduce the value of upload_data_size.

con_cls

reference to a pointer, initially set to NULL, that this 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).

Function Pointer: void *MHD_RequestCompletedCallback (void *cls, struct MHD_Connectionconnection, void **con_cls, enum MHD_RequestTerminationCode toe)

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

cls

custom value selected at callback registration time;

connection

connection handle;

con_cls

value as set by the last call to the MHD_AccessHandlerCallback;

toe

reason for request termination see MHD_OPTION_NOTIFY_COMPLETED.

Function Pointer: 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.

Return MHD_YES to continue iterating, MHD_NO to abort the iteration.

Function Pointer: int *MHD_ContentReaderCallback (void *cls, size_t pos, char *buf, int max)

Callback used by MHD in order to obtain content. The callback has 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 MHD to try again, either “immediately” if in multi-threaded mode (in which case the callback may want to do blocking operations) or in the next round if MHD_run is used. Returning zero for a daemon that runs in internal select() mode is an error (since it would result in busy waiting) and will cause the program to be aborted (abort()).

cls

custom value selected at callback registration time;

pos

position in the datastream to access; note that if an 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 an MHD_Response is not re-used, MHD guarantees that pos will be the sum of all non-negative return values obtained from the content reader so far.

Return -1 on error (MHD will no longer try to read content and instead close the connection with the client).

Function Pointer: void *MHD_ContentReaderFreeCallback (void *cls)

This method is called by MHD if we are done with a content reader. It should be used to free resources associated with the content reader.

Function Pointer: 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, size_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

custom value selected at callback registration time;

kind

type of the value;

key

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

Return MHD_YES to continue iterating, MHD_NO to abort the iteration.

This document was generated by Christian Grothoff on May, 26 2008 using texi2html 1.78.