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.