Next: , Previous: microhttpd-response enqueue, Up: microhttpd-responses


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_fd_at_offset (uint64_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_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);