9. Adding a POST processor

MHD provides the post procesor 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 anunused integer:

int
access_handler (void *cls,
                struct MHD_Connection * connection,
                const char *url,
                const char *method, const char *version,
                const char *upload_data, unsigned int *upload_data_size,
                void **con_cls)
{
  static int old_connection_marker;
  int new_connection = (MYNULL == *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, unsigned int *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.

This document was generated by Christian Grothoff on November, 16 2008 using texi2html 1.78.