commit 7c5b14acec6ca88e19113084f41611705e36cac4
parent 61b997d944dc45a698850191ba6679c12898005f
Author: Evgeny Grin (Karlson2k) <k2k@narod.ru>
Date: Thu, 4 Nov 2021 16:15:47 +0300
Doxy: finally clarified how to work with callbacks
Clarified doxy descriptions for the key callback AccessHandlerCallback,
MHD_queue_response(), and MHD_suspend_connection()
Diffstat:
3 files changed, 48 insertions(+), 15 deletions(-)
diff --git a/src/include/microhttpd.h b/src/include/microhttpd.h
@@ -2349,12 +2349,27 @@ typedef enum MHD_Result
/**
- * A client has requested the given url using the given method
- * (#MHD_HTTP_METHOD_GET, #MHD_HTTP_METHOD_PUT,
- * #MHD_HTTP_METHOD_DELETE, #MHD_HTTP_METHOD_POST, etc). The callback
- * must call MHD callbacks to provide content to give back to the
- * client and return an HTTP status code (i.e. #MHD_HTTP_OK,
- * #MHD_HTTP_NOT_FOUND, etc.).
+ * A client has requested the given @a url using the given @a method
+ * (#MHD_HTTP_METHOD_GET, #MHD_HTTP_METHOD_PUT, #MHD_HTTP_METHOD_DELETE,
+ * #MHD_HTTP_METHOD_POST, etc).
+ *
+ * The callback must call MHD function MHD_queue_response() to provide content
+ * to give back to the client and return an HTTP status code
+ * (i.e. #MHD_HTTP_OK, #MHD_HTTP_NOT_FOUND, etc.). The response can be created
+ * in this callback or prepared in advance.
+ * As soon as response is provided this callback will not be called anymore
+ * for the current request.
+ * Alternatively, callback may call MHD_suspend_connection() to temporarily
+ * suspend data processing for this connection.
+ * For each HTTP request this callback is called several times:
+ * * after request headers are fully received and decoded,
+ * * for each received part of request body (optional, if request has body),
+ * * when request is fully received.
+ * If response is provided before request is fully received, the rest
+ * of the request is discarded and connection is automatically closed
+ * after sending response.
+ * If the request is fully received, but response hasn't been provided and
+ * connection is not suspended, the callback can be called again immediately.
*
* @param cls argument given together with the function
* pointer when the handler was registered with MHD
@@ -2386,6 +2401,8 @@ typedef enum MHD_Result
* @return #MHD_YES if the connection was handled successfully,
* #MHD_NO if the socket must be closed due to a serious
* error while handling the request
+ *
+ * @sa #MHD_queue_response()
*/
typedef enum MHD_Result
(*MHD_AccessHandlerCallback)(void *cls,
@@ -3162,12 +3179,18 @@ MHD_lookup_connection_value_n (struct MHD_Connection *connection,
* Queue a response to be transmitted to the client (as soon as
* possible but after #MHD_AccessHandlerCallback returns).
*
+ * For any active connection this function must be called
+ * only by #MHD_AccessHandlerCallback callback.
+ * For suspended connection this function can be called at any moment. Response
+ * will be sent as soon as connection is resumed.
+ *
* @param connection the connection identifying the client
* @param status_code HTTP status code (i.e. #MHD_HTTP_OK)
* @param response response to transmit
* @return #MHD_NO on error (i.e. reply already sent),
* #MHD_YES on success or if message has been queued
* @ingroup response
+ * @sa #MHD_AccessHandlerCallback
*/
_MHD_EXTERN enum MHD_Result
MHD_queue_response (struct MHD_Connection *connection,
@@ -3176,8 +3199,9 @@ MHD_queue_response (struct MHD_Connection *connection,
/**
- * Suspend handling of network data for a given connection. This can
- * be used to dequeue a connection from MHD's event loop for a while.
+ * Suspend handling of network data for a given connection.
+ * This can be used to dequeue a connection from MHD's event loop
+ * (not applicable to thread-per-connection!) for a while.
*
* If you use this API in conjunction with an "internal" socket polling,
* you must set the option #MHD_USE_ITC to ensure that a resumed
@@ -3199,6 +3223,8 @@ MHD_queue_response (struct MHD_Connection *connection,
* resume all connections before stopping the daemon.
*
* @param connection the connection to suspend
+ *
+ * @sa #MHD_AccessHandlerCallback
*/
_MHD_EXTERN void
MHD_suspend_connection (struct MHD_Connection *connection);
diff --git a/src/microhttpd/connection.c b/src/microhttpd/connection.c
@@ -4920,12 +4920,18 @@ MHD_set_connection_option (struct MHD_Connection *connection,
* Queue a response to be transmitted to the client (as soon as
* possible but after #MHD_AccessHandlerCallback returns).
*
+ * For any active connection this function must be called
+ * only by #MHD_AccessHandlerCallback callback.
+ * For suspended connection this function can be called at any moment. Response
+ * will be sent as soon as connection is resumed.
+ *
* @param connection the connection identifying the client
* @param status_code HTTP status code (i.e. #MHD_HTTP_OK)
* @param response response to transmit
* @return #MHD_NO on error (i.e. reply already sent),
* #MHD_YES on success or if message has been queued
* @ingroup response
+ * @sa #MHD_AccessHandlerCallback
*/
enum MHD_Result
MHD_queue_response (struct MHD_Connection *connection,
diff --git a/src/microhttpd/daemon.c b/src/microhttpd/daemon.c
@@ -3126,14 +3126,13 @@ internal_suspend_connection_ (struct MHD_Connection *connection)
/**
- * Suspend handling of network data for a given connection. This can
- * be used to dequeue a connection from MHD's event loop (external
- * select, internal select or thread pool; not applicable to
- * thread-per-connection!) for a while.
+ * Suspend handling of network data for a given connection.
+ * This can be used to dequeue a connection from MHD's event loop
+ * (not applicable to thread-per-connection!) for a while.
*
- * If you use this API in conjunction with a internal select or a
- * thread pool, you must set the option #MHD_USE_ITC to
- * ensure that a resumed connection is immediately processed by MHD.
+ * If you use this API in conjunction with an "internal" socket polling,
+ * you must set the option #MHD_USE_ITC to ensure that a resumed
+ * connection is immediately processed by MHD.
*
* Suspended connections continue to count against the total number of
* connections allowed (per daemon, as well as per IP, if such limits
@@ -3155,6 +3154,8 @@ internal_suspend_connection_ (struct MHD_Connection *connection)
* daemon's select()/poll()/etc.
*
* @param connection the connection to suspend
+ *
+ * @sa #MHD_AccessHandlerCallback
*/
void
MHD_suspend_connection (struct MHD_Connection *connection)
