[libmicrohttpd] 02/02: Doxy: finally clarified how to work with callbacks

[gnunet]

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

karlson2k pushed a commit to branch master
in repository libmicrohttpd.

commit 7c5b14acec6ca88e19113084f41611705e36cac4
Author: Evgeny Grin (Karlson2k) <k2k@narod.ru>
AuthorDate: Thu Nov 4 16:15:47 2021 +0300

    Doxy: finally clarified how to work with callbacks
    
    Clarified doxy descriptions for the key callback AccessHandlerCallback,
    MHD_queue_response(), and MHD_suspend_connection()
---
 src/include/microhttpd.h    | 42 ++++++++++++++++++++++++++++++++++--------
 src/microhttpd/connection.c |  6 ++++++
 src/microhttpd/daemon.c     | 15 ++++++++-------
 3 files changed, 48 insertions(+), 15 deletions(-)

diff --git a/src/include/microhttpd.h b/src/include/microhttpd.h
index 9fece2e5..3f285eb5 100644
--- 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
index eef0f5d3..a068bfe4 100644
--- 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
index 0ff7bffc..32334621 100644
--- 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)

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