commit 76974808b9109dc00a8c2b8ea0503261cacc5bbe
parent c3b29e2e9a860a301bbbfea10e01ade862a9ee25
Author: Evgeny Grin (Karlson2k) <k2k@drgrin.dev>
Date: Sat, 4 Jul 2026 17:26:12 +0200
Clarified StatusCode sections descriptions
Diffstat:
2 files changed, 50 insertions(+), 46 deletions(-)
diff --git a/src/include/microhttpd2.h b/src/include/microhttpd2.h
@@ -401,24 +401,24 @@ struct MHD_UploadAction;
/**
- * Return values for reporting errors, also used for logging.
+ * Status codes returned by API functions, also used for logging.
*
- * A value of 0 indicates success (as a return value).
- * Values between 0 and 10000 must be handled explicitly by the app.
- * Values from 10000-19999 are informational.
- * Values from 20000-29999 indicate successful operations.
- * Values from 30000-39999 indicate unsuccessful (normal) operations.
- * Values from 40000-49999 indicate client errors.
- * Values from 50000-59999 indicate MHD server errors.
- * Values from 60000-65535 indicate application errors.
+ * As a return value, zero (#MHD_SC_OK) always indicates success.
+ * Values 00001-09999 must be handled explicitly by the application.
+ * Values 10000-19999 are informational events.
+ * Values 20000-29999 indicate successful operations.
+ * Values 30000-39999 indicate unsuccessful but normal operations.
+ * Values 40000-49999 indicate client (or network) errors.
+ * Values 50000-59999 indicate MHD-internal (or platform) errors.
+ * Values 60000-65535 indicate application errors.
*
* @ingroup general
*/
enum MHD_FIXED_ENUM_MHD_SET_ MHD_StatusCode
{
- /* 00000-level status codes indicate return values
- the application must act on. */
+ /* 00000-level codes are return values the application must handle.
+ The zero code always means success. */
/**
* Successful operation (not used for logging).
@@ -427,8 +427,7 @@ enum MHD_FIXED_ENUM_MHD_SET_ MHD_StatusCode
MHD_SC_OK = 0
,
- /* 10000-level status codes indicate intermediate
- results of some kind. */
+ /* 10000-level codes are purely informational events. */
/**
* Informational event, MHD started.
@@ -467,7 +466,9 @@ enum MHD_FIXED_ENUM_MHD_SET_ MHD_StatusCode
MHD_SC_ACCEPTED_SOCKADDR_TOO_LARGE = 10041
,
- /* 20000-level status codes indicate success of some kind. */
+ /* 20000-level codes indicate successful operations. */
+ /* Examples: a connection has been closed normally, the response data
+ generation has been completed. */
/**
* MHD is closing a connection after the client closed it
@@ -488,8 +489,9 @@ enum MHD_FIXED_ENUM_MHD_SET_ MHD_StatusCode
MHD_SC_AUTH_ABSENT = 20060
,
- /* 30000-level status codes indicate transient failures
- that might go away if the client tries again. */
+ /* 30000-level codes indicate unsuccessful but normal operations. */
+ /* Examples: a connections limit has been reached, the accept policy
+ callback has rejected a connection, a memory pool is exhausted. */
/**
@@ -613,8 +615,7 @@ enum MHD_FIXED_ENUM_MHD_SET_ MHD_StatusCode
MHD_SC_NO_SYS_RESOURCES = 30180
,
- /* 40000-level errors are caused by the HTTP client
- (or the network) */
+ /* 40000-level errors are caused by the HTTP client or the network. */
/**
* MHD is closing a connection because parsing the
@@ -846,9 +847,10 @@ enum MHD_FIXED_ENUM_MHD_SET_ MHD_StatusCode
MHD_SC_ALPN_H2_NO_PREFACE = 43001
,
- /* 50000-level errors are because of an error internal
- to the MHD logic, possibly including our interaction
- with the operating system (but not the application) */
+ /* 50000-level errors are internal MHD or platform failures,
+ not caused by the application (see 60000-level). */
+ /* Examples: a socket error on a broken connection, a read failure for
+ a file-backed response, an unexpected accept() error. */
/**
* This build of MHD does not support TLS, but the application
@@ -1496,8 +1498,8 @@ enum MHD_FIXED_ENUM_MHD_SET_ MHD_StatusCode
MHD_SC_INTERNAL_ERROR = 59900
,
- /* 60000-level errors are because the application
- logic did something wrong or generated an error. */
+ /* 60000-level errors are caused by the application
+ (callbacks, settings or API misuse). */
/**
* The application called function too early.
diff --git a/src/include/microhttpd2_preamble.h.in b/src/include/microhttpd2_preamble.h.in
@@ -401,24 +401,24 @@ struct MHD_UploadAction;
/**
- * Return values for reporting errors, also used for logging.
+ * Status codes returned by API functions, also used for logging.
*
- * A value of 0 indicates success (as a return value).
- * Values between 0 and 10000 must be handled explicitly by the app.
- * Values from 10000-19999 are informational.
- * Values from 20000-29999 indicate successful operations.
- * Values from 30000-39999 indicate unsuccessful (normal) operations.
- * Values from 40000-49999 indicate client errors.
- * Values from 50000-59999 indicate MHD server errors.
- * Values from 60000-65535 indicate application errors.
+ * As a return value, zero (#MHD_SC_OK) always indicates success.
+ * Values 00001-09999 must be handled explicitly by the application.
+ * Values 10000-19999 are informational events.
+ * Values 20000-29999 indicate successful operations.
+ * Values 30000-39999 indicate unsuccessful but normal operations.
+ * Values 40000-49999 indicate client (or network) errors.
+ * Values 50000-59999 indicate MHD-internal (or platform) errors.
+ * Values 60000-65535 indicate application errors.
*
* @ingroup general
*/
enum MHD_FIXED_ENUM_MHD_SET_ MHD_StatusCode
{
- /* 00000-level status codes indicate return values
- the application must act on. */
+ /* 00000-level codes are return values the application must handle.
+ The zero code always means success. */
/**
* Successful operation (not used for logging).
@@ -427,8 +427,7 @@ enum MHD_FIXED_ENUM_MHD_SET_ MHD_StatusCode
MHD_SC_OK = 0
,
- /* 10000-level status codes indicate intermediate
- results of some kind. */
+ /* 10000-level codes are purely informational events. */
/**
* Informational event, MHD started.
@@ -467,7 +466,9 @@ enum MHD_FIXED_ENUM_MHD_SET_ MHD_StatusCode
MHD_SC_ACCEPTED_SOCKADDR_TOO_LARGE = 10041
,
- /* 20000-level status codes indicate success of some kind. */
+ /* 20000-level codes indicate successful operations. */
+ /* Examples: a connection has been closed normally, the response data
+ generation has been completed. */
/**
* MHD is closing a connection after the client closed it
@@ -488,8 +489,9 @@ enum MHD_FIXED_ENUM_MHD_SET_ MHD_StatusCode
MHD_SC_AUTH_ABSENT = 20060
,
- /* 30000-level status codes indicate transient failures
- that might go away if the client tries again. */
+ /* 30000-level codes indicate unsuccessful but normal operations. */
+ /* Examples: a connections limit has been reached, the accept policy
+ callback has rejected a connection, a memory pool is exhausted. */
/**
@@ -613,8 +615,7 @@ enum MHD_FIXED_ENUM_MHD_SET_ MHD_StatusCode
MHD_SC_NO_SYS_RESOURCES = 30180
,
- /* 40000-level errors are caused by the HTTP client
- (or the network) */
+ /* 40000-level errors are caused by the HTTP client or the network. */
/**
* MHD is closing a connection because parsing the
@@ -846,9 +847,10 @@ enum MHD_FIXED_ENUM_MHD_SET_ MHD_StatusCode
MHD_SC_ALPN_H2_NO_PREFACE = 43001
,
- /* 50000-level errors are because of an error internal
- to the MHD logic, possibly including our interaction
- with the operating system (but not the application) */
+ /* 50000-level errors are internal MHD or platform failures,
+ not caused by the application (see 60000-level). */
+ /* Examples: a socket error on a broken connection, a read failure for
+ a file-backed response, an unexpected accept() error. */
/**
* This build of MHD does not support TLS, but the application
@@ -1496,8 +1498,8 @@ enum MHD_FIXED_ENUM_MHD_SET_ MHD_StatusCode
MHD_SC_INTERNAL_ERROR = 59900
,
- /* 60000-level errors are because the application
- logic did something wrong or generated an error. */
+ /* 60000-level errors are caused by the application
+ (callbacks, settings or API misuse). */
/**
* The application called function too early.
