[libmicrohttpd2] branch master updated: introspection chapter skeleton

[Admin]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository libmicrohttpd2.

The following commit(s) were added to refs/heads/master by this push:
     new ce8259d  introspection chapter skeleton
ce8259d is described below

commit ce8259d5416b803e51f4f63f9e68d5b8816e17cb
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Mon Feb 17 22:35:29 2025 +0100

    introspection chapter skeleton
---
 doc/libmicrohttpd2.texi      |  12 +-
 doc/manual/introspection.inc | 784 +++++++++++++++++++++++++++++++++----------
 2 files changed, 618 insertions(+), 178 deletions(-)

diff --git a/doc/libmicrohttpd2.texi b/doc/libmicrohttpd2.texi
index 56f96d3..05e38c4 100644
--- a/doc/libmicrohttpd2.texi
+++ b/doc/libmicrohttpd2.texi
@@ -64,10 +64,9 @@ Free Documentation License".
 * libmicrohttpd2-post::             Parsing @code{POST} data.
 * libmicrohttpd2-auth::             Using HTTP authentication.
 * libmicrohttpd2-upgrade::          Upgrading HTTP/1.1 connections.
-* libmicrohttpd2-introspection::    Obtaining status information.
+* libmicrohttpd2-introspection::    Introspecting MHD objects.
 * libmicrohttpd2-util::             Utilities and special-use functions.
 * libmicrohttpd2-migration::        Migration from GNU libmicrohttpd 1.0.
-* libmicrohttpd2-flow::             Flow control?
 
 Appendices
 
@@ -118,6 +117,11 @@ Indices
 @chapter Using HTTP authentication
 @include manual/authentication.inc
 
+@node libmicrohttpd2-introspection
+@chapter Introspecting MHD objects.
+@include manual/introspection.inc
+
+
 @c NEXT:
 @c - introspection [Mo]
 @c - upgrade + response-upgrade [Di]
@@ -129,10 +133,6 @@ Indices
 @bye
 
 
-@node libmicrohttpd2-info
-@chapter Obtaining and modifying status information.
-@include manual/introspection.inc
-
 @node libmicrohttpd2-websocket
 @chapter Websocket functions.
 @include manual/websocket.inc
diff --git a/doc/manual/introspection.inc b/doc/manual/introspection.inc
index 98a4b62..800248b 100644
--- a/doc/manual/introspection.inc
+++ b/doc/manual/introspection.inc
@@ -1,259 +1,699 @@
+This chapter explains how applications can introspect the state of the
+MHD library, a @code{struct MHD_Daemon}, a @code{struct
+MHD_Connection}, a @code{struct MHD_Session} or a
+@code{MHD_Request}. Now, until now most of the discussed APIs have
+primarily interacted with a daemon or a request, which raises the
+question how applications can even get hold of a connection or
+session. The two main ways are either to set daemon options to receive
+callbacks (say when a connection or session is established or
+completed), or via introspection of a given request.
+
+All introspection APIs work in a similar way: they are given the
+object to inspect, a member of an enumeration specifying what
+property the application is interested in, and a pointer to a
+@code{union} where MHD is to store the value of the property.
+
+Introspection APIs for each type of object are split into two
+sub-APIs. One function to obtain @emph{fixed} data that never changes
+during the lifetime of the inspected object and that the application
+can thus continue to reference until the underlying object is
+destroyed, and a second function to obtain @emph{dynamic} data that is
+ephemeral and that can change over time (including becoming available
+later or disappearing) and where the application thus has to be
+careful when to ask for the data and to not keep pointers to stale
+addresses.
+
+Furthermore, each of the two sub-APIs comes in two variants, one
+main function (such as @code{MHD_daemon_get_info_dynamic_sz()})
+and associated macro (for example, @code{MHD_daemon_get_info_dynamic()})
+that the application should actually use. The difference between
+the macro and the function is that the function takes an extra
+@code{size_t} argument that specifies the size of the
+@code{union} used for the @var{output}. This argument allows MHD
+to check that the application's output buffer is of sufficient
+size, which could be important if the @code{union} changes between
+MHD versions and thus the application possibly has been built with
+a different @code{union} definition.  The macro simply runs
+@code{sizeof()} on the @var{output} variable to provide the
+size of the application's allocation. If the buffer is too small
+for the requested information, MHD fails safe and returns
+@code{MHD_SC_INFO_GET_BUFF_TOO_SMALL}.  In the next subsections
+we will thus only present the macros that applications should
+use, and skip over the @code{_sz()}-functions with the extra
+@code{size_t} argument.
 
 @menu
