microhttpd2.h edits

src/include/microhttpd2.h

@@ -229,7 +229,6 @@ typedef intptr_t ssize_t;
  */
 #define MHD_VERSION 0x02000000
 
-// FIXME: doxy edited
 /**
  * Representation of 'bool' in the public API as stdbool.h may not
  * always be available and presence of 'bool' keyword may depend on
@@ -260,7 +259,6 @@ enum MHD_Bool
  */
 struct MHD_String
 {
-  // FIXME: edited
   /**
    * Number of characters in @e buf, not counting 0-termination.
    */
@@ -1270,8 +1268,7 @@ MHD_status_code_is_fatal(enum MHD_StatusCode code)
 MHD_FUNC_CONST_;
 
 
-// FIXME: struct MHD_String
-const char *
+const struct MHD_String *
 MHD_status_code_to_string (enum MHD_StatusCode code)
 MHD_FUNC_CONST_ MHD_FUNC_RETURNS_NONNULL_;
 
@@ -1360,7 +1357,7 @@ enum MHD_HTTP_Method
 
 // FIXME: added
 // FIXME: return 'const char *'?
-_MHD_EXTERN const struct MHD_String
+_MHD_EXTERN const struct MHD_String *
 MHD_get_http_method_string(enum MHD_HTTP_Method method)
 MHD_FUNC_CONST_;
 
@@ -1372,7 +1369,6 @@ MHD_FUNC_CONST_;
  * @{
  */
 
-// FIXME: added
 /* Main HTTP methods. */
 /* Safe.     Idempotent.     RFC9110, Section 9.3.1. */
 #define MHD_HTTP_METHOD_STR_GET      "GET"
@@ -2064,7 +2060,6 @@ typedef const struct MHD_Action *
                         uint_fast64_t upload_size);
 
 
-// FIXME: add port? It is used by most of the application.
 /**
  * Create (but do not yet start) an MHD daemon.
  * Usually, you will want to set various options before
@@ -2253,6 +2248,7 @@ enum MHD_DeamonOptionBool
   /**
    * Disable converting plus ('+') character to space in GET
    * parameters (URI part after '?').
+   * TODO: Add explanation, RFCs, HTML
    */
   MHD_DAEMON_OB_DISABLE_PLUS_SPACE
 };
@@ -2477,6 +2473,7 @@ struct MHD_DaemonOptioniUIntEntry
    * The value to update for the @a option
    */
   unsigned int value;
+  // TODO: union
 };
 
 /**
@@ -2493,15 +2490,14 @@ struct MHD_DaemonOptioniUIntEntry
  *         #MHD_NO if at least single option failed (for more
  *         details check @a results)
  */
-_MHD_EXTERN enum MHD_Bool
+_MHD_EXTERN enum MHD_StatusCode // First failed // TODO: Document that rest may be used
 MHD_daemon_set_option_uint (
   struct MHD_Daemon *daemon,
   size_t num_entries,
-  struct MHD_DaemonOptioniUIntEntry opt_val[MHD_C99_ (static num_entries)],
-  enum MHD_StatusCode *results)
+  struct MHD_DaemonOptioniUIntEntry opt_val[MHD_C99_ (static num_entries)])
 MHD_FUNC_PARAM_NONNULL_ (1) MHD_FUNC_PARAM_NONNULL_ (3);
 
-
+// TODO: combine all types of options into single list with union
 /**
  * Accept connections from the given socket.  Socket
  * must be a TCP or UNIX domain (stream) socket.
@@ -2519,7 +2515,7 @@ MHD_FUNC_PARAM_NONNULL_ (1) MHD_FUNC_PARAM_NONNULL_ (3);
  *         #MHD_SC_FEATURE_NOT_AVAILABLE if this options is not supported on this system
  *         #MHD_SC_OPTIONS_CONFLICT
  */
-_MHD_EXTERN enum MHD_StatusCode // FIXME - corrected
+_MHD_EXTERN enum MHD_StatusCode
 MHD_daemon_listen_socket (struct MHD_Daemon *daemon,
                           MHD_socket listen_socket)
 MHD_FUNC_PARAM_NONNULL_ (1);
