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.

custom value selected at callback registration time;
address information from the client;
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

custom value selected at callback registration time;
the URL requested by the client;
the HTTP method used by the client (GET, PUT, DELETE, POST, etc.);
the HTTP version string (i.e. HTTP/1.1);
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;

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

custom value selected at callback registration time;
connection handle;
value as set by the last call to the MHD_AccessHandlerCallback;
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.

custom value selected at callback registration time;
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.

custom value selected at callback registration time;
type of the value;
zero-terminated key for the value;
name of the uploaded file, NULL if not known;
mime-type of the data, NULL if not known;
encoding of the data, NULL if not known;
pointer to size bytes of data at the specified offset;
offset of data in the overall value;
number of bytes in data available.

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