-* microhttpd-info daemon::      State information about an MHD daemon
-* microhttpd-info conn::        State information about a connection
-* microhttpd-option conn::      Modify per-connection options
+* libmicrohttpd-info library::     State information about the library
+* libmicrohttpd-info daemon::      State information about a daemon
+* libmicrohttpd-info connection::  State information about a connection
+* libmicrohttpd-info session::     State information about a session
+* libmicrohttpd-info request::     State information about a request
 @end menu
 
+@node libmicrohttpd-info library
+@section Obtaining state information about the MHD library
 
-@c ------------------------------------------------------------
-@node microhttpd-info daemon
-@section Obtaining state information about an MHD daemon
+This introspection API returns information about how the MHD
+library was compiled. It is primarily useful for applications
+that want to double-check that particular features are available.
 
-@deftypefun {const union MHD_DaemonInfo *} MHD_get_daemon_info (struct 
MHD_Daemon *daemon, enum MHD_DaemonInfoType infoType, ...)
-Obtain information about the given daemon.  This function
-is currently not fully implemented.
+@anchor{MHD_lib_get_info_fixed}
+@deftypefun {enum MHD_StatusCode} MHD_lib_get_info_fixed (enum 
MHD_LibInfoFixed info_type, union MHD_LibInfoFixedData *output_buf)
+
+Obtain information about the MHD library.
+
+@table @var
+@item info_type
+the type of information that is desired
+
+@item output_buf
+where to write the desired information (which member is set depends on 
@var{info_type})
+@end table
+
+Returns a status code:
+@itemize
+@item @code{MHD_SC_OK} on success,
+@item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown,
+@item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL}
+  if @var{output_buf} is too small for this request
+@end itemize
+The list is not exhaustive, other error codes may be added in the future.
+@end deftypefun
+
+@anchor{MHD_LibInfoFixed}
+@deftp {Enumeration} MHD_LibInfoFixed
+Values of this enum are used to specify what
+dynamic information about a daemon is desired.
+
+@table @code
+
+@item FIXME_CONSTANT_NAME
+FIXME_CONSTANT_DESCRIPTION
+
+@end table
+@end deftp
+
+
+@anchor{MHD_LibInfoFixedData}
+@deftp {C Union} MHD_LibInfoFixedData
+Represents introspection data that can be returned about the
+MHD library. Which member will be set on success depends on the value
+given for @var{info_type}.
+@table @var
+@item @code{FIXME_DATATYPE} FIXME_name
+FIXME_DESCRIPTION.
+
+@end table
+@end deftp
+
+
+
+@anchor{MHD_lib_get_info_dynamic}
+@deftypefun {enum MHD_StatusCode} MHD_lib_get_info_dynamic (enum 
MHD_LibInfoDynamicType info_type, union MHD_LibInfoDynamicData *output_buf)
+
+Obtain information about the MHD library.
+This information may change after the start of MHD.
+
+@table @var
+@item info_type
+the type of information that is desired
+
+@item output_buf
+where to write the desired information (which member is set depends on 
@var{info_type})
+@end table
+
+Returns a status code:
+@itemize
+@item @code{MHD_SC_OK} on success,
+@item @code{MHD_SC_TOO_EARLY} if the information is not yet available,
+  usually because the respective stage in processing was not yet reached,
+@item @code{MHD_SC_TOO_LATE} if the information is no longer available,
+  usually because processing is past the stage where the information is kept,
+@item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown,
+@item @code{MHD_SC_INFO_GET_TYPE_NOT_APPLICABLE}
+  if the requested information is not available for this specific
+  object due to how that object was configured
+@item @code{MHD_SC_INFO_GET_TYPE_UNOBTAINABLE}
+  if the requested information should be available
+  but cannot be provided due to some error or other reason,
+@item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL}
+  if @var{output_buf} is too small for this request
+@end itemize
+The list is not exhaustive, other error codes may be added in the future.
+@end deftypefun
+
+
+@anchor{MHD_LibInfoDynamic}
+@deftp {Enumeration} MHD_LibInfoDynamic
+Values of this enum are used to specify what
+dynamic information about a lib is desired.
+
+@table @code
+@item FIXME_CONSTANT_NAME
+FIXME_CONSTANT_DESCRIPTION
+
+@end table
+@end deftp
+
+
+@deftp {C Union} MHD_LibInfoDynamicData
+Represents introspection data that can be returned about a
+@var{lib}. Which member will be set on success depends on the value
+given for @var{info_type}.
+@table @var
+@item @code{FIXME_DATATYPE} FIXME_name
+FIXME_DESCRIPTION.
+
+@end table
+@end deftp
+
+
+
+@node libmicrohttpd-info daemon
+@section Obtaining state information about a daemon
+
+This introspection API returns information about a daemon.
+
+@anchor{MHD_daemon_get_info_fixed}
+@deftypefun {enum MHD_StatusCode} MHD_daemon_get_info_fixed (struct MHD_Daemon 
*daemon, enum MHD_DaemonInfoFixed info_type, union MHD_DaemonInfoFixedData 
*output_buf)
+
+Obtain information about the MHD @var{daemon}.
+The information returned is not changed at after the start
+of the daemon until the daemon is destroyed.
+
+@table @var
+@item info_type
+the type of information that is desired
+
+@item output_buf
+where to write the desired information (which member is set depends on 
@var{info_type})
+@end table
+
+Returns a status code:
+@itemize
+@item @code{MHD_SC_OK} on success,
+@c FIXME: can we really have TOO_EARLY/TOO_LATE for *fixed* data?
+@item @code{MHD_SC_TOO_EARLY} if the information is not yet available,
+  usually because the respective stage in processing was not yet reached,
+@item @code{MHD_SC_TOO_LATE} if the information is no longer available,
+  usually because processing is past the stage where the information is kept,
+@item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown,
+@item @code{MHD_SC_INFO_GET_TYPE_NOT_APPLICABLE}
+  if the requested information is not available for this specific
+  object due to how that object was configured
+@item @code{MHD_SC_INFO_GET_TYPE_UNOBTAINABLE}
+  if the requested information should be available
+  but cannot be provided due to some error or other reason,
+@item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL}
+  if @var{output_buf} is too small for this request
+@end itemize
+The list is not exhaustive, other error codes may be added in the future.
+@end deftypefun
+
+
+@anchor{MHD_DaemonInfoFixed}
+@deftp {Enumeration} MHD_DaemonInfoFixed
+Values of this enum are used to specify what
+dynamic information about a @var{daemon} is desired.
+
+@table @code
+@item FIXME_CONSTANT_NAME
+FIXME_CONSTANT_DESCRIPTION
+
+@end table
+@end deftp
+
+
+@anchor{MHD_DaemonInfoFixedData}
+@deftp {C Union} MHD_DaemonInfoFixedData
+Represents introspection data that can be returned about a
+@var{daemon}. Which member will be set on success depends on the value
+given for @var{info_type}.
+@table @var
+@item @code{FIXME_DATATYPE} FIXME_name
+FIXME_DESCRIPTION.
+
+@end table
+@end deftp
+
+@anchor{MHD_daemon_get_info_dynamic}
+@deftypefun {enum MHD_StatusCode} MHD_daemon_get_info_dynamic (struct 
MHD_Daemon *daemon, enum MHD_DaemonInfoDynamicType info_type, union 
MHD_DaemonInfoDynamicData *output_buf)
+
+Obtain information about the given @var{daemon}.
+This information may change after the start of the @var{daemon}.
 
 @table @var
 @item daemon
 the daemon about which information is desired;
 
