commit 8dce8e2c7408b0f391b5f64cafb4392e91fb387a
parent 76cc7599b28bf942336f2bfa41045f4b2cb2c4db
Author: Evgeny Grin (Karlson2k) <k2k@drgrin.dev>
Date: Thu, 29 Oct 2026 22:57:06 +0100
microhttpd2.h: corrected public contract for some functions actually accepting NULL
Diffstat:
4 files changed, 38 insertions(+), 23 deletions(-)
diff --git a/doc/manual/responses.inc b/doc/manual/responses.inc
@@ -227,11 +227,13 @@ in the @var{buffer} will be copied into internal storage of MHD.
@item sc
HTTP status code for the response.
-@item size
-size of the data portion of the response;
+@item buffer_size
+size of the data portion of the response; must be zero if @var{buffer}
+is @code{NULL};
@item buffer
-the body to return, must contain at least @var{size} bytes of data;
+the body to return, must contain at least @var{buffer_size} bytes of data;
+can be @code{NULL} if @var{buffer_size} is zero;
the @var{buffer} can become invalid immediately after the
call to @code{MHD_response_from_buffer_copy()} returns as MHD
will make a copy of the data contained in it.
@@ -276,10 +278,15 @@ Create a response object from an array of memory buffers.
HTTP status code for the response.
@item iov_count
-the number of elements in @var{iov};
+the number of elements in @var{iov}; must be zero if @var{iov}
+is @code{NULL};
@item iov
-the array for response data buffers of length @var{iov_count}, an internal copy of the @var{iov} will be made; however, note that the data pointed to by the @var{iov} is @strong{not} copied and must be preserved unchanged at the given locations until the response is no longer in use and the @var{free_cb} is called;
+the array for response data buffers of length @var{iov_count}; can be
+@code{NULL} if @var{iov_count} is zero; an internal copy of the @var{iov}
+will be made; however, note that the data pointed to by the @var{iov} is
+@strong{not} copied and must be preserved unchanged at the given locations
+until the response is no longer in use and the @var{free_cb} is called;
@item free_cb
the callback to call to free resources associated with @var{iov};
diff --git a/src/include/microhttpd2.h b/src/include/microhttpd2.h
@@ -3904,9 +3904,10 @@ struct MHD_ServerCredentialsContext;
* server.
*
* @param mscc the context
- * @param psk_size the number of bytes in @a psk
+ * @param psk_size the number of bytes in @a psk,
+ * must be zero if @a psk is NULL
* @param psk the pre-shared-key; should be allocated with malloc(),
- * will be freed by MHD
+ * will be freed by MHD; can be NULL if @a psk_size is zero
*/
MHD_EXTERN_ enum MHD_StatusCode
MHD_connection_set_psk (
@@ -6637,10 +6638,12 @@ MHD_FN_PAR_IN_SIZE_ (3, 2);
* header information.
*
* @param sc status code to use for the response
- * @param buffer_size the size of the data portion of the response
- * @param buffer the @a size bytes containing the response's data portion,
- * an internal copy will be made, there is no need to
- * keep this data after return from this function
+ * @param buffer_size the size of the data portion of the response,
+ * must be zero if @a buffer is NULL
+ * @param buffer the @a buffer_size bytes containing the response's data
+ * portion, can be NULL if @a buffer_size is zero,
+ * an internal copy will be made, there is no need to keep this
+ * data after return from this function
* @return new response object on success,
* NULL on failure (i.e. invalid arguments, out of memory)
* @ingroup response
@@ -6682,9 +6685,10 @@ struct MHD_IoVec
* headers) are used.
*
* @param sc status code to use for the response
- * @param iov_count the number of elements in @a iov
- * @param iov the array for response data buffers, an internal copy of this
- * will be made
+ * @param iov_count the number of elements in @a iov,
+ * must be zero if @a iov is NULL
+ * @param iov the array for response data buffers, can be NULL if @a iov_count
+ * is zero, an internal copy of this will be made
* @param free_cb the callback to clean up any data associated with @a iov when
* the response is destroyed.
* @param free_cb_cls the argument passed to @a free_cb
diff --git a/src/include/microhttpd2_main.h.in b/src/include/microhttpd2_main.h.in
@@ -1577,10 +1577,12 @@ MHD_FN_PAR_IN_SIZE_ (3, 2);
* header information.
*
* @param sc status code to use for the response
- * @param buffer_size the size of the data portion of the response
- * @param buffer the @a size bytes containing the response's data portion,
- * an internal copy will be made, there is no need to
- * keep this data after return from this function
+ * @param buffer_size the size of the data portion of the response,
+ * must be zero if @a buffer is NULL
+ * @param buffer the @a buffer_size bytes containing the response's data
+ * portion, can be NULL if @a buffer_size is zero,
+ * an internal copy will be made, there is no need to keep this
+ * data after return from this function
* @return new response object on success,
* NULL on failure (i.e. invalid arguments, out of memory)
* @ingroup response
@@ -1622,9 +1624,10 @@ struct MHD_IoVec
* headers) are used.
*
* @param sc status code to use for the response
- * @param iov_count the number of elements in @a iov
- * @param iov the array for response data buffers, an internal copy of this
- * will be made
+ * @param iov_count the number of elements in @a iov,
+ * must be zero if @a iov is NULL
+ * @param iov the array for response data buffers, can be NULL if @a iov_count
+ * is zero, an internal copy of this will be made
* @param free_cb the callback to clean up any data associated with @a iov when
* the response is destroyed.
* @param free_cb_cls the argument passed to @a free_cb
diff --git a/src/include/microhttpd2_preamble.h.in b/src/include/microhttpd2_preamble.h.in
@@ -3904,9 +3904,10 @@ struct MHD_ServerCredentialsContext;
* server.
*
* @param mscc the context
- * @param psk_size the number of bytes in @a psk
+ * @param psk_size the number of bytes in @a psk,
+ * must be zero if @a psk is NULL
* @param psk the pre-shared-key; should be allocated with malloc(),
- * will be freed by MHD
+ * will be freed by MHD; can be NULL if @a psk_size is zero
*/
MHD_EXTERN_ enum MHD_StatusCode
MHD_connection_set_psk (
