libmicrohttpd

commit c3563144ee580e94e242c187772c51714e1b2311
parent 470e65c68fd346d8c5367d141f049bbc018ca0fb
Author: Evgeny Grin (Karlson2k) <k2k@narod.ru>
Date:   Mon, 14 Mar 2022 21:22:21 +0300

MHD_queue_response(): significantly improved doxy

Diffstat:
M
src/include/microhttpd.h
 | 
22
++++++++++++++++++----
M
src/microhttpd/connection.c
 | 
22
++++++++++++++++++----

2 files changed, 36 insertions(+), 8 deletions(-)
diff --git a/src/include/microhttpd.h b/src/include/microhttpd.h
@@ -3224,10 +3224,24 @@ MHD_lookup_connection_value_n (struct MHD_Connection *connection,
  * For suspended connection this function can be called at any moment. Response
  * will be sent as soon as connection is resumed.
  *
- * If response object is used to answer HEAD request then the body of
- * the response is not used, while all headers (including automatic headers)
- * are used. In practice, the same response object can be used to respond to
- * both HEAD and GET requests.
+ * If HTTP specifications require use no body in reply, like @a status_code with
+ * value 1xx, the response body is automatically not sent even if it is present
+ * in the response. No "Content-Length" or "Transfer-Encoding" headers are
+ * generated and added.
+ *
+ * When the response is used to respond HEAD request or used with @a status_code
+ * #MHD_HTTP_NOT_MODIFIED, then response body is not sent, but "Content-Length"
+ * header is added automatically based the size of the body in the response.
+ * If body size it set to #MHD_SIZE_UNKNOWN or chunked encoding is enforced
+ * then "Transfer-Encoding: chunked" header (for HTTP/1.1 only) is added instead
+ * of "Content-Length" header.
+ *
+ * In situations, where reply body is required, like answer for the GET request
+ * with @a status_code #MHD_HTTP_OK, headers "Content-Length" (for known body
+ * size) or "Transfer-Encoding: chunked" (for #MHD_SIZE_UNKNOWN with HTTP/1.1)
+ * are added automatically.
+ * In practice, the same response object can be used to respond to both HEAD and
+ * GET requests.
  *
  * @param connection the connection identifying the client
  * @param status_code HTTP status code (i.e. #MHD_HTTP_OK)
diff --git a/src/microhttpd/connection.c b/src/microhttpd/connection.c
@@ -5136,10 +5136,24 @@ MHD_set_connection_option (struct MHD_Connection *connection,
  * For suspended connection this function can be called at any moment. Response
  * will be sent as soon as connection is resumed.
  *
- * If response object is used to answer HEAD request then the body of
- * the response is not used, while all headers (including automatic headers)
- * are used. In practice, the same response object can be used to respond to
- * both HEAD and GET requests.
+ * If HTTP specifications require use no body in reply, like @a status_code with
+ * value 1xx, the response body is automatically not sent even if it is present
+ * in the response. No "Content-Length" or "Transfer-Encoding" headers are
+ * generated and added.
+ *
+ * When the response is used to respond HEAD request or used with @a status_code
+ * #MHD_HTTP_NOT_MODIFIED, then response body is not sent, but "Content-Length"
+ * header is added automatically based the size of the body in the response.
+ * If body size it set to #MHD_SIZE_UNKNOWN or chunked encoding is enforced
+ * then "Transfer-Encoding: chunked" header (for HTTP/1.1 only) is added instead
+ * of "Content-Length" header.
+ *
+ * In situations, where reply body is required, like answer for the GET request
+ * with @a status_code #MHD_HTTP_OK, headers "Content-Length" (for known body
+ * size) or "Transfer-Encoding: chunked" (for #MHD_SIZE_UNKNOWN with HTTP/1.1)
+ * are added automatically.
+ * In practice, the same response object can be used to respond to both HEAD and
+ * GET requests.
  *
  * @param connection the connection identifying the client
  * @param status_code HTTP status code (i.e. #MHD_HTTP_OK)