4 Callback functions definition

Function Pointer: enum MHD_Result *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: enum MHD_Result *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)

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

microhttpd-post, 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):

POST data will be made available incrementally in upload_data; even if POST data is available, the first time the callback is invoked there won’t be upload data, as this is done just after MHD parses the headers. If supported by the client and the HTTP version, the application can at this point queue an error response to possibly avoid the upload entirely. If no response is generated, MHD will (if required) automatically send a 100 CONTINUE reply to the client.

Afterwards, POST data will be passed to the callback to be processed incrementally by the application. The application may return MHD_NO to forcefully terminate the TCP connection without generating a proper HTTP response. Once all of the upload data has been provided to the application, the application will be called again with 0 bytes of upload data. At this point, a response should be queued to complete the handling of the request.

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: enum MHD_Result *MHD_KeyValueIterator (void *cls, enum MHD_ValueKind kind, const char *key, const char *value, size_t value_size)

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.

cls

custom value specified when iteration was triggered;

kind

kind of the header we are looking at

key

key for the value, can be an empty string

value

value corresponding value, can be NULL

value_size

number of bytes in value. This argument was introduced in MHD_VERSION 0x00096301 to allow applications to use binary zeros in values. Applications using this argument must ensure that they are using a sufficiently recent version of MHD, i.e. by testing MHD_get_version() for values above or equal to 0.9.64. Applications that do not need zeros in values and that want to compile without warnings against newer versions of MHD should not declare this argument and cast the function pointer argument to MHD_KeyValueIterator.

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

Function Pointer: ssize_t *MHD_ContentReaderCallback (void *cls, uint64_t pos, char *buf, size_t 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. Thus, returning zero should only be used in conjunction with MHD_suspend_connection() to avoid busy waiting.

While usually the callback simply returns the number of bytes written into buf, there are two special return value:

MHD_CONTENT_READER_END_OF_STREAM (-1) should be returned 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) is used 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.

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: enum MHD_Result *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

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.