microhttpd-response create (The GNU libmicrohttpd Reference Manual)

8.2 Creating a response object

Function: struct MHD_Response * MHD_create_response_from_callback (uint64_t size, size_t block_size, MHD_ContentReaderCallback crc, void *crc_cls, MHD_ContentReaderFreeCallback crfc)

Create a response object. The response object can be extended with header information and then it can be used any number of times.

size: size of the data portion of the response, -1 for unknown;
block_size: preferred block size for querying crc (advisory only, MHD may still call crc using smaller chunks); this is essentially the buffer size used for IO, clients should pick a value that is appropriate for IO and memory performance requirements;
crc: callback to use to obtain response data;
crc_cls: extra argument to crc;
crfc: callback to call to free crc_cls resources.

Return NULL on error (i.e. invalid arguments, out of memory).

Function: struct MHD_Response * MHD_create_response_from_fd (uint64_t size, int fd)

Create a response object. The response object can be extended with header information and then it can be used any number of times.

size: size of the data portion of the response (should be smaller or equal to the size of the file)
fd: file descriptor referring to a file on disk with the data; will be closed when response is destroyed; note that ’fd’ must be an actual file descriptor (not a pipe or socket) since MHD might use ’sendfile’ or ’seek’ on it. The descriptor should be in blocking-IO mode.

Return NULL on error (i.e. invalid arguments, out of memory).

Function: struct MHD_Response * MHD_create_response_from_pipe (uint64_t size, int fd)

Create a response object. The response object can be extended with header information and then it can be used ONLY ONCE.

fd: file descriptor of the read-end of the pipe; will be closed when response is destroyed. The descriptor should be in blocking-IO mode.

Return NULL on error (i.e. out of memory).

Function: struct MHD_Response * MHD_create_response_from_fd_at_offset (size_t size, int fd, off_t offset)

Create a response object. The response object can be extended with header information and then it can be used any number of times. Note that you need to be a bit careful about off_t when writing this code. Depending on your platform, MHD is likely to have been compiled with support for 64-bit files. When you compile your own application, you must make sure that off_t is also a 64-bit value. If not, your compiler may pass a 32-bit value as off_t, which will result in 32-bits of garbage.

If you use the autotools, use the AC_SYS_LARGEFILE autoconf macro and make sure to include the generated config.h file before microhttpd.h to avoid problems. If you do not have a build system and only want to run on a GNU/Linux system, you could also use

#define _FILE_OFFSET_BITS 64
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <microhttpd.h>

to ensure 64-bit off_t. Note that if your operating system does not support 64-bit files, MHD will be compiled with a 32-bit off_t (in which case the above would be wrong).

size: size of the data portion of the response (number of bytes to transmit from the file starting at offset).
fd: file descriptor referring to a file on disk with the data; will be closed when response is destroyed; note that ’fd’ must be an actual file descriptor (not a pipe or socket) since MHD might use ’sendfile’ or ’seek’ on it. The descriptor should be in blocking-IO mode.
offset: offset to start reading from in the file

Return NULL on error (i.e. invalid arguments, out of memory).

Function: struct MHD_Response * MHD_create_response_from_buffer (size_t size, void *data, enum MHD_ResponseMemoryMode mode)

Create a response object. The response object can be extended with header information and then it can be used any number of times.

size: size of the data portion of the response;
buffer: the data itself;
mode: memory management options for buffer; use MHD_RESPMEM_PERSISTENT if the buffer is static/global memory, use MHD_RESPMEM_MUST_FREE if the buffer is heap-allocated and should be freed by MHD and MHD_RESPMEM_MUST_COPY if the buffer is in transient memory (i.e. on the stack) and must be copied by MHD;

Return NULL on error (i.e. invalid arguments, out of memory).

Function: struct MHD_Response * MHD_create_response_from_buffer_with_free_callback (size_t size, void *data, MHD_ContentReaderFreeCallback crfc)

Create a response object. The buffer at the end must be free’d by calling the crfc function.

size: size of the data portion of the response;
buffer: the data itself;
crfc: function to call at the end to free memory allocated at buffer.

Return NULL on error (i.e. invalid arguments, out of memory).

Function: struct MHD_Response * MHD_create_response_from_data (size_t size, void *data, int must_free, int must_copy)

Create a response object. The response object can be extended with header information and then it can be used any number of times. This function is deprecated, use MHD_create_response_from_buffer instead.

size: size of the data portion of the response;
data: the data itself;
must_free: if true: MHD should free data when done;
must_copy: if true: MHD allocates a block of memory and use it to make a copy of data embedded in the returned MHD_Response structure; handling of the embedded memory is responsibility of MHD; data can be released anytime after this call returns.

Return NULL on error (i.e. invalid arguments, out of memory).

Example: create a response from a statically allocated string:

const char * data = "<html><body><p>Error!</p></body></html>";

struct MHD_Connection * connection = ...;
struct MHD_Response *   response;

response = MHD_create_response_from_buffer (strlen(data), data,
                                            MHD_RESPMEM_PERSISTENT);
MHD_queue_response(connection, 404, response);
MHD_destroy_response(response);