-@item infoType
-type of information that is desired
+@item info_type
+the type of information that is desired
 
-@item ...
-additional arguments about the desired information (depending on
-infoType)
+@item output_buf
+where to write the desired information (which member is set depends on 
@var{info_type})
 @end table
 
-Returns a union with the respective member (depending on
-infoType) set to the desired information), or @code{NULL}
-in case the desired information is not available or
-applicable.
+Returns a status code:
+@itemize
+@item @code{MHD_SC_OK} on success,
+@item @code{MHD_SC_TOO_EARLY} if the information is not yet available,
+  usually because the respective stage in processing was not yet reached,
+@item @code{MHD_SC_TOO_LATE} if the information is no longer available,
+  usually because processing is past the stage where the information is kept,
+@item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown,
+@item @code{MHD_SC_INFO_GET_TYPE_NOT_APPLICABLE}
+  if the requested information is not available for this specific
+  object due to how that object was configured
+@item @code{MHD_SC_INFO_GET_TYPE_UNOBTAINABLE}
+  if the requested information should be available
+  but cannot be provided due to some error or other reason,
+@item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL}
+  if @var{output_buf} is too small for this request
+@end itemize
+The list is not exhaustive, other error codes may be added in the future.
 @end deftypefun
 
 
-@deftp {Enumeration} MHD_DaemonInfoType
+@c FIXME: inconsistent suffix "Type" not used for others!
+@anchor{MHD_DaemonInfoDynamicType}
+@deftp {Enumeration} MHD_DaemonInfoDynamicType
 Values of this enum are used to specify what
