commit 131368c7194d776adae1263aba4868f041694b42
parent ee69fbf07d1e2fa824d5333c85b826bd7b20b08a
Author: Christian Grothoff <christian@grothoff.org>
Date: Thu, 22 Aug 2013 04:44:38 +0000
improving doxygen use
Diffstat:
1 file changed, 344 insertions(+), 192 deletions(-)
diff --git a/src/include/microhttpd.h b/src/include/microhttpd.h
@@ -28,7 +28,7 @@
* errors (you can only enable or disable logging to stderr). Also,
* it may not support all of the HTTP features directly, where
* applicable, portions of HTTP may have to be handled by clients of
- * the library.<p>
+ * the library.
*
* The library is supposed to handle everything that it must handle
* (because the API would not allow clients to do this), such as basic
@@ -38,14 +38,14 @@
* the response and not the body, even if the client supplied a body.
* The library also understands headers that control connection
* management (specifically, "Connection: close" and "Expect: 100
- * continue" are understood and handled automatically).<p>
+ * continue" are understood and handled automatically).
*
* MHD understands POST data and is able to decode certain formats
* (at the moment only "application/x-www-form-urlencoded" and
* "mulitpart/formdata"). Unsupported encodings and large POST
* submissions may require the application to manually process
* the stream, which is provided to the main application (and thus can be
- * processed, just not conveniently by MHD).<p>
+ * processed, just not conveniently by MHD).
*
* The header file defines various constants used by the HTTP protocol.
* This does not mean that MHD actually interprets all of these
@@ -53,11 +53,11 @@
* for users of the library. MHD does not verify that transmitted
* HTTP headers are part of the standard specification; users of the
* library are free to define their own extensions of the HTTP
- * standard and use those with MHD.<p>
+ * standard and use those with MHD.
*
* All functions are guaranteed to be completely reentrant and
- * thread-safe (with the exception of 'MHD_set_connection_value',
- * which must only be used in a particular context).<p>
+ * thread-safe (with the exception of #MHD_set_connection_value,
+ * which must only be used in a particular context).
*
* NEW: Before including "microhttpd.h" you should add the necessary
* includes to define the "uint64_t", "size_t", "fd_set", "socklen_t"
@@ -67,6 +67,16 @@
* should also have a line with "#define MHD_PLATFORM_H" which will
* prevent this header from trying (and, depending on your platform,
* failing) to include the right headers.
+ *
+ * @defgroup tls HTTPS/SSL/TLS control
+ * @defgroup event event-loop control
+ * @defgroup response generation of responses
+ * @defgroup request handling of requests
+ * @defgroup authentication HTTP authentication
+ * @defgroup logging logging and error handling
+ * @defgroup networking general networking
+ * @defgroup specialized misc. specialized functions
+ * @defgroup limits configuring resource limitations
*/
#ifndef MHD_MICROHTTPD_H
@@ -167,7 +177,8 @@ extern "C"
/**
- * HTTP response codes.
+ * @defgroup httpcode HTTP response codes.
+ * @{
*/
#define MHD_HTTP_CONTINUE 100
#define MHD_HTTP_SWITCHING_PROTOCOLS 101
@@ -230,13 +241,20 @@ extern "C"
#define MHD_HTTP_BANDWIDTH_LIMIT_EXCEEDED 509
#define MHD_HTTP_NOT_EXTENDED 510
+/** @} */ /* end of group httpcode */
+
/**
* Flag to be "OR"ed with MHD_HTTP status code for
* SHOUTcast. This will cause the response to begin
* with the SHOUTcast "ICY" line instad of "HTTP".
+ * @ingroup specialized
*/
#define MHD_ICY_FLAG ((uint32_t)(1 << 31))
+/**
+ * @defgroup headers HTTP headers
+ * @{
+ */
/* See also: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html */
#define MHD_HTTP_HEADER_ACCEPT "Accept"
#define MHD_HTTP_HEADER_ACCEPT_CHARSET "Accept-Charset"
@@ -290,15 +308,21 @@ extern "C"
#define MHD_HTTP_HEADER_WARNING "Warning"
#define MHD_HTTP_HEADER_WWW_AUTHENTICATE "WWW-Authenticate"
+/** @} */ /* end of group headers */
+
/**
- * HTTP versions (used to match against the first line of the
+ * @defgroup versions HTTP versions (used to match against the first line of the
* HTTP header as well as in the response code).
+ * @{
*/
#define MHD_HTTP_VERSION_1_0 "HTTP/1.0"
#define MHD_HTTP_VERSION_1_1 "HTTP/1.1"
+/** @} */ /* end of group versions */
+
/**
- * HTTP methods
+ * @defgroup methods HTTP methods
+ * @{
*/
#define MHD_HTTP_METHOD_CONNECT "CONNECT"
#define MHD_HTTP_METHOD_DELETE "DELETE"
@@ -309,18 +333,23 @@ extern "C"
#define MHD_HTTP_METHOD_PUT "PUT"
#define MHD_HTTP_METHOD_TRACE "TRACE"
+/** @} */ /* end of group methods */
+
/**
- * HTTP POST encodings, see also
+ * @defgroup postenc HTTP POST encodings, see also
* http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4
+ * @{
*/
#define MHD_HTTP_POST_ENCODING_FORM_URLENCODED "application/x-www-form-urlencoded"
#define MHD_HTTP_POST_ENCODING_MULTIPART_FORMDATA "multipart/form-data"
+/** @} */ /* end of group postenc */
+
/**
* Options for the MHD daemon. Note that if neither
- * MHD_USE_THREAD_PER_CONNECTION nor MHD_USE_SELECT_INTERNALLY is
+ * #MHD_USE_THREAD_PER_CONNECTION nor #MHD_USE_SELECT_INTERNALLY is
* used, the client wants control over the process and will call the
- * appropriate microhttpd callbacks.<p>
+ * appropriate microhttpd callbacks.
*
* Starting the daemon may also fail if a particular option is not
* implemented or not supported on the target platform (i.e. no
@@ -337,55 +366,63 @@ enum MHD_FLAG
* Run in debug mode. If this flag is used, the
* library should print error messages and warnings
* to stderr.
+ * @ingroup logging
*/
MHD_USE_DEBUG = 1,
/**
- * Run in https mode.
+ * Run in HTTPS mode.
+ * @ingroup tls
*/
MHD_USE_SSL = 2,
/**
* Run using one thread per connection.
+ * @ingroup event
*/
MHD_USE_THREAD_PER_CONNECTION = 4,
/**
- * Run using an internal thread (or thread pool) doing SELECT.
+ * Run using an internal thread (or thread pool) doing select().
+ * @ingroup event
*/
MHD_USE_SELECT_INTERNALLY = 8,
/**
* Run using the IPv6 protocol (otherwise, MHD will just support
* IPv4). If you want MHD to support IPv4 and IPv6 using a single
- * socket, pass MHD_USE_DUAL_STACK, otherwise, if you only pass
+ * socket, pass #MHD_USE_DUAL_STACK, otherwise, if you only pass
* this option, MHD will try to bind to IPv6-only (resulting in
* no IPv4 support).
+ * @ingroup networking
*/
MHD_USE_IPv6 = 16,
/**
* Be pedantic about the protocol (as opposed to as tolerant as
* possible). Specifically, at the moment, this flag causes MHD to
- * reject http 1.1 connections without a "Host" header. This is
+ * reject HTTP 1.1 connections without a "Host" header. This is
* required by the standard, but of course in violation of the "be
* as liberal as possible in what you accept" norm. It is
* recommended to turn this ON if you are testing clients against
* MHD, and OFF in production.
+ * @ingroup logging
*/
MHD_USE_PEDANTIC_CHECKS = 32,
/**
* Use poll instead of select. This allows sockets with fd >=
* FD_SETSIZE. This option is not compatible with using an
- * 'external' select mode (as there is no API to get the file
+ * 'external' select() mode (as there is no API to get the file
* descriptors for the external select from MHD) and must also not
- * be used in combination with MHD_USE_EPOLL_LINUX_ONLY.
+ * be used in combination with #MHD_USE_EPOLL_LINUX_ONLY.
+ * @ingroup event
*/
MHD_USE_POLL = 64,
/**
- * Run using an internal thread (or thread pool) doing POLL.
+ * Run using an internal thread (or thread pool) doing poll().
+ * @ingroup event
*/
MHD_USE_POLL_INTERNALLY = MHD_USE_SELECT_INTERNALLY | MHD_USE_POLL,
@@ -394,60 +431,67 @@ enum MHD_FLAG
* This option should ONLY be used on systems that do not have a clock
* and that DO provide other mechanisms for cache control. See also
* RFC 2616, section 14.18 (exception 3).
+ * @ingroup specialized
*/
MHD_SUPPRESS_DATE_NO_CLOCK = 128,
/**
* Run without a listen socket. This option only makes sense if
- * 'MHD_add_connection' is to be used exclusively to connect HTTP
+ * #MHD_add_connection is to be used exclusively to connect HTTP
* clients to the HTTP server. This option is incompatible with
- * using a thread pool; if it is used, 'MHD_OPTION_THREAD_POOL_SIZE'
+ * using a thread pool; if it is used, #MHD_OPTION_THREAD_POOL_SIZE
* is ignored.
+ * @ingroup specialized
*/
MHD_USE_NO_LISTEN_SOCKET = 256,
/**
- * Use 'epoll' instead of 'select' or 'poll' for the event loop.
+ * Use epoll() instead of select() or poll() for the event loop.
* This option is only available on Linux; using the option on
- * non-Linux systems will cause 'MHD_start_daemon' to fail.
+ * non-Linux systems will cause #MHD_start_daemon to fail.
+ * @ingroup event
*/
MHD_USE_EPOLL_LINUX_ONLY = 512,
/**
- * Run using an internal thread (or thread pool) doing EPOLL.
+ * Run using an internal thread (or thread pool) doing epoll().
* This option is only available on Linux; using the option on
- * non-Linux systems will cause 'MHD_start_daemon' to fail.
+ * non-Linux systems will cause #MHD_start_daemon to fail.
+ * @ingroup event
*/
MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY = MHD_USE_SELECT_INTERNALLY | MHD_USE_EPOLL_LINUX_ONLY,
/**
* Force MHD to use a signal pipe to notify the event loop (of
* threads) of our shutdown. This is required if an appliction uses
- * 'MHD_USE_INTERNAL_SELECT' or 'MHD_USE_THREAD_PER_CONNECTION' and
- * then performs 'MHD_quiesce_daemon' (which eliminates our ability
+ * #MHD_USE_INTERNAL_SELECT or #MHD_USE_THREAD_PER_CONNECTION and
+ * then performs #MHD_quiesce_daemon (which eliminates our ability
* to signal termination via the listen socket). In these modes,
- * 'MHD_quiesce_daemon' will fail if this option was not set. Also,
+ * #MHD_quiesce_daemon will fail if this option was not set. Also,
* use of this option is automatic (as in, you do not even have to
- * specify it), if 'MHD_USE_NO_LISTEN_SOCKET' is specified. In
- * "external" select mode, this option is always simply ignored.
+ * specify it), if #MHD_USE_NO_LISTEN_SOCKET is specified. In
+ * "external" select() mode, this option is always simply ignored.
* On W32 a pair of sockets is used instead of a pipe.
*
* You must also use this option if you use internal select mode
- * or a thread pool in conjunction with 'MHD_add_connection'.
+ * or a thread pool in conjunction with #MHD_add_connection.
+ * @ingroup event
*/
MHD_USE_PIPE_FOR_SHUTDOWN = 1024,
/**
* Use a single socket for IPv4 and IPv6.
+ * @ingroup networking
*/
MHD_USE_DUAL_STACK = MHD_USE_IPv6 | 2048,
/**
- * Enable EPOLL turbo. Disables certain calls to 'shutdown'
+ * Enable epoll() turbo. Disables certain calls to shutdown()
* and enables aggressive non-blocking optimisitc reads.
- * Most effects only happen with MHD_USE_EPOLL_LINUX_ONLY.
- * Enalbed always on W32 as winsock doesn't properly behave
- * with shutdown and this then fixes potential problems.
+ * Most effects only happen with #MHD_USE_EPOLL_LINUX_ONLY.
+ * Enalbed always on W32 as winsock does not properly behave
+ * with shutdown() and this then fixes potential problems.
+ * @ingroup event
*/
MHD_USE_EPOLL_TURBO = 4096
@@ -458,14 +502,15 @@ enum MHD_FLAG
* Type of a callback function used for logging by MHD.
*
* @param cls closure
- * @param fm format string (printf-style)
- * @param ap arguments to 'fm'
+ * @param fm format string (printf()-style)
+ * @param ap arguments to @a fm
+ * @ingroup logging
*/
typedef void (*MHD_LogCallback)(void *cls, const char *fm, va_list ap);
/**
- * MHD options. Passed in the varargs portion of MHD_start_daemon.
+ * MHD options. Passed in the varargs portion of #MHD_start_daemon.
*/
enum MHD_OPTION
{
@@ -478,16 +523,18 @@ enum MHD_OPTION
/**
* Maximum memory size per connection (followed by a size_t).
- * Default is 32 kb (MHD_POOL_SIZE_DEFAULT).
+ * Default is 32 kb (#MHD_POOL_SIZE_DEFAULT).
* Values above 128k are unlikely to result in much benefit, as half
* of the memory will be typically used for IO, and TCP buffers are
* unlikely to support window sizes above 64k on most systems.
+ * @ingroup limits
*/
MHD_OPTION_CONNECTION_MEMORY_LIMIT = 1,
/**
* Maximum number of concurrent connections to
* accept (followed by an unsigned int).
+ * @ingroup limits
*/
MHD_OPTION_CONNECTION_LIMIT = 2,
@@ -495,6 +542,7 @@ enum MHD_OPTION
* After how many seconds of inactivity should a
* connection automatically be timed out? (followed
* by an unsigned int; use zero for no timeout).
+ * @ingroup limits
*/
MHD_OPTION_CONNECTION_TIMEOUT = 3,
@@ -503,12 +551,13 @@ enum MHD_OPTION
* been completed (this can be used for application-specific clean
* up). Requests that have never been presented to the application
* (via MHD_AccessHandlerCallback) will not result in
- * notifications.<p>
+ * notifications.
*
* This option should be followed by TWO pointers. First a pointer
* to a function of type "MHD_RequestCompletedCallback" and second a
* pointer to a closure to pass to the request completed callback.
* The second pointer maybe NULL.
+ * @ingroup request
*/
MHD_OPTION_NOTIFY_COMPLETED = 4,
@@ -521,13 +570,15 @@ enum MHD_OPTION
* should be followed by an "unsigned int". The default is
* zero, which means no limit on the number of connections
* from the same IP address.
+ * @ingroup limits
*/
MHD_OPTION_PER_IP_CONNECTION_LIMIT = 5,
/**
* Bind daemon to the supplied sockaddr. this option should be followed by a
- * 'struct sockaddr *'. If 'MHD_USE_IPv6' is specified, the 'struct sockaddr*'
+ * 'struct sockaddr *'. If #MHD_USE_IPv6 is specified, the 'struct sockaddr*'
* should point to a 'struct sockaddr_in6', otherwise to a 'struct sockaddr_in'.
+ * @ingroup networking
*/
MHD_OPTION_SOCK_ADDR = 6,
@@ -539,7 +590,7 @@ enum MHD_OPTION
* logging. This option should be followed by two arguments, the first
* one must be of the form
* <pre>
- * void * my_logger(void * cls, const char * uri)
+ * void * my_logger(void *cls, const char *uri)
* </pre>
* where the return value will be passed as
* (*con_cls) in calls to the MHD_AccessHandlerCallback
@@ -547,26 +598,29 @@ enum MHD_OPTION
* value of NULL has no special significance (however,
* note that if you return non-NULL, you can no longer
* rely on the first call to the access handler having
- * NULL == *con_cls on entry;)
+ * `NULL == *con_cls` on entry;)
* "cls" will be set to the second argument following
- * MHD_OPTION_URI_LOG_CALLBACK. Finally, uri will
+ * #MHD_OPTION_URI_LOG_CALLBACK. Finally, uri will
* be the 0-terminated URI of the request.
+ * @ingroup logging
*/
MHD_OPTION_URI_LOG_CALLBACK = 7,
/**
* Memory pointer for the private key (key.pem) to be used by the
* HTTPS daemon. This option should be followed by an
- * "const char*" argument.
- * This should be used in conjunction with 'MHD_OPTION_HTTPS_MEM_CERT'.
+ * "const char *" argument.
+ * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_CERT.
+ * @ingroup tls
*/
MHD_OPTION_HTTPS_MEM_KEY = 8,
/**
* Memory pointer for the certificate (cert.pem) to be used by the
* HTTPS daemon. This option should be followed by an
- * "const char*" argument.
- * This should be used in conjunction with 'MHD_OPTION_HTTPS_MEM_KEY'.
+ * "const char *" argument.
+ * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY.
+ * @ingroup tls
*/
MHD_OPTION_HTTPS_MEM_CERT = 9,
@@ -574,12 +628,14 @@ enum MHD_OPTION
* Daemon credentials type.
* Followed by an argument of type
* "gnutls_credentials_type_t".
+ * @ingroup tls
*/
MHD_OPTION_HTTPS_CRED_TYPE = 10,
/**
- * Memory pointer to a "const char*" specifying the
+ * Memory pointer to a "const char *" specifying the
* cipher algorithm (default: "NORMAL").
+ * @ingroup tls
*/
MHD_OPTION_HTTPS_PRIORITIES = 11,
@@ -588,6 +644,7 @@ enum MHD_OPTION
* option is used, MHD will not open its own listen socket(s). The
* argument passed must be of type "int" and refer to an
* existing socket that has been bound to a port and is listening.
+ * @ingroup specialized
*/
MHD_OPTION_LISTEN_SOCKET = 12,
@@ -595,14 +652,15 @@ enum MHD_OPTION
* Use the given function for logging error messages.
* This option must be followed by two arguments; the
* first must be a pointer to a function
- * of type "void fun(void * arg, const char * fmt, va_list ap)"
+ * of type `void fun (void *arg, const char *fmt, va_list ap)`
* (also known as MHD_LogCallback)
- * and the second a pointer "void*" which will
+ * and the second a pointer "void *" which will
* be passed as the "arg" argument to "fun".
* <p>
* Note that MHD will not generate any log messages
* if it was compiled without the "--enable-messages"
* flag being set.
+ * @ingroup logging
*/
MHD_OPTION_EXTERNAL_LOGGER = 13,
@@ -610,16 +668,17 @@ enum MHD_OPTION
* Number (unsigned int) of threads in thread pool. Enable
* thread pooling by setting this value to to something
* greater than 1. Currently, thread model must be
- * MHD_USE_SELECT_INTERNALLY if thread pooling is enabled
- * (MHD_start_daemon returns NULL for an unsupported thread
+ * #MHD_USE_SELECT_INTERNALLY if thread pooling is enabled
+ * (#MHD_start_daemon returns NULL for an unsupported thread
* model).
+ * @ingroup event
*/
MHD_OPTION_THREAD_POOL_SIZE = 14,
/**
* Additional options given in an array of "struct MHD_OptionItem".
* The array must be terminated with an entry '{MHD_OPTION_END, 0, NULL}'.
- * An example for code using MHD_OPTION_ARRAY is:
+ * An example for code using #MHD_OPTION_ARRAY is:
* <code>
* struct MHD_OptionItem ops[] = {
* { MHD_OPTION_CONNECTION_LIMIT, 100, NULL },
@@ -634,6 +693,7 @@ enum MHD_OPTION
* second member of the struct MHD_OptionItem is ignored.
* For options that expect two pointer arguments, the first
* argument must be cast to 'intptr_t'.
+ * @ingroup specialized
*/
MHD_OPTION_ARRAY = 15,
@@ -646,14 +706,15 @@ enum MHD_OPTION
* This option should be followed by two arguments, the first
* one must be of the form
* <pre>
- * size_t my_unescaper(void * cls, struct MHD_Connection *c, char *s)
+ * size_t my_unescaper(void *cls, struct MHD_Connection *c, char *s)
* </pre>
* where the return value must be "strlen(s)" and
* "s" should be updated. Note that the unescape function
* must not lengthen "s" (the result must be shorter than
* the input and still be 0-terminated).
* "cls" will be set to the second argument following
- * MHD_OPTION_UNESCAPE_CALLBACK.
+ * #MHD_OPTION_UNESCAPE_CALLBACK.
+ * @ingroup specialized
*/
MHD_OPTION_UNESCAPE_CALLBACK = 16,
@@ -665,6 +726,7 @@ enum MHD_OPTION
* Note that the application must ensure that the buffer of the
* second argument remains allocated and unmodified while the
* deamon is running.
+ * @ingroup auth
*/
MHD_OPTION_DIGEST_AUTH_RANDOM = 17,
@@ -672,12 +734,14 @@ enum MHD_OPTION
* Size of the internal array holding the map of the nonce and
* the nonce counter. This option should be followed by a "unsigend int"
* argument.
+ * @ingroup auth
*/
MHD_OPTION_NONCE_NC_SIZE = 18,
/**
* Desired size of the stack for threads created by MHD. Followed
* by an argument of type 'size_t'. Use 0 for system 'default'.
+ * @ingroup event
*/
MHD_OPTION_THREAD_STACK_SIZE = 19,
@@ -685,24 +749,27 @@ enum MHD_OPTION
* Memory pointer for the certificate (ca.pem) to be used by the
* HTTPS daemon for client authentification.
* This option should be followed by a "const char*" argument.
+ * @ingroup tls
*/
MHD_OPTION_HTTPS_MEM_TRUST = 20,
/**
* Increment to use for growing the read buffer (followed by a
- * size_t). Must fit within MHD_OPTION_CONNECTION_MEMORY_LIMIT.
+ * size_t). Must fit within #MHD_OPTION_CONNECTION_MEMORY_LIMIT.
+ * @ingroup limits
*/
MHD_OPTION_CONNECTION_MEMORY_INCREMENT = 21
};
/**
- * Entry in an MHD_OPTION_ARRAY.
+ * Entry in an #MHD_OPTION_ARRAY.
+ * @ingroup specialized
*/
struct MHD_OptionItem
{
/**
- * Which option is being given. Use MHD_OPTION_END
+ * Which option is being given. Use #MHD_OPTION_END
* to terminate the array.
*/
enum MHD_OPTION option;
@@ -726,23 +793,27 @@ struct MHD_OptionItem
/**
* The MHD_ValueKind specifies the source of
* the key-value pairs in the HTTP protocol.
+ * @ingroup request
*/
enum MHD_ValueKind
{
/**
* Response header
+ * @ingroup response
*/
MHD_RESPONSE_HEADER_KIND = 0,
/**
* HTTP header.
+ * @ingroup request
*/
MHD_HEADER_KIND = 1,
/**
* Cookies. Note that the original HTTP header containing
* the cookie(s) will still be available and intact.
+ * @ingroup request
*/
MHD_COOKIE_KIND = 2,
@@ -753,16 +824,19 @@ enum MHD_ValueKind
* memory pool. Note that in that case, the upload data
* given to the MHD_AccessHandlerCallback will be
* empty (since it has already been processed).
+ * @ingroup request
*/
MHD_POSTDATA_KIND = 4,
/**
* GET (URI) arguments.
+ * @ingroup request
*/
MHD_GET_ARGUMENT_KIND = 8,
/**
* HTTP footer (only for http 1.1 chunked encodings).
+ * @ingroup request
*/
MHD_FOOTER_KIND = 16
};
@@ -771,12 +845,14 @@ enum MHD_ValueKind
/**
* The MHD_RequestTerminationCode specifies reasons
* why a request has been terminated (or completed).
+ * @ingroup request
*/
enum MHD_RequestTerminationCode
{
/**
* We finished sending the response.
+ * @ingroup request
*/
MHD_REQUEST_TERMINATED_COMPLETED_OK = 0,
@@ -784,28 +860,32 @@ enum MHD_RequestTerminationCode
* Error handling the connection (resources
* exhausted, other side closed connection,
* application error accepting request, etc.)
+ * @ingroup request
*/
MHD_REQUEST_TERMINATED_WITH_ERROR = 1,
/**
* No activity on the connection for the number
* of seconds specified using
- * MHD_OPTION_CONNECTION_TIMEOUT.
+ * #MHD_OPTION_CONNECTION_TIMEOUT.
+ * @ingroup request
*/
MHD_REQUEST_TERMINATED_TIMEOUT_REACHED = 2,
/**
* We had to close the session since MHD was being
* shut down.
+ * @ingroup request
*/
MHD_REQUEST_TERMINATED_DAEMON_SHUTDOWN = 3,
/**
* We tried to read additional data, but the other side closed the
* connection. This error is similar to
- * MHD_REQUEST_TERMINATED_WITH_ERROR, but specific to the case where
+ * #MHD_REQUEST_TERMINATED_WITH_ERROR, but specific to the case where
* the connection died because the other side did not send expected
* data.
+ * @ingroup request
*/
MHD_REQUEST_TERMINATED_READ_ERROR = 4
@@ -815,18 +895,21 @@ enum MHD_RequestTerminationCode
/**
* Values of this enum are used to specify what
* information about a connection is desired.
+ * @ingroup request
*/
enum MHD_ConnectionInfoType
{
/**
* What cipher algorithm is being used.
* Takes no extra arguments.
+ * @ingroup request
*/
MHD_CONNECTION_INFO_CIPHER_ALGO,
/**
*
* Takes no extra arguments.
+ * @ingroup request
*/
MHD_CONNECTION_INFO_PROTOCOL,
@@ -835,16 +918,18 @@ enum MHD_ConnectionInfoType
* Returns essentially a "struct sockaddr **" (since the API returns
* a "union MHD_ConnectionInfo *" and that union contains a "struct
* sockaddr *").
+ * @ingroup request
*/
MHD_CONNECTION_INFO_CLIENT_ADDRESS,
/**
- * Get the GNUTLS session handle.
+ * Get the gnuTLS session handle.
+ * @ingroup request
*/
MHD_CONNECTION_INFO_GNUTLS_SESSION,
/**
- * Get the GNUTLS client certificate handle. Dysfunctional (never
+ * Get the gnuTLS client certificate handle. Dysfunctional (never
* implemented, deprecated). Use MHD_CONNECTION_INFO_GNUTLS_SESSION
* to get the gnutls_session_t and then call
* gnutls_certificate_get_peers().
@@ -853,13 +938,14 @@ enum MHD_ConnectionInfoType
/**
* Get the 'struct MHD_Daemon' responsible for managing this connection.
+ * @ingroup request
*/
MHD_CONNECTION_INFO_DAEMON,
-
/**
* Request the file descriptor for the listening socket.
* No extra arguments should be passed.
+ * @ingroup request
*/
MHD_CONNECTION_INFO_CONNECTION_FD
@@ -893,12 +979,14 @@ enum MHD_DaemonInfoType
/**
* Request the file descriptor for the listening socket.
* No extra arguments should be passed.
+ * @ingroup networking
*/
MHD_DAEMON_INFO_LISTEN_FD,
/**
* Request the file descriptor for the external epoll.
* No extra arguments should be passed.
+ * @ingroup event
*/
MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY
};
@@ -906,6 +994,7 @@ enum MHD_DaemonInfoType
/**
* Handle for the daemon (listening on a socket for HTTP traffic).
+ * @ingroup event
*/
struct MHD_Daemon;
@@ -914,16 +1003,19 @@ struct MHD_Daemon;
* requests can be run over the same connection. However, MHD will
* only show one request per TCP connection to the client at any given
* time.
+ * @ingroup request
*/
struct MHD_Connection;
/**
* Handle for a response.
+ * @ingroup response
*/
struct MHD_Response;
/**
* Handle for POST processing.
+ * @ingroup response
*/
struct MHD_PostProcessor;
@@ -936,6 +1028,7 @@ struct MHD_PostProcessor;
* @param file where the error occured
* @param line where the error occured
* @param reason error detail, may be NULL
+ * @ingroup logging
*/
typedef
void (*MHD_PanicCallback) (void *cls,
@@ -947,8 +1040,8 @@ typedef
* 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
+ * @param addrlen length of @a addr
+ * @return #MHD_YES if connection is allowed, #MHD_NO if not
*/
typedef int
(*MHD_AcceptPolicyCallback) (void *cls,
@@ -973,9 +1066,9 @@ typedef int
* given in upload_data and is instead available as
* part of MHD_get_connection_values; very large POST
* data *will* be made available incrementally in
- * upload_data)
+ * @a upload_data)
* @param upload_data_size set initially to the size of the
- * upload_data provided; the method must update this
+ * @a upload_data provided; the method must update this
* value to the number of bytes NOT processed;
* @param con_cls pointer that the callback can set to some
* address and that will be preserved by MHD for future
@@ -985,15 +1078,15 @@ typedef int
* to easily associate some request-specific state.
* If necessary, this state can be cleaned up in the
* global "MHD_RequestCompleted" callback (which
- * can be set with the MHD_OPTION_NOTIFY_COMPLETED).
+ * can be set with the #MHD_OPTION_NOTIFY_COMPLETED).
* Initially, <tt>*con_cls</tt> will be NULL.
- * @return MHS_YES if the connection was handled successfully,
- * MHS_NO if the socket must be closed due to a serios
+ * @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_Connection * connection,
+ struct MHD_Connection *connection,
const char *url,
const char *method,
const char *version,
@@ -1011,7 +1104,8 @@ typedef int
* @param con_cls value as set by the last call to
* the MHD_AccessHandlerCallback
* @param toe reason for request termination
- * @see MHD_OPTION_NOTIFY_COMPLETED
+ * @see #MHD_OPTION_NOTIFY_COMPLETED
+ * @ingroup request
*/
typedef void
(*MHD_RequestCompletedCallback) (void *cls,
@@ -1027,8 +1121,9 @@ typedef void
* 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
+ * @return #MHD_YES to continue iterating,
+ * #MHD_NO to abort the iteration
+ * @ingroup request
*/
typedef int
(*MHD_KeyValueIterator) (void *cls,
@@ -1038,14 +1133,14 @@ typedef int
/**
* 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
+ * callback is to copy at most @a max bytes of content into @a buf. The
+ * total number of bytes that has been placed into @a 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
+ * 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()).
*
@@ -1059,28 +1154,28 @@ typedef int
* the sum of all non-negative return values
* obtained from the content reader so far.
* @param buf where to copy the data
- * @param max maximum number of bytes to copy to buf (size of buf)
- * @return number of bytes written to 'buf';
+ * @param max maximum number of bytes to copy to @a buf (size of @a buf)
+ * @return number of bytes written to @a buf;
* 0 is legal unless we are running in internal select mode (since
* this would cause busy-waiting); 0 in external select mode
* will cause this function to be called again once the external
* select calls MHD again;
- * MHD_CONTENT_READER_END_OF_STREAM (-1) for the regular
+ * #MHD_CONTENT_READER_END_OF_STREAM (-1) for the regular
* end of transmission (with chunked encoding, MHD will then
* terminate the chunk and send any HTTP footers that might be
* present; without chunked encoding and given an unknown
* response size, MHD will simply close the connection; note
- * that while returning END_OF_STREAM is not technically
+ * that while returning #MHD_CONTENT_READER_END_OF_STREAM is not technically
* legal if a response size was specified, MHD accepts this
- * and treats it just as MHD_CONTENT_READER_END_WITH_ERROR;
- * MHD_CONTENT_READER_END_WITH_ERROR (-2) to indicate a server
+ * and treats it just as #MHD_CONTENT_READER_END_WITH_ERROR;
+ * #MHD_CONTENT_READER_END_WITH_ERROR (-2) to indicate a server
* error generating the response; this will cause MHD to simply
* close the connection immediately. If a response size was
* given or if chunked encoding is in use, this will indicate
* an error to the client. Note, however, that if the client
* does not know a response size and chunked encoding is not in
* use, then clients will not be able to tell the difference between
- * MHD_CONTENT_READER_END_WITH_ERROR and MHD_CONTENT_READER_END_OF_STREAM.
+ * #MHD_CONTENT_READER_END_WITH_ERROR and #MHD_CONTENT_READER_END_OF_STREAM.
* This is not a limitation of MHD but rather of the HTTP protocol.
*/
typedef ssize_t
@@ -1095,6 +1190,9 @@ typedef ssize_t
* are done with a content reader. It should
* be used to free resources associated with the
* content reader.
+ *
+ * @param cls closure
+ * @ingroup response
*/
typedef void
(*MHD_ContentReaderFreeCallback) (void *cls);
@@ -1107,17 +1205,17 @@ typedef void
* POST data.
*
* @param cls user-specified closure
- * @param kind type of the value, always MHD_POSTDATA_KIND when called from MHD
+ * @param kind type of the value, always #MHD_POSTDATA_KIND when called from MHD
* @param key 0-terminated key for the value
* @param filename name of the uploaded file, NULL if not known
* @param content_type mime-type of the data, NULL if not known
* @param transfer_encoding encoding of the data, NULL if not known
- * @param data pointer to size bytes of data at the
+ * @param data pointer to @a size bytes of data at the
* specified offset
* @param off offset of data in the overall value
- * @param size number of bytes in data available
- * @return MHD_YES to continue iterating,
- * MHD_NO to abort the iteration
+ * @param size number of bytes in @a data available
+ * @return #MHD_YES to continue iterating,
+ * #MHD_NO to abort the iteration
*/
typedef int
(*MHD_PostDataIterator) (void *cls,
@@ -1143,10 +1241,11 @@ typedef int
* accepted
* @param apc_cls extra argument to apc
* @param dh handler called for all requests (repeatedly)
- * @param dh_cls extra argument to dh
+ * @param dh_cls extra argument to @a dh
* @param ap list of options (type-value pairs,
- * terminated with MHD_OPTION_END).
+ * terminated with #MHD_OPTION_END).
* @return NULL on error, handle to daemon on success
+ * @ingroup event
*/
struct MHD_Daemon *
MHD_start_daemon_va (unsigned int flags,
@@ -1158,7 +1257,7 @@ MHD_start_daemon_va (unsigned int flags,
/**
* Start a webserver on the given port. Variadic version of
- * MHD_start_daemon_va.
+ * #MHD_start_daemon_va.
*
* @param flags combination of MHD_FLAG values
* @param port port to bind to
@@ -1168,8 +1267,9 @@ MHD_start_daemon_va (unsigned int flags,
* accepted
* @param apc_cls extra argument to apc
* @param dh handler called for all requests (repeatedly)
- * @param dh_cls extra argument to dh
+ * @param dh_cls extra argument to @a dh
* @return NULL on error, handle to daemon on success
+ * @ingroup event
*/
struct MHD_Daemon *
MHD_start_daemon (unsigned int flags,
@@ -1185,17 +1285,18 @@ MHD_start_daemon (unsigned int flags,
* connections. Note that the caller is responsible for closing the
* returned socket; however, if MHD is run using threads (anything but
* external select mode), it must not be closed until AFTER
- * "MHD_stop_daemon" has been called (as it is theoretically possible
+ * #MHD_stop_daemon has been called (as it is theoretically possible
* that an existing thread is still using it).
*
* Note that some thread modes require the caller to have passed
- * MHD_USE_PIPE_FOR_SHUTDOWN when using this API. If this daemon is
+ * #MHD_USE_PIPE_FOR_SHUTDOWN when using this API. If this daemon is
* in one of those modes and this option was not given to
- * 'MHD_start_daemon', this function will return -1.
+ * #MHD_start_daemon, this function will return -1.
*
* @param daemon daemon to stop accepting new connections for
* @return old listen socket on success, -1 if the daemon was
* already not listening anymore
+ * @ingroup specialized
*/
int
MHD_quiesce_daemon (struct MHD_Daemon *daemon);
@@ -1205,6 +1306,7 @@ MHD_quiesce_daemon (struct MHD_Daemon *daemon);
* Shutdown an http daemon.
*
* @param daemon daemon to stop
+ * @ingroup event
*/
void
MHD_stop_daemon (struct MHD_Daemon *daemon);
@@ -1219,7 +1321,7 @@ MHD_stop_daemon (struct MHD_Daemon *daemon);
*
* If you use this API in conjunction with a internal select or a
* thread pool, you must set the option
- * @code{MHD_USE_PIPE_FOR_SHUTDOWN} to ensure that the freshly added
+ * #MHD_USE_PIPE_FOR_SHUTDOWN to ensure that the freshly added
* connection is immediately processed by MHD.
*
* The given client socket will be managed (and closed!) by MHD after
@@ -1230,11 +1332,12 @@ MHD_stop_daemon (struct MHD_Daemon *daemon);
* @param client_socket socket to manage (MHD will expect
* to receive an HTTP request from this socket next).
* @param addr IP address of the client
- * @param addrlen number of bytes in addr
- * @return MHD_YES on success, MHD_NO if this daemon could
- * not handle the connection (i.e. malloc failed, etc).
- * The socket will be closed in any case; 'errno' is
+ * @param addrlen number of bytes in @a addr
+ * @return #MHD_YES on success, #MHD_NO if this daemon could
+ * not handle the connection (i.e. malloc() failed, etc).
+ * The socket will be closed in any case; @code{errno} is
* set to indicate further details about the error.
+ * @ingroup specialized
*/
int
MHD_add_connection (struct MHD_Daemon *daemon,
@@ -1252,9 +1355,10 @@ MHD_add_connection (struct MHD_Daemon *daemon,
* @param except_fd_set except set
* @param max_fd increased to largest FD added (if larger
* than existing value); can be NULL
- * @return MHD_YES on success, MHD_NO if this
+ * @return #MHD_YES on success, #MHD_NO if this
* daemon was not started with the right
* options for this call.
+ * @ingroup event
*/
int
MHD_get_fdset (struct MHD_Daemon *daemon,
@@ -1265,40 +1369,41 @@ MHD_get_fdset (struct MHD_Daemon *daemon,
/**
- * Obtain timeout value for select for this daemon (only needed if
- * connection timeout is used). The returned value is how long select
- * should at most block, not the timeout value set for connections.
- * This function MUST NOT be called if MHD is running with
- * "MHD_USE_THREAD_PER_CONNECTION".
+ * Obtain timeout value for select() for this daemon (only needed if
+ * connection timeout is used). The returned value is how long
+ * select() or poll() should at most block, not the timeout value set
+ * for connections. This function MUST NOT be called if MHD is
+ * running with #MHD_USE_THREAD_PER_CONNECTION.
*
* @param daemon daemon to query for timeout
* @param timeout set to the timeout (in milliseconds)
- * @return MHD_YES on success, MHD_NO if timeouts are
+ * @return #MHD_YES on success, #MHD_NO if timeouts are
* not used (or no connections exist that would
* necessiate the use of a timeout right now).
+ * @ingroup event
*/
int MHD_get_timeout (struct MHD_Daemon *daemon,
MHD_UNSIGNED_LONG_LONG *timeout);
/**
- * 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.
+ * 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.
*
* This function is a convenience method, which is useful if the
- * fd_sets from "MHD_get_fdset" were not directly passed to 'select';
- * with this function, MHD will internally do the appropriate 'select'
- * call itself again. While it is always safe to call 'MHD_run' (in
- * external select mode), you should call 'MHD_run_from_select' if
+ * fd_sets from #MHD_get_fdset were not directly passed to select();
+ * with this function, MHD will internally do the appropriate select()
+ * call itself again. While it is always safe to call #MHD_run (in
+ * external select mode), you should call #MHD_run_from_select if
* performance is important (as it saves an expensive call to
- * 'select').
+ * select()).
*
* @param daemon daemon to run
- * @return MHD_YES on success, MHD_NO if this
+ * @return #MHD_YES on success, #MHD_NO if this
* daemon was not started with the right
* options for this call.
+ * @ingroup event
*/
int
MHD_run (struct MHD_Daemon *daemon);
@@ -1306,21 +1411,21 @@ MHD_run (struct MHD_Daemon *daemon);
/**
* Run webserver operations. This method should be called by clients
- * in combination with MHD_get_fdset if the client-controlled select
+ * in combination with #MHD_get_fdset if the client-controlled select
* method is used.
*
- * You can use this function instead of "MHD_run" if you called
- * 'select' on the result from "MHD_get_fdset". File descriptors in
+ * You can use this function instead of #MHD_run if you called
+ * select() on the result from #MHD_get_fdset. File descriptors in
* the sets that are not controlled by MHD will be ignored. Calling
- * this function instead of "MHD_run" is more efficient as MHD will
- * not have to call 'select' again to determine which operations are
+ * this function instead of #MHD_run is more efficient as MHD will
+ * not have to call select() again to determine which operations are
* ready.
*
* @param daemon daemon to run select loop for
* @param read_fd_set read set
* @param write_fd_set write set
* @param except_fd_set except set (not used, can be NULL)
- * @return MHD_NO on serious errors, MHD_YES on success
+ * @return #MHD_NO on serious errors, #MHD_YES on success
*/
int
MHD_run_from_select (struct MHD_Daemon *daemon,
@@ -1340,8 +1445,9 @@ MHD_run_from_select (struct MHD_Daemon *daemon,
* @param kind types of values to iterate over
* @param iterator callback to call on each header;
* maybe NULL (then just count headers)
- * @param iterator_cls extra argument to iterator
+ * @param iterator_cls extra argument to @a iterator
* @return number of entries iterated over
+ * @ingroup request
*/
int
MHD_get_connection_values (struct MHD_Connection *connection,
@@ -1350,33 +1456,29 @@ MHD_get_connection_values (struct MHD_Connection *connection,
/**
- * This function can be used to add an entry to
- * the HTTP headers of a connection (so that the
- * MHD_get_connection_values function will return
- * them -- and the MHD PostProcessor will also
- * see them). This maybe required in certain
- * situations (see Mantis #1399) where (broken)
- * HTTP implementations fail to supply values needed
- * by the post processor (or other parts of the
- * application).
- * <p>
- * This function MUST only be called from within
- * the MHD_AccessHandlerCallback (otherwise, access
- * maybe improperly synchronized). Furthermore,
- * the client must guarantee that the key and
- * value arguments are 0-terminated strings that
- * are NOT freed until the connection is closed.
- * (The easiest way to do this is by passing only
- * arguments to permanently allocated strings.).
+ * This function can be used to add an entry to the HTTP headers of a
+ * connection (so that the #MHD_get_connection_values function will
+ * return them -- and the MHD PostProcessor will also see them). This
+ * maybe required in certain situations (see Mantis #1399) where
+ * (broken) HTTP implementations fail to supply values needed by the
+ * post processor (or other parts of the application).
+ *
+ * This function MUST only be called from within the
+ * MHD_AccessHandlerCallback (otherwise, access maybe improperly
+ * synchronized). Furthermore, the client must guarantee that the key
+ * and value arguments are 0-terminated strings that are NOT freed
+ * until the connection is closed. (The easiest way to do this is by
+ * passing only arguments to permanently allocated strings.).
*
* @param connection the connection for which a
* value should be set
* @param kind kind of the value
* @param key key for the value
* @param value the value itself
- * @return MHD_NO if the operation could not be
+ * @return #MHD_NO if the operation could not be
* performed due to insufficient memory;
- * MHD_YES on success
+ * #MHD_YES on success
+ * @ingroup request
*/
int
MHD_set_connection_value (struct MHD_Connection *connection,
@@ -1386,19 +1488,20 @@ MHD_set_connection_value (struct MHD_Connection *connection,
/**
- * Sets the global error handler to a different implementation. "cb"
+ * Sets the global error handler to a different implementation. @a cb
* will only be called in the case of typically fatal, serious
* internal consistency issues. These issues should only arise in the
* case of serious memory corruption or similar problems with the
- * architecture. While "cb" is allowed to return and MHD will then
+ * architecture. While @a cb is allowed to return and MHD will then
* try to continue, this is never safe.
*
* The default implementation that is used if no panic function is set
- * simply prints an error message and calls "abort". Alternative
- * implementations might call "exit" or other similar functions.
+ * simply prints an error message and calls abort(). Alternative
+ * implementations might call exit() or other similar functions.
*
* @param cb new error handler
- * @param cls passed to error handler
+ * @param cls passed to @a cb
+ * @ingroup logging
*/
void
MHD_set_panic_func (MHD_PanicCallback cb, void *cls);
@@ -1412,6 +1515,7 @@ MHD_set_panic_func (MHD_PanicCallback cb, void *cls);
* @param kind what kind of value are we looking for
* @param key the header to look for, NULL to lookup 'trailing' value without a key
* @return NULL if no such item was found
+ * @ingroup request
*/
const char *
MHD_lookup_connection_value (struct MHD_Connection *connection,
@@ -1426,8 +1530,9 @@ MHD_lookup_connection_value (struct MHD_Connection *connection,
* @param connection the connection 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
+ * @return #MHD_NO on error (i.e. reply already sent),
+ * #MHD_YES on success or if message has been queued
+ * @ingroup response
*/
int
MHD_queue_response (struct MHD_Connection *connection,
@@ -1441,16 +1546,17 @@ MHD_queue_response (struct MHD_Connection *connection,
* 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, MHD_SIZE_UNKNOWN for unknown
+ * @param size size of the data portion of the response, #MHD_SIZE_UNKNOWN for unknown
* @param block_size preferred block size for querying crc (advisory only,
- * MHD may still call crc using smaller chunks); this
+ * MHD may still call @a 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
* @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
+ * @param crc_cls extra argument to @a crc
+ * @param crfc callback to call to free @a crc_cls resources
* @return NULL on error (i.e. invalid arguments, out of memory)
+ * @ingroup response
*/
struct MHD_Response *
MHD_create_response_from_callback (uint64_t size,
@@ -1463,14 +1569,15 @@ MHD_create_response_from_callback (uint64_t size,
* 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 size size of the @a 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
+ * @param must_copy libmicrohttpd must make a copy of @a data
* right away, the data maybe released anytime after
* this call returns
* @return NULL on error (i.e. invalid arguments, out of memory)
- * @deprecated use MHD_create_response_from_buffer instead
+ * @deprecated use #MHD_create_response_from_buffer instead
+ * @ingroup response
*/
struct MHD_Response *
MHD_create_response_from_data (size_t size,
@@ -1482,28 +1589,33 @@ MHD_create_response_from_data (size_t size,
/**
* Specification for how MHD should treat the memory buffer
* given for the response.
+ * @ingroup response
*/
-enum MHD_ResponseMemoryMode {
+enum MHD_ResponseMemoryMode
+{
/**
* Buffer is a persistent (static/global) buffer that won't change
* for at least the lifetime of the response, MHD should just use
* it, not free it, not copy it, just keep an alias to it.
+ * @ingroup response
*/
MHD_RESPMEM_PERSISTENT,
/**
- * Buffer is heap-allocated with 'malloc' (or equivalent) and
+ * Buffer is heap-allocated with malloc() (or equivalent) and
* should be freed by MHD after processing the response has
* concluded (response reference counter reaches zero).
+ * @ingroup response
*/
MHD_RESPMEM_MUST_FREE,
/**
* Buffer is in transient memory, but not on the heap (for example,
* on the stack or non-malloc allocated) and only valid during the
- * call to 'MHD_create_response_from_buffer'. MHD must make its
+ * call to #MHD_create_response_from_buffer. MHD must make its
* own private copy of the data for processing.
+ * @ingroup response
*/
MHD_RESPMEM_MUST_COPY
@@ -1518,6 +1630,7 @@ enum MHD_ResponseMemoryMode {
* @param buffer size bytes containing the response's data portion
* @param mode flags for buffer management
* @return NULL on error (i.e. invalid arguments, out of memory)
+ * @ingroup response
*/
struct MHD_Response *
MHD_create_response_from_buffer (size_t size,
@@ -1534,6 +1647,7 @@ MHD_create_response_from_buffer (size_t size,
* data; will be closed when response is destroyed;
* fd should be in 'blocking' mode
* @return NULL on error (i.e. invalid arguments, out of memory)
+ * @ingroup response
*/
struct MHD_Response *
MHD_create_response_from_fd (size_t size,
@@ -1554,6 +1668,7 @@ MHD_create_response_from_fd (size_t size,
* also has to be compiled using the same options! Read
* the MHD manual for more details.
* @return NULL on error (i.e. invalid arguments, out of memory)
+ * @ingroup response
*/
struct MHD_Response *
MHD_create_response_from_fd_at_offset (size_t size,
@@ -1702,8 +1817,10 @@ MHD_create_response_for_upgrade (MHD_UpgradeHandler upgrade_handler,
* necessarily be freed immediatley.
*
* @param response response to destroy
+ * @ingroup response
*/
-void MHD_destroy_response (struct MHD_Response *response);
+void
+MHD_destroy_response (struct MHD_Response *response);
/**
@@ -1712,8 +1829,9 @@ void MHD_destroy_response (struct MHD_Response *response);
* @param response response to add a header to
* @param header the header to add
* @param content value to add
- * @return MHD_NO on error (i.e. invalid header or content format),
+ * @return #MHD_NO on error (i.e. invalid header or content format),
* or out of memory
+ * @ingroup response
*/
int
MHD_add_response_header (struct MHD_Response *response,
@@ -1726,7 +1844,8 @@ MHD_add_response_header (struct MHD_Response *response,
* @param response response to remove a header from
* @param footer the footer to delete
* @param content value to delete
- * @return MHD_NO on error (i.e. invalid footer or content format).
+ * @return #MHD_NO on error (i.e. invalid footer or content format).
+ * @ingroup response
*/
int
MHD_add_response_footer (struct MHD_Response *response,
@@ -1739,7 +1858,8 @@ MHD_add_response_footer (struct MHD_Response *response,
* @param response response to remove a header from
* @param header the header to delete
* @param content value to delete
- * @return MHD_NO on error (no such header known)
+ * @return #MHD_NO on error (no such header known)
+ * @ingroup response
*/
int
MHD_del_response_header (struct MHD_Response *response,
@@ -1752,8 +1872,9 @@ MHD_del_response_header (struct MHD_Response *response,
* @param response response to query
* @param iterator callback to call on each header;
* maybe NULL (then just count headers)
- * @param iterator_cls extra argument to iterator
+ * @param iterator_cls extra argument to @a iterator
* @return number of entries iterated over
+ * @ingroup response
*/
int
MHD_get_response_headers (struct MHD_Response *response,
@@ -1766,9 +1887,11 @@ MHD_get_response_headers (struct MHD_Response *response,
* @param response response to query
* @param key which header to get
* @return NULL if header does not exist
+ * @ingroup response
*/
-const char *MHD_get_response_header (struct MHD_Response *response,
- const char *key);
+const char *
+MHD_get_response_header (struct MHD_Response *response,
+ const char *key);
/* ********************** PostProcessor functions ********************** */
@@ -1779,7 +1902,7 @@ const char *MHD_get_response_header (struct MHD_Response *response,
* A PostProcessor can be used to (incrementally) parse the data
* portion of a POST request. Note that some buggy browsers fail to
* set the encoding type. If you want to support those, you may have
- * to call 'MHD_set_connection_value' with the proper encoding type
+ * to call #MHD_set_connection_value with the proper encoding type
* before creating a post processor (if no supported encoding type is
* set, this function will fail).
*
@@ -1793,41 +1916,44 @@ const char *MHD_get_response_header (struct MHD_Response *response,
* performance, use 32 or 64k (i.e. 65536).
* @param iter iterator to be called with the parsed data,
* Must NOT be NULL.
- * @param iter_cls first argument to iter
- * @return NULL on error (out of memory, unsupported encoding),
- * otherwise a PP handle
+ * @param iter_cls first argument to @a iter
+ * @return NULL on error (out of memory, unsupported encoding),
+ * otherwise a PP handle
+ * @ingroup request
*/
struct MHD_PostProcessor *
MHD_create_post_processor (struct MHD_Connection *connection,
size_t buffer_size,
MHD_PostDataIterator iter, void *iter_cls);
+
/**
- * Parse and process POST data.
- * Call this function when POST data is available
- * (usually during an MHD_AccessHandlerCallback)
- * with the upload_data and upload_data_size.
- * Whenever possible, this will then cause calls
- * to the MHD_IncrementalKeyValueIterator.
+ * Parse and process POST data. Call this function when POST data is
+ * available (usually during an MHD_AccessHandlerCallback) with the
+ * upload_data and upload_data_size. Whenever possible, this will
+ * then cause calls to the MHD_IncrementalKeyValueIterator.
*
* @param pp the post processor
- * @param post_data post_data_len bytes of POST data
- * @param post_data_len length of post_data
- * @return MHD_YES on success, MHD_NO on error
+ * @param post_data @a post_data_len bytes of POST data
+ * @param post_data_len length of @a post_data
+ * @return #MHD_YES on success, #MHD_NO on error
* (out-of-memory, iterator aborted, parse error)
+ * @ingroup request
*/
int
MHD_post_process (struct MHD_PostProcessor *pp,
const char *post_data, size_t post_data_len);
+
/**
* Release PostProcessor resources.
*
* @param pp the PostProcessor to destroy
- * @return MHD_YES if processing completed nicely,
- * MHD_NO if there were spurious characters / formatting
+ * @return #MHD_YES if processing completed nicely,
+ * #MHD_NO if there were spurious characters / formatting
* problems; it is common to ignore the return
* value of this function
+ * @ingroup request
*/
int
MHD_destroy_post_processor (struct MHD_PostProcessor *pp);
@@ -1839,6 +1965,7 @@ MHD_destroy_post_processor (struct MHD_PostProcessor *pp);
/**
* Constant to indicate that the nonce of the provided
* authentication code was wrong.
+ * @ingroup authentication
*/
#define MHD_INVALID_NONCE -1
@@ -1849,6 +1976,7 @@ MHD_destroy_post_processor (struct MHD_PostProcessor *pp);
* @param connection The MHD connection structure
* @return NULL if no username could be found, a pointer
* to the username if found
+ * @ingroup authentication
*/
char *
MHD_digest_auth_get_username (struct MHD_Connection *connection);
@@ -1863,8 +1991,9 @@ MHD_digest_auth_get_username (struct MHD_Connection *connection);
* @param password The password used in the authentication
* @param nonce_timeout The amount of time for a nonce to be
* invalid in seconds
- * @return MHD_YES if authenticated, MHD_NO if not,
- * MHD_INVALID_NONCE if nonce is invalid
+ * @return #MHD_YES if authenticated, #MHD_NO if not,
+ * #MHD_INVALID_NONCE if nonce is invalid
+ * @ingroup authentication
*/
int
MHD_digest_auth_check (struct MHD_Connection *connection,
@@ -1883,9 +2012,10 @@ MHD_digest_auth_check (struct MHD_Connection *connection,
* @param response reply to send; should contain the "access denied"
* body; note that this function will set the "WWW Authenticate"
* header and that the caller should not do this
- * @param signal_stale MHD_YES if the nonce is invalid to add
+ * @param signal_stale #MHD_YES if the nonce is invalid to add
* 'stale=true' to the authentication header
- * @return MHD_YES on success, MHD_NO otherwise
+ * @return #MHD_YES on success, #MHD_NO otherwise
+ * @ingroup authentication
*/
int
MHD_queue_auth_fail_response (struct MHD_Connection *connection,
@@ -1902,6 +2032,7 @@ MHD_queue_auth_fail_response (struct MHD_Connection *connection,
* @param password a pointer for the password
* @return NULL if no username could be found, a pointer
* to the username if found
+ * @ingroup authentication
*/
char *
MHD_basic_auth_get_username_password (struct MHD_Connection *connection,
@@ -1916,7 +2047,8 @@ MHD_basic_auth_get_username_password (struct MHD_Connection *connection,
* @param connection The MHD connection structure
* @param realm the realm presented to the client
* @param response response object to modify and queue
- * @return MHD_YES on success, MHD_NO otherwise
+ * @return #MHD_YES on success, #MHD_NO otherwise
+ * @ingroup authentication
*/
int
MHD_queue_basic_auth_fail_response (struct MHD_Connection *connection,
@@ -1933,41 +2065,49 @@ union MHD_ConnectionInfo
/**
* Cipher algorithm used, of type "enum gnutls_cipher_algorithm".
+ * @ingroup tls
*/
int /* enum gnutls_cipher_algorithm */ cipher_algorithm;
/**
* Protocol used, of type "enum gnutls_protocol".
+ * @ingroup tls
*/
int /* enum gnutls_protocol */ protocol;
/**
* Connect socket
+ * @ingroup networking
*/
int connect_fd;
/**
* GNUtls session handle, of type "gnutls_session_t".
+ * @ingroup tls
*/
void * /* gnutls_session_t */ tls_session;
/**
* GNUtls client certificate handle, of type "gnutls_x509_crt_t".
+ * @ingroup tls
*/
void * /* gnutls_x509_crt_t */ client_cert;
/**
* Address information for the client.
+ * @ingroup networking
*/
struct sockaddr *client_addr;
/**
* Which daemon manages this connection (useful in case there are many
* daemons running).
+ * @ingroup specialized
*/
struct MHD_Daemon *daemon;
};
+
/**
* Obtain information about the given connection.
*
@@ -1976,6 +2116,7 @@ union MHD_ConnectionInfo
* @param ... depends on infoType
* @return NULL if this information is not available
* (or if the infoType is unknown)
+ * @ingroup specialized
*/
const union MHD_ConnectionInfo *
MHD_get_connection_info (struct MHD_Connection *connection,
@@ -1984,8 +2125,9 @@ MHD_get_connection_info (struct MHD_Connection *connection,
/**
- * MHD connection options. Given to 'MHD_set_connection_option' to
+ * MHD connection options. Given to #MHD_set_connection_option to
* set custom options for a particular connection.
+ * @ingroup specialized
*/
enum MHD_CONNECTION_OPTION
{
@@ -1994,6 +2136,7 @@ enum MHD_CONNECTION_OPTION
* Set a custom timeout for the given connection. Specified
* as the number of seconds, given as an 'unsigned int'. Use
* zero for no timeout.
+ * @ingroup limits
*/
MHD_CONNECTION_OPTION_TIMEOUT
@@ -2006,7 +2149,8 @@ enum MHD_CONNECTION_OPTION
* @param connection connection to modify
* @param option option to set
* @param ... arguments to the option, depending on the option type
- * @return MHD_YES on success, MHD_NO if setting the option failed
+ * @return #MHD_YES on success, #MHD_NO if setting the option failed
+ * @ingroup specialized
*/
int
MHD_set_connection_option (struct MHD_Connection *connection,
@@ -2016,25 +2160,30 @@ MHD_set_connection_option (struct MHD_Connection *connection,
/**
* Information about an MHD daemon.
+ * @ingroup specialized
*/
union MHD_DaemonInfo
{
/**
* Size of the key (unit??)
+ * @ingroup tls
*/
size_t key_size;
/**
* Size of the mac key (unit??)
+ * @ingroup tls
*/
size_t mac_key_size;
/**
* Listen socket file descriptor
+ * @ingroup networking
*/
int listen_fd;
};
+
/**
* Obtain information about the given daemon
* (not fully implemented!).
@@ -2044,6 +2193,7 @@ union MHD_DaemonInfo
* @param ... depends on infoType
* @return NULL if this information is not available
* (or if the infoType is unknown)
+ * @ingroup specialized
*/
const union MHD_DaemonInfo *
MHD_get_daemon_info (struct MHD_Daemon *daemon,
@@ -2055,10 +2205,12 @@ MHD_get_daemon_info (struct MHD_Daemon *daemon,
* Obtain the version of this library
*
* @return static version string, e.g. "0.9.9"
+ * @ingroup specialized
*/
const char*
MHD_get_version (void);
+
#if 0 /* keep Emacsens' auto-indent happy */
{
#endif
