GNU libmicrohttpd is a small C library that is supposed to make it easy to run an HTTP server as part of another application. GNU libmicrohttpd is free software and part of the GNU project. Key features that distinguish libmicrohttpd from other projects are:
libmicrohttpd is licensed under the GNU LGPL. If you disable HTTPS/SSL support, you can also choose the second license, the eCos License. If you have questions about licensing, please contact the maintainer.
You can find the current release including binaries for Windows here and on GNU ftp mirrors. The latest version of the source code can be browsed from here or obtained using
$ svn checkout https://gnunet.org/svn/libmicrohttpd/
If you want to be notified about updates, subscribe to libmicrohttpd on freshmeat A public mailinglist for libmicrohttpd is hosted at http://lists.gnu.org/mailman/listinfo/libmicrohttpd.
In addition to the brief documentation on this webpage, we have various other forms of documentation available:
The rest of this section gives a general overview.
Before including the microhttpd.h header, you may need to include the headers of your operating system that define the size_t, fd_set, socklen_t and struct sockaddr data types and define MHD_PLATFORM_H. Otherwise, the microhttpd.h header will attempt to include the appropriate headers automatically, which may fail for more exotic platforms.
Here is a minimal example for GNU/Linux (included in the distribution):
#include <microhttpd.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#define PAGE "<html><head><title>libmicrohttpd demo</title>"\
"</head><body>libmicrohttpd demo</body></html>"
static int ahc_echo(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 ** ptr) {
static int dummy;
const char * page = cls;
struct MHD_Response * response;
int ret;
if (0 != strcmp(method, "GET"))
return MHD_NO; /* unexpected method */
if (&dummy != *ptr)
{
/* The first time only the headers are valid,
do not respond in the first round... */
*ptr = &dummy;
return MHD_YES;
}
if (0 != *upload_data_size)
return MHD_NO; /* upload data in a GET!? */
*ptr = NULL; /* clear context pointer */
response = MHD_create_response_from_data(strlen(page),
(void*) page,
MHD_NO,
MHD_NO);
ret = MHD_queue_response(connection,
MHD_HTTP_OK,
response);
MHD_destroy_response(response);
return ret;
}
int main(int argc,
char ** argv) {
struct MHD_Daemon * d;
if (argc != 2) {
printf("%s PORT\n",
argv[0]);
return 1;
}
d = MHD_start_daemon(MHD_USE_THREAD_PER_CONNECTION,
atoi(argv[1]),
NULL,
NULL,
&ahc_echo,
PAGE,
MHD_OPTION_END);
if (d == NULL)
return 1;
(void) getc ();
MHD_stop_daemon(d);
return 0;
}
The example above uses the simplest threading model, MHD_USE_THREAD_PER_CONNECTION. In this model, MHD starts one thread to listen on the port for new connections and then spawns a new thread to handle each connection. This model is great if the HTTP server has hardly any state that is shared between connections (no synchronization issues!) and may need to perform blocking operations (such as extensive IO or running of code) to handle an individual connection.
The second threading model, MHD_USE_SELECT_INTERNALLY, uses
only a single thread to handle listening on the port and processing of
requests. This model is preferable if spawning a thread for each
connection would be costly. If the HTTP server is able to quickly
produce responses without much computational overhead for each
connection, this model can be a great choice. Note that MHD will
still start a single thread for itself -- this way, the main program
can continue with its operations after calling MHD_daemon_start.
Naturally, if the HTTP server needs to interact with
shared state in the main application, synchronization will be
required. If such synchronization in code providing a response
results in blocking, all HTTP server operations on all connections
will stall. This mode is a bad choice if response data (for responses
generated using the MHD_create_response_from_callback
function) cannot always be provided instantly. The reason is that the
code generating responses should not block (since that would block all
other connections) and on the other hand, if response data is not
available immediately, MHD will start to busy wait on it. Use the
first model if you want to block on providing response data in the
callback, or the last model if you want to use a more event-driven
model with one big select loop.
The third model combines a thread pool with
the MHD_USE_SELECT_INTERNALLY mode, which can benefit
implementations that require scalability. As said before, by default
this mode only uses a single thread. When combined with the thread pool option, it
is possible to handle multiple connections with multiple threads. The
number of threads is specified using the
MHD_OPTION_THREAD_POOL_SIZE; any value greater than one for
this option will activate the use of the thread pool. In contrast to
the MHD_USE_THREAD_PER_CONNECTION mode (where each thread
handles one and only one connection), threads in the pool can handle a
large number of concurrent connections. Using
MHD_USE_SELECT_INTERNALLY in combination with a thread pool
is typically the most scalable (but also hardest to debug) mode of
operation for MHD.
The fourth threading model (used when no specific flag is given), uses no threads. Instead, the main application must (periodically) request file descriptor sets from MHD, perform a select call and then call MHD_run. MHD_run will then process HTTP requests as usual and return. MHD_run is guaranteed to not block; however, access handlers and response processing callbacks that it invokes may block. This mode is useful if a single-threaded implementation is desired and in particular if the main application already uses a select loop for its processing. If the application is not ready to provide a response, it can just return zero for the number of bytes read and use its file descriptors in the external select loop to wake up and continue once the data is ready -- MHD will unlist the socket from the write set if the application failed to provide response data (this only happens in this mode).
The testcases provided include examples for using each of the threading modes.
MHD provides various functions to create struct MHD_Response objects. A response consists of a set of HTTP headers and a (possibly empty) body. The three main ways to create a response are either by specifying a given (fixed-size) body (MHD_create_response_from_data), by providing a function of type MHD_ContentReaderCallback which provides portions of the response as needed or by providing an open file descriptor (MHD_create_response_from_fd). The first response construction is great for small and in particular static webpages that fit into memory. The second response type should be used for response objects where the size is initially not known or where the response maybe too large to fit into memory. Finally, using a file descriptor can be used on Linux systems to use the highly efficient sendfile call for the file transfer.
A response is used by calling MHD_queue_response which sends the response back to the client on the specified connection. Once created, a response object can be used any number of times. Internally, each response uses a reference counter. The response is freed once the reference counter reaches zero. The HTTP server should call MHD_destroy_response when a response object is no longer needed, that is, the server will not call MHD_queue_response again using this response object. Note that this does not mean that the response will be immediately destroyed -- destruction may be delayed until sending of the response is complete on all connections that have the response in the queue.
Clients should never create a "100 CONTINUE" response. MHD handles "100 CONTINUE" internally and only allows clients to queue a single response per connection. Furthermore, clients must not queue a response before the request has been fully received (except in the case of rejecting PUT or POST operations in HTTP 1.1). If a client attempts to queue multiple responses or attempts to queue a response early, MHD_queue_response will fail (and return MHD_NO).
The callback function for the respective URL will be called at least twice. The first call happens after the server has received the headers. The client should use the last void** argument to store internal context for the session. The first call to the callback function is mostly for this type of initialization and for internal access checks. At least, the callback function should "remember" that the first call with just the headers has happened. Queueing a response during the first call (for a given connection) should only be used for errors -- if the client queues a response during this first call, a 100 CONTINUE response will be suppressed, the request body will not be read and the connection will be closed after sending the response. After the first call, the callback function will be called with upload data. Until *upload_data_size is zero, the callback may not queue a response, any such attempt will fail. The callback function should update *upload_data_size to indicate how many bytes were processed. Depending on available buffer space, incremental processing of the upload maybe required. Once all of the upload data has been processed, MHD will call the callback a second time with *upload_data_size being zero. At this point, the callback should queue a "normal" response. If queueing a response is not possible, the callback may either block or simply not queue a response depending on the threading model that is used. If the callback does not queue a response at this point, MHD will either (eventually) timeout the connection or keep calling it.
MHD includes a set of three functions for parsing and processing data received in POST requests. The functions allow incremental parsing and processing of POST data. Only a tiny fraction of the overall POST data needs to fit into memory. As a result, applications using MHD can support POST requests of arbitrary size. POST data is processed by providing MHD with a callback function that is called on portions of the received values. The POST parser itself is invoked repeatedly whenever more input bytes become available. MHD supports both uri- and multipart/form-encoded POST data.
The application can determine the size of buffers that MHD should use for handling of HTTP requests and parsing of POST data. This way, MHD users can trade-off processing time and memory utilization. Applications can limit the overall number of connections MHD will accept, as well as the total amount of memory used per connection. MHD will gracefully handle all out-of-memory situations (by closing the connection and cleaning up any remaining state).
libmicrohttpd uses Mantis for bugtracking. Visit https://gnunet.org/bugs/ to report bugs. You need to sign up for a reporter account. Please make sure you report bugs under libmicrohttpd and not under any of the other projects.
For questions and discussions please use the GNU libmicrohttpd mailinglist. Messages to the list from non-subscribers are subject to manual moderation and are hence likely to be delayed significantly.
If you write an application that uses libmicrohttpd, please let us know so that we can add you to the list!
If you are aware of a competing library that might be a better fit for some developers, please let us know so that we can add it to the list!
GNU libmicrohttpd development is currently funded in part by the Deutsche Forschungsgemeinschaft under ENP GR 3688/1-1.
Copyright (C) 2007, 2008, 2009, 2010, 2011 Christian Grothoff. Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.