-information about a daemon is desired.
+dynamic information about a daemon is desired.
+
 @table @code
-@item MHD_DAEMON_INFO_KEY_SIZE
-Request information about the key size for a particular cipher
-algorithm.  The cipher algorithm should be passed as an extra argument
-(of type 'enum MHD_GNUTLS_CipherAlgorithm').  No longer supported,
-using this value will cause @code{MHD_get_daemon_info} to return NULL.
-
-@item MHD_DAEMON_INFO_MAC_KEY_SIZE
-Request information about the key size for a particular cipher
-algorithm.  The cipher algorithm should be passed as an extra argument
-(of type 'enum MHD_GNUTLS_HashAlgorithm').  No longer supported,
-using this value will cause @code{MHD_get_daemon_info} to return NULL.
-
-@item MHD_DAEMON_INFO_LISTEN_FD
-@cindex listen
-Request the file-descriptor number that MHD is using to listen to the
-server socket.  This can be useful if no port
-was specified and a client needs to learn what port
-is actually being used by MHD.
-No extra arguments should be passed.
-
-@item MHD_DAEMON_INFO_EPOLL_FD
-@cindex epoll
-Request the file-descriptor number that MHD is using for epoll.  If
-the build is not supporting epoll, NULL is returned; if we are using a
-thread pool or this daemon was not started with
-@code{MHD_USE_EPOLL}, (a pointer to) -1 is returned.  If we are
-using @code{MHD_USE_INTERNAL_POLLING_THREAD} or are in 'external' select mode, 
the
-internal epoll FD is returned.  This function must be used in external
-select mode with epoll to obtain the FD to call epoll on.  No extra
-arguments should be passed.
-
-@item MHD_DAEMON_INFO_CURRENT_CONNECTIONS
-@cindex connection, limiting number of connections
-Request the number of current connections handled by the daemon.  No
-extra arguments should be passed and a pointer to a @code{union
-MHD_DaemonInfo} value is returned, with the @code{num_connections}
-member of type @code{unsigned int} set to the number of active
-connections.
-
-Note that in multi-threaded or internal-select mode, the real number of current
-connections may already be different when @code{MHD_get_daemon_info} returns.
-The number of current connections can be used (even in multi-threaded and
-internal-select mode) after @code{MHD_quiesce_daemon} to detect whether all
-connections have been handled.
+@item FIXME_CONSTANT_NAME
+FIXME_CONSTANT_DESCRIPTION
 
 @end table
 @end deftp
 
 
+@deftp {C Union} MHD_DaemonInfoDynamicData
+Represents introspection data that can be returned about a
+@var{daemon}. Which member will be set on success depends on the value
+given for @var{info_type}.
+@table @var
+@item @code{FIXME_DATATYPE} FIXME_name
+FIXME_DESCRIPTION.
 
-@c ------------------------------------------------------------
-@node microhttpd-info conn
+@end table
+@end deftp
+
+
+@node libmicrohttpd-info connection
 @section Obtaining state information about a connection
 
+This introspection API returns information about a connection.
+
+
+@anchor{MHD_connection_get_info_fixed}
+@deftypefun {enum MHD_StatusCode} MHD_connection_get_info_fixed (struct 
MHD_Connection *connection, enum MHD_ConnectionInfoFixed info_type, union 
MHD_ConnectionInfoFixedData *output_buf)
 