@@ -2576,7 +2572,6 @@ MHD_FUNC_PARAM_NONNULL_ (1);
  */
 enum MHD_ProtocolStrictLevel
 {
-// FIXME: updated
 
   /* * Basic levels * */
   /**
@@ -2655,7 +2650,6 @@ enum MHD_ProtocolStrictLevel
   MHD_PSL_EXTRA_PERMISSIVE = -3,
 };
 
-// FIXME: Added
 /**
  * The way Strict Level is enforced.
  * MHD can be compiled with limited set of strictness levels.
@@ -2678,7 +2672,7 @@ enum MHD_UseStictLevel
    * Use requested level if available or the nearest level (stricter
    * or more permissive).
    */
-  MHD_USL_NEAREST = -1
+  MHD_USL_NEAREST = 2
 };
 
 /**
@@ -2691,7 +2685,7 @@ enum MHD_UseStictLevel
  *         #MHD_SC_TOO_LATE if this option was set after the daemon was started and it cannot be set anymore
  *         #MHD_SC_FEATURE_DISABLED if this option is not implemented in this version of the library,
  */
-_MHD_EXTERN enum MHD_StatusCode // FIXME - corrected
+_MHD_EXTERN enum MHD_StatusCode
 MHD_daemon_protocol_strict_level (struct MHD_Daemon *daemon,
                                   enum MHD_ProtocolStrictLevel sl,
                                   enum MHD_UseStictLevel how)
@@ -2699,6 +2693,7 @@ MHD_FUNC_PARAM_NONNULL_ (1);
 
 // FIXME: do we want to keep it as generic API?
 // FIXME: other TLS backends will not support it.
+// TODO: remove and use low-level from callback
 // + TLS ciphers
 // + 'application name' for lookup
 // of TLS cipher option in configuration file.
@@ -2710,6 +2705,7 @@ MHD_daemon_set_option_string (struct MHD_Daemon *daemon,
                               const char *value)
 MHD_FUNC_PARAM_NONNULL_ (1);
 
+// TODO: three options
 /**
  * Provide TLS key and certificate data in-memory.
  *
@@ -2765,21 +2761,22 @@ MHD_FUNC_PARAM_NONNULL_ (1);
  */
 enum MHD_TlsBackend
 {
+  /**
+   * TODO add descr
+   */
+  MHD_TLS_BACKEND_NONE = 0,
   /**
    * Use best available TLS backend.
    * Currently this is equivalent to GnuTLS (if TLS is enabled
    * for MHD build).
    */
-  MHD_TLS_BACKEND_ANY = 0,
+  MHD_TLS_BACKEND_ANY = 1,
   /**
    * Use GnuTLS as TLS backend.
    */
-  MHD_TLS_BACKEND_GNUTLS = 1
+  MHD_TLS_BACKEND_GNUTLS = 2
 };
 
