Next: , Previous: microhttpd-struct, Up: Top


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, 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):
  • 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, 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, either “immediately” if in multi-threaded mode (in which case the callback may want to do blocking operations to avoid busy waiting) 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 cause the program to be aborted (abort()).

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

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.