-@deftypefun {const union MHD_ConnectionInfo *} MHD_get_connection_info (struct 
MHD_Connection *connection, enum MHD_ConnectionInfoType infoType, ...)
-Obtain information about the given connection.
+Obtain information about the MHD @var{connection}.
+The information returned is not changed at after the start
+of the connection until the connection is destroyed.
+
+@table @var
+@item info_type
+the type of information that is desired
+
+@item output_buf
+where to write the desired information (which member is set depends on 
@var{info_type})
+@end table
+
+Returns a status code:
+@itemize
+@item @code{MHD_SC_OK} on success,
+@c FIXME: can we really have TOO_EARLY/TOO_LATE for *fixed* data?
+@item @code{MHD_SC_TOO_EARLY} if the information is not yet available,
+  usually because the respective stage in processing was not yet reached,
+@item @code{MHD_SC_TOO_LATE} if the information is no longer available,
+  usually because processing is past the stage where the information is kept,
+@item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown,
+@item @code{MHD_SC_INFO_GET_TYPE_NOT_APPLICABLE}
+  if the requested information is not available for this specific
+  object due to how that object was configured
+@item @code{MHD_SC_INFO_GET_TYPE_UNOBTAINABLE}
+  if the requested information should be available
+  but cannot be provided due to some error or other reason,
+@item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL}
+  if @var{output_buf} is too small for this request
+@end itemize
+The list is not exhaustive, other error codes may be added in the future.
+@end deftypefun
+
+
+@anchor{MHD_ConnectionInfoFixed}
+@deftp {Enumeration} MHD_ConnectionInfoFixed
+Values of this enum are used to specify what
+dynamic information about a @var{connection} is desired.
+
+@table @code
+@item FIXME_CONSTANT_NAME
+FIXME_CONSTANT_DESCRIPTION
+
+@end table
+@end deftp
+
+
+@anchor{MHD_ConnectionInfoFixedData}
+@deftp {C Union} MHD_ConnectionInfoFixedData
+Represents introspection data that can be returned about a
+@var{connection}. Which member will be set on success depends on the value
+given for @var{info_type}.
+@table @var
+@item @code{FIXME_DATATYPE} FIXME_name
+FIXME_DESCRIPTION.
+
+@end table
+@end deftp
+
+
+@anchor{MHD_connection_get_info_dynamic}
+@deftypefun {enum MHD_StatusCode} MHD_connection_get_info_dynamic (struct 
MHD_Connection *connection, enum MHD_ConnectionInfoDynamicType info_type, union 
MHD_ConnectionInfoDynamicData *output_buf)
+
+Obtain information about the given @var{connection}.
+This information may change after the start of the @var{connection}.
 
 @table @var
 @item connection
 the connection about which information is desired;
 
-@item infoType
-type of information that is desired
+@item info_type
+the type of information that is desired
 
-@item ...
-additional arguments about the desired information (depending on
-infoType)
+@item output_buf
+where to write the desired information (which member is set depends on 
@var{info_type})
 @end table
 
-Returns a union with the respective member (depending on
-infoType) set to the desired information), or @code{NULL}
-in case the desired information is not available or
-applicable.
+Returns a status code:
+@itemize
+@item @code{MHD_SC_OK} on success,
+@item @code{MHD_SC_TOO_EARLY} if the information is not yet available,
+  usually because the respective stage in processing was not yet reached,
+@item @code{MHD_SC_TOO_LATE} if the information is no longer available,
+  usually because processing is past the stage where the information is kept,
+@item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown,
+@item @code{MHD_SC_INFO_GET_TYPE_NOT_APPLICABLE}
+  if the requested information is not available for this specific
+  object due to how that object was configured
+@item @code{MHD_SC_INFO_GET_TYPE_UNOBTAINABLE}
+  if the requested information should be available
+  but cannot be provided due to some error or other reason,
+@item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL}
+  if @var{output_buf} is too small for this request
+@end itemize
+The list is not exhaustive, other error codes may be added in the future.
 @end deftypefun
 
-@deftp {Enumeration} MHD_ConnectionInfoType
-Values of this enum are used to specify what information about a
-connection is desired.
+
+@c FIXME: inconsistent suffix "Type" not used for others!
+@deftp {Enumeration} MHD_ConnectionInfoDynamicType
+Values of this enum are used to specify what
+dynamic information about a connection is desired.
 
 @table @code
+@item FIXME_CONSTANT_NAME
+FIXME_CONSTANT_DESCRIPTION
 
-@item MHD_CONNECTION_INFO_CIPHER_ALGO
-What cipher algorithm is being used (HTTPS connections only).
-@code{NULL} is returned for non-HTTPS connections.
+@end table
+@end deftp
 
-Takes no extra arguments.
 
-@item MHD_CONNECTION_INFO_PROTOCOL,
-Allows finding out the TLS/SSL protocol used
-(HTTPS connections only).
-@code{NULL} is returned for non-HTTPS connections.
+@deftp {C Union} MHD_ConnectionInfoDynamicData
+Represents introspection data that can be returned about a
+@var{connection}. Which member will be set on success depends on the value
+given for @var{info_type}.
+@table @var
+@item @code{FIXME_DATATYPE} FIXME_name
+FIXME_DESCRIPTION.
 
-Takes no extra arguments.
+@end table
+@end deftp
 
-@item MHD_CONNECTION_INFO_CLIENT_ADDRESS
-Returns information about the address of the client.  Returns
-essentially a @code{struct sockaddr **} (since the API returns
-a @code{union MHD_ConnectionInfo *} and that union contains
-a @code{struct sockaddr *}).
 
