commit 845b05cc597431ee09c52c05c0678535ab0d48bb
parent 96b2dcfc43eb89eeaec4689b7eb802370f6be741
Author: Christian Grothoff <christian@grothoff.org>
Date: Sat, 23 Dec 2006 12:39:05 +0000
miro
Diffstat:
1 file changed, 431 insertions(+), 0 deletions(-)
diff --git a/src/include/microhttpd.h b/src/include/microhttpd.h
@@ -0,0 +1,431 @@
+/*
+ This file is part of libmicrohttpd
+ (C) 2006 Christian Grothoff (and other contributing authors)
+
+ libmicrohttpd is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published
+ by the Free Software Foundation; either version 2, or (at your
+ option) any later version.
+
+ libmicrohttpd is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with libmicrohttpd; see the file COPYING. If not, write to the
+ Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA.
+*/
+
+/**
+ * @file microhttpd.h
+ * @brief public interface to libmicrohttpd
+ * @author Christian Grothoff
+ *
+ * All symbols defined in this header start with MHD. MHD is a
+ * micro-httpd library. As such, it does not have any API for logging
+ * errors.<p>
+ *
+ * All functions are guaranteed to be completely reentrant and
+ * thread-safe.<p>
+ *
+ * TODO:
+ * - Is it ok to treat POST data and GET-URI arguments (a=4&b=5) equally,
+ * or do we need an extra pair of methods?
+ * - We probably need a significantly more extensive API for
+ * proper SSL support (set local certificate, etc.)
+ */
+
+#ifndef MHD_MICROHTTPD_H
+#define MHD_MICROHTTPD_H
+
+#include <sys/types.h>
+#include <sys/select.h>
+#include <sys/socket.h>
+
+#ifdef __cplusplus
+extern "C" {
+#if 0 /* keep Emacsens' auto-indent happy */
+}
+#endif
+#endif
+
+#define MHD_VERSION 0x00000000
+
+#define MHD_YES 1
+
+#define MHD_NO 0
+
+/**
+ * Options for the MHD daemon. Note that if neither
+ * MHD_USER_THREAD_PER_CONNECTION nor MHD_USE_SELECT_INTERNALLY are
+ * used, the client wants control over the process and will call the
+ * appropriate microhttpd callbacks.<p>
+ *
+ * Note that it is legal to specify that both IPv4 and IPv6
+ * should be used. However, if neither IPv4 nor IPv6 is
+ * specified, starting the daemon will fail.<p>
+ *
+ * Starting the daemon may also fail if a particular option is not
+ * implemented or not supported on the target platform (i.e. no
+ * support for SSL, threads or IPv6).
+ */
+enum MHD_OPTION {
+ /**
+ * No options selected.
+ */
+ MHD_NO_OPTION = 0,
+
+ /**
+ * Run in debug mode. If this flag is used, the
+ * library should print error messages and warnings
+ * to stderr.
+ */
+ MHD_USE_DEBUG = 1,
+
+ /**
+ * Run in https mode.
+ */
+ MHD_USE_SSL = 2,
+
+ /**
+ * Run using one thread per connection.
+ */
+ MHD_USE_THREAD_PER_CONNECTION = 4,
+
+ /**
+ * Run using an internal thread doing SELECT.
+ */
+ MHD_USE_SELECT_INTERNALLY = 8,
+
+ /**
+ * Run using the IPv4 protocol
+ */
+ MHD_USE_IPv4 = 16,
+
+ /**
+ * Run using the IPv6 protocol
+ */
+ MHD_USE_IPv6 = 32,
+};
+
+struct MHD_Daemon;
+
+struct MHD_Session;
+
+struct MHD_Response;
+
+/**
+ * Allow or deny a client to connect.
+ *
+ *
+ * @param addr address information from the client
+ * @param addrlen length of the address information
+ * @return MHD_YES if connection is allowed, MHD_NO if not
+ */
+typedef int
+(*MHD_AcceptPolicyCallback)(void * cls,
+ const struct sockaddr * addr,
+ socklen_t addrlen);
+
+/**
+ * A client has requested the given url using the given method ("GET",
+ * "PUT" or "POST"). The callback must call MHS callbacks to provide
+ * content to give back to the client and return an HTTP status code
+ * (i.e. 200 for OK, 404, etc.).
+ *
+ * @return MHS_YES if the connection was handled successfully,
+ * MHS_NO if the socket must be closed due to a serios
+ * error while handling the request
+ */
+typedef int
+(*MHD_AccessHandlerCallback)(void * cls,
+ struct MHD_Session * session,
+ const char * url,
+ const char * method);
+
+/**
+ * Iterator over key-value pairs. This iterator
+ * can be used to iterate over all of the cookies,
+ * headers, or POST-data fields of a request, and
+ * also to iterate over the headers that have been
+ * added to a response.
+ *
+ * @return MHD_YES to continue iterating,
+ * MHD_NO to abort the iteration
+ */
+typedef int
+(*MHD_KeyValueIterator)(void * cls,
+ const char * key,
+ const char * value);
+
+/**
+ * Callback used by libmicrohttpd in order to obtain content. The
+ * callback is to copy at most "max" bytes of content into "buf". The
+ * total number of bytes that has been placed into "buf" should be
+ * returned.<p>
+ *
+ * Note that returning zero will cause libmicrohttpd to try again,
+ * either "immediately" if in multi-threaded mode (in which case the
+ * callback may want to do blocking operations) or in the next round
+ * if MHD_run is used. Returning 0 for a daemon that runs in internal
+ * select mode is an error (since it would result in busy waiting) and
+ * will cause the program to be aborted (abort()).
+ *
+ * @param cls extra argument to the callback
+ * @param pos position in the datastream to access;
+ * note that if an MHD_Response object is re-used,
+ * it is possible for the same content reader to
+ * be queried multiple times for the same data;
+ * however, if an MHD_Response is not re-used,
+ * libmicrohttpd guarantees that "pos" will be
+ * the sum of all non-negative return values
+ * obtained from the content reader so far.
+ * @return -1 on error (libmicrohttpd will no longer
+ * try to read content and instead close the connection
+ * with the client).
+ */
+typedef int
+(*MHD_ContentReaderCallback)(void * cls,
+ size_t pos,
+ char * buf,
+ int max);
+
+/**
+ * This method is called by libmicrohttpd if we
+ * are done with a content reader. It should
+ * be used to free resources associated with the
+ * content reader.
+ */
+typedef void
+(*MHD_ContentReaderFreeCallback)(void * cls);
+
+/**
+ * Start a webserver on the given port.
+ * @param port port to bind to
+ * @param apc callback to call to check which clients
+ * will be allowed to connect
+ * @param apc_cls extra argument to apc
+ * @param dh default handler for all URIs
+ * @param dh_cls extra argument to dh
+ * @return NULL on error, handle to daemon on success
+ */
+struct MHD_Daemon *
+MHD_start_daemon(unsigned int options,
+ unsigned short port,
+ MHD_AcceptPolicyCallback apc,
+ void * apc_cls,
+ MHD_AccessHandlerCallback dh,
+ void * dh_cls);
+
+
+
+/**
+ * Shutdown an http daemon.
+ */
+void
+MHD_stop_daemon(struct MHD_Daemon * daemon);
+
+
+/**
+ * Obtain the select sets for this daemon.
+ *
+ * @return MHD_YES on success, MHD_NO if this
+ * daemon was not started with the right
+ * options for this call.
+ */
+int
+MHD_get_fdset(struct MHD_Daemon * daemon,
+ fd_set * read_fd_set,
+ fd_set * write_fd_set,
+ fd_set * exc_fd_set,
+ int * max_fd);
+
+/**
+ * Run webserver operations (without blocking unless
+ * in client callbacks). This method should be called
+ * by clients in combination with MHD_get_fdset
+ * if the client-controlled select method is used.
+ *
+ * @return MHD_YES on success, MHD_NO if this
+ * daemon was not started with the right
+ * options for this call.
+ */
+int
+MHD_run(struct MHD_Daemon * daemon);
+
+
+/**
+ * Register an access handler for all URIs beginning with uri_prefix.
+ *
+ * @param uri_prefix
+ * @return MRI_NO if a handler for this exact prefix
+ * already exists
+ */
+int
+MHD_register_handler(struct MHD_Daemon * daemon,
+ const char * uri_prefix,
+ MHD_AccessHandlerCallback dh,
+ void * dh_cls);
+
+/**
+ * Unregister an access handler for the URIs beginning with
+ * uri_prefix.
+ *
+ * @param uri_prefix
+ * @return MHD_NO if a handler for this exact prefix
+ * is not known for this daemon
+ */
+ */
+int
+MHD_unregister_handler(struct MHD_Daemon * daemon,
+ const char * uri_prefix,
+ MHD_AccessHandlerCallback dh,
+ void * dh_cls);
+
+/**
+ * Get all of the headers from the request.
+ *
+ * @param iterator callback to call on each header;
+ * maybe NULL (then just count headers)
+ * @param iterator_cls extra argument to iterator
+ * @return number of entries iterated over
+ */
+int
+MHD_get_session_headers(struct MHD_Session * session,
+ MHD_KeyValueIterator * iterator,
+ void * iterator_cls);
+
+/**
+ * Get a particular header value.
+ *
+ * @param key the header to look for
+ * @return NULL if no such item was found
+ */
+const char *
+MHD_lookup_session_header(struct MHD_Session * session,
+ const char * key);
+
+/**
+ * Get all of the form fields from POST.
+ *
+ * @param iterator callback to call on each header;
+ * maybe NULL (then just count headers)
+ * @param iterator_cls extra argument to iterator
+ * @return number of entries iterated over
+ */
+int
+MHD_get_post_items(struct MHD_Session * session,
+ MHD_KeyValueIterator * iterator,
+ void * iterator_cls);
+
+/**
+ * Get a particular form field from POST.
+ *
+ * @param key the field to look for
+ * @return NULL if no such item was found
+ */
+const char *
+MHD_lookup_post_item(struct MHD_Session * session,
+ const char * key);
+
+/**
+ * Queue a response to be transmitted to the client (as soon as
+ * possible).
+ *
+ * @param session the session identifying the client
+ * @param status_code HTTP status code (i.e. 200 for OK)
+ * @param response response to transmit
+ * @return MHD_NO on error (i.e. reply already sent),
+ * MHD_YES on success or if message has been queued
+ */
+int
+MHD_queue_response(struct MHD_Session * session,
+ unsigned int status_code,
+ struct MHD_Response * response);
+
+/**
+ * Create a response object. The response object can be extended with
+ * header information and then be used any number of times.
+ *
+ * @param size size of the data portion of the response, -1 for unknown
+ * @param crc callback to use to obtain response data
+ * @param crc_cls extra argument to crc
+ * @param crfc callback to call to free crc_cls resources
+ * @return NULL on error (i.e. invalid arguments, out of memory)
+ */
+struct MHD_Response *
+MHD_create_response_from_callback(size_t 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 be used any number of times.
+ *
+ * @param size size of the data portion of the response
+ * @param data the data itself
+ * @param must_free libmicrohttpd should free data when done
+ * @param must_copy libmicrohttpd must make a copy of data
+ * right away, the data maybe released anytime after
+ * this call returns
+ * @return NULL on error (i.e. invalid arguments, out of memory)
+ */
+struct MHD_Response *
+MHD_create_response_from_data(size_t size,
+ void * data,
+ int must_free,
+ int must_copy);
+
+/**
+ * Destroy a response object and associated resources. Note that
+ * libmicrohttpd 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 immediatley.
+ */
+void
+MHD_destroy_response(struct MHD_Response * response);
+
+/**
+ * Add a header line to the response.
+ *
+ * @return MHD_NO on error (i.e. invalid header or content format).
+ */
+int
+MHD_add_response_header(struct MHD_Response * response,
+ const char * header,
+ const char * content);
+
+/**
+ * Delete a header line from the response.
+ *
+ * @return MHD_NO on error (no such header known)
+ */
+int
+MHD_del_response_header(struct MHD_Response * response,
+ const char * header,
+ const char * content);
+
+/**
+ * Get all of the headers added to a response.
+ *
+ * @param iterator callback to call on each header;
+ * maybe NULL (then just count headers)
+ * @param iterator_cls extra argument to iterator
+ * @return number of entries iterated over
+ */
+int
+MHD_get_response_headers(struct MHD_Response * response,
+ MHD_KeyValueIterator * iterator,
+ void * iterator_cls);
+
+#if 0 /* keep Emacsens' auto-indent happy */
+{
+#endif
+#ifdef __cplusplus
+}
+#endif
+
+#endif
