[libmicrohttpd] 03/05: MHD_add_response_header: added detailed comment about automatic headers

[gnunet]

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

karlson2k pushed a commit to branch master
in repository libmicrohttpd.

commit bbbcf4838ae137052e8b8a98f26e14a90c8b420c
Author: Evgeny Grin (Karlson2k) <k2k@narod.ru>
AuthorDate: Sun Jun 13 16:53:46 2021 +0300

    MHD_add_response_header: added detailed comment about automatic headers
    
    Automatic header handling was not documented, while this mechanism is
    important for MHD functionality and the absence of this description
    resulted in wrong assumptions made by users.
---
 src/include/microhttpd.h  | 30 ++++++++++++++++++++++++++----
 src/microhttpd/response.c | 31 +++++++++++++++++++++++++++----
 2 files changed, 53 insertions(+), 8 deletions(-)

diff --git a/src/include/microhttpd.h b/src/include/microhttpd.h
index 0fee465c..4f09bee5 100644
--- a/src/include/microhttpd.h
+++ b/src/include/microhttpd.h
@@ -3612,10 +3612,32 @@ MHD_destroy_response (struct MHD_Response *response);
 /**
  * Add a header line to the response.
  *
- * @param response response to add a header to
- * @param header the header to add
- * @param content value to add
- * @return #MHD_NO on error (i.e. invalid header or content format),
+ * When reply is generated with queued response, some headers are generated
+ * automatically. Automatically generated headers are only sent to the client,
+ * but not added back to the response.
+ *
+ * The list of automatic headers:
+ * + "Date" header is added automatically unless already set by
+ *   this function
+ * + "Content-Length" is added automatically when required, attempt to set
+ *   it manually by this function is ignored.
+ *   @see #MHD_RF_INSANITY_HEADER_CONTENT_LENGTH
+ * + "Transfer-Encoding" with value "chunked" is added automatically,
+ *   when chunked transfer encoding is used automatically. Same header with
+ *   the same value can be set manually by this function to enforce chunked
+ *   encoding, however for HTTP/1.0 clients chunked encoding will not be used
+ *   and manually set "Transfer-Encoding" header is automatically removed
+ *   for HTTP/1.0 clients
+ * + "Connection" is added automatically with value "Keep-Alive" or "Close".
+ *   The header "Connection" with value "Close" could be set by this function
+ *   to enforce closure of the connection after sending this response.
+ *   "Keep-Alive" cannot be enforced and will be removed automatically.
+ *
+ * @param response the response to add a header to
+ * @param header the header name to add
+ * @param content the header value to add
+ * @return #MHD_YES on success,
+ *         #MHD_NO on error (i.e. invalid header or content format),
  *         or out of memory
  * @ingroup response
  */
diff --git a/src/microhttpd/response.c b/src/microhttpd/response.c
index 3c8444ce..ff034194 100644
--- a/src/microhttpd/response.c
+++ b/src/microhttpd/response.c
@@ -124,10 +124,33 @@ add_response_entry (struct MHD_Response *response,
 /**
  * Add a header line to the response.
  *
- * @param response response to add a header to
- * @param header the header to add
- * @param content value to add
- * @return #MHD_NO on error (i.e. invalid header or content format).
+ * When reply is generated with queued response, some headers are generated
+ * automatically. Automatically generated headers are only sent to the client,
+ * but not added back to the response.
+ *
+ * The list of automatic headers:
+ * + "Date" header is added automatically unless already set by
+ *   this function
+ * + "Content-Length" is added automatically when required, attempt to set
+ *   it manually by this function is ignored.
+ *   @see #MHD_RF_INSANITY_HEADER_CONTENT_LENGTH
+ * + "Transfer-Encoding" with value "chunked" is added automatically,
+ *   when chunked transfer encoding is used automatically. Same header with
+ *   the same value can be set manually by this function to enforce chunked
+ *   encoding, however for HTTP/1.0 clients chunked encoding will not be used
+ *   and manually set "Transfer-Encoding" header is automatically removed
+ *   for HTTP/1.0 clients
+ * + "Connection" is added automatically with value "Keep-Alive" or "Close".
+ *   The header "Connection" with value "Close" could be set by this function
+ *   to enforce closure of the connection after sending this response.
+ *   "Keep-Alive" cannot be enforced and will be removed automatically.
+ *
+ * @param response the response to add a header to
+ * @param header the header name to add
+ * @param content the header value to add
+ * @return #MHD_YES on success,
+ *         #MHD_NO on error (i.e. invalid header or content format),
+ *         or out of memory
  * @ingroup response
  */
 enum MHD_Result

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