-// FIXME: should we enforce the order of settings applied?
-// Is it required to first enable TLS before using any
-// TLS-specific settings?
 /**
  * Enable and configure TLS.
  *
@@ -2796,7 +2793,6 @@ enum MHD_TlsBackend
 _MHD_EXTERN enum MHD_StatusCode
 MHD_daemon_set_tls_backend (struct MHD_Daemon *daemon,
                             enum MHD_TlsBackend backend);
-
 MHD_FUNC_PARAM_NONNULL_ (1);
 
 
@@ -3035,15 +3031,14 @@ MHD_daemon_set_notify_connection (struct MHD_Daemon *daemon,
 MHD_FUNC_PARAM_NONNULL_ (1);
 
 
-// FIXME: Added
 /**
  * The `enum MHD_ConnectionNotificationCode` specifies types
  * of connection notifications.
+ * TODO: document possible extensibility
  * @ingroup request
  */
 enum MHD_StreamNotificationCode
 {
-  // FIXME: more codes, like "server started", "closed with error"&
   /**
    * A new connection has been started.
    * @ingroup request
@@ -3058,7 +3053,14 @@ enum MHD_StreamNotificationCode
 
 };
 
-// FIXME: Added
+// TODO: finish
+struct MHD_something
+{
+  struct MHD_Stream *stream; // const?
+  enum MHD_StreamNotificationCode code;
+  union something;
+};
+
 /**
  * Signature of the callback used by MHD to notify the
  * application about started/stopped data stream
@@ -3074,11 +3076,9 @@ enum MHD_StreamNotificationCode
 typedef void
 (MHD_FUNC_PARAM_NONNULL_ (2)
  *MHD_NotifyStreamCallback) (void *cls,
-                             struct MHD_Stream *stream,
-                             enum MHD_ConnectionNotificationCode toe);
+                             const struct MHD_something *notification);
 
 
-// FIXME: Added
 /**
  * Register a function that should be called whenever a stream is
  * started or closed.
@@ -3108,6 +3108,7 @@ enum MHD_DaemonOptionSizet
   MHD_DAEMON_OPTION_SIZET_CONN_MEM_LIMIT,
   // FIXME: remove this option completely and manage it in MHD?
   // Users do not have clear understanding of what is it and why is it needed/
+  // TODO: remove for now
   /**
    * The step in which read buffer is incremented when needed.
    * If initial half size of the connection's memory region is not enough
@@ -3124,7 +3125,7 @@ enum MHD_DaemonOptionSizet
   MHD_DAEMON_OPTION_SIZET_STACK_SIZE,
 
 };
-// FIXME:
+// FIXME: finish
 _MHD_EXTERN void
 MHD_daemon_option_set_sizet (struct MHD_Daemon *daemon,
                              enum MHD_DaemonOptionSizet option,
@@ -3139,7 +3140,7 @@ MHD_FUNC_PARAM_NONNULL_ (1);
  */
 enum MHD_ThreadingMode
 {
-  // FIXME: Updated
+  // FIXME: Updated - OK
   /**
    * The daemon has no internal threads.
    * The application periodically calls #MHD_process_data(), MHD checks
@@ -3149,7 +3150,7 @@ enum MHD_ThreadingMode
   MHD_TM_EXTERNAL_PERIODIC = 0,
   /**
    * Use an external event loop.
-   * Application used one of MHD APIs to watch sockets status.
+   * Application use one of MHD APIs to watch sockets status.
    */
   MHD_TM_EXTERNAL_EVENT_LOOP = 1,
 // FIXME: updated
@@ -3169,6 +3170,7 @@ enum MHD_ThreadingMode
 
   // FIXME: could be unavailable for HTTP/2 and /3. Streams must be
   // multiplexed. Multiplexing from several threads looks overcomplicated.
+  // TODO: update doxy
   /**
    * MHD should create its own thread for listening and furthermore create
    * another thread per request. Threads may be re-used on the same
@@ -3176,7 +3178,7 @@ enum MHD_ThreadingMode
    * your application is thread-safe and you have plenty of memory (per
    * request).
    */
-  MHD_TM_THREAD_PER_REQUEST = 3
+  MHD_TM_THREAD_PER_CONNECTION = 3
 
 };
 
@@ -3316,14 +3318,30 @@ MHD_set_external_event_loop (struct MHD_Daemon *daemon,
                              void *cb_cls);
 
 
-// FIXME: Alternative style
-
-struct MHD_WatchedFD
+// FIXME: Updated
+// FIXME: any better name? "send_ready"?
+/**
+ * The network status of the socket.
+ * When set by MHD (by #MHD_get_watched_fds() or #MHD_get_watched_fds_update())
+ * it indicates a request to watch for specific socket state:
+ * readiness for receiving the data, readiness for sending the data and/or
+ * exception state of the socket.
+ * When set by application and provided for #MHD_process_watched_fds() it must
+ * indicate the actual status of the socket.
+ *
+ * Any actual state is a bitwise OR combination of #MHD_FD_STATE_RECV,
+ * #MHD_FD_STATE_SEND, #MHD_FD_STATE_EXCEPT.
+ */
+enum MHD_FdState
 {
   /**
-   * The watched socket
+   * The socket is not ready for receiving or sending and
+   * does not have any exceptional state.
+   * The state never set by MHD.
    */
-  MHD_socket fd;
+  MHD_FD_STATE_NONE = 0,
+
+  /* ** Three bit-flags ** */
 
   /**
    * Indicates that socket should be watched for incoming data
@@ -3331,16 +3349,14 @@ struct MHD_WatchedFD
    * / socket has incoming data ready to read (when used for
    * #MHD_process_watched_fds())
    */
-  enum MHD_bool recv_ready;
-
+  MHD_FD_STATE_RECV = 1 << 0,
   /**
    * Indicates that socket should be watched for availability for sending
    * (when set by #MHD_get_watched_fds())
    * / socket has ability to send data (when used for
    * #MHD_process_watched_fds())
    */
-  enum MHD_bool send_ready;
-
+  MHD_FD_STATE_SEND = 1 << 1,
   /**
    * Indicates that socket should be watched for disconnect, out-of-band
    * data available or high priority data available (when set by
@@ -3352,7 +3368,66 @@ struct MHD_WatchedFD
    * Note: #MHD_get_watched_fds() always set it as exceptions must be
    * always watched.
    */
-  enum MHD_bool exception;
+  MHD_FD_STATE_EXCEPT = 1 << 2,
+
+  /* The rest of the list is a bit-wise combination of three main
+   * state. Application may use three main states directly as
+   * a bit-mask instead of using of following values
+   */
+
+  /**
+   * Combination of #MHD_FD_STATE_RECV and #MHD_FD_STATE_SEND states.
+   */
+  MHD_FD_STATE_RECV_SEND = MHD_FD_STATE_RECV | MHD_FD_STATE_SEND,
+  /**
+   * Combination of #MHD_FD_STATE_RECV and #MHD_FD_STATE_EXCEPT states.
+   */
+  MHD_FD_STATE_RECV_EXCEPT = MHD_FD_STATE_RECV | MHD_FD_STATE_EXCEPT,
+  /**
+   * Combination of #MHD_FD_STATE_RECV and #MHD_FD_STATE_EXCEPT states.
+   */
+  MHD_FD_STATE_SEND_EXCEPT = MHD_FD_STATE_RECV | MHD_FD_STATE_EXCEPT,
+  /**
+   * Combination of #MHD_FD_STATE_RECV, #MHD_FD_STATE_SEND and
+   * #MHD_FD_STATE_EXCEPT states.
+   */
+  MHD_FD_STATE_RECV_SEND_EXCEPT = \
+    MHD_FD_STATE_RECV | MHD_FD_STATE_SEND | MHD_FD_STATE_EXCEPT
+};
+
+// TODO: add doxy
+#define MHD_FD_STATE_SET(var,state) \
+  (var) = (enum MHD_FdState)((var) | (state))
+#define MHD_FD_STATE_CLEAR(var,state) \
+  (var) = (enum MHD_FdState)((var) & (((enum MHD_FdState))(~state)))
+
+#define MHD_FD_STATE_SET_RECV(var) MHD_FD_STATE_SET((var),MHD_FD_STATE_RECV)
+#define MHD_FD_STATE_SET_SEND(var) MHD_FD_STATE_SET((var),MHD_FD_STATE_SEND)
+#define MHD_FD_STATE_SET_EXCEPT(var) \
+  MHD_FD_STATE_SET((var),MHD_FD_STATE_EXCEPT)
+
+#define MHD_FD_STATE_CLEAR_RECV(var) \
+  MHD_FD_STATE_CLEAR((var),MHD_FD_STATE_RECV)
+#define MHD_FD_STATE_CLEAR_SEND(var) \
+  MHD_FD_STATE_CLEAR((var),MHD_FD_STATE_SEND)
+#define MHD_FD_STATE_CLEAR_EXCEPT(var) \
+  MHD_FD_STATE_CLEAR((var),MHD_FD_STATE_EXCEPT)
+
+struct MHD_WatchedFD
+{
+  /**
+   * The watched socket.
+   * Ignored if set by application to #MHD_INVALID_SOCKET. TODO: Improve wording
+   */
+  MHD_socket fd;
+
+  /**
+   * Indicates that socket should be watched for specific network state
+   * (when set by #MHD_get_watched_fds(), #MHD_get_watched_fds_update())
+   * / the network state of the socket (when used for
+   * #MHD_process_watched_fds())
+   */
+  enum MHD_FdState state;
 };
 
 /**
@@ -3366,7 +3441,7 @@ struct MHD_WatchedFD
  * @param num_elements the number of elements in @a fds list
  * @param[out] fds the arrays of @a num_elements of sockets to be watched
  *                 by application,
- *                 could be NULL to get the required number of elements
+ *                 could be NULL to get the required number of elements // TODO: replace with introspection
  * @param[out] max_wait the pointer to value set to maximum wait time
  *                      for the network events, set only if @fds is not NULL
  * @return number of elements set in @a fds, never larger than
@@ -3425,8 +3500,8 @@ struct MHD_WatchedFdUpdate
  * @param num_elements the number of elements in @a fds list
  * @param[out] fds the arrays of @a num_elements to update the list
  *                 of watched sockets,
- *                 could be NULL to get the required number of elements
- * @param[out] max_wait the pointer to value set to maximum wait time
+ *                 could be NULL to get the required number of elements // TODO: convert to introspection
+ * @param[out] max_wait the pointer to value set to maximum wait time in millisec // TODO: check with microseconds
  *                      for the network events, set only if @fds is not NULL
  * @return number of elements set in @a fds, never larger than
  *         @a num_elements (if @a fds in not NULL);
@@ -3457,7 +3532,7 @@ MHD_process_watched_fds (
   struct MHD_Daemon *daemon,
   unsigned int num_elements,
   struct MHD_WatchedFD fds[MHD_C99_ (static num_elements)],
-  enum MHD_TriggerLevel type)
+  enum MHD_TriggerLevel type) // TODO: maybe not need
 MHD_FUNC_PARAM_NONNULL_ (1) MHD_FUNC_PARAM_NONNULL_ (2);
 
 /**