[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[libmicrohttpd2] branch master updated: fix misc internal links
|
From: |
Admin |
|
Subject: |
[libmicrohttpd2] branch master updated: fix misc internal links |
|
Date: |
Mon, 24 Feb 2025 17:02:55 +0100 |
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 0ff262a fix misc internal links
0ff262a is described below
commit 0ff262a8591517a9466fec55518926f99735c506
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Mon Feb 24 17:02:52 2025 +0100
fix misc internal links
---
doc/libmicrohttpd2.texi | 3 +-
doc/manual/actions.inc | 8 +-
doc/manual/authentication.inc | 35 ++-
doc/manual/constants.inc | 664 ----------------------------------------
doc/manual/daemon_options.inc | 14 +-
doc/manual/doptions.inc | 1 +
doc/manual/external.inc | 5 +-
doc/manual/init.inc | 48 ++-
doc/manual/introduction.inc | 12 +-
doc/manual/postprocessor.inc | 10 +-
doc/manual/requests.inc | 20 +-
doc/manual/response_options.inc | 6 +-
doc/manual/responses.inc | 128 ++++++--
13 files changed, 205 insertions(+), 749 deletions(-)
diff --git a/doc/libmicrohttpd2.texi b/doc/libmicrohttpd2.texi
index a7b69f7..ee4a64e 100644
--- a/doc/libmicrohttpd2.texi
+++ b/doc/libmicrohttpd2.texi
@@ -63,7 +63,6 @@ Free Documentation License".
* libmicrohttpd2-responses:: Generating HTTP responses.
* libmicrohttpd2-post:: Parsing @code{POST} data.
* libmicrohttpd2-auth:: Using HTTP authentication.
-* libmicrohttpd2-upgrade:: Upgrading HTTP/1.1 connections.
* libmicrohttpd2-introspection:: Introspecting MHD objects.
* libmicrohttpd2-migration:: Migration from GNU libmicrohttpd 1.0.
@@ -112,7 +111,7 @@ Indices
@chapter Responses to HTTP requests
@include manual/responses.inc
-@node libmicrohttpd2-post
+@node libmicrohttpd2-postprocessor
@chapter Parsing HTML form data with the POST processor
@include manual/postprocessor.inc
diff --git a/doc/manual/actions.inc b/doc/manual/actions.inc
index 9fb6019..7f5b190 100644
--- a/doc/manual/actions.inc
+++ b/doc/manual/actions.inc
@@ -40,7 +40,7 @@ detail. This chapter will focus on the @emph{other} three
cases.@footnote{There is a special forth case which applies when an
HTTP/1.x client requests a ``protocol upgrade''. This is most often
used to create a WebSocket. Creating an action for such protocol
-upgrades is described in @ref{libmicrohttpd2-upgrade}.}
+upgrades is described in @ref{libmicrohttpd-upgrade}.}
@node libmicrohttpd-actions-fail
@section Failing hard by closing the connection
@@ -248,10 +248,10 @@ once or just the latest increment) and must return a
the @var{request}.
+@anchor{MHD_UploadCallback}
+@deftypefn {Function Pointer} {struct MHD_UploadAction *}
(*MHD_UploadCallback) (void *cls, struct MHD_Request *request, size_t
content_data_size, void *content_data)
-@deftypefn {Function Pointer} struct MHD_UploadAction * (*MHD_UploadCallback)
(void *cls, struct MHD_Request *request, size_t content_data_size, void
*content_data)
-
-FFunctions of this type are invoked by MHD whenever an application
+Functions of this type are invoked by MHD whenever an application
should process the HTTP body of a client's request.
@table @var
diff --git a/doc/manual/authentication.inc b/doc/manual/authentication.inc
index fdc86c5..3cb697f 100644
--- a/doc/manual/authentication.inc
+++ b/doc/manual/authentication.inc
@@ -1,3 +1,4 @@
+@cindex authentication
@noindent
MHD support three types of client authentication.
@@ -34,8 +35,9 @@ user authentication).
@node libmicrohttpd-dauth basic
@section Using Basic Authentication
+@cindex basic authentication
-@ref{@code{MHD_LIB_INFO_FIXED_HAS_AUTH_BASIC},,MHD_LIB_INFO_FIXED_HAS_AUTH_BASIC}
+@ref{MHD_LIB_INFO_FIXED_HAS_AUTH_BASIC,,@code{MHD_LIB_INFO_FIXED_HAS_AUTH_BASIC}}
can be used to detect if the MHD built includes support for HTTP basic
authorization.
@@ -101,7 +103,7 @@ The function returns
@c FIXME: also not convinced this API is even all that useful. Maybe remove?
MHD provides a convenience API that adds the basic authentication challenge
to response and turns it into the action to be returned
-from the @ref{@code{MHD_request_callback},,MHD_request_callback}.
+from the @ref{MHD_RequestCallback,,@code{MHD_RequestCallback}}.
@deftypefun {const struct MHD_Action *} MHD_action_basic_auth_challenge
(struct MHD_Request *request, const char *realm, enum MHD_Bool prefer_utf8,
struct MHD_Response *response, enum MHD_Bool abort_if_failed)
@@ -173,8 +175,9 @@ transmission from the client.
@node libmicrohttpd-dauth digest
@section Using Digest Authentication
+@cindex digest authentication
-@ref{@code{MHD_LIB_INFO_FIXED_HAS_AUTH_DIGEST},,MHD_LIB_INFO_FIXED_HAS_AUTH_DIGEST}
+@ref{MHD_LIB_INFO_FIXED_HAS_AUTH_DIGEST,,@code{MHD_LIB_INFO_FIXED_HAS_AUTH_DIGEST}}
can be used to detect if the MHD built includes support for HTTP digest
authorization.
@@ -197,6 +200,7 @@ must be specified by the application when creating the
challenge.
Adds a digest authentication "challenge" to the response.
The @var{response} must use @code{MHD_HTTP_STATUS_UNAUTHORIZED} for its HTTP
status code.
+@cindex qop
If @var{mqop} allows both RFC 2069 (@code{MHD_DIGEST_AUTH_QOP_NONE})
and other QOP values, then the "challenge" is formed like if
@code{MHD_DIGEST_AUTH_QOP_NONE} bit was not set, because such
@@ -290,7 +294,7 @@ The function returns
@end deftypefun
-
+@cindex qop
@anchor{MHD_DigestAuthMultiQOP}
@deftp {Enumeration} MHD_DigestAuthMultiQOP
Quality of protection (QOP) levels supported by the server. Values of
@@ -332,7 +336,8 @@ Currently supported by MHD as 'auth' QOP type only.
@end deftp
-
+@cindex hash
+@cindex digest
@anchor{MHD_DigestAuthMultiAlgo}
@deftp {Enumeration} MHD_DigestAuthMultiAlgo
Which digest algorithm should be used. Values of
@@ -421,7 +426,9 @@ have to compute the @var{userhash} from the @var{username}
and the
+@cindex userhash
+@anchor{MHD_digest_auth_calc_userhash}
@deftypefun {enum MHD_StatusCode} MHD_digest_auth_calc_userhash (enum
MHD_DigestAuthAlgo algo, const char *username, const char *realm, size_t
bin_buf_size, void *userhash_bin)
Calculates the @var{userhash_bin} and returns it as binary data.
@@ -432,7 +439,7 @@ The "userhash" can be used to avoid sending username in
cleartext in
a header when a client is using digest authorization.
The userhash is not designed to hide the username in a local database or
files, as the username in cleartext is still required for
-the @code{MHD_digest_auth_check()} function to check the response,
+the @code{MHD_digest_auth_check_digest()} function to check the response,
it can only can be used to hide the plaintext username in HTTP headers.
This function could be used when the new username is added to a username
@@ -480,6 +487,8 @@ Possible return values include:
Different hash algorithms can be specified for the
@var{algo} when computing the userhash.
+@cindex hash
+@cindex digest
@anchor{MHD_DigestAuthAlgorithm}
@deftp {Enumeration} MHD_DigestAuthAlgorithm
Which digest algorithm should be used.
@@ -509,7 +518,7 @@ Use SHA-512_256-sess. Not supported by MHD.
@end table
@end deftp
-Given a @ref{@code{MHD_DigestAuthAlgorithm},,MHD_DigestAuthAlgorithm},
+Given a @ref{MHD_DigestAuthAlgorithm,,@code{MHD_DigestAuthAlgorithm}},
@code{MHD_digest_get_hash_size()} can be used to determine the length
of the corresponding binary hash value.
@@ -539,7 +548,9 @@ in cleartext. Instead, applications @emph{should} use
@code{MHD_digest_auth_calc_userdigest()} to compute a hash of
the user's credentials and only store the resulting digest.
+@cindex userdigest
+@anchor{MHD_digest_auth_calc_userdigest}
@deftypefun {enum MHD_StatusCode} MHD_digest_auth_calc_userdigest (enum
MHD_DigestAuthAlgo algo, const char *username, const char *realm, const char
*password, size_t bin_buf_size, void *userhash_bin)
Calculates a userdigest and returns it as a binary data.
@@ -595,7 +606,7 @@ Possible return values include:
When a client provides a digest authentication header, the application
@emph{must} first use introspection using
-@ref{@code{MHD_REQUEST_INFO_DYNAMIC_AUTH_DIGEST_INFO},,MHD_REQUEST_INFO_DYNAMIC_AUTH_DIGEST_INFO}
+@ref{MHD_REQUEST_INFO_DYNAMIC_AUTH_DIGEST_INFO,,@code{MHD_REQUEST_INFO_DYNAMIC_AUTH_DIGEST_INFO}}
to determine the client's identity and algorithmic choices.
Introspection will return a @code{struct MHD_AuthDigestInfo}, or
@code{NULL} if the client did not provide a digest
@@ -696,7 +707,7 @@ The type of nonce count (nc) value provided in the request.
@item MHD_DIGEST_AUTH_NC_NUMBER
Readable hexdecimal non-zero number.
The decoded value is placed in the @var{nc} member of
-@ref{@code{MHD_AuthDigestInfo},,MHD_AuthDigestInfo}.
+@ref{MHD_AuthDigestInfo,,@code{MHD_AuthDigestInfo}}.
@code MHD_DIGEST_AUTH_NC_ZERO
Readable zero number.
@@ -721,6 +732,8 @@ Can be treated as request with a stale nonce or as an
invalid request.
@end table
@end deftp
+@c FIXME: MHD_DigestAuthUsernameType not defined
+
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
@@ -728,8 +741,10 @@ and always determine the userdigest. Given the
@var{username} and
it can can use @code{MHD_digest_auth_check_digest()} to actually check
the digest authentication provided by the client's request.
+@anchor{MHD_digest_auth_check_digest}
@deftypefun {enum MHD_DigestAuthResult} MHD_digest_auth_check_digest (struct
MHD_Request *request, const char *realm, const char *username, size_t
userdigest_size, const void *userdigest, uint_fast32_t max_nc, enum
MHD_DigestAuthMultiQOP mqop, enum MHD_DigestAuthMultiAlgo malgo)
+@cindex userdigest
Authenticates the authorization header sent by the client by using
hash of "username:realm:password".
@@ -759,7 +774,7 @@ hashing algorithm
@item userdigest
the precalculated binary hash of the string
"username:realm:password",
-@xref{@code{MHD_digest_auth_calc_userdigest},,MHD_digest_auth_calc_userdigest}
+@xref{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
diff --git a/doc/manual/constants.inc b/doc/manual/constants.inc
deleted file mode 100644
index 467a54f..0000000
--- a/doc/manual/constants.inc
+++ /dev/null
@@ -1,664 +0,0 @@
-
-@deftp {Enumeration} MHD_HTTP_PostEncoding
-
-Represents the different HTTP POST encodings supported
-by MHD. The special value @code{MHD_HTTP_POST_ENCODING_OTHER} is used to
support encodings that are not supported
-by MHD. Supported encodings include
-@code{MHD_HTTP_POST_ENCODING_FORM_URLENCODED},
-@code{MHD_HTTP_POST_ENCODING_MULTIPART_FORMDATA} and
-@code{MHD_HTTP_POST_ENCODING_TEXT_PLAIN}.
-
-@deftp {Enumeration} MHD_PredefinedHeader
-
-Enumeration that includes some HTTP header keys that
-are part of the HPACK static data.
-
-@c FIXME: not complete in code _OTHER is missing!
-
-The convenience function @code{MHD_predef_header_to_string()}
-can be used to convert members of this enumeration to
-a string value.
-
-
-
-@deftp {Enumeration} MHD_FdState
-
-Represents the network status of a socket.
-
-
-@deftp {Enumeration} MHD_WorkMode
-
-Determines the threading and polling mode used by MHD.
-@c FIXME: why again the odd numeric values?
-
-
-@deftp {Enumeration} MHD_DaemonOptionBindType
-
-Specifies how MHD should bind the listen socket. Controls
-sharing of the port with other processes.
-
-@deftp {Enumeration} MHD_FastOpenType
-
-Controls the use of TCP fast open.
-@c FIXME: reference RFC!
-
-@deftp {Enumeration} MHD_AddressFamily
-
-Determines which IP address family (IPv4, IPv6, dual) MHD
-should use.
-
-@deftp {Enumeration} MHD_SockPollSyscall
-
-Determines which system call MHD should use for polling.
-
-
-@deftp {Enumeration} MHD_ProtocolStrictLevel
-
-Determines how strict MHD should be with respect to
-enforcing clients behave according to the HTTP protocol.
-The default applies some balanced level for reasonable
-security but also broad compatibility.
-More relaxed settings can be useful to enable compatibility
-with broken implementations, while more strict settings
-can be useful to test client implementations.
-
-@deftp {Enumeration} MHD_UseStrictLevel
-
-Determines how the protocol strictless level is
-enforced.
-
-@deftp {Enumeration} MHD_TlsBackend
-
-Specifies which TLS backend should be used.
-
-@deftp {Enumeration} MHD_DaemonOptionValueDAuthBindNonce
-
-These values can limit the scope of validity of MHD-generated nonces.
-Values can be combined with bitwise OR.
-
-@deftp {Enumeration} MHD_ConnectionNotificationCode
-
-Used to specify the type of connection notification.
-
-@deftp {Enumeration} MHD_StreamNotificationCode
-
-Used to specify the type of stream notification.
-
-@deftp {Enumeration} MHD_RequestEndedCode
-
-Used to specify the type of request notification.
-
-@deftp {Enumeration} MHD_HTTP_ProtocolVersion
-
-Used to specify the type of request notification.
-
-
-
-@deftp {Enumeration} MHD_RequestTerminationCode
-The @code{MHD_RequestTerminationCode} specifies reasons why a request
-has been terminated (or completed).
-
-@table @code
-@item MHD_REQUEST_TERMINATED_COMPLETED_OK
-We finished sending the response.
-
-@item MHD_REQUEST_TERMINATED_WITH_ERROR
-Error handling the connection (resources exhausted, other side closed
-connection, application error accepting request, etc.)
-
-@item MHD_REQUEST_TERMINATED_TIMEOUT_REACHED
-No activity on the connection for the number of seconds specified using
-@code{MHD_OPTION_CONNECTION_TIMEOUT}.
-
-@item MHD_REQUEST_TERMINATED_DAEMON_SHUTDOWN
-We had to close the session since MHD was being shut down.
-@end table
-@end deftp
-
-
-@deftp {Enumeration} MHD_ResponseFlags
-Response-specific flags. Passed as an argument to
-@code{MHD_set_response_options()}.
-
-@table @code
-@item MHD_RF_NONE
-No special handling.
-
-@item MHD_RF_HTTP_VERSION_1_0_ONLY
-Only respond in conservative HTTP 1.0-mode. In particular,
-do not (automatically) sent "Connection" headers and always
-close the connection after generating the response.
-
-By default, MHD will respond using the same HTTP version which
-was set in the request. You can also set the
-@code{MHD_RF_HTTP_VERSION_1_0_RESPONSE} flag to force version 1.0
-in the response.
-
-@item MHD_RF_HTTP_VERSION_1_0_RESPONSE
-Only respond in HTTP 1.0-mode. Contrary to the
-@code{MHD_RF_HTTP_VERSION_1_0_ONLY} flag, the response's HTTP version will
-always be set to 1.0 and ``Connection'' headers are still supported.
-
-You can even combine this option with MHD_RF_HTTP_VERSION_1_0_ONLY to
-change the response's HTTP version while maintaining strict compliance
-with HTTP 1.0 regarding connection management.
-
-This solution is not perfect as this flag is set on the response which
-is created after header processing. So MHD will behave as a HTTP 1.1
-server until the response is queued. It means that an invalid HTTP 1.1
-request will fail even if the response is sent with HTTP 1.0 and the
-request would be valid if interpreted with this version. For example,
-this request will fail in strict mode:
-
-@verbatim
-GET / HTTP/1.1
-@end verbatim
-
-as the ``Host'' header is missing and is mandatory in HTTP 1.1, but it
-should succeed when interpreted with HTTP 1.0.
-
-@item MHD_RF_INSANITY_HEADER_CONTENT_LENGTH
-Disable sanity check preventing clients from manually
-setting the HTTP content length option.
-
-@end table
-@end deftp
-
-
-@deftp {Enumeration} MHD_ResponseOptions
-Response-specific options. Passed in the varargs portion of
-@code{MHD_set_response_options()}.
-
-@table @code
-@item MHD_RO_END
-No more options / last option. This is used to terminate the VARARGs
-list.
-@end table
-@end deftp
-
-
-@deftp {Enumeration} MHD_WEBSOCKET_FLAG
-@cindex websocket
-Options for the MHD websocket stream.
-
-This is used for initialization of a websocket stream when calling
-@code{MHD_websocket_stream_init} or @code{MHD_websocket_stream_init2} and
-alters the behavior of the websocket stream.
-
-Note that websocket streams are only available if you include the header file
-@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
-
-@table @code
-@item MHD_WEBSOCKET_FLAG_SERVER
-The websocket stream is initialized in server mode (default).
-Thus all outgoing payload will not be masked.
-All incoming payload must be masked.
-
-This flag cannot be used together with @code{MHD_WEBSOCKET_FLAG_CLIENT}.
-
-@item MHD_WEBSOCKET_FLAG_CLIENT
-The websocket stream is initialized in client mode.
-You will usually never use that mode in combination with @emph{libmicrohttpd},
-because @emph{libmicrohttpd} provides a server and not a client.
-In client mode all outgoing payload will be masked
-(XOR-ed with random values).
-All incoming payload must be unmasked.
-If you use this mode, you must always call @code{MHD_websocket_stream_init2}
-instead of @code{MHD_websocket_stream_init}, because you need
-to pass a random number generator callback function for masking.
-
-This flag cannot be used together with @code{MHD_WEBSOCKET_FLAG_SERVER}.
-
-@item MHD_WEBSOCKET_FLAG_NO_FRAGMENTS
-You don't want to get fragmented data while decoding (default).
-Fragmented frames will be internally put together until
-they are complete.
-Whether or not data is fragmented is decided
-by the sender of the data during encoding.
-
-This cannot be used together with @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}.
-
-@item MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS
-You want fragmented data, if it appears while decoding.
-You will receive the content of the fragmented frame,
-but if you are decoding text, you will never get an unfinished
-UTF-8 sequence (if the sequence appears between two fragments).
-Instead the text will end before the unfinished UTF-8 sequence.
-With the next fragment, which finishes the UTF-8 sequence,
-you will get the complete UTF-8 sequence.
-
-This cannot be used together with @code{MHD_WEBSOCKET_FLAG_NO_FRAGMENTS}.
-
-@item MHD_WEBSOCKET_FLAG_GENERATE_CLOSE_FRAMES_ON_ERROR
-If the websocket stream becomes invalid during decoding due to
-protocol errors, a matching close frame will automatically
-be generated.
-The close frame will be returned via the parameters
-@code{payload} and @code{payload_len} of @code{MHD_websocket_decode} and
-the return value is negative (a value of @code{enum MHD_WEBSOCKET_STATUS}).
-
-The generated close frame must be freed by the caller
-with @code{MHD_websocket_free}.
-
-@end table
-@end deftp
-
-
-@deftp {Enumeration} MHD_WEBSOCKET_FRAGMENTATION
-@cindex websocket
-This enumeration is used to specify the fragmentation behavior
-when encoding of data (text/binary) for a websocket stream.
-This is used with @code{MHD_websocket_encode_text} or
-@code{MHD_websocket_encode_binary}.
-
-Note that websocket streams are only available if you include the header file
-@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
-
-@table @code
-@item MHD_WEBSOCKET_FRAGMENTATION_NONE
-You don't want to use fragmentation.
-The encoded frame consists of only one frame.
-
-@item MHD_WEBSOCKET_FRAGMENTATION_FIRST
-You want to use fragmentation.
-The encoded frame is the first frame of
-a series of data frames of the same type
-(text or binary).
-You may send control frames (ping, pong or close)
-between these data frames.
-
-@item MHD_WEBSOCKET_FRAGMENTATION_FOLLOWING
-You want to use fragmentation.
-The encoded frame is not the first frame of
-the series of data frames, but also not the last one.
-You may send control frames (ping, pong or close)
-between these data frames.
-
-@item MHD_WEBSOCKET_FRAGMENTATION_LAST
-You want to use fragmentation.
-The encoded frame is the last frame of
-the series of data frames, but also not the first one.
-After this frame, you may send all types of frames again.
-
-@end table
-@end deftp
-
-
-@deftp {Enumeration} MHD_WEBSOCKET_STATUS
-@cindex websocket
-This enumeration is used for the return value of almost
-every websocket stream function.
-Errors are negative and values equal to or above zero mean a success.
-Positive values are only used by @code{MHD_websocket_decode}.
-
-Note that websocket streams are only available if you include the header file
-@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
-
-@table @code
-@item MHD_WEBSOCKET_STATUS_OK
-The call succeeded.
-Especially for @code{MHD_websocket_decode} this means that no error occurred,
-but also no frame has been completed yet.
-For other functions this means simply a success.
-
-@item MHD_WEBSOCKET_STATUS_TEXT_FRAME
-@code{MHD_websocket_decode} has decoded a text frame.
-The parameters @code{payload} and @code{payload_len} are filled with
-the decoded text (if any).
-You must free the returned @code{payload} after use with
-@code{MHD_websocket_free}.
-
-@item MHD_WEBSOCKET_STATUS_BINARY_FRAME
-@code{MHD_websocket_decode} has decoded a binary frame.
-The parameters @code{payload} and @code{payload_len} are filled with
-the decoded binary data (if any).
-You must free the returned @code{payload} after use with
-@code{MHD_websocket_free}.
-
-@item MHD_WEBSOCKET_STATUS_CLOSE_FRAME
-@code{MHD_websocket_decode} has decoded a close frame.
-This means you must close the socket using @code{MHD_upgrade_action}
-with @code{MHD_UPGRADE_ACTION_CLOSE}.
-You may respond with a close frame before closing.
-The parameters @code{payload} and @code{payload_len} are filled with
-the close reason (if any).
-The close reason starts with a two byte sequence of close code
-in network byte order (see @code{enum MHD_WEBSOCKET_CLOSEREASON}).
-After these two bytes a UTF-8 encoded close reason may follow.
-You can call @code{MHD_websocket_split_close_reason} to split that
-close reason.
-You must free the returned @code{payload} after use with
-@code{MHD_websocket_free}.
-
-@item MHD_WEBSOCKET_STATUS_PING_FRAME
-@code{MHD_websocket_decode} has decoded a ping frame.
-You should respond to this with a pong frame.
-The pong frame must contain the same binary data as
-the corresponding ping frame (if it had any).
-The parameters @code{payload} and @code{payload_len} are filled with
-the binary ping data (if any).
-You must free the returned @code{payload} after use with
-@code{MHD_websocket_free}.
-
-@item MHD_WEBSOCKET_STATUS_PONG_FRAME
-@code{MHD_websocket_decode} has decoded a pong frame.
-You should usually only receive pong frames if you sent
-a ping frame before.
-The binary data should be equal to your ping frame and can be
-used to distinguish the response if you sent multiple ping frames.
-The parameters @code{payload} and @code{payload_len} are filled with
-the binary pong data (if any).
-You must free the returned @code{payload} after use with
-@code{MHD_websocket_free}.
-
-@item MHD_WEBSOCKET_STATUS_TEXT_FIRST_FRAGMENT
-@code{MHD_websocket_decode} has decoded a text frame fragment.
-The parameters @code{payload} and @code{payload_len} are filled with
-the decoded text (if any).
-This is like @code{MHD_WEBSOCKET_STATUS_TEXT_FRAME}, but it can only
-appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS} during
-the call of @code{MHD_websocket_stream_init} or
-@code{MHD_websocket_stream_init2}.
-You must free the returned @code{payload} after use with
-@code{MHD_websocket_free}.
-
-@item MHD_WEBSOCKET_STATUS_TEXT_FIRST_FRAGMENT
-@code{MHD_websocket_decode} has decoded a binary frame fragment.
-The parameters @code{payload} and @code{payload_len} are filled with
-the decoded binary data (if any).
-This is like @code{MHD_WEBSOCKET_STATUS_BINARY_FRAME}, but it can only
-appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS} during
-the call of @code{MHD_websocket_stream_init} or
-@code{MHD_websocket_stream_init2}.
-You must free the returned @code{payload} after use with
-@code{MHD_websocket_free}.
-
-@item MHD_WEBSOCKET_STATUS_TEXT_NEXT_FRAGMENT
-@code{MHD_websocket_decode} has decoded the next text frame fragment.
-The parameters @code{payload} and @code{payload_len} are filled with
-the decoded text (if any).
-This is like @code{MHD_WEBSOCKET_STATUS_TEXT_FIRST_FRAGMENT}, but it appears
-only after the first and before the last fragment of a series of fragments.
-It can only appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}
-during the call of @code{MHD_websocket_stream_init} or
-@code{MHD_websocket_stream_init2}.
-You must free the returned @code{payload} after use with
-@code{MHD_websocket_free}.
-
-@item MHD_WEBSOCKET_STATUS_BINARY_NEXT_FRAGMENT
-@code{MHD_websocket_decode} has decoded the next binary frame fragment.
-The parameters @code{payload} and @code{payload_len} are filled with
-the decoded binary data (if any).
-This is like @code{MHD_WEBSOCKET_STATUS_BINARY_FIRST_FRAGMENT}, but it appears
-only after the first and before the last fragment of a series of fragments.
-It can only appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}
-during the call of @code{MHD_websocket_stream_init} or
-@code{MHD_websocket_stream_init2}.
-You must free the returned @code{payload} after use with
-@code{MHD_websocket_free}.
-
-@item MHD_WEBSOCKET_STATUS_TEXT_LAST_FRAGMENT
-@code{MHD_websocket_decode} has decoded the last text frame fragment.
-The parameters @code{payload} and @code{payload_len} are filled with
-the decoded text (if any).
-This is like @code{MHD_WEBSOCKET_STATUS_TEXT_FIRST_FRAGMENT}, but it appears
-only for the last fragment of a series of fragments.
-It can only appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}
-during the call of @code{MHD_websocket_stream_init} or
-@code{MHD_websocket_stream_init2}.
-You must free the returned @code{payload} after use with
-@code{MHD_websocket_free}.
-
-@item MHD_WEBSOCKET_STATUS_BINARY_LAST_FRAGMENT
-@code{MHD_websocket_decode} has decoded the last binary frame fragment.
-The parameters @code{payload} and @code{payload_len} are filled with
-the decoded binary data (if any).
-This is like @code{MHD_WEBSOCKET_STATUS_BINARY_FIRST_FRAGMENT}, but it appears
-only for the last fragment of a series of fragments.
-It can only appear if you specified @code{MHD_WEBSOCKET_FLAG_WANT_FRAGMENTS}
-during the call of @code{MHD_websocket_stream_init} or
-@code{MHD_websocket_stream_init2}.
-You must free the returned @code{payload} after use with
-@code{MHD_websocket_free}.
-
-@item MHD_WEBSOCKET_STATUS_PROTOCOL_ERROR
-The call failed and the stream is invalid now for decoding.
-You must close the websocket now using @code{MHD_upgrade_action}
-with @code{MHD_UPGRADE_ACTION_CLOSE}.
-You may send a close frame before closing.
-This is only used by @code{MHD_websocket_decode} and happens
-if the stream contains errors (i. e. invalid byte data).
-
-@item MHD_WEBSOCKET_STATUS_STREAM_BROKEN
-You tried to decode something, but the stream has already
-been marked invalid.
-You must close the websocket now using @code{MHD_upgrade_action}
-with @code{MHD_UPGRADE_ACTION_CLOSE}.
-You may send a close frame before closing.
-This is only used by @code{MHD_websocket_decode} and happens
-if you call @code{MDM_websocket_decode} again after
-has been invalidated.
-You can call @code{MHD_websocket_stream_is_valid} at any time
-to check whether a stream is invalid or not.
-
-@item MHD_WEBSOCKET_STATUS_MEMORY_ERROR
-A memory allocation failed. The stream remains valid.
-If this occurred while decoding, the decoding could be
-possible later if enough memory is available.
-This could happen while decoding if you received a too big data frame.
-You could try to specify max_payload_size during the call of
-@code{MHD_websocket_stream_init} or @code{MHD_websocket_stream_init2} to
-avoid this and close the websocket instead.
-
-@item MHD_WEBSOCKET_STATUS_PARAMETER_ERROR
-You passed invalid parameters during the function call
-(i. e. a NULL pointer for a required parameter).
-The stream remains valid.
-
-@item MHD_WEBSOCKET_STATUS_MAXIMUM_SIZE_EXCEEDED
-The maximum payload size has been exceeded.
-If you got this return code from @code{MHD_websocket_decode} then
-the stream becomes invalid and the websocket must be closed
-using @code{MHD_upgrade_action} with @code{MHD_UPGRADE_ACTION_CLOSE}.
-You may send a close frame before closing.
-The maximum payload size is specified during the call of
-@code{MHD_websocket_stream_init} or @code{MHD_websocket_stream_init2}.
-This can also appear if you specified 0 as maximum payload size
-when the message is greater than the maximum allocatable memory size
-(i. e. more than 4 GiB on 32 bit systems).
-If you got this return code from @code{MHD_websocket_encode_close},
-@code{MHD_websocket_encode_ping} or @code{MHD_websocket_encode_pong} then
-you passed to much payload data. The stream remains valid then.
-
-@item MHD_WEBSOCKET_STATUS_UTF8_ENCODING_ERROR
-An UTF-8 sequence is invalid.
-If you got this return code from @code{MHD_websocket_decode} then
-the stream becomes invalid and you must close the websocket
-using @code{MHD_upgrade_action} with @code{MHD_UPGRADE_ACTION_CLOSE}.
-You may send a close frame before closing.
-If you got this from @code{MHD_websocket_encode_text} or
-@code{MHD_websocket_encode_close} then you passed invalid UTF-8 text.
-The stream remains valid then.
-
-@item MHD_WEBSOCKET_STATUS_NO_WEBSOCKET_HANDSHAKE_HEADER
-A check routine for the HTTP headers came to the conclusion that
-the header value isn't valid for a websocket handshake request.
-This value can only be returned from the following functions:
-@code{MHD_websocket_check_http_version},
-@code{MHD_websocket_check_connection_header},
-@code{MHD_websocket_check_upgrade_header},
-@code{MHD_websocket_check_version_header},
-@code{MHD_websocket_create_accept_header}
-
-@end table
-@end deftp
-
-
-@deftp {Enumeration} MHD_WEBSOCKET_CLOSEREASON
-@cindex websocket
-Enumeration of possible close reasons for websocket close frames.
-
-The possible values are specified in RFC 6455 7.4.1
-These close reasons here are the default set specified by RFC 6455,
-but also other close reasons could be used.
-
-The definition is for short:
-@itemize @bullet
-@item 0-999 are never used (if you pass 0 in
-@code{MHD_websocket_encode_close} then no close reason is used).
-@item 1000-2999 are specified by RFC 6455.
-@item 3000-3999 are specified by libraries, etc. but must be registered by
IANA.
-@item 4000-4999 are reserved for private use.
-@end itemize
-
-Note that websocket streams are only available if you include the header file
-@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
-
-@table @code
-@item MHD_WEBSOCKET_CLOSEREASON_NO_REASON
-This value is used as placeholder for @code{MHD_websocket_encode_close}
-to tell that you don't want to specify any reason.
-If you use this value then no reason text may be used.
-This value cannot be a result of decoding, because this value
-is not a valid close reason for the websocket protocol.
-
-@item MHD_WEBSOCKET_CLOSEREASON_REGULAR
-You close the websocket because it fulfilled its purpose and shall
-now be closed in a normal, planned way.
-
-@item MHD_WEBSOCKET_CLOSEREASON_GOING_AWAY
-You close the websocket because you are shutting down the server or
-something similar.
-
-@item MHD_WEBSOCKET_CLOSEREASON_PROTOCOL_ERROR
-You close the websocket because a protocol error occurred
-during decoding (i. e. invalid byte data).
-
-@item MHD_WEBSOCKET_CLOSEREASON_UNSUPPORTED_DATATYPE
-You close the websocket because you received data which you don't accept.
-For example if you received a binary frame,
-but your application only expects text frames.
-
-@item MHD_WEBSOCKET_CLOSEREASON_MALFORMED_UTF8
-You close the websocket because it contains malformed UTF-8.
-The UTF-8 validity is automatically checked by @code{MHD_websocket_decode},
-so you don't need to check it on your own.
-UTF-8 is specified in RFC 3629.
-
-@item MHD_WEBSOCKET_CLOSEREASON_POLICY_VIOLATED
-You close the websocket because you received a frame which is too big
-to process.
-You can specify the maximum allowed payload size during the call of
-@code{MHD_websocket_stream_init} or @code{MHD_websocket_stream_init2}.
-
-@item MHD_WEBSOCKET_CLOSEREASON_MISSING_EXTENSION
-This status code can be sent by the client if it
-expected a specific extension, but this extension hasn't been negotiated.
-
-@item MHD_WEBSOCKET_CLOSEREASON_UNEXPECTED_CONDITION
-The server closes the websocket because it encountered
-an unexpected condition that prevented it from fulfilling the request.
-
-@end table
-@end deftp
-
-
-@deftp {Enumeration} MHD_WEBSOCKET_UTF8STEP
-@cindex websocket
-Enumeration of possible UTF-8 check steps for websocket functions
-
-These values are used during the encoding of fragmented text frames
-or for error analysis while encoding text frames.
-Its values specify the next step of the UTF-8 check.
-UTF-8 sequences consist of one to four bytes.
-This enumeration just says how long the current UTF-8 sequence is
-and what is the next expected byte.
-
-Note that websocket streams are only available if you include the header file
-@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
-
-@table @code
-@item MHD_WEBSOCKET_UTF8STEP_NORMAL
-There is no open UTF-8 sequence.
-The next byte must be 0x00-0x7F or 0xC2-0xF4.
-
-@item MHD_WEBSOCKET_UTF8STEP_UTF2TAIL_1OF1
-The second byte of a two byte UTF-8 sequence.
-The first byte was 0xC2-0xDF.
-The next byte must be 0x80-0xBF.
-
-@item MHD_WEBSOCKET_UTF8STEP_UTF3TAIL1_1OF2
-The second byte of a three byte UTF-8 sequence.
-The first byte was 0xE0.
-The next byte must be 0xA0-0xBF.
-
-@item MHD_WEBSOCKET_UTF8STEP_UTF3TAIL2_1OF2
-The second byte of a three byte UTF-8 sequence.
-The first byte was 0xED.
-The next byte must by 0x80-0x9F.
-
-@item MHD_WEBSOCKET_UTF8STEP_UTF3TAIL_1OF2
-The second byte of a three byte UTF-8 sequence.
-The first byte was 0xE1-0xEC or 0xEE-0xEF.
-The next byte must be 0x80-0xBF.
-
-@item MHD_WEBSOCKET_UTF8STEP_UTF3TAIL_2OF2
-The third byte of a three byte UTF-8 sequence.
-The next byte must be 0x80-0xBF.
-
-@item MHD_WEBSOCKET_UTF8STEP_UTF4TAIL1_1OF3
-The second byte of a four byte UTF-8 sequence.
-The first byte was 0xF0.
-The next byte must be 0x90-0xBF.
-
-@item MHD_WEBSOCKET_UTF8STEP_UTF4TAIL2_1OF3
-The second byte of a four byte UTF-8 sequence.
-The first byte was 0xF4.
-The next byte must be 0x80-0x8F.
-
-@item MHD_WEBSOCKET_UTF8STEP_UTF4TAIL_1OF3
-The second byte of a four byte UTF-8 sequence.
-The first byte was 0xF1-0xF3.
-The next byte must be 0x80-0xBF.
-
-@item MHD_WEBSOCKET_UTF8STEP_UTF4TAIL_2OF3
-The third byte of a four byte UTF-8 sequence.
-The next byte must be 0x80-0xBF.
-
-@item MHD_WEBSOCKET_UTF8STEP_UTF4TAIL_3OF3
-The fourth byte of a four byte UTF-8 sequence.
-The next byte must be 0x80-0xBF.
-
-@end table
-@end deftp
-
-
-@deftp {Enumeration} MHD_WEBSOCKET_VALIDITY
-@cindex websocket
-Enumeration of validity values of a websocket stream
-
-These values are used for @code{MHD_websocket_stream_is_valid}
-and specify the validity status.
-
-Note that websocket streams are only available if you include the header file
-@code{microhttpd_ws.h} and compiled @emph{libmicrohttpd} with websockets.
-
-@table @code
-@item MHD_WEBSOCKET_VALIDITY_INVALID
-The stream is invalid.
-It cannot be used for decoding anymore.
-
-@item MHD_WEBSOCKET_VALIDITY_VALID
-The stream is valid.
-Decoding works as expected.
-
-@item MHD_WEBSOCKET_VALIDITY_ONLY_VALID_FOR_CONTROL_FRAMES
-The stream has received a close frame and
-is partly invalid.
-You can still use the stream for decoding,
-but if a data frame is received an error will be reported.
-After a close frame has been sent, no data frames
-may follow from the sender of the close frame.
-
-@end table
-@end deftp
diff --git a/doc/manual/daemon_options.inc b/doc/manual/daemon_options.inc
index 93bd5d7..95cd495 100644
--- a/doc/manual/daemon_options.inc
+++ b/doc/manual/daemon_options.inc
@@ -143,7 +143,7 @@ with the requested settings.
@end deftypefun
How to use an external event loop is described in detail
-in another chapter of this manual. @xref{libmicrohttpd-external}
+in another chapter of this manual. @xref{libmicrohttpd2-external}
@node libmicrohttpd-daemon-workmode-external-single-fd
@@ -155,7 +155,7 @@ in another chapter of this manual.
@xref{libmicrohttpd-external}
Create parameter for @code{MHD_daemon_set_options()} to create a work
mode with no internal threads and an aggregate watch file descriptor (FD).
When using this setting, applications @emph{must} use
-@ref{@code{MHD_DAEMON_INFO_FIXED_AGGREAGATE_FD},,MHD_DAEMON_INFO_FIXED_AGGREAGATE_FD}
+@ref{MHD_DAEMON_INFO_FIXED_AGGREAGATE_FD,,@code{MHD_DAEMON_INFO_FIXED_AGGREAGATE_FD}}
to get the single FD that gets triggered by any MHD event. This FD can
be watched as an aggregate indicator for all MHD events. This mode is
available only on selected platforms (currently GNU/Linux
@@ -229,7 +229,7 @@ connection. Use this if handling requests is CPU-intensive
or blocking,
our application is thread-safe and you have plenty of memory (per
connection) as each thread requires its own stack.
Applications using this mode should strongly consider using
-@ref{@code{MHD_D_OPTION_GLOBAL_CONNECTION_LIMIT},,MHD_D_OPTION_GLOBAL_CONNECTION_LIMIT}.
+@ref{MHD_D_OPTION_GLOBAL_CONNECTION_LIMIT,,@code{MHD_D_OPTION_GLOBAL_CONNECTION_LIMIT}}.
Returns an object of type @code{struct MHD_DaemonOptionAndValue}
with the requested settings.
@@ -252,7 +252,7 @@ option is not set. @xref{MHD_SockPollSyscall}
Returns the option to pass to @code{MHD_daemon_set_options()}
@end deftypefun
-
+@anchor{MHD_SockPollSyscall}
@deftp {Enumeration} MHD_SockPollSyscall
Possible ways for sockets polling for internal syscalls.
@@ -318,6 +318,8 @@ the closure for the callback
Returns the option to pass to @code{MHD_daemon_set_options()}.
@end deftypefun
+@c FIXME: MHD_EarlyUriLogCallback not explained!
+
@deftypefun {struct MHD_DaemonOptionAndValue}
MHD_D_OPTION_DAEMON_READY_CALLBACK (MHD_DaemonReadyCallback cb, void *cb_cls)
@@ -568,7 +570,7 @@ Returns the option to pass to
@code{MHD_daemon_set_options()}.
@end deftypefun
-
+@anchor{MHD_TCPFastOpenType}
@deftp {Enumeration} MHD_TCPFastOpenType
Possible levels of support or enforcement for TCP_FASTOPEN.
@@ -981,7 +983,7 @@ Returns the option to pass to
@code{MHD_daemon_set_options()}
@deftypefun {struct MHD_DaemonOptionAndValue}
MHD_D_OPTION_DISALLOW_SUSPEND_RESUME ()
-Disable @ref{@code{MHD_action_suspend()},,MHD_action_suspend} functionality.
+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.
The suspend is not disallowed (suspend is allowed) by default.
diff --git a/doc/manual/doptions.inc b/doc/manual/doptions.inc
index 633d88c..aea7c7a 100644
--- a/doc/manual/doptions.inc
+++ b/doc/manual/doptions.inc
@@ -1,4 +1,5 @@
@anchor{MHD_DaemonOptionAndValue}
+@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
index d764f3c..2419c3e 100644
--- a/doc/manual/external.inc
+++ b/doc/manual/external.inc
@@ -70,7 +70,8 @@ cases, the application must provide a function of type
@code{MHD_SocketRegistrationUpdateCallback} when enabling
the option.
-@deftypefn {Function Pointer} MHD_APP_SOCKET_CNTX_TYPE *
(*MHD_SocketRegistrationUpdateCallback) (void *cls, MHD_Socket fd, enum
MHD_FdState watch_for, MHD_APP_SOCKET_CNTX_TYPE *app_cntx_old, struct
MHD_EventUpdateContext *ecb_cntx)
+@anchor{MHD_SocketRegistrationUpdateCallback}
+@deftypefn {Function Pointer} {MHD_APP_SOCKET_CNTX_TYPE *}
(*MHD_SocketRegistrationUpdateCallback) (void *cls, MHD_Socket fd, enum
MHD_FdState watch_for, MHD_APP_SOCKET_CNTX_TYPE *app_cntx_old, struct
MHD_EventUpdateContext *ecb_cntx)
Type of a function for registration or de-registration of the sockets to
watch in the external event loop.
@@ -246,7 +247,7 @@ must still call @code{MHD_daemon_process_reg_events()}.
@section Processing externally triggered events
-@deftypefun enum MHD_StatusCode MHD_daemon_process_reg_events (struct
MHD_Daemon *daemon, uint_fast64_t *next_max_wait)
+@deftypefun {enum MHD_StatusCode} MHD_daemon_process_reg_events (struct
MHD_Daemon *daemon, uint_fast64_t *next_max_wait)
Process registered network events and updates sockets registration.
This function first processes @emph{all}
diff --git a/doc/manual/init.inc b/doc/manual/init.inc
index 9bba884..5ea2fd4 100644
--- a/doc/manual/init.inc
+++ b/doc/manual/init.inc
@@ -5,6 +5,7 @@ goes really wrong inside of MHD.
@node libmicrohttpd-init-panic
@section Setting up a panic handler
+@cindex logging
@code{MHD_PanicCallback} is the type of a function that MHD
calls when it encounters an error that it cannot handle. This
@@ -15,7 +16,9 @@ failed assertion). MHD will not cause a panic in case of
normal operation or when there would be a safe way to continue
the execution.
-@deftypefn {Function Pointer} enum MHD_Result (*MHD_PanicCallback) (void *cls,
const char *file, const char *func, unsigned int line, const char *message)
+@anchor{MHD_PanicCallback}
+@deftypefn {Function Pointer} {enum MHD_Result} (*MHD_PanicCallback) (void
*cls, const char *file, const char *func, unsigned int line, const char
*message)
+
Invoked in the context of a serious error condition. The callback should not
return. Some parameters could be empty strings (with zero-termination at zero
position),
especially if MHD is built without support for log messages.
@table @var
@@ -63,7 +66,11 @@ closure argument for @var{cb}; the other arguments are the
name of the source fi
@node libmicrohttpd-init-create
@section Creating an HTTP daemon
+@cindex daemon
+
+@anchor{MHD_Daemon}
@deftp {C Struct} MHD_Daemon
+
Handle for an HTTP daemon. A daemon contains the MHD configuration
and state to listening on a socket for HTTP clients and handle
their requests.
@@ -75,6 +82,7 @@ from at most one @code{listen()} socket.
The @code{MHD_daemon_create()} function is used by applications to
create a @code{struct MHD_Daemon}.
+@anchor{MHD_daemon_create}
@deftypefun {struct MHD_Daemon *} MHD_daemon_create (MHD_RequestCallback
req_cb, void *req_cb_cls)
Create a new HTTP daemon object. Does not actually start
the HTTP daemon.
@@ -94,8 +102,10 @@ When creating an HTTP daemon the application must pass the
address of
a function of type @code{MHD_RequestCallback} which MHD will call for
each HTTP request that daemon receives from the network.
+@cindex anchor
@anchor{MHD_RequestCallback}
-@deftypefn {Function Pointer} struct MHD_Action * (*MHD_RequestCallback) (void
*cls, struct MHD_Request *request, const struct MHD_String *path, enum
MHD_HTTP_Method method, uint_fast64_t upload_size)
+@deftypefn {Function Pointer} {struct MHD_Action *} (*MHD_RequestCallback)
(void *cls, struct MHD_Request *request, const struct MHD_String *path, enum
MHD_HTTP_Method method, uint_fast64_t upload_size)
+
Functions of this type are invoked by MHD whenever it received an HTTP
request and needs to handle it.
@@ -123,7 +133,7 @@ handling the request. Implementations must call MHD
functions to create a @code{struct MHD_Action} which then determines
the next steps.
-@ref{libmicrohttpd-actions} explains in more detail how to create
+@ref{libmicrohttpd2-actions} explains in more detail how to create
various possible actions. It is also possible to return @code{NULL},
in which case MHD will close the HTTP connection without returning
anything (not even an error message). This can be used if the socket
@@ -137,6 +147,7 @@ by providing an enumeration value applications often can
avoid
implementing case-insensitive ASCII string comparissons. However,
the enumeration only works for HTTP methods specified in RFC 9110.
+@cindex method
@deftp {Enumeration} MHD_HTTP_Method
Represents canonical HTTP methods as per RFC 9110.
@@ -184,7 +195,8 @@ The convenience function @code{MHD_http_method_to_string()}
can be used to convert members of this enumeration to
a string value.
-@deftypefun const struct MHD_String * MHD_http_method_to_string (enum
MHD_HTTP_Method method)
+@anchor{MHD_http_method_to_string}
+@deftypefun {const struct MHD_String *} MHD_http_method_to_string (enum
MHD_HTTP_Method method)
Get text version of the method name.
Returns a pointer (!) to the HTTP method as a string.
@@ -207,15 +219,16 @@ RFCs. Check the header for constants with the prefix
After creating an MHD daemon, applications will typically configure
various optional features, such as support for TLS.
-@ref{libmicrohttpd-doptions} explains how to set the various options.
+@ref{libmicrohttpd2-doptions} explains how to set the various options.
Once the daemon is correctly configured, applications can start
processing client requests using @code{MHD_daemon_start()}.
-@deftypefun enum MHD_StatusCode MHD_daemon_start (struct MHD_Daemon *daemon)
-Starts an HTTP daemon. Checks that options are consistent,
-initializes the TLS library (if enabled),
-creates the listen socket (if not disabled) and
-launches the internal threads (if configured to do so).
+@anchor{MHD_daemon_start}
+@deftypefun {enum MHD_StatusCode} MHD_daemon_start (struct MHD_Daemon *daemon)
+
+Starts an HTTP daemon. Checks that options are consistent, initializes
+the TLS library (if enabled), creates the listen socket (if not
+disabled) and launches the internal threads (if configured to do so).
@table @var
@item daemon
@@ -230,10 +243,11 @@ Note that if you configured the daemon to use an
@emph{external} event loop, calling @code{MHD_daemon_start()}
is not sufficient to actually start processing client requests.
In this case, you must also integrate MHD into your event loop.
-@xref{libmicrohttpd-threadmodes-external}.
+@xref{libmicrohttpd2-external}.
@node libmicrohttpd-status-codes
@section Interpreting status codes
+@cindex status code
MHD uses the @code{enum MHD_StatusCode} to inform the application
about errors.
@@ -268,7 +282,8 @@ which indicates a successful operation.
To obtain a human-readable message explaining the status code,
applications can use @code{MHD_status_code_to_string()}.
-@deftypefun {const struct MHD_String} * MHD_status_code_to_string (struct
MHD_StatusCode code)
+@anchor{MHD_status_code_to_string}
+@deftypefun {const struct MHD_String *} MHD_status_code_to_string (struct
MHD_StatusCode code)
Get text description for the MHD status code.
This function works for MHD status codes, not for HTTP status codes!
@@ -291,14 +306,15 @@ also ensures that the result is never @code{NULL} by
returning
@node libmicrohttpd-init-quiesce
@section Quiescing an HTTP daemon
+@cindex quiesce
Quiescing an HTTP daemon prevents it from further accepting new
connections, but allows it to finish handling existing clients. This
is useful to minimize the disruptions when gracefully shutting down,
restarting or reloading an HTTP service.
+@anchor{MHD_quiesce_daemon}
@deftypefun MHD_Socket MHD_quiesce_daemon (struct MHD_Daemon *daemon)
-@cindex quiesce
Stop accepting connections from the listening socket. Allows clients
to continue processing, but stops accepting new connections.
@@ -321,7 +337,8 @@ A value of @code{-1} is returned if either the daemon was
not
started or was not listening on a socket.
@end deftypefun
-@cindex MHD_Socket
+@cindex socket
+@anchor{MHD_Socket}
@deftp {Typedef} MHD_Socket
The type @code{MHD_Socket} is platform-dependent:
@@ -341,9 +358,12 @@ was not quiesced first, the listen socket will still be
closed and all
ongoing requests will simply be terminated hard by closing the
connections.
+@anchor{MHD_daemon_destroy}
@deftypefun void MHD_daemon_destroy (struct MHD_Daemon *daemon)
+
Shutdown and destroy an HTTP daemon. Frees all
resources still associated with the daemon.
+
@table @var
@item daemon
Handle to the HTTP daemon to destroy.
diff --git a/doc/manual/introduction.inc b/doc/manual/introduction.inc
index 845fffc..11d2ff2 100644
--- a/doc/manual/introduction.inc
+++ b/doc/manual/introduction.inc
@@ -65,7 +65,7 @@ continue} are understood and handled automatically).
socket (or something that behaves like the real socket in the case of
TLS) to the application (after sending the desired HTTP response
header).
-@xref{libmicrohttpd2-upgrade} explains how to implement connection
+@xref{libmicrohttpd-upgrade} explains how to implement connection
upgrades (for example, to implement WebSockets).
MHD largely leaves implementing the semantics of the different HTTP
@@ -100,14 +100,16 @@ MHD checks for allocation failures and tries to recover
gracefully
specify resource limits on the overall number of connections, number
of connections per IP address and memory used per connection to avoid
resource exhaustion.
-@xref{libmicrohttpd2-options} explains the MHD API for configuring
-the various settings supported by the library.
+@xref{libmicrohttpd2-doptions} explains the MHD API for configuring
+the various settings supported for the daemon.
@node libmicrohttpd-introduction-threadmodes
@section Thread modes and event loops
@cindex poll
@cindex epoll
+@cindex mode
+@cindex threads
@cindex select
MHD supports four basic thread modes and up to three event loop
@@ -161,8 +163,8 @@ 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-threadmodes} provides details on how to
-use MHD with the different thread modes.
+@xref{libmicrohttpd2-external} for details on how to
+use MHD with an external event loop.
@node libmicrohttpd-introduction-compiling
@section Compiling GNU libmicrohttpd
diff --git a/doc/manual/postprocessor.inc b/doc/manual/postprocessor.inc
index 39899e1..32004a2 100644
--- a/doc/manual/postprocessor.inc
+++ b/doc/manual/postprocessor.inc
@@ -26,7 +26,7 @@ POST handling using this style is initiated by returning an
action
created via @code{MHD_action_parse_post()} from
@ref{MHD_RequestCallback,,@code{MHD_RequestCallback}}.
-@deftypefun const struct MHD_Action * MHD_action_parse_post (struct
MHD_Request *request, size_t buffer_size, size_t max_nonstream_size, enum
MHD_HTTP_PostEncoding enc, MHD_PostDataReader stream_reader, void *reader_cls,
MHD_PostDataFinished done_cb, void *done_cb_cls)
+@deftypefun {const struct MHD_Action *} MHD_action_parse_post (struct
MHD_Request *request, size_t buffer_size, size_t max_nonstream_size, enum
MHD_HTTP_PostEncoding enc, MHD_PostDataReader stream_reader, void *reader_cls,
MHD_PostDataFinished done_cb, void *done_cb_cls)
Creates an action to parse the POSTed content from the client.
The action starts parsing of the POST data. Any record that is larger
@@ -100,8 +100,8 @@ After returning the action created via
@code{MHD_action_parse_post}
MHD will first call the given @code{MHD_PostDataReader} for incremental
processing of all records that exceed the length threshold.
-@deftypefn {Function Pointer} enum MHD_Bool (*MHD_PostDataReader) (void *cls,
struct MHD_Request *req, const struct MHD_String *name, const struct
MHD_StringNullable *filename, const struct MHD_StringNullable *content_type,
const struct MHD_StringNullable *encoding, size_t size, const void *data,
uint_fast64_t off, enum MHD_Bool final_data);
-
+@anchor{MHD_PostDataReader}
+@deftypefn {Function Pointer} {enum MHD_Bool} (*MHD_PostDataReader) (void
*cls, struct MHD_Request *req, const struct MHD_String *name, const struct
MHD_StringNullable *filename, const struct MHD_StringNullable *content_type,
const struct MHD_StringNullable *encoding, size_t size, const void *data,
uint_fast64_t off, enum MHD_Bool final_data)
Stream reader for incremental processing of POST records. This
callback is called to incrementally process parsed POST records sent
@@ -175,7 +175,7 @@ application a chance to inspect the records that were small
enough to
fit fully into memory and to decide the next action.
@anchor{MHD_PostDataFinished}
-@deftypefn {Function Pointer} struct MHD_UploadAction (*MHD_PostDataFinished)
(void *cls, struct MHD_Request *req, const struct MHD_PostParseResult
*parsing_result)
+@deftypefn {Function Pointer} {struct MHD_UploadAction}
(*MHD_PostDataFinished) (void *cls, struct MHD_Request *req, const struct
MHD_PostParseResult *parsing_result)
The callback to be called when MHD isfinished with parsing
all of the body. The @var{stream_reader} will not be called
@@ -296,7 +296,7 @@ available or a postprocessor was not used with
@var{request}.
@c FIXME: "Field" is probably a bad name, I think we should change it to
"Record" everywhere in the API
@anchor{MHD_PostDataIterator}
-@deftypefn {Function Pointer} enum MHD_Bool (*MHD_PostDataIterator) (void
*cls, const struct MHD_PostField *data)
+@deftypefn {Function Pointer} {enum MHD_Bool} (*MHD_PostDataIterator) (void
*cls, const struct MHD_PostField *data)
Iterator over POST data. The @var{data} pointer is valid only until
the application returns from this function. However, the pointers to
diff --git a/doc/manual/requests.inc b/doc/manual/requests.inc
index 5f0ff64..901cd4a 100644
--- a/doc/manual/requests.inc
+++ b/doc/manual/requests.inc
@@ -27,6 +27,8 @@ are represented by the @code{enum MHD_ValueKind}.
@anchor{MHD_ValueKind}
@deftp {Enumeration} MHD_ValueKind
+@cindex header
+@cindex kind
Specifies the source of the name-value pairs in the HTTP protocol.
@@ -47,10 +49,11 @@ This is available only if @code{MHD_action_parse_post()} is
used,
a content encoding is supported by MHD, and only if the posted content
fits within the specified memory buffers.
+@cindex Transfer-Encoding
Warning: The encoding ``multipart/form-data'' has more fields than just
``name'' and ``value'' which are not available via the APIs discussed
-in this chapter. @xref{MHD_request_get_post_data_cb()} and
-@ref{MHD_request_get_post_data_list()} for more information.
+in this chapter. @xref{MHD_request_get_post_data_cb} and
+@ref{MHD_request_get_post_data_list,,@code{MHD_request_get_post_data_list()}}
for more information.
In particular it could be important
to check the ``Transfer-Encoding''.
@@ -104,7 +107,8 @@ are simply given the specific @var{kind} and name-and-value
pair.
@anchor{MHD_NameValueIterator}
-@deftypefn {Function Pointer} enum MHD_Bool (*MHD_NameValueIterator) (void
*cls, enum MHD_ValueKind kind, const struct MHD_NameAndValue *nv)
+@deftypefn {Function Pointer} {enum MHD_Bool} (*MHD_NameValueIterator) (void
*cls, enum MHD_ValueKind kind, const struct MHD_NameAndValue *nv)
+
Functions of this type are invoked by MHD for each matching
name-value pair.
@@ -183,6 +187,7 @@ than @var{num_elements}, zero if there were no matching
elements or on any error.
@end deftypefun
+@anchor{MHD_NameValueKind}
@deftp {C Struct} MHD_NameValueKind nv kind
Represents a triplet of a name, value and kind.
@table @code
@@ -196,8 +201,9 @@ The kind of the field
@end table
@end deftp
-
+@anchor{MHD_request_get_value}
@deftypefun {const struct MHD_StringNullable *} MHD_request_get_value (struct
MHD_Connection *connection, enum MHD_ValueKind kind, const char *key)
+
Returns a particular data value from a @var{request}.
@table @var
@@ -233,7 +239,6 @@ value of a ``Host:'' header.
@node libmicrohttpd-requests-info
@section Obtaining request status information
-
@deftypefun {enum MHD_StatusCode} MHD_request_get_info_fixed_sz (struct
MHD_Request *request, enum MHD_RequestInfoFixedType info_type, union
MHD_RequestInfoFixedData *output_buf, size_t output_buf_size)
Obtain fixed information about the given request.
@@ -341,6 +346,7 @@ The result is placed in @var{v_ppvoid} member.
@end table
@end deftp
+@c FIXME: define MHD_RequestTerminationCallback!
@deftp {C Union} MHD_RequestInfoFixedType
@@ -465,7 +471,7 @@ The macro returns the same values as
@end deftypefun
-
+@anchor{MHD_RequestInfoDynamicType}
@deftp {Enumeration} MHD_RequestInfoDynamicType
Selects what dynamic information about request is desired.
@@ -585,7 +591,7 @@ The result is placed in @var{v_auth_basic_creds} member.
-
+@anchor{MHD_RequestInfoDynamicData}
@deftp {C Union} MHD_RequestInfoDynamicData
Stores dynamic information about a request.
diff --git a/doc/manual/response_options.inc b/doc/manual/response_options.inc
index 3eadbb1..bf790cd 100644
--- a/doc/manual/response_options.inc
+++ b/doc/manual/response_options.inc
@@ -5,9 +5,9 @@
Make the response object re-usable.
The response will not be consumed by
-@ref{@code{MHD_action_from_response()},,MHD_action_from_response()}
+@ref{MHD_action_from_response,,@code{MHD_action_from_response()}}
and must be destroyed by
-@ref{@code{MHD_response_destroy()},,MHD_response_destroy()}
+@ref{MHD_response_destroy,,@code{MHD_response_destroy()}}
Useful if the same response is repeatedly used.
@table @var
@end table
@@ -26,7 +26,7 @@ requests.
The flag also allows applications to set an arbitrary "Content-Length"
header using
-@ref{@code{MHD_response_add_header()},,MHD_response_add_header()}.
+@ref{MHD_response_add_header,,@code{MHD_response_add_header()}}.
This flag value can be used only with responses created with a body of
zero length.
diff --git a/doc/manual/responses.inc b/doc/manual/responses.inc
index 5a1e47b..1ede74e 100644
--- a/doc/manual/responses.inc
+++ b/doc/manual/responses.inc
@@ -1,3 +1,4 @@
+@cindex response
@noindent
Response objects handling by MHD is asynchronous with respect to the
@@ -11,6 +12,8 @@ A response includes the HTTP status code, HTTP headers,
a body and possibly HTTP footers.
@end deftp
+@cindex action
+
In the simplest case we allocate a new @code{struct MHD_Response} structure
for each response, use it to create an action and it is (automatically)
destroyed:
@@ -47,7 +50,7 @@ in the chapter on setting response options.
* libmicrohttpd-response create:: Creating responses.
* libmicrohttpd-response headers:: Adding headers to a response.
* libmicrohttpd-response options:: Setting response options.
-* libmicrohttpd-response upgrade:: Creating a response for protocol upgrades.
+* libmicrohttpd-upgrade:: Creating a response for protocol upgrades.
@end menu
@c ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@@ -62,7 +65,9 @@ above, handling a request requires applications to return a
common way to create an action is from a @code{struct MHD_Response}
via @code{MHD_action_from_response}.
-@deftypefun struct MHD_Action * MHD_action_from_response (struct MHD_Request
*request, struct MHD_Response *response)
+@anchor{MHD_action_from_response}
+@deftypefun {struct MHD_Action *} MHD_action_from_response (struct MHD_Request
*request, struct MHD_Response *response)
+
This instructs MHD to transmit the given @var{response} to
the client. The @var{request} must match the request handle
given to the call that is returning the action.
@@ -108,6 +113,7 @@ was successfull created must @emph{either} be converted
into an action
via @code{MHD_action_from_response()} or explicitly destroyed via
@code{MHD_response_destroy()}.
+@anchor{MHD_response_destroy}
@deftypefun void MHD_response_destroy (struct MHD_Response *response)
Destroys a response object and associated resources (decrement the
reference counter). Note that MHD may keep some of the resources
@@ -121,6 +127,7 @@ the response to destroy.
@end deftypefun
@subsection HTTP status codes
+@cindex status code
When creating a response object, you must always specify the HTTP
status code that should be returned with the response. MHD provides
@@ -130,7 +137,7 @@ cases MHD will be unable to provide the human-readable
status code
description and clients are likely to be unhappy about the use of
non-standard codes.
-
+@anchor{MHD_HTTP_StatusCode}
@deftp {Enumeration} MHD_HTTP_StatusCode
Represents canonical HTTP status codes.
@@ -146,7 +153,9 @@ Represents canonical HTTP status codes.
You can use any of the following functions (or convenience macros)
to create responses from static data in memory:
+@anchor{MHD_response_from_buffer}
@deftypefun {struct MHD_Response *} MHD_response_from_buffer (enum
MHD_HTTP_StatusCode sc, size_t buffer_size, const char *buffer,
MHD_FreeCallback free_cb, void *free_cb_cls)
+
Create a response object with a callback that can be used to free resources
after the response has been sent to the client.
@table @var
@@ -180,8 +189,9 @@ A common value to pass is @var{buffer}.
Return @code{NULL} on error (i.e. invalid arguments, out of memory).
@end deftypefun
-
+@anchor{MHD_FreeCallback}
@deftypefn {Function Pointer} void (*MHD_FreeCallback) (void *cls)
+
Functions of this type are invoked by MHD whenever it wants to give
the application a chance to free resources.
@@ -196,6 +206,7 @@ When releasing resources is unnecessary, applications can
instead
use the simplified @code{MHD_response_from_buffer_static()} API
that simply omits the @var{free_cb} and @var{free_cb_cls} arguments.
+@anchor{MHD_response_from_buffer_static}
@deftypefun {struct MHD_Response *} MHD_response_from_buffer_static (enum
MHD_HTTP_StatusCode sc, size_t buffer_size, const char *buffer)
Create a response object without the need to free resources after the response
has been sent to the client.
@@ -216,8 +227,9 @@ but in this case it might be simpler to use
@code{MHD_response_from_empty()}.
Return @code{NULL} on error (i.e. invalid arguments, out of memory).
@end deftypefun
-
+@anchor{MHD_response_from_buffer_copy}
@deftypefun {struct MHD_Response *} MHD_response_from_buffer_copy (enum
MHD_HTTP_StatusCode sc, size_t buffer_size, const char buffer[buffer_size])
+
Create a response object from an ephemeral @var{buffer}. The data
in the @var{buffer} will be copied into internal storage of MHD.
@@ -238,7 +250,7 @@ will make a copy of the data contained in it.
Return @code{NULL} on error (i.e. invalid arguments, out of memory).
@end deftypefun
-
+@anchor{MHD_response_from_empty}
@deftypefun {struct MHD_Response *} MHD_response_from_empty (enum
MHD_HTTP_StatusCode sc)
Create an response with an empty body.
@@ -262,7 +274,12 @@ 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}
+@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)
+
Create a response object from an array of memory buffers.
@table @var
@item sc
@@ -285,7 +302,7 @@ additional argument to pass to the @var{free_cb}.
Return @code{NULL} on error (i.e. invalid arguments, out of memory).
@end deftypefun
-
+@anchor{MHD_IoVec}
@deftp {C Struct} MHD_IoVec
Input/output vector type. Informations MHD about a fragment of
data in memory for assembly as part of an HTTP response body.
@@ -299,7 +316,9 @@ The size (in bytes) of the memory region pointed to by
@var{iov_base}.
@subsection Responses from file descriptors
+@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)
Create a response object based on a file descriptor @var{fd} from
which the body is supposed to be read.
@@ -332,8 +351,10 @@ Returns @code{NULL} on error (i.e. invalid arguments, out
of memory).
The @var{fd} is closed on error.
@end deftypefun
-
+@cindex{splice}
+@anchor{MHD_response_from_pipe}
@deftypefun {struct MHD_Response *} MHD_response_from_pipe (enum
MHD_HTTP_StatusCode sc, int fd)
+
Create a response object where the response body is created by reading from
the provided pipe.
@@ -359,7 +380,12 @@ response body, possibly even with significant delays
between
chunks. This is also the only API that applications can use to
return responses for which they do not know the length up-front.
+@cindex dynamic responses
+@cindex generation
+
+@anchor{MHD_response_from_callback}
@deftypefun {struct MHD_Response *} MHD_response_from_callback (enum
MHD_HTTP_StatusCode sc, uint_fast64_t size, MHD_DynamicContentCreator dyn_cont,
void *dyn_cont_cls, MHD_FreeCallback dyn_cont_fc)
+
Create a response object with a body that will be yielded over
time by the @code{dyn_cont} callback.
@@ -390,7 +416,8 @@ The interesting work for dynamic response generation
happens in the
dynamic content creation callback, which must be a function of
type @code{MHD_DynamicContentCreator}.
-@deftypefn {Function Pointer} struct MHD_DynamicContentCreatorAction *
(*MHD_DynamicContentCreator) (void *dyn_cont_cls, struct
MHD_DynamicContentCreatorContext *ctx, uint_fast64_t pos, void *buf, size_t max)
+@anchor{MHD_DynamicContentCreator}
+@deftypefn {Function Pointer} {struct MHD_DynamicContentCreatorAction *}
(*MHD_DynamicContentCreator) (void *dyn_cont_cls, struct
MHD_DynamicContentCreatorContext *ctx, uint_fast64_t pos, void *buf, size_t max)
@table @var
@item dyn_cont_cls
@@ -429,6 +456,9 @@ return @code{NULL} in which case response generation will
be aborted and MHD will @code{close()} the connection.
@end deftypefn
+@cindex dynamic content creator action
+
+@anchor{MHD_DynamicContentCreatorAction}
@deftp {C Struct} MHD_DynamicContentCreatorAction
Special type of action that must be returned by a
@code{MHD_DynamicContentCreator}.
@@ -442,6 +472,7 @@ can be created per @var{ctx}.
We begin with DCC actions that end the process of
dynamic response generation:
+@anchor{MHD_DCC_action_abort}
@deftypefun {struct MHD_DynamicContentCreatorAction *} MHD_DCC_action_abort
(struct MHD_DynamicContentCreatorContext *ctx)
Aborts handling the request by closing the connection. This
@@ -451,6 +482,7 @@ not emit a warning for not using @var{ctx}.
@end deftypefun
+@anchor{MHD_DCC_action_finish}
@deftypefun {struct MHD_DynamicContentCreatorAction *} MHD_DCC_action_finish
(struct MHD_DynamicContentCreatorContext *ctx)
Create a "finished" action that signals MHD that the dynamic content creation
@@ -473,6 +505,7 @@ HTTP has not only headers, but also the lesser-known
concept of
to append a checksum after dynamic content creation) using
@code{MHD_DCC_action_finish_with_footer()}.
+@anchor{MHD_DCC_action_finish_with_footer}
@deftypefun {struct MHD_DynamicContentCreatorAction *}
MHD_DCC_action_finish_with_footer (struct MHD_DynamicContentCreatorContext
*ctx, size_t num_footers, const struct MHD_NameValueCStr *footers)
Create a "finished" action that signals MHD that the dynamic content creation
@@ -499,6 +532,7 @@ The @var{footers} are provided as key-value pairs of
0-terminated C strings
in a @code{struct MHD_NameValueCStr}. In this context, both members must
not be @code{NULL}.
+@anchor{MHD_NameValueCStr}
@deftp {C Struct} MHD_NameValueCStr name value
Name with value pair as C strings.
@table @var
@@ -518,6 +552,7 @@ may not (yet) have more data to return to the client. In
this case,
applications must @emph{suspend} response generation. This is done
using @code{MHD_DCC_action_suspend()}.
+@anchor{MHD_DCC_action_suspend}
@deftypefun {struct MHD_DynamicContentCreatorAction *} MHD_DCC_action_suspend
(struct MHD_DynamicContentCreatorContext *ctx)
Creates a DCC action that suspends response generation. The connection
@@ -543,6 +578,8 @@ After dynamic content creation was suspended with
processing the client's request.
@cindex long-polling
+
+@anchor{MHD_request_resume}
@deftypefun void MHD_request_resume (struct MHD_Request *request)
Resume handling of network data for suspended request. It is
@@ -551,7 +588,7 @@ function on a request that was not previously suspended will
result in undefined behaviour.
If you are using this function in ``external'' select mode
-(@xref{libmicrohttpd-threadmodes}), you must
+(@xref{libmicrohttpd2-external}), you must
additionally make sure to call @code{MHD_daemon_process_blocking()}
afterwards! Otherwise the change may not be reflected in the set
returned to your @code{MHD_SocketRegistrationUpdateCallback} and the
@@ -568,6 +605,7 @@ identifies the request to resume
Finally, we consider DCC actions that can be used to signal MHD data to be
returned in the MHD body.
+@anchor{MHD_DCC_action_continue}
@deftypefun {struct MHD_DynamicContentCreatorAction *} MHD_DCC_action_continue
(struct MHD_DynamicContentCreatorContext *ctx, size_t data_size)
Creates an action that indicates that a chunk of @var{data_size} bytes
@@ -631,6 +669,7 @@ locations in the application's memory, and in fact it is
possible to @emph{mix} both strategies using
@code{MHD_DCC_action_continue_zc()}:
+@anchor{MHD_DCC_action_continue_zc}
@deftypefun {struct MHD_DynamicContentCreatorAction *}
MHD_DCC_action_continue_zc (struct MHD_DynamicContentCreatorContext *ctx,
size_t data_size, const struct MHD_DynContentZCIoVec *iov_data, const char
*chunk_ext)
Yields a chunk of body data to MHD with (optional) chunk-extension.
@@ -674,7 +713,11 @@ return @code{NULL}.
The @code{struct MHD_DynContentZCIoVec} adds cleanup logic to
an array of @code{struct MHD_IoVec}s:
+@cindex iovec
+@cindex writev
+@cindex scatter write
+@anchor{MHD_DynContentZCIoVec}
@deftp {C Struct} MHD_DynContentZCIoVec
Structure to pass various memory buffers to MHD together with
a callback for cleaning up after MHD is done using the data.
@@ -700,6 +743,11 @@ Parameter to pass to @var{iov_fcb}.
@node libmicrohttpd-response headers
@section Adding headers to a response
+@cindex header
+@cindex Connection
+@cindex Date
+@cindex Content-Length
+@cindex Transfer-Encoding
After creating a response, but @emph{before} using it to create an
@code{struct MHD_Action}, applications may add custom HTTP headers
@@ -726,8 +774,9 @@ response (@xref{microhttpd-response options}) as MHD will
automatically set a correct ``Content-Length'' header if it is
possible and allowed by the HTTP protocol.
+@anchor{MHD_response_add_header}
+@deftypefun {enum MHD_StatusCode} MHD_response_add_header (struct MHD_Response
*response, const char *name, const char *value)
-@deftypefun enum MHD_StatusCode MHD_response_add_header (struct MHD_Response
*response, const char *name, const char *value)
Add a header line to the response.
@table @var
@@ -747,6 +796,9 @@ Notice that both strings must not contain newlines,
carriage returns or
tabulator characters. On success @code{MHD_SC_OK} is returned.
@end deftypefun
+@cindex HTTP2
+@cindex predefined HTTP header
+@cindex header
HTTP2 introduced @emph{predefined} (standard) HTTP headers. For such
headers, it is (slightly) more efficient to set the headers using
@@ -756,7 +808,7 @@ encode these headers using a number instead of a string,
and by having
the application directly provide the numeric value MHD does not have
to map the string to the number.}
-@deftypefun enum MHD_StatusCode MHD_response_add_predef_header (struct
MHD_Response *response, enum MHD_PredefinedHeader stk, const char *content)
+@deftypefun {enum MHD_StatusCode} MHD_response_add_predef_header (struct
MHD_Response *response, enum MHD_PredefinedHeader stk, const char *content)
Adds a header line to the response.
@table @var
@@ -775,6 +827,7 @@ Notice that the content must not contain newlines, carriage
returns or
tabulator characters. On success @code{MHD_SC_OK} is returned.
@end deftypefun
+@anchor{MHD_PredefinedHeader}
@deftp {Enumeration} MHD_PredefinedHeader
Predefined list of canonical HTTP headers, useful for HTTP2
@@ -793,7 +846,7 @@ header packing (HPACK).
MHD provides a convenience function to map @code{enum MHD_PredefinedHeader}
values to the human readable names:
-@deftypefun const struct MHD_String * MHD_predef_header_to_string (enum
MHD_PredefinedHeader stk)
+@deftypefun {const struct MHD_String *} MHD_predef_header_to_string (enum
MHD_PredefinedHeader stk)
Get textual representation of the predefined header.
@table @var
@@ -808,7 +861,7 @@ Returns a pointer to the text version, or @code{NULL} if
@node libmicrohttpd-response options
@section Setting response options
-
+@cindex option
This section is about setting response options. In principle, setting
response options works like setting other options in
@@ -883,6 +936,7 @@ An easy way to set a bunch of options without having to
worry
about explicitly allocating an array or checking each return
value is to use @code{MHD_RESPONSE_SET_OPTIONS()}.
+@anchor{MHD_RESPONSE_SET_OPTIONS}
@deftypefun {struct MHD_StatusCode} MHD_RESPONSE_SET_OPTIONS (struct
MHD_Response *response, ...)
@table @var
@@ -913,10 +967,10 @@ response options available to applications today.
@include manual/response_options.inc
-@node libmicrohttpd-response upgrade
-@section Creating a response for protocol upgrades (TBD)
+@node libmicrohttpd-upgrade
+@section Creating a response for protocol upgrades
@cindex WebSockets
-@cindex Upgrade
+@cindex HTTP Upgrade
@cindex HTTP2
@cindex RFC2817
@@ -933,18 +987,19 @@ additional headers, in particular the ``Upgrade'' header.
MHD supports switching protocols using this mechanism
by returning a special @code{MHD_action_upgrade()} action
-from the @ref{@code{MHD_RequestCallback},,MHD_RequestCallback}.
+from the @ref{MHD_RequestCallback,,@code{MHD_RequestCallback}}.
Note that support for upgrading connections is an @emph{optional}
feature that could be left out especially in embedded builds. Use
-@ref{@code{MHD_LIB_INFO_FIXED_HAS_UPGRADE},,MHD_LIB_INFO_FIXED_HAS_UPGRADE}
+@ref{MHD_LIB_INFO_FIXED_HAS_UPGRADE,,@code{MHD_LIB_INFO_FIXED_HAS_UPGRADE}}
to check if the library supports it. Furthermore, connection upgrades
can be disabled for a daemon using
@code{MHD_D_OPTION_DISALLOW_UPGRADE()} for some potential minor
performance benefit. Thus, you may want to make sure the feature is
actually properly enabled.
-@deftypefun const struct MHD_Action * MHD_action_upgrade (struct MHD_Request
*request, const char *upgrade_hdr_value, MHD_UpgradeHandler upgrade_handler,
void *upgrade_handler_cls, size_t num_headers, const struct MHD_NameValueCStr
*headers)
+@anchor{MHD_action_upgrade}
+@deftypefun {const struct MHD_Action *} MHD_action_upgrade (struct MHD_Request
*request, const char *upgrade_hdr_value, MHD_UpgradeHandler upgrade_handler,
void *upgrade_handler_cls, size_t num_headers, const struct MHD_NameValueCStr
*headers)
Create a action object that can be used for 101 Upgrade
responses, for example to implement WebSockets. After sending the
@@ -988,8 +1043,8 @@ can be @code{NULL} if @var{num_headers} is zero;
The @var{upgrade_handler} argument has the following type:
-
-@deftypefn {Function Pointer} void {*MHD_UpgradeHandler} (void *cls, struct
MHD_Request *request, struct MHD_UpgradeHandle *urh)
+@anchor{MHD_UpgradeHandler}
+@deftypefn {Function Pointer} void (*MHD_UpgradeHandler) (void *cls, struct
MHD_Request *request, struct MHD_UpgradeHandle *urh)
Applications must implement functions of this type which be called
once MHD has transmitted the header of the response to the connection
@@ -1030,8 +1085,8 @@ 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()}.
-
-@deftypefun enum MHD_StatusCode MHD_upgraded_recv (struct MHD_UpgradeHandle
*urh, size_t recv_buf_size, void *recv_buf, size_t *received_size,
uint_fast64_t max_wait_millisec)
+@anchor{MHD_upgraded_recv}
+@deftypefun {enum MHD_StatusCode} MHD_upgraded_recv (struct MHD_UpgradeHandle
*urh, size_t recv_buf_size, void *recv_buf, size_t *received_size,
uint_fast64_t max_wait_millisec)
Receive data on the HTTP-Upgraded connection.
@@ -1092,8 +1147,27 @@ if timed wait is not supported by this MHD build or
platform
@end table
@end deftypefun
+@cindex upgraded handle
-@deftypefun enum MHD_StatusCode MHD_upgraded_send (struct MHD_UpgradeHandle
*urh, size_t send_buf_size, const void *send_buf, size_t *sent_size,
uint_fast64_t max_wait_millisec, enum MHD_Bool more_data_to_come)
+After the upgrade, the application must use the
+@code{struct MHD_UpgradedHandle} to continue the
+interaction with the client.
+
+@anchor{MHD_UpgradedHandle}
+@deftp {C Struct} MHD_UpgradedHandle
+Handle for response that has been "upgraded" (say to a WebSocket).
+@end deftp
+
+Using the handle, the application primarily has
+three ways to interact with the client:
+@itemize
+@item send data,
+@item receive data, or
+@item close the connection.
+@end itemize
+
+@anchor{MHD_upgraded_send}
+@deftypefun {enum MHD_StatusCode} MHD_upgraded_send (struct MHD_UpgradeHandle
*urh, size_t send_buf_size, const void *send_buf, size_t *sent_size,
uint_fast64_t max_wait_millisec, enum MHD_Bool more_data_to_come)
Sends data on an HTTP-Upgraded connection.
@@ -1166,8 +1240,8 @@ if timed wait is not supported by this MHD build or
platform
@end deftypefun
-
-@deftypefun enum MHD_StatusCode MHD_upgraded_close (struct MHD_UpgradeHandle
*urh)
+@anchor{MHD_upgraded_close}
+@deftypefun {enum MHD_StatusCode} MHD_upgraded_close (struct MHD_UpgradeHandle
*urh)
Close HTTP-Upgraded connection handle.
The handle cannot be used after successful return from this function.
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [libmicrohttpd2] branch master updated: fix misc internal links,
Admin <=