-Takes no extra arguments.
 
-@item MHD_CONNECTION_INFO_GNUTLS_SESSION,
-Takes no extra arguments.  Allows access to the underlying GNUtls session,
-including access to the underlying GNUtls client certificate
-(HTTPS connections only).  Takes no extra arguments.
-@code{NULL} is returned for non-HTTPS connections.
+@node libmicrohttpd-info session
+@section Obtaining state information about a session
 
-Takes no extra arguments.
 
-@item MHD_CONNECTION_INFO_GNUTLS_CLIENT_CERT,
-Dysfunctional (never implemented, deprecated).  Use
-MHD_CONNECTION_INFO_GNUTLS_SESSION to get the @code{gnutls_session_t}
-and then call @code{gnutls_certificate_get_peers()}.
+This introspection API returns information about a session.
 
-@item MHD_CONNECTION_INFO_DAEMON
-Returns information about @code{struct MHD_Daemon} which manages
-this connection.
+@deftypefun {enum MHD_StatusCode} MHD_session_get_info_fixed (struct 
MHD_Session *session, enum MHD_SessionInfoFixed info_type, union 
MHD_SessionInfoFixedData *output_buf)
 
-Takes no extra arguments.
+Obtain information about the MHD @var{session}.
+The information returned is not changed at after the start
+of the session until the session is destroyed.
 
-@item MHD_CONNECTION_INFO_CONNECTION_FD
-Returns the file descriptor (usually a TCP socket) associated with
-this connection (in the ``connect-fd'' member of the returned struct).
-Note that manipulating the descriptor directly can have problematic
-consequences (as in, break HTTP).  Applications might use this access
-to manipulate TCP options, for example to set the ``TCP-NODELAY''
-option for COMET-like applications.  Note that MHD will set TCP-CORK
-after sending the HTTP header and clear it after finishing the footers
-automatically (if the platform supports it).  As the connection
-callbacks are invoked in between, those might be used to set different
-values for TCP-CORK and TCP-NODELAY in the meantime.
+@table @var
+@item info_type
+the type of information that is desired
 
-Takes no extra arguments.
+@item output_buf
+where to write the desired information (which member is set depends on 
@var{info_type})
+@end table
 
-@item MHD_CONNECTION_INFO_CONNECTION_SUSPENDED
-Returns pointer to an integer that is @code{MHD_YES} if the connection
-is currently suspended (and thus can be safely resumed) and
-@code{MHD_NO} otherwise.
+Returns a status code:
+@itemize
+@item @code{MHD_SC_OK} on success,
+@c FIXME: can we really have TOO_EARLY/TOO_LATE for *fixed* data?
+@item @code{MHD_SC_TOO_EARLY} if the information is not yet available,
+  usually because the respective stage in processing was not yet reached,
+@item @code{MHD_SC_TOO_LATE} if the information is no longer available,
+  usually because processing is past the stage where the information is kept,
+@item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown,
+@item @code{MHD_SC_INFO_GET_TYPE_NOT_APPLICABLE}
+  if the requested information is not available for this specific
+  object due to how that object was configured
+@item @code{MHD_SC_INFO_GET_TYPE_UNOBTAINABLE}
+  if the requested information should be available
+  but cannot be provided due to some error or other reason,
+@item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL}
+  if @var{output_buf} is too small for this request
+@end itemize
+The list is not exhaustive, other error codes may be added in the future.
+@end deftypefun
 
-Takes no extra arguments.
 
-@item MHD_CONNECTION_INFO_SOCKET_CONTEXT
-Returns the client-specific pointer to a @code{void *} that was
-(possibly) set during a @code{MHD_NotifyConnectionCallback} when the
-socket was first accepted.  Note that this is NOT the same as the
-@code{req_cls} argument of the @code{MHD_AccessHandlerCallback}.  The
-@code{req_cls} is fresh for each HTTP request, while the
-@code{socket_context} is fresh for each socket.
+@deftp {Enumeration} MHD_SessionInfoFixed
+Values of this enum are used to specify what
+dynamic information about a @var{session} is desired.
 
-Takes no extra arguments.
+@table @code
+@item FIXME_CONSTANT_NAME
+FIXME_CONSTANT_DESCRIPTION
 
-@item MHD_CONNECTION_INFO_CONNECTION_TIMEOUT
-Returns pointer to an @code{unsigned int} that is the current timeout
-used for the connection (in seconds, 0 for no timeout).  Note that
-while suspended connections will not timeout, the timeout value
-returned for suspended connections will be the timeout that the
-connection will use after it is resumed, and thus might not be zero.
+@end table
+@end deftp
 
