11 Adding a POST processor

MHD provides the post processor API to make it easier for applications to parse the data of a client’s POST request: the MHD_AccessHandlerCallback will be invoked multiple times to process data as it arrives; at each invocation a new chunk of data must be processed. The arguments upload_data and upload_data_size are used to reference the chunk of data.

When MHD_AccessHandlerCallback is invoked for a new connection: its *con_cls argument is set to NULL. When POST data comes in the upload buffer it is mandatory to use the con_cls to store a reference to per-connection data. The fact that the pointer was initially NULL can be used to detect that this is a new request.

One method to detect that a new connection was established is to set *con_cls to an unused integer:

int
access_handler (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)
{
 static int old_connection_marker;
 int new_connection = (NULL == *con_cls);
 if (new_connection)
 {
 /* new connection with POST */
 *con_cls = &old_connection_marker;
 }
 ...
}

In contrast to the previous example, for POST requests in particular, it is more common to use the value of *con_cls to keep track of actual state used during processing, such as the post processor (or a struct containing a post processor):

int
access_handler (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)
{
 struct MHD_PostProcessor * pp = *con_cls;
 if (pp == NULL)
 {
 pp = MHD_create_post_processor(connection, ...);
 *con_cls = pp;
 return MHD_YES;
 }
 if (*upload_data_size)
 {
 MHD_post_process(pp, upload_data, *upload_data_size);
 *upload_data_size = 0;
 return MHD_YES;
 }
 else
 {
 MHD_destroy_post_processor(pp);
 return MHD_queue_response(...);
 }
}

Note that the callback from MHD_OPTION_NOTIFY_COMPLETED should be used to destroy the post processor. This cannot be done inside of the access handler since the connection may not always terminate normally.