commit 4811d60ef32482c6a4a8ae86c967d2c870255272
parent f4afef0017a846465600847b0ad68d02e34b01c9
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Mon, 28 Apr 2025 12:20:56 +0200
fix doc compile errors
Diffstat:
15 files changed, 148 insertions(+), 261 deletions(-)
diff --git a/Makefile.am b/Makefile.am
@@ -3,7 +3,7 @@ ACLOCAL_AMFLAGS = -I m4
SUBDIRS = contrib m4 src .
if BUILD_DOC
-# SUBDIRS += doc
+ SUBDIRS += doc
endif
diff --git a/doc/Makefile.am b/doc/Makefile.am
@@ -10,11 +10,21 @@ endif
DISTCLEANFILES = \
libmicrohttpd2.cps \
+ libmicrohttpd2.fn \
+ libmicrohttpd2.toc \
+ libmicrohttpd2.tp \
+ libmicrohttpd2.tps \
+ libmicrohttpd2.aux \
+ libmicrohttpd2.info \
+ libmicrohttpd2.info-1 \
+ libmicrohttpd2.info-2 \
libmicrohttpd2.dvi
info_TEXINFOS = \
libmicrohttpd2.texi
libmicrohttpd_TEXINFOS = \
+ manual/*.inc \
+ examples/*.c \
lgpl.texi \
ecos.texi \
gpl-2.0.texi \
diff --git a/doc/libmicrohttpd2.texi b/doc/libmicrohttpd2.texi
@@ -64,9 +64,10 @@ We are grateful for financial support from the SovereignTechFund
* libmicrohttpd2-requests:: Accessing client request data.
* libmicrohttpd2-actions:: Acting on HTTP requests.
* libmicrohttpd2-responses:: Generating HTTP responses.
-* libmicrohttpd2-post:: Parsing POST data.
-* libmicrohttpd2-auth:: Using HTTP authentication.
+* libmicrohttpd2-postprocessor:: Parsing POST data.
+* libmicrohttpd2-authentication:: Using HTTP authentication.
* libmicrohttpd2-introspection:: Introspecting MHD objects.
+* libmicrohttpd2-utility:: Utility functions.
* libmicrohttpd2-migration:: Migration from GNU libmicrohttpd 1.0.
Appendices
@@ -126,21 +127,17 @@ Indices
@chapter Introspecting MHD objects.
@include manual/introspection.inc
+@node libmicrohttpd2-utility
+@chapter Utility functions.
+@include manual/utility.inc
+
@node libmicrohttpd2-migration
@chapter Migrating code to MHD2
@include manual/migration.inc
-@c NEXT:
-@c - chapter on migration! [Sa+Su]
-
@c FIXME: document other options (connection, request, session)
-@c FIXME: document utility functions
-@c @node libmicrohttpd2-util
-@c @chapter Utility functions.
-@c @include manual/utility.inc
-
@node GNU-LGPL
@unnumbered GNU-LGPL
diff --git a/doc/manual/authentication.inc b/doc/manual/authentication.inc
@@ -29,15 +29,16 @@ user authentication).
@end itemize
@menu
-* libmicrohttpd-dauth basic:: Using Basic Authentication.
+* libmicrohttpd-bauth basic:: Using Basic Authentication.
+* libmicrohttpd-bauth example:: Example for Basic Authentication.
* libmicrohttpd-dauth digest:: Using Digest Authentication.
-* libmicrohttpd-dauth example:: Example for Digest Authentication.
+@c * libmicrohttpd-dauth example:: Example for Digest Authentication.
@c * libmicrohttpd-dauth token:: Using Token Authentication.
@c FIXME * libmicrohttpd-dauth tls:: Using TLS Client Authentication.
@end menu
-@node libmicrohttpd-dauth basic
+@node libmicrohttpd-bauth basic
@section Using Basic Authentication
@cindex basic authentication
@@ -64,7 +65,7 @@ HTTP status code.
If access to any resource should be limited to specific users,
authenticated by basic authentication mechanism, and the request for
this resource does not have basic authentication information
-(@xref{@code{MHD_AuthBasicCreds},,MHD_AuthBasicCreds}), then a
+(see @ref{MHD_AuthBasicCreds,,@code{MHD_AuthBasicCreds}}), then a
response with a basic authentication "challenge" should be sent by
extending an error response using this function. This works as an
indication that basic authentication should be used for the access.
@@ -118,7 +119,7 @@ status code.
If access to any resource should be limited to specific users,
authenticated by basic authentication mechanism, and the request for
this resource does not have basic authentication information
-(@xref{MHD_AuthBasicCreds}), then a response with a basic
+(see @ref{MHD_AuthBasicCreds,,@code{MHD_AuthBasicCreds}}), then a response with a basic
authentication "challenge" should be sent by extending an error
response using this function. This works as an indication that basic
authentication should be used for the access.
@@ -173,6 +174,10 @@ transmission from the client.
@end table
@end deftp
+@node libmicrohttpd-bauth example
+@section Example for Basic Authentication
+@cindex basic authentication
+
@example
@verbatiminclude examples/basic-authentication.c
@@ -202,6 +207,7 @@ MHD supports various features of HTTP digest authentication, including
various hash algorithms and levels of quality of protection (qop) which
must be specified by the application when creating the challenge.
+@anchor{MHD_response_add_auth_digest_challenge}
@deftypefun {enum MHD_StatusCode} MHD_response_add_auth_digest_challenge (struct MHD_Response *response, const char *realm, const char *opaque, const char *domain, enum MHD_Bool indicate_stale, enum MHD_DigestAuthMultiQOP mqop, enum MHD_DigestAuthMultiAlgo malgo, enum MHD_Bool userhash_support, enum MHD_Bool prefer_utf8)
Adds a digest authentication "challenge" to the response.
@@ -263,7 +269,7 @@ nonce and the same credentials, without asking the user
for the new password;
@item mqop
-the quality of protection to use (@xref{MHD_DigestAuthMultiQOP});
+the quality of protection to use (see @ref{MHD_DigestAuthMultiQOP,,@code{MHD_DigestAuthMultiQOP}});
@item algo
digest algorithm to use; if several algorithms are allowed
@@ -278,8 +284,8 @@ note that clients are @emph{allowed} to provide the username
in cleartext even if this parameter set to @code{MHD_YES};
when userhash is used, the application must be ready to
identify users by provided userhash value instead of
-the plaintext username; @xref{MHD_digest_auth_calc_userhash} and
-@xref{MHD_digest_auth_calc_userhash_hex}
+the plaintext username; see @ref{MHD_digest_auth_calc_userhash}
+@c and @ref{MHD_digest_auth_calc_userhash_hex}
@item prefer_utf8
if set to @code{MHD_YES}, the parameter ``charset=UTF-8'' is
@@ -462,7 +468,7 @@ The result of the computation may be cached and reused across requests.
@table @var
@item algo
-the hash algorithm to use for userhash calculations, @xref{MHD_DigestAuthAlgorithm};
+the hash algorithm to use for userhash calculations, see @ref{MHD_DigestAuthAlgorithm};
@item username
the username;
@@ -538,7 +544,7 @@ Return the digest size in bytes for the specified hash algorithm @var{algo}.
@table @var
@item algo
-the hash algorithm to use for userhash calculations, @xref{MHD_DigestAuthAlgorithm};
+the hash algorithm to use for userhash calculations, see @ref{MHD_DigestAuthAlgorithm};
@end table
The function returns the number of bytes of a hash value of the
given @var{algo}. It returns zero if @var{algo} is invalid or
@@ -579,7 +585,7 @@ and enable @var{userhash_support}.
@table @var
@item algo
-the hash algorithm to use for userhash calculations, @xref{MHD_DigestAuthAlgorithm};
+the hash algorithm to use for userhash calculations, see @ref{MHD_DigestAuthAlgorithm};
@item username
the username
@@ -634,7 +640,7 @@ Set automatically to MD5 if not explicitly specified by client.
@item @code{enum MHD_DigestAuthUsernameType} uname_type
The type of username used by client.
-@xref{MHD_DigestAuthUsernameType}
+@xref{MHD_DigestAuthUsernameType}.
@item @code{struct MHD_StringNullable} username
The username as a string.
@@ -688,7 +694,7 @@ A few kilobytes is a reasonable limit, typical values for
@item @code{enum MHD_DigestAuthNC} nc_type
The type of the nonce count (nc) value provided in the request.
-@xref{MHD_DigestAuthNC}
+@xref{MHD_DigestAuthNC}.
@item @code{uint_fast32_t} nc
The nonce count (nc) parameter value.
@@ -717,22 +723,22 @@ Readable hexdecimal non-zero number.
The decoded value is placed in the @var{nc} member of
@ref{MHD_AuthDigestInfo,,@code{MHD_AuthDigestInfo}}.
-@code MHD_DIGEST_AUTH_NC_ZERO
+@item MHD_DIGEST_AUTH_NC_ZERO
Readable zero number.
Compliant clients should not use such values.
Should probably be treated as an invalid request.
-@code MHD_DIGEST_AUTH_NC_NONE
+@item MHD_DIGEST_AUTH_NC_NONE
No @var{nc} value was provided by the client.
Unless old RFC 2069 mode is allowed, this should be treated as an invalid
request.
-@code MHD_DIGEST_AUTH_NC_TOO_LONG
+@item MHD_DIGEST_AUTH_NC_TOO_LONG
The provided ``nc'' value was too long to be decoded.
Compliant clients should not use such values.
Should be treated as an invalid request.
-@code MHD_DIGEST_AUTH_NC_TOO_LARGE
+@item MHD_DIGEST_AUTH_NC_TOO_LARGE
The provided ``nc'' value was too large to fit into a @code{uint32_t}.
Compliant clients should not use such values.
Can be treated as request with a stale nonce or as an invalid request.
@@ -742,6 +748,50 @@ Can be treated as request with a stale nonce or as an invalid request.
@c FIXME: MHD_DigestAuthUsernameType not defined
+@anchor{MHD_DigestAuthUsernameType}
+@deftp {enum} MHD_DigestAuthUsernameType
+
+Type of username encoded by the client in a digest authorization
+header.
+
+@table @var
+@item @code{MHD_DIGEST_AUTH_UNAME_TYPE_MISSING}
+ No username parameter is in Digest Authorization header.
+ Not used currently. Value @code{MHD_SC_REQ_AUTH_DATA_BROKEN} is returned
+ by @ref{MHD_request_get_info_dynamic_sz,,@code{MHD_request_get_info_dynamic_sz()}}
+ if the request has no username.
+
+@item @code{MHD_DIGEST_AUTH_UNAME_TYPE_STANDARD}
+ The 'username' parameter is used to specify the username.
+
+@item @code{MHD_DIGEST_AUTH_UNAME_TYPE_EXTENDED}
+ The username is specified by 'username*' parameter with
+ the extended notation (see RFC 5987, section-3.2.1).
+ The only difference between standard and extended types is
+ the way how username value is encoded in the header.
+
+@item @code{MHD_DIGEST_AUTH_UNAME_TYPE_USERHASH}
+ The username provided in form of 'userhash' as
+ specified by RFC 7616, section-3.4.4.
+ @xref{MHD_digest_auth_calc_userhash,,@code{MHD_digest_auth_calc_userhash()}}.
+
+@item @code{MHD_DIGEST_AUTH_UNAME_TYPE_INVALID}
+ The invalid combination of username parameters are used by client.
+ Either:
+ @itemize @bullet
+ @item both 'username' and 'username*' are used
+ @item 'username*' is used with 'userhash=true'
+ @item 'username*' used with invalid extended notation
+ @item 'username' is not hexadecimal string, while 'userhash' set to 'true'
+ @end itemize
+ Not used currently. Value @code{MHD_SC_REQ_AUTH_DATA_BROKEN} is returned by
+ @ref{MHD_request_get_info_dynamic_sz,,@code{MHD_request_get_info_dynamic_sz()}}
+ if the request has broken username.
+@end table
+@end deftp
+
+
+
Finally, given the client's identity (username or userhash) the
application must possibly determine the username from the userhash,
and always determine the userdigest. Given the @var{username} and
@@ -781,8 +831,8 @@ hashing algorithm;
@item userdigest
the precalculated binary hash of the string
-"username:realm:password",
-@xref{MHD_digest_auth_calc_userdigest,,@code{MHD_digest_auth_calc_userdigest}};
+"username:realm:password";
+see @ref{MHD_digest_auth_calc_userdigest,,@code{MHD_digest_auth_calc_userdigest}};
@item max_nc
the maximum allowed nonce counter (nc) value, if a client's nc
@@ -873,4 +923,13 @@ The 'response' is wrong. May indicate using the wrong password.
@end table
@end deftp
-@c FIXME: we should probably add an example here...
-\ No newline at end of file
+
+@c @node libmicrohttpd-dauth example
+@c @section Example for Digest Authentication
+@c @cindex digest authentication
+
+@c FIXME: we should probably add an example here...
+
+@c @example
+@c @verbatiminclude examples/digest-authentication.c
+@c @end example
diff --git a/doc/manual/callbacks.inc b/doc/manual/callbacks.inc
@@ -15,8 +15,8 @@ length of the address information.
@end deftypefn
-
-@deftypefn {Function Pointer} void {*MHD_RequestCompletedCallback} (void *cls, struct MHD_Connectionconnection, void **req_cls, enum MHD_RequestTerminationCode toe)
+@anchor{MHD_RequestCompletedCallback}
+@deftypefn {Function Pointer} void {*MHD_RequestCompletedCallback} (void *cls, struct MHD_Connection *connection, void **req_cls, enum MHD_RequestTerminationCode toe)
Signature of the callback used by MHD to notify the application about
completed requests.
diff --git a/doc/manual/daemon_options.inc b/doc/manual/daemon_options.inc
@@ -893,10 +893,6 @@ If this option is set but TLS is not enabled overall,
it is silently ignored (does not cause a failure).
By default ALPN is automatically used for TLS connections.
-@table @var
-
-@end table
-
Returns the option to pass to @code{MHD_daemon_set_options()}.
@end deftypefun
@@ -1145,10 +1141,6 @@ Works only with
@code{MHD_D_OPTION_WM_WORKER_THREADS()} or
@code{MHD_D_OPTION_WM_THREAD_PER_CONNECTION()}.
-@table @var
-
-@end table
-
Returns the option to pass to @code{MHD_daemon_set_options()}
@end deftypefun
@@ -1188,10 +1180,6 @@ Disables certain calls to @code{shutdown()}, enables aggressive non-blocking opt
Most effects only happen with internal threads with @code{epoll()}.
The 'turbo' mode is disabled by default.
-@table @var
-
-@end table
-
Returns the option to pass to @code{MHD_daemon_set_options()}.
@end deftypefun
@@ -1204,10 +1192,6 @@ Not compatible with any internal threads modes.
If MHD is compiled with custom configuration for embedded projects without threads support, this option is mandatory.
Thread safety is enabled by default.
-@table @var
-
-@end table
-
Returns the option to pass to @code{MHD_daemon_set_options()}.
@end deftypefun
@@ -1218,10 +1202,6 @@ Upgrade may require usage of additional internal resources, which MHD can avoid
You should only use this option if you do not use upgrade functionality and need a generally minor boost in performance and resources savings.
HTTP upgrade is allowed by default.
-@table @var
-
-@end table
-
Returns the option to pass to @code{MHD_daemon_set_options()}.
@end deftypefun
@@ -1232,10 +1212,6 @@ Disable @ref{MHD_action_suspend,,@code{MHD_action_suspend()}} functionality.
You should only use this function if you do not use suspend functionality and need a generally minor boost in performance.
Suspending requests is allowed by default.
-@table @var
-
-@end table
-
Returns the option to pass to @code{MHD_daemon_set_options()}
@end deftypefun
@@ -1246,10 +1222,6 @@ Disable cookies parsing.
Disable automatic cookies processing if cookies are not used.
Cookies are automatically parsed by default.
-@table @var
-
-@end table
-
Returns the option to pass to @code{MHD_daemon_set_options()}
@end deftypefun
@@ -1266,10 +1238,6 @@ Inform that SIGPIPE is suppressed or handled by application.
If suppressed/handled, MHD uses network functions that could generate SIGPIPE, like @code{sendfile()}.
Silently ignored when MHD creates internal threads as for them SIGPIPE is suppressed automatically.
-@table @var
-
-@end table
-
Returns the option to pass to @code{MHD_daemon_set_options()}.
@end deftypefun
@@ -1281,14 +1249,10 @@ Disable converting plus ('+') character to space in URL arguments (URL part afte
Plus conversion is not required by HTTP RFCs, however it required by HTML specifications, see https://url.spec.whatwg.org/#application/x-www-form-urlencoded for details.
By default plus is converted to space in the query part of a URL.
-@table @var
-
-@end table
-
Returns the option to pass to @code{MHD_daemon_set_options()}.
@end deftypefun
-@cindex{real-time clock}
+@cindex real-time clock
@anchor{MHD_D_OPTION_SUPPRESS_DATE_HEADER}
@deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_SUPPRESS_DATE_HEADER ()
@@ -1296,22 +1260,14 @@ Suppresse use of 'Date:' header.
According to RFC should be suppressed only if the system has no real-time clock (RTC).
The 'Date:' is not suppressed (the header is enabled) by default.
-@table @var
-
-@end table
-
Returns the option to pass to @code{MHD_daemon_set_options()}.
@end deftypefun
-@cindex{Shoutcast}
+@cindex Shoutcast
@deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_ENABLE_SHOUTCAST ()
Use SHOUTcast for responses.
This will cause @emph{all} responses to begin with the SHOUTcast 'ICY' line instead of 'HTTP'.
-@table @var
-
-@end table
-
Returns the option to pass to @code{MHD_daemon_set_options()}.
@end deftypefun
diff --git a/doc/manual/doptions.inc b/doc/manual/doptions.inc
@@ -1,5 +1,5 @@
@anchor{MHD_DaemonOptionAndValue}
-@cindex{option}
+@cindex option
This chapter is about configuring an MHD daemon. MHD daemon
configuration options are represented using a @code{struct
diff --git a/doc/manual/external.inc b/doc/manual/external.inc
@@ -58,7 +58,7 @@ notifying when the status changed to ready) and level triggers
ready).
-@anchor{MHD_SocketRegistrationUpdateCallback}
+@anchor{external-registration}
@node libmicrohttpd-external-registration
@section The @code{MHD_SocketRegistrationUpdateCallback}
@@ -77,7 +77,7 @@ Type of a function for registration or de-registration of the sockets to
watch in the external event loop.
Implementations of this callback must not call
-@ref{MHD_daemon_destroy,,code{MHD_daemon_destroy()}},
+@ref{MHD_daemon_destroy,,@code{MHD_daemon_destroy()}},
@ref{MHD_daemon_quiesce,,@code{MHD_daemon_quiesce()}} or
@ref{MHD_daemon_add_connection,,@code{MHD_daemon_add_connection()}}.
@@ -205,7 +205,7 @@ whenever the specified type of event is triggered, and
MHD to understand which socket changed state.
-@anchor{MHD_daemon_event_update}
+@anchor{external-trigger}
@node libmicrohttpd-external-trigger
@section Notifying MHD that a socket is ready
@@ -246,7 +246,7 @@ update its internal state. To actually do work, applications
must still call @code{MHD_daemon_process_reg_events()}.
-@anchor{MHD_daemon_process_reg_events}
+@anchor{external-runner}
@node libmicrohttpd-external-runner
@section Processing externally triggered events
diff --git a/doc/manual/introduction.inc b/doc/manual/introduction.inc
@@ -178,7 +178,7 @@ In practice, you rarely need to worry about selecting the event
loop style: MHD offers the "automatic" setting, which will pick
the fastest mode available on your platform automatically.
-@xref{libmicrohttpd2-external,,Using external event loops} for details
+@ref{libmicrohttpd2-external,,Using external event loops} for details
on how to use MHD with an external event loop.
@node libmicrohttpd-introduction-compiling
@@ -360,13 +360,14 @@ Similar build commands should work for cross-compilation to other platforms.
Note that you may have to first cross-compile the respective TLS library
to get MHD with TLS support.
-
+@node libmicrohttpd-introduction-w32
@section Portability to W32
MHD in general ported well to W32. Most MHD features are
supported. W32 do not support some functions, like @code{epoll} and
corresponding MHD features are thus not available on W32.
+@node libmicrohttpd-introduction-zos
@section Portability to z/OS
It has been a long time since the developers had access to z/OS.
diff --git a/doc/manual/introspection.inc b/doc/manual/introspection.inc
@@ -80,8 +80,8 @@ Returns a status code:
The list is not exhaustive, other error codes may be added in the future.
@end deftypefun
-@anchor{MHD_LibInfoFixedData}
-@deftp {Enumeration} MHD_LibInfoFixedData
+@anchor{MHD_LibInfoFixed}
+@deftp {Enumeration} MHD_LibInfoFixed
Values of this enum are used to specify what
dynamic information about a daemon is desired.
@@ -602,4 +602,4 @@ FIXME_DESCRIPTION.
@section Obtaining state information about a request
Introspection of requests is described in
-@ref{libmicrohttpd-requests-info}.
+@ref{libmicrohttpd-request-status-info}.
diff --git a/doc/manual/migration.inc b/doc/manual/migration.inc
@@ -477,8 +477,8 @@ type of information requested
@item MHD_REQUEST_INFO_
replaced by @code{MHD_REQUEST_INFO_FIXED_} or
@code{MHD_REQUEST_INFO_DYNAMIC_} depending on the
-type of information requested
-@xref{libmicrohttpd2-info request,,request introspection}
+type of information requested;
+see @ref{libmicrohttpd2-info request,,request introspection}
@item MHD_get_daemon_info
replaced by @ref{MHD_daemon_get_info_fixed} or
@@ -493,8 +493,8 @@ type of information daemoned
@item MHD_DAEMON_INFO_
replaced by @code{MHD_DAEMON_INFO_FIXED_} or
@code{MHD_DAEMON_INFO_DYNAMIC_} depending on the
-type of information daemoned.
-@xref{libmicrohttpd2-info daemon, daemon introspection}
+type of information daemoned;
+see @ref{libmicrohttpd2-info daemon,,daemon introspection}
@end table
diff --git a/doc/manual/requests.inc b/doc/manual/requests.inc
@@ -18,7 +18,7 @@ from the request @emph{header}.
by HTTP clients in the body of a request.
-@node libmicrohttpd-requests-info
+@node libmicrohttpd-requests-name-value-info
@section Inspecting request name-value pairs
When inspecting requests, MHD classifies values from a client's
@@ -241,7 +241,7 @@ value of a ``Host:'' header.
-@node libmicrohttpd-requests-info
+@node libmicrohttpd-request-status-info
@section Obtaining request status information
This section describes the request introspection API. It follows the
@@ -365,8 +365,8 @@ The result is placed in the @var{v_stream} member of @var{output_buf}.
@item MHD_REQUEST_INFO_FIXED_APP_CONTEXT
Returns the pointer to a variable pointing to request-specific
application context data. The same data is provided for
-@ref{MHD_EarlyUriLogCallback,,@code{MHD_EarlyUriLogCallback}} and
-@ref{MHD_RequestTerminationCallback,,@code{MHD_RequestTerminationCallback}}.
+@ref{MHD_EarlyUriLogCallback,,@code{MHD_EarlyUriLogCallback}}.
+@c FIXME and @ref{MHD_RequestCompletedCallback,,@code{MHD_RequestCompletedCallback}}.
By using provided pointer application may get or set the pointer to
any data specific for the particular request.
The result is placed in the @var{v_ppvoid} member of @var{output_buf}.
diff --git a/doc/manual/response_options.inc b/doc/manual/response_options.inc
@@ -36,10 +36,6 @@ response body must be sent to the client. This flag is primarily
intended to be used when automatic "Content-Length" header computation
by MHD is undesirable in response to HEAD requests.
-@table @var
-
-@end table
-
Returns the option to pass to @code{MHD_response_set_options()}.
@end deftypefun
@@ -202,7 +198,8 @@ The response was successfully sent.
The response was successfully sent and connection is being switched to another protocol.
@item MHD_REQUEST_ENDED_TIMEOUT_REACHED
-No activity on the connection for the number of seconds excdeeding the value specified using @ref{MHD_C_OPTION_TIMEOUT}.
+No activity on the connection for the number of seconds exceeding the timeout value.
+@c FIXME: specified using @ref{MHD_C_OPTION_TIMEOUT}.
@item MHD_REQUEST_ENDED_CONNECTION_ERROR
The connection was broken or we had a TLS protocol error.
diff --git a/doc/manual/responses.inc b/doc/manual/responses.inc
@@ -19,19 +19,7 @@ for each request, use it to create an action and it is (automatically)
destroyed:
@example
-struct MHD_Action *
-simple_reply_to_request (struct MHD_Request *request)
-{
- const char *data = "<html><body><p>Error!</p></body></html>";
-
- return MHD_action_from_response (
- request,
- MHD_response_from_buffer_static (
- MHD_HTTP_STATUS_NOT_FOUND,
- strlen(data),
- data);
- );
-}
+@verbatiminclude examples/simple_reply_fragment.c
@end example
The above code will cause MHD to @code{close()} a connection in
@@ -48,11 +36,11 @@ under @ref{MHD_R_OPTION_REUSABLE} in the section on
performance optimization}.
@menu
-* libmicrohttpd-response enqueue:: Returning a response.
-* libmicrohttpd-response create:: Creating responses.
-* libmicrohttpd-response headers:: Adding headers to a response.
-* libmicrohttpd-response options:: Setting response options.
-* libmicrohttpd-upgrade:: Creating a response for protocol upgrades.
+* libmicrohttpd-response enqueue:: Returning a response.
+* libmicrohttpd-response create:: Creating responses.
+* libmicrohttpd-response headers:: Adding headers to a response.
+* libmicrohttpd2-response options:: Setting response options.
+* libmicrohttpd-upgrade:: Creating a response for protocol upgrades.
@end menu
@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@@ -276,9 +264,9 @@ memory.@footnote{See the @code{writev()} POSIX call for an example of
the type of scatter input operationg system interface that MHD might
use to implement this.}
-@cindex{iovec}
-@cindex{scatter write}
-@cindex{writev}
+@cindex iovec
+@cindex scatter write
+@cindex writev
@anchor{MHD_response_from_iovec}
@deftypefun {struct MHD_Response *} MHD_response_from_iovec (enum MHD_HTTP_StatusCode sc, unsigned int iov_count, const struct MHD_IoVec iov[iov_count], MHD_FreeCallback free_cb, void *free_cb_cls)
@@ -318,7 +306,7 @@ The size (in bytes) of the memory region pointed to by @var{iov_base}.
@subsection Responses from file descriptors
-@cindex sendfile()
+@cindex sendfile
@anchor{MHD_response_from_fd}
@deftypefun {struct MHD_Response *} MHD_response_from_fd (enum MHD_HTTP_StatusCode sc, int fd, uint_fast64_t offset, uint_fast64_t size)
@@ -353,7 +341,7 @@ Returns @code{NULL} on error (i.e. invalid arguments, out of memory).
The @var{fd} is closed on error.
@end deftypefun
-@cindex{splice}
+@cindex splice
@anchor{MHD_response_from_pipe}
@deftypefun {struct MHD_Response *} MHD_response_from_pipe (enum MHD_HTTP_StatusCode sc, int fd)
@@ -751,7 +739,7 @@ particular behavior.
@code{MHD_response_add_header()} also prevents applications from setting a
``Content-Length'' header unless special options are set for the
-response (@xref{libmicrohttpd2-response options,,response options}) as
+response (see @ref{libmicrohttpd2-response options,,response options}) as
MHD will automatically set a correct ``Content-Length'' header if it
is possible and allowed by the HTTP protocol.
@@ -1059,7 +1047,7 @@ handle to interact with the client.
@c FIXME: Evgeny: this is correct, right?
When upgrading a connection, applications using an external event loop may
-use the connection @ref{libmicrohttpd-requests-info,,request
+use the connection @ref{libmicrohttpd-request-status-info,,request
introspection API} to obtain the socket underlying the HTTP request
and then add that socket to their own event loop to decide when to
call @code{MHD_upgraded_recv()} and @code{MHD_upgraded_send()}.
diff --git a/doc/manual/utility.inc b/doc/manual/utility.inc
@@ -1,7 +1,7 @@
@menu
* microhttpd-add connection:: Passing externally accepted connections
-* microhttpd-util feature:: Test supported MHD features
-* microhttpd-util unescape:: Unescape strings
+@c * microhttpd-util feature:: Test supported MHD features
+@c * microhttpd-util unescape:: Unescape strings
@end menu
@@ -10,8 +10,8 @@
@section Passing externally accepted connections
-
-@deftypefun void MHD_add_connection (struct MHD_Daemon *daemon, int client_socket, const struct sockaddr *addr, socklen_t addrlen)
+@anchor{MHD_daemon_add_connection}
+@deftypefun void MHD_daemon_add_connection (struct MHD_Daemon *daemon, MHD_Socket client_socket, size_t addrlen, const struct sockaddr *addr, void *connection_cntx)
Add another client connection to the set of connections
managed by MHD. This API is usually not needed (since
MHD will accept inbound connections on the server socket).
@@ -19,149 +19,29 @@ Use this API in special cases, for example if your HTTP
server is behind NAT and needs to connect out to the
HTTP client, or if you are building a proxy.
-If you use this API in conjunction with a internal select or a thread
-pool, you must set the option @code{MHD_USE_ITC} to
-ensure that the freshly added connection is immediately processed by
-MHD.
-
The given client socket will be managed (and closed!) by MHD after
this call and must no longer be used directly by the application
afterwards.
+The client socket will be closed by MHD even if error returned.
+
@table @var
@item daemon
daemon that manages the connection
@item client_socket
socket to manage (MHD will expect to receive an HTTP request from this socket next).
+@item addrlen
+number of bytes in @var{addr}
@item addr
IP address of the client
-@item addrlen
-number of bytes in addr
+@item connection_cntx meta data the application wants to
+ * associate with the new connection object
@end table
-This function will return @code{MHD_YES} on success,
-@code{MHD_NO} if this daemon could
+This function will return @code{MHD_SC_OK} on success,
+or an code indicating an error if this daemon could
not handle the connection (i.e. malloc failed, etc).
-The socket will be closed in any case; 'errno' is set
-to indicate further details about the error.
+The socket will be closed in any case.
@end deftypefun
-
-@c ------------------------------------------------------------
-@node microhttpd-util feature
-@section Testing for supported MHD features
-
-
-@deftp {Enumeration} MHD_FEATURE
-Values of this enum are used to specify what
-information about a daemon is desired.
-@table @code
-@item MHD_FEATURE_MESSAGES
-Get whether messages are supported. If supported then in debug
-mode messages can be printed to stderr or to external logger.
-
-@item MHD_FEATURE_SSL
-Get whether HTTPS is supported. If supported then flag
-MHD_USE_SSL and options MHD_OPTION_HTTPS_MEM_KEY,
-MHD_OPTION_HTTPS_MEM_CERT, MHD_OPTION_HTTPS_MEM_TRUST,
-MHD_OPTION_HTTPS_MEM_DHPARAMS, MHD_OPTION_HTTPS_CRED_TYPE,
-MHD_OPTION_HTTPS_PRIORITIES can be used.
-
-@item MHD_FEATURE_HTTPS_CERT_CALLBACK
-Get whether option #MHD_OPTION_HTTPS_CERT_CALLBACK is
-supported.
-
-@item MHD_FEATURE_IPv6
-Get whether IPv6 is supported. If supported then flag
-MHD_USE_IPv6 can be used.
-
-@item MHD_FEATURE_IPv6_ONLY
-Get whether IPv6 without IPv4 is supported. If not supported
-then IPv4 is always enabled in IPv6 sockets and
-flag MHD_USE_DUAL_STACK if always used when MHD_USE_IPv6 is
-specified.
-
-@item MHD_FEATURE_POLL
-Get whether @code{poll()} is supported. If supported then flag
-MHD_USE_POLL can be used.
-
-@item MHD_FEATURE_EPOLL
-Get whether @code{epoll()} is supported. If supported then Flags
-MHD_USE_EPOLL and
-MHD_USE_EPOLL_INTERNAL_THREAD can be used.
-
-@item MHD_FEATURE_SHUTDOWN_LISTEN_SOCKET
-Get whether shutdown on listen socket to signal other
-threads is supported. If not supported flag
-MHD_USE_ITC is automatically forced.
-
-@item MHD_FEATURE_SOCKETPAIR
-Get whether a @code{socketpair()} is used internally instead of
-a @code{pipe()} to signal other threads.
-
-@item MHD_FEATURE_TCP_FASTOPEN
-Get whether TCP Fast Open is supported. If supported then
-flag MHD_USE_TCP_FASTOPEN and option
-MHD_OPTION_TCP_FASTOPEN_QUEUE_SIZE can be used.
-
-@item MHD_FEATURE_BASIC_AUTH
-Get whether HTTP Basic authorization is supported. If supported
-then functions @code{MHD_basic_auth_get_username_password()} and
-@code{MHD_queue_basic_auth_fail_response()} can be used.
-
-@item MHD_FEATURE_DIGEST_AUTH
-Get whether HTTP Digest authorization is supported. If
-supported then options MHD_OPTION_DIGEST_AUTH_RANDOM,
-MHD_OPTION_NONCE_NC_SIZE and functions @code{MHD_digest_auth_check()},
-can be used.
-
-@item MHD_FEATURE_POSTPROCESSOR
-Get whether postprocessor is supported. If supported then
-functions @code{MHD_create_post_processor()},
-@code{MHD_post_process()}, @code{MHD_destroy_post_processor()}
-can be used.
-
-@item MHD_FEATURE_SENDFILE
-Get whether @code{sendfile()} is supported.
-
-@end table
-@end deftp
-
-
-
-@deftypefun {int} MHD_is_feature_supported (enum MHD_FEATURE feature)
-Get information about supported MHD features. Indicate that MHD was
-compiled with or without support for particular feature. Some features
-require additional support by the kernel. However, kernel support is not
-checked by this function.
-
-@table @var
-@item feature
-type of requested information
-@end table
-
-Returns @code{MHD_YES} if the feature is supported,
-and @code{MHD_NO} if not.
-@end deftypefun
-
-
-@c ------------------------------------------------------------
-@node microhttpd-util unescape
-@section Unescape strings
-
-@deftypefun {size_t} MHD_http_unescape (char *val)
-Process escape sequences ('%HH') Updates val in place; the result
-should be UTF-8 encoded and cannot be larger than the input. The
-result must also still be 0-terminated.
-
-@table @var
-@item val
-value to unescape (modified in the process), must be
-a 0-terminated UTF-8 string.
-@end table
-
-Returns length of the resulting val (@code{strlen(val)} may be
-shorter afterwards due to elimination of escape sequences).
-
-@end deftypefun