-Takes no extra arguments.
 
-@item MHD_CONNECTION_INFO_REQUEST_HEADER_SIZE
-@cindex performance
-Returns pointer to an @code{size_t} that represents the size of the
-HTTP header received from the client. Only valid after the first callback
-to the access handler.
+@deftp {C Union} MHD_SessionInfoFixedData
+Represents introspection data that can be returned about a
+@var{session}. Which member will be set on success depends on the value
+given for @var{info_type}.
+@table @var
+@item @code{FIXME_DATATYPE} FIXME_name
+FIXME_DESCRIPTION.
 
-Takes no extra arguments.
+@end table
+@end deftp
+
+
+@deftypefun {enum MHD_StatusCode} MHD_session_get_info_dynamic (struct 
MHD_Session *session, enum MHD_SessionInfoDynamicType info_type, union 
MHD_SessionInfoDynamicData *output_buf)
+
+Obtain information about the given @var{session}.
+This information may change after the start of the @var{session}.
 
-@item MHD_CONNECTION_INFO_HTTP_STATUS
-Returns the HTTP status code of the response that was
-queued. Returns NULL if no response was queued yet.
+@table @var
+@item session
+the session about which information is desired;
 
-Takes no extra arguments.
+@item info_type
+the type of information that is desired
+
+@item output_buf
+where to write the desired information (which member is set depends on 
@var{info_type})
+@end table
+
+Returns a status code:
+@itemize
+@item @code{MHD_SC_OK} on success,
+@item @code{MHD_SC_TOO_EARLY} if the information is not yet available,
+  usually because the respective stage in processing was not yet reached,
+@item @code{MHD_SC_TOO_LATE} if the information is no longer available,
+  usually because processing is past the stage where the information is kept,
+@item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown,
+@item @code{MHD_SC_INFO_GET_TYPE_NOT_APPLICABLE}
+  if the requested information is not available for this specific
+  object due to how that object was configured
+@item @code{MHD_SC_INFO_GET_TYPE_UNOBTAINABLE}
+  if the requested information should be available
+  but cannot be provided due to some error or other reason,
+@item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL}
+  if @var{output_buf} is too small for this request
+@end itemize
+The list is not exhaustive, other error codes may be added in the future.
+@end deftypefun
+
+
+@c FIXME: inconsistent suffix "Type" not used for others!
+@anchor{MHD_SessionInfoDynamicType}
+@deftp {Enumeration} MHD_SessionInfoDynamicType
+Values of this enum are used to specify what
+dynamic information about a session is desired.
+
+@table @code
+@item FIXME_CONSTANT_NAME
+FIXME_CONSTANT_DESCRIPTION
+
+@end table
+@end deftp
+
+
+@anchor{MHD_SessionInfoDynamicData}
+@deftp {C Union} MHD_SessionInfoDynamicData
+Represents introspection data that can be returned about a
+@var{session}. Which member will be set on success depends on the value
+given for @var{info_type}.
+@table @var
+@item @code{FIXME_DATATYPE} FIXME_name
+FIXME_DESCRIPTION.
 
 @end table
 @end deftp
 
 
 
-@c ------------------------------------------------------------
-@node microhttpd-option conn
-@section Setting custom options for an individual connection
-@cindex timeout
+@node libmicrohttpd-info request
+@section Obtaining state information about a request
 
 
+This introspection API returns information about a request.
 
-@deftypefun {int} MHD_set_connection_option (struct MHD_Connection *daemon, 
enum MHD_CONNECTION_OPTION option, ...)
-Set a custom option for the given connection.
+@anchor{MHD_request_get_info_fixed}
+@deftypefun {enum MHD_StatusCode} MHD_request_get_info_fixed (struct 
MHD_Request *request, enum MHD_RequestInfoFixed info_type, union 
MHD_RequestInfoFixedData *output_buf)
+
+Obtain information about the MHD @var{request}.
+The information returned is not changed at after the start
+of the request until the request is destroyed.
 
 @table @var
