mhd_future.h (11920B)
1 #ifndef MHD_EXTERN_ 2 # if ! defined(_WIN32) 3 # define MHD_EXTERN_ extern 4 # else /* defined(_WIN32) */ 5 # if ! defined(MHD_W32LIB) 6 # define MHD_EXTERN_ extern 7 # else /* defined(_WIN32) && efined(MHD_W32LIB) */ 8 /* Define MHD_W32DLL when using MHD as W32 .DLL to speed up linker a little */ 9 # define MHD_EXTERN_ extern __declspec(dllimport) 10 # endif 11 # endif 12 #endif 13 14 15 #ifndef MHD_FIXED_ENUM_ 16 # define MHD_FIXED_ENUM_ /* empty */ 17 #endif /* MHD_FIXED_ENUM_ */ 18 #ifndef MHD_FLAGS_ENUM_ 19 # define MHD_FLAGS_ENUM_ /* empty */ 20 #endif /* MHD_FLAGS_ENUM_ */ 21 22 #ifndef MHD_FIXED_FLAGS_ENUM_ 23 # define MHD_FIXED_FLAGS_ENUM_ MHD_FIXED_ENUM_ MHD_FLAGS_ENUM_ 24 #endif 25 26 #ifndef MHD_FIXED_ENUM_APP_SET_ 27 /* The enum is set by an application to the fixed list of values */ 28 # define MHD_FIXED_ENUM_APP_SET_ MHD_FIXED_ENUM_ 29 #endif 30 31 #ifndef MHD_FLAGS_ENUM_APP_SET_ 32 /* The enum is set by an application, it is a bitmap */ 33 # define MHD_FLAGS_ENUM_APP_SET_ MHD_FLAGS_ENUM_ 34 #endif 35 36 #ifndef MHD_FIXED_FLAGS_ENUM_APP_SET_ 37 /* The enum is set by an application to the fixed bitmap values */ 38 # define MHD_FIXED_FLAGS_ENUM_APP_SET_ MHD_FIXED_FLAGS_ENUM_ 39 #endif 40 41 #ifndef MHD_FIXED_ENUM_MHD_SET_ 42 /* The enum is set by MHD to the fixed list of values */ 43 # define MHD_FIXED_ENUM_MHD_SET_ /* enum can be extended in next MHD versions */ 44 #endif 45 46 #ifndef MHD_FLAGS_ENUM_MHD_SET_ 47 /* The enum is set by MHD, it is a bitmap */ 48 # define MHD_FLAGS_ENUM_MHD_SET_ MHD_FLAGS_ENUM_ 49 #endif 50 51 #ifndef MHD_FIXED_FLAGS_ENUM_MHD_SET_ 52 /* The enum is set by MHD to the fixed bitmap values */ 53 # define MHD_FIXED_FLAGS_ENUM_MHD_SET_ MHD_FLAGS_ENUM_ /* enum can be extended in next MHD versions */ 54 #endif 55 56 #ifndef MHD_FIXED_ENUM_MHD_APP_SET_ 57 /* The enum is set by both MHD and app to the fixed list of values */ 58 # define MHD_FIXED_ENUM_MHD_APP_SET_ /* enum can be extended in next MHD versions */ 59 #endif 60 61 #ifndef MHD_FLAGS_ENUM_MHD_APP_SET_ 62 /* The enum is set by both MHD and app, it is a bitmap */ 63 # define MHD_FLAGS_ENUM_MHD_APP_SET_ MHD_FLAGS_ENUM_ 64 #endif 65 66 #ifndef MHD_FIXED_FLAGS_ENUM_MHD_APP_SET_ 67 /* The enum is set by both MHD and app to the fixed bitmap values */ 68 # define MHD_FIXED_FLAGS_ENUM_MHD_APP_SET_ MHD_FLAGS_ENUM_ /* enum can be extended in next MHD versions */ 69 #endif 70 71 72 #ifndef MHD_FN_CONST_ 73 # define MHD_FN_CONST_ /* empty */ 74 #endif /* ! MHD_FN_CONST_ */ 75 #ifndef MHD_FN_PURE_ 76 # define MHD_FN_PURE_ /* empty */ 77 #endif /* ! MHD_FN_PURE_ */ 78 #ifndef MHD_FN_MUST_CHECK_RESULT_ 79 # define MHD_FN_MUST_CHECK_RESULT_ /* empty */ 80 #endif /* ! MHD_FN_MUST_CHECK_RESULT_ */ 81 #ifndef MHD_FN_PAR_NONNULL_ 82 # define MHD_FN_PAR_NONNULL_(param_num) /* empty */ 83 #endif /* ! MHD_FN_PAR_NONNULL_ */ 84 #ifndef MHD_FN_PAR_NONNULL_ALL_ 85 # define MHD_FN_PAR_NONNULL_ALL_ /* empty */ 86 #endif /* ! MHD_FN_PAR_NONNULL_ALL_ */ 87 #ifndef MHD_FN_PAR_IN_ 88 # define MHD_FN_PAR_IN_(param_num) /* empty */ 89 #endif /* !MHD_FN_PAR_IN_ */ 90 #ifndef MHD_FN_PAR_IN_SIZE_ 91 # define MHD_FN_PAR_IN_SIZE_(param_num,size_num) /* empty */ 92 #endif /* !MHD_FN_PAR_IN_SIZE_ */ 93 #ifndef MHD_FN_PAR_OUT_ 94 # define MHD_FN_PAR_OUT_(param_num) /* empty */ 95 #endif /* !MHD_FN_PAR_OUT_ */ 96 #ifndef MHD_FN_PAR_OUT_SIZE_ 97 # define MHD_FN_PAR_OUT_SIZE_(param_num,size_num) /* empty */ 98 #endif /* !MHD_FN_PAR_OUT_SIZE_ */ 99 #ifndef MHD_FN_PAR_INOUT_ 100 # define MHD_FN_PAR_INOUT_(param_num) /* empty */ 101 #endif /* !MHD_FN_PAR_INOUT_ */ 102 #ifndef MHD_FN_PAR_INOUT_SIZE_ 103 # define MHD_FN_PAR_INOUT_SIZE_(param_num,size_num) /* empty */ 104 #endif /* !MHD_FN_PAR_INOUT_SIZE_ */ 105 #ifndef MHD_FN_PAR_FD_READ_ 106 # define MHD_FN_PAR_FD_READ_(param_num) /* empty */ 107 #endif /* !MHD_FN_PAR_FD_READ_ */ 108 #ifndef MHD_FN_PAR_CSTR_ 109 # define MHD_FN_PAR_CSTR_(param_num) /* empty */ 110 #endif /* ! MHD_FN_PAR_CSTR_ */ 111 #ifndef MHD_FN_RETURNS_NONNULL_ 112 # define MHD_FN_RETURNS_NONNULL_ /* empty */ 113 #endif /* ! MHD_FN_RETURNS_NONNULL_ */ 114 115 116 /** 117 * Which threading and polling mode should be used by MHD? 118 */ 119 enum MHD_FIXED_ENUM_MHD_SET_ MHD_ThreadingPollingMode 120 { 121 /** 122 * Use an external event loop. 123 * Application uses #MHD_get_watched_fds()/#MHD_get_watched_fds_update() 124 * and #MHD_process_watched_fds() with level triggered sockets 125 * polling (like select() or poll()). 126 */ 127 MHD_TM_EXTERNAL_EVENT_LOOP_WFD_LEVEL = 10 128 , 129 /** 130 * Use an external event loop. 131 * Application uses #MHD_get_watched_fds()/#MHD_get_watched_fds_update() 132 * and #MHD_process_watched_fds() with edge triggered sockets polling. 133 */ 134 MHD_TM_EXTERNAL_EVENT_LOOP_WFD_EDGE = 11 135 , 136 }; 137 138 /* FUTURE: 139 (with eventually option "number of masters") 140 MHD_TM_WORKER_THREADS_WITH_MASTER_LISTENER = 3 */ 141 142 143 // Alternative style 144 145 struct MHD_WatchedFD 146 { 147 /** 148 * The watched socket. 149 * Ignored if set by application to #MHD_INVALID_SOCKET. TODO: Improve wording 150 */ 151 MHD_Socket fd; 152 153 /** 154 * Indicates that socket should be watched for specific network state 155 * (when set by #MHD_get_watched_fds(), #MHD_get_watched_fds_update()) 156 * / the network state of the socket (when used for 157 * #MHD_process_watched_fds()) 158 */ 159 enum MHD_FdState state; 160 }; 161 162 /** 163 * Get the full list of the sockets that must be watched by application. 164 * 165 * The application may use this function each time to get a full list of 166 * the sockets for watch or may use #MHD_get_watched_fds_update() to 167 * get the incremental updates. 168 * 169 * // TODO: add introspection reference 170 * 171 * @param daemon the daemon to get the list 172 * @param num_elements the number of elements in @a fds list 173 * @param[out] wfds the arrays of @a num_elements of sockets to be watched 174 * by application, the unused elements (if any) at 175 * the end of the array are filled with 176 * { MHD_INVALID_SOCKET, MHD_FD_STATE_NONE } 177 * @param[out] max_wait the pointer to value set to maximum wait time 178 * for the network events, in microseconds 179 * @return ::MHD_SC_OK on success, 180 * error code otherwise 181 * @ingroup event 182 */ 183 MHD_EXTERN_ enum MHD_StatusCode 184 MHD_get_watched_fds ( 185 struct MHD_Daemon *daemon, 186 unsigned int num_elements, 187 struct MHD_WatchedFD wfds[MHD_FN_PAR_DYN_ARR_SIZE_ (num_elements)], 188 uint_fast64_t *max_wait) 189 MHD_FN_PAR_NONNULL_ (1) 190 MHD_FN_PAR_OUT_(3) MHD_FN_PAR_NONNULL_(3) 191 MHD_FN_PAR_OUT_(4) MHD_FN_PAR_NONNULL_ (4); 192 193 194 enum MHD_WatchedFdAction 195 { 196 /** 197 * New watched FD, to be added to the list 198 */ 199 MHD_WFA_ADD = 1 200 , 201 /** 202 * Update watching interest in already watched FD 203 */ 204 MHD_WFA_UPDATE = 2 205 , 206 /** 207 * Delete FD from watching list 208 */ 209 MHD_WFA_REMOVE = 3 210 , 211 /** 212 * No action. Used to fill the end of the array 213 * The matching FD is always #MHD_INVALID_SOCKET. 214 */ 215 MHD_WFA_NONE = 0 216 }; 217 218 struct MHD_WatchedFdUpdate 219 { 220 /** 221 * The required action: add/update/delete 222 */ 223 enum MHD_WatchedFdAction action; 224 225 /** 226 * The watched FD to add, update or delete. 227 */ 228 struct MHD_WatchedFD watched_fd; 229 }; 230 231 /** 232 * Get the update of the list of the sockets that must be watched 233 * by application. 234 * This function provides an update to the list of watched sockets 235 * since the last call of #MHD_get_watched_fds() or 236 * #MHD_get_watched_fds_update(). 237 * If this function is called before #MHD_get_watched_fds() then it 238 * returns full list of sockets to watch with action #MHD_WFA_ADD. 239 * 240 * @param daemon the daemon to get the list 241 * @param num_elements the number of elements in @a fds list 242 * @param[out] wfdus the arrays of @a num_elements to update the list 243 * of watched sockets, the unused elements (if any) at 244 * the end of the array are filled with 245 * { MHD_WFA_NONE, { MHD_INVALID_SOCKET, MHD_FD_STATE_NONE } } 246 * @param[out] max_wait the pointer to value set to maximum wait time 247 * for the network events, in microseconds 248 * @return ::MHD_SC_OK on success, 249 * error code otherwise 250 * @ingroup event 251 */ 252 MHD_EXTERN_ enum MHD_StatusCode 253 MHD_get_watched_fds_update ( 254 struct MHD_Daemon *daemon, 255 unsigned int num_elements, 256 struct MHD_WatchedFdUpdate wfdus[MHD_FN_PAR_DYN_ARR_SIZE_ (num_elements)], 257 uint_fast64_t *max_wait) 258 MHD_FN_PAR_NONNULL_ (1) 259 MHD_FN_PAR_OUT_(3) MHD_FN_PAR_NONNULL_(3) 260 MHD_FN_PAR_OUT_(4) MHD_FN_PAR_NONNULL_ (4); 261 ; 262 263 264 /** 265 * Perform round of sockets processing, including receiving, sending, 266 * data processing, sockets closing and other things. 267 * @param daemon the daemon to process 268 * @param num_elements the number of elements in the @a fds array 269 * @param fds the array of watched sockets, must be complete list of 270 * all watched sockets level sockets triggering used or 271 * could be just partial list if edge sockets triggering used 272 * @return ::MHD_SC_OK on success, 273 * otherwise error code TODO: complete list of error codes 274 */ 275 MHD_EXTERN_ enum MHD_StatusCode 276 MHD_process_watched_fds ( 277 struct MHD_Daemon *daemon, 278 unsigned int num_elements, 279 const struct MHD_WatchedFD fds[MHD_FN_PAR_DYN_ARR_SIZE_ (num_elements)]) 280 MHD_FN_PAR_NONNULL_ (1) 281 MHD_FN_PAR_IN_(3) MHD_FN_PAR_NONNULL_ (3); 282 283 284 // FIXME: convert introspection 285 /** 286 * Obtain timeout value for polling function for this daemon. 287 * 288 * This function set value to amount of milliseconds for which polling 289 * function (`select()` or `poll()`) should at most block, not the 290 * timeout value set for connections. 291 * It is important to always use this function, even if connection 292 * timeout is not set, as in some cases MHD may already have more 293 * data to process on next turn (data pending in TLS buffers, 294 * connections are already ready with epoll etc.) and returned timeout 295 * will be zero. 296 * 297 * @param[in,out] daemon daemon to query for timeout 298 * @param[out] timeout set to the timeout (in milliseconds), 299 * #MHD_WAIT_INDEFINITELY if timeouts are // FIXME: redesigned 300 * not used (or no connections exist that would 301 * necessitate the use of a timeout right now) 302 * @return #MHD_SC_OK on success, otherwise 303 * an error code 304 * @ingroup event 305 */ 306 MHD_EXTERN_ enum MHD_StatusCode 307 MHD_daemon_ext_polling_get_max_wait (struct MHD_Daemon *daemon, 308 uint_fast64_t *timeout) 309 MHD_FN_PAR_NONNULL_ (1) 310 MHD_FN_PAR_NONNULL_ (2) MHD_FN_PAR_OUT_ (2); 311 312 // FIXME: gana? table for RFC 7541... 313 // TODO: extract https://www.rfc-editor.org/rfc/rfc7541.html#appendix-A 314 enum MHD_PredefinedHeader; 315 316 317 /** 318 * Get last occurrence of a particular header value under 319 * the given @a skt. 320 * 321 * The pointer to the string in @a value is valid until the response 322 * is queued. If the data is needed beyond this point, it should be copied. 323 * 324 * @param[in,out] request request to get values from 325 * @param kind what kind of value are we looking for 326 * @param skt the header to look for based on RFC 7541 Appendix A. 327 * @param[out] value the found value, the str pointer set to 328 * NULL if nothing is found 329 * @return #MHD_SC_OK if found, 330 * error code otherwise 331 * @ingroup request 332 */ 333 MHD_EXTERN_ enum MHD_StatusCode 334 MHD_request_lookup_value_by_static_header (struct MHD_Request *request, 335 enum MHD_ValueKind kind, 336 enum MHD_PredefinedHeader skt, 337 struct MHD_StringNullable *value) 338 MHD_FN_PAR_NONNULL_ (1) MHD_FN_PAR_NONNULL_ (4); // TODO: convert like previous 339 340 341 /* FUTURE: 342 (with eventually option "number of masters") 343 MHD_TM_WORKER_THREADS_WITH_MASTER_LISTENER = 3 */ 344 345 346 // FIXME: remove completely? 347 /** 348 * Configure DH parameters (dh.pem) to use for the TLS key 349 * exchange. 350 * 351 * @param daemon daemon to configure tls for 352 * @param dh parameters to use 353 * @return #MHD_SC_OK upon success; TODO: define failure modes 354 */ 355 MHD_EXTERN_ enum MHD_StatusCode 356 MHD_daemon_tls_mem_dhparams (struct MHD_Daemon *daemon, 357 const char *dh) 358 MHD_FN_PAR_NONNULL_ (1);