8.1 Enqueuing a response

Function: enum MHD_Result MHD_queue_response (struct MHD_Connection *connection, unsigned int status_code, struct MHD_Response *response)

Queue a response to be transmitted to the client as soon as possible but only after MHD_AccessHandlerCallback returns. This function checks that it is legal to queue a response at this time for the given connection. It also increments the internal reference counter for the response object (the counter will be decremented automatically once the response has been transmitted).

connection

the connection identifying the client;

status_code

HTTP status code (i.e. 200 for OK);

response

response to transmit.

Return MHD_YES on success or if message has been queued. Return MHD_NO: if arguments are invalid (example: NULL pointer); on error (i.e. reply already sent).

Function: void MHD_destroy_response (struct MHD_Response *response)

Destroy a response object and associated resources (decrement the reference counter). Note that MHD may keep some of the resources around if the response is still in the queue for some clients, so the memory may not necessarily be freed immediately.

An explanation of reference counting¹:

1. a MHD_Response object is allocated:

   struct MHD_Response * response = MHD_create_response_from_buffer(...);
   /* here: reference counter = 1 */
   

2. the MHD_Response object is enqueued in a MHD_Connection:

   MHD_queue_response(connection, , response);
   /* here: reference counter = 2 */
   

3. the creator of the response object discharges responsibility for it:

   MHD_destroy_response(response);
   /* here: reference counter = 1 */
   

4. the daemon handles the connection sending the response’s data to the client then decrements the reference counter by calling MHD_destroy_response(): the counter’s value drops to zero and the MHD_Response object is released.