-@item connection
-the connection for which an option should be set or modified;
+@item info_type
+the type of information that is desired
+
+@item output_buf
+where to write the desired information (which member is set depends on 
@var{info_type})
+@end table
+
+Returns a status code:
+@itemize
+@item @code{MHD_SC_OK} on success,
+@c FIXME: can we really have TOO_EARLY/TOO_LATE for *fixed* data?
+@item @code{MHD_SC_TOO_EARLY} if the information is not yet available,
+  usually because the respective stage in processing was not yet reached,
+@item @code{MHD_SC_TOO_LATE} if the information is no longer available,
+  usually because processing is past the stage where the information is kept,
+@item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown,
+@item @code{MHD_SC_INFO_GET_TYPE_NOT_APPLICABLE}
+  if the requested information is not available for this specific
+  object due to how that object was configured
+@item @code{MHD_SC_INFO_GET_TYPE_UNOBTAINABLE}
+  if the requested information should be available
+  but cannot be provided due to some error or other reason,
+@item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL}
+  if @var{output_buf} is too small for this request
+@end itemize
+The list is not exhaustive, other error codes may be added in the future.
+@end deftypefun
+
+
+@anchor{MHD_RequestInfoFixed}
+@deftp {Enumeration} MHD_RequestInfoFixed
+Values of this enum are used to specify what
+dynamic information about a @var{request} is desired.
+
+@table @code
+@item FIXME_CONSTANT_NAME
+FIXME_CONSTANT_DESCRIPTION
+
+@end table
+@end deftp
+
 
-@item option
-option to set
+@anchor{MHD_RequestInfoFixedData}
+@deftp {C Union} MHD_RequestInfoFixedData
+Represents introspection data that can be returned about a
+@var{request}. Which member will be set on success depends on the value
+given for @var{info_type}.
+@table @var
+@item @code{FIXME_DATATYPE} FIXME_name
+FIXME_DESCRIPTION.
 
-@item ...
-additional arguments for the option (depending on option)
 @end table
+@end deftp
+
+
+@anchor{MHD_request_get_info_dynamic}
+@deftypefun {enum MHD_StatusCode} MHD_request_get_info_dynamic (struct 
MHD_Request *request, enum MHD_RequestInfoDynamicType info_type, union 
MHD_RequestInfoDynamicData *output_buf)
 
-Returns @code{MHD_YES} on success, @code{MHD_NO} for errors
-(i.e. option argument invalid or option unknown).
+Obtain information about the given @var{request}.
+This information may change after the start of the @var{request},
+especially when the application provides MHD with actions.
+
+@table @var
+@item request
+the request about which information is desired;
+
+@item info_type
+the type of information that is desired
+
+@item output_buf
+where to write the desired information (which member is set depends on 
@var{info_type})
+@end table
+
+Returns a status code:
+@itemize
+@item @code{MHD_SC_OK} on success,
+@item @code{MHD_SC_TOO_EARLY} if the information is not yet available,
+  usually because the respective stage in processing was not yet reached,
+@item @code{MHD_SC_TOO_LATE} if the information is no longer available,
+  usually because processing is past the stage where the information is kept,
+@item @code{MHD_SC_INFO_GET_TYPE_UNKNOWN} if @var{info_type} is unknown,
+@item @code{MHD_SC_INFO_GET_TYPE_NOT_APPLICABLE}
+  if the requested information is not available for this specific
+  object due to how that object was configured
+@item @code{MHD_SC_INFO_GET_TYPE_UNOBTAINABLE}
+  if the requested information should be available
+  but cannot be provided due to some error or other reason,
+@item @code{MHD_SC_INFO_GET_BUFF_TOO_SMALL}
+  if @var{output_buf} is too small for this request
+@end itemize
+The list is not exhaustive, other error codes may be added in the future.
 @end deftypefun
 
 
-@deftp {Enumeration} MHD_CONNECTION_OPTION
-Values of this enum are used to specify which option for a
-connection should be changed.
+@c FIXME: inconsistent suffix "Type" not used for others!
+@anchor{MHD_RequestInfoDynamicType}
+@deftp {Enumeration} MHD_RequestInfoDynamicType
+Values of this enum are used to specify what
+dynamic information about a request is desired.
 
 @table @code
+@item FIXME_CONSTANT_NAME
+FIXME_CONSTANT_DESCRIPTION
 
-@item MHD_CONNECTION_OPTION_TIMEOUT
-Set a custom timeout for the given connection.   Specified
-as the number of seconds, given as an @code{unsigned int}.  Use
-zero for no timeout.
+@end table
+@end deftp
+
+
+@anchor{MHD_RequestInfoDynamicData}
+@deftp {C Union} MHD_RequestInfoDynamicData
+Represents introspection data that can be returned about a
+@var{request}. Which member will be set on success depends on the value
+given for @var{info_type}.
+@table @var
+@item @code{FIXME_DATATYPE} FIXME_name
+FIXME_DESCRIPTION.
 
 @end table
 @end deftp

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.