mhd_future.h (11921B)
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 /* FUTURE: 138 (with eventually option "number of masters") 139 MHD_TM_WORKER_THREADS_WITH_MASTER_LISTENER = 3 */ 140 141 142 // Alternative style 143 144 struct MHD_WatchedFD 145 { 146 /** 147 * The watched socket. 148 * Ignored if set by application to #MHD_INVALID_SOCKET. TODO: Improve wording 149 */ 150 MHD_Socket fd; 151 152 /** 153 * Indicates that socket should be watched for specific network state 154 * (when set by #MHD_get_watched_fds(), #MHD_get_watched_fds_update()) 155 * / the network state of the socket (when used for 156 * #MHD_process_watched_fds()) 157 */ 158 enum MHD_FdState state; 159 }; 160 161 /** 162 * Get the full list of the sockets that must be watched by application. 163 * 164 * The application may use this function each time to get a full list of 165 * the sockets for watch or may use #MHD_get_watched_fds_update() to 166 * get the incremental updates. 167 * 168 * // TODO: add introspection reference 169 * 170 * @param daemon the daemon to get the list 171 * @param num_elements the number of elements in @a fds list 172 * @param[out] wfds the arrays of @a num_elements of sockets to be watched 173 * by application, the unused elements (if any) at 174 * the end of the array are filled with 175 * { MHD_INVALID_SOCKET, MHD_FD_STATE_NONE } 176 * @param[out] max_wait the pointer to value set to maximum wait time 177 * for the network events, in microseconds 178 * @return ::MHD_SC_OK on success, 179 * error code otherwise 180 * @ingroup event 181 */ 182 MHD_EXTERN_ enum MHD_StatusCode 183 MHD_get_watched_fds ( 184 struct MHD_Daemon *daemon, 185 unsigned int num_elements, 186 struct MHD_WatchedFD wfds[MHD_FN_PAR_DYN_ARR_SIZE_ (num_elements)], 187 uint_fast64_t *max_wait) 188 MHD_FN_PAR_NONNULL_ (1) 189 MHD_FN_PAR_OUT_ (3) MHD_FN_PAR_NONNULL_ (3) 190 MHD_FN_PAR_OUT_ (4) MHD_FN_PAR_NONNULL_ (4); 191 192 193 enum MHD_WatchedFdAction 194 { 195 /** 196 * New watched FD, to be added to the list 197 */ 198 MHD_WFA_ADD = 1 199 , 200 /** 201 * Update watching interest in already watched FD 202 */ 203 MHD_WFA_UPDATE = 2 204 , 205 /** 206 * Delete FD from watching list 207 */ 208 MHD_WFA_REMOVE = 3 209 , 210 /** 211 * No action. Used to fill the end of the array 212 * The matching FD is always #MHD_INVALID_SOCKET. 213 */ 214 MHD_WFA_NONE = 0 215 }; 216 217 struct MHD_WatchedFdUpdate 218 { 219 /** 220 * The required action: add/update/delete 221 */ 222 enum MHD_WatchedFdAction action; 223 224 /** 225 * The watched FD to add, update or delete. 226 */ 227 struct MHD_WatchedFD watched_fd; 228 }; 229 230 /** 231 * Get the update of the list of the sockets that must be watched 232 * by application. 233 * This function provides an update to the list of watched sockets 234 * since the last call of #MHD_get_watched_fds() or 235 * #MHD_get_watched_fds_update(). 236 * If this function is called before #MHD_get_watched_fds() then it 237 * returns full list of sockets to watch with action #MHD_WFA_ADD. 238 * 239 * @param daemon the daemon to get the list 240 * @param num_elements the number of elements in @a fds list 241 * @param[out] wfdus the arrays of @a num_elements to update the list 242 * of watched sockets, the unused elements (if any) at 243 * the end of the array are filled with 244 * { MHD_WFA_NONE, { MHD_INVALID_SOCKET, MHD_FD_STATE_NONE } } 245 * @param[out] max_wait the pointer to value set to maximum wait time 246 * for the network events, in microseconds 247 * @return ::MHD_SC_OK on success, 248 * error code otherwise 249 * @ingroup event 250 */ 251 MHD_EXTERN_ enum MHD_StatusCode 252 MHD_get_watched_fds_update ( 253 struct MHD_Daemon *daemon, 254 unsigned int num_elements, 255 struct MHD_WatchedFdUpdate wfdus[MHD_FN_PAR_DYN_ARR_SIZE_ (num_elements)], 256 uint_fast64_t *max_wait) 257 MHD_FN_PAR_NONNULL_ (1) 258 MHD_FN_PAR_OUT_ (3) MHD_FN_PAR_NONNULL_ (3) 259 MHD_FN_PAR_OUT_ (4) MHD_FN_PAR_NONNULL_ (4); 260 ; 261 262 263 /** 264 * Perform round of sockets processing, including receiving, sending, 265 * data processing, sockets closing and other things. 266 * @param daemon the daemon to process 267 * @param num_elements the number of elements in the @a fds array 268 * @param fds the array of watched sockets, must be complete list of 269 * all watched sockets level sockets triggering used or 270 * could be just partial list if edge sockets triggering used 271 * @return ::MHD_SC_OK on success, 272 * otherwise error code TODO: complete list of error codes 273 */ 274 MHD_EXTERN_ enum MHD_StatusCode 275 MHD_process_watched_fds ( 276 struct MHD_Daemon *daemon, 277 unsigned int num_elements, 278 const struct MHD_WatchedFD fds[MHD_FN_PAR_DYN_ARR_SIZE_ (num_elements)]) 279 MHD_FN_PAR_NONNULL_ (1) 280 MHD_FN_PAR_IN_ (3) MHD_FN_PAR_NONNULL_ (3); 281 282 283 // FIXME: convert introspection 284 /** 285 * Obtain timeout value for polling function for this daemon. 286 * 287 * This function set value to amount of milliseconds for which polling 288 * function (`select()` or `poll()`) should at most block, not the 289 * timeout value set for connections. 290 * It is important to always use this function, even if connection 291 * timeout is not set, as in some cases MHD may already have more 292 * data to process on next turn (data pending in TLS buffers, 293 * connections are already ready with epoll etc.) and returned timeout 294 * will be zero. 295 * 296 * @param[in,out] daemon daemon to query for timeout 297 * @param[out] timeout set to the timeout (in milliseconds), 298 * #MHD_WAIT_INDEFINITELY if timeouts are // FIXME: redesigned 299 * not used (or no connections exist that would 300 * necessitate the use of a timeout right now) 301 * @return #MHD_SC_OK on success, otherwise 302 * an error code 303 * @ingroup event 304 */ 305 MHD_EXTERN_ enum MHD_StatusCode 306 MHD_daemon_ext_polling_get_max_wait (struct MHD_Daemon *daemon, 307 uint_fast64_t *timeout) 308 MHD_FN_PAR_NONNULL_ (1) 309 MHD_FN_PAR_NONNULL_ (2) MHD_FN_PAR_OUT_ (2); 310 311 // FIXME: gana? table for RFC 7541... 312 // TODO: extract https://www.rfc-editor.org/rfc/rfc7541.html#appendix-A 313 enum MHD_PredefinedHeader; 314 315 316 /** 317 * Get last occurrence of a particular header value under 318 * the given @a skt. 319 * 320 * The pointer to the string in @a value is valid until the response 321 * is queued. If the data is needed beyond this point, it should be copied. 322 * 323 * @param[in,out] request request to get values from 324 * @param kind what kind of value are we looking for 325 * @param skt the header to look for based on RFC 7541 Appendix A. 326 * @param[out] value the found value, the str pointer set to 327 * NULL if nothing is found 328 * @return #MHD_SC_OK if found, 329 * error code otherwise 330 * @ingroup request 331 */ 332 MHD_EXTERN_ enum MHD_StatusCode 333 MHD_request_lookup_value_by_static_header (struct MHD_Request *request, 334 enum MHD_ValueKind kind, 335 enum MHD_PredefinedHeader skt, 336 struct MHD_StringNullable *value) 337 MHD_FN_PAR_NONNULL_ (1) MHD_FN_PAR_NONNULL_ (4); // TODO: convert like previous 338 339 340 /* FUTURE: 341 (with eventually option "number of masters") 342 MHD_TM_WORKER_THREADS_WITH_MASTER_LISTENER = 3 */ 343 344 345 // FIXME: remove completely? 346 /** 347 * Configure DH parameters (dh.pem) to use for the TLS key 348 * exchange. 349 * 350 * @param daemon daemon to configure tls for 351 * @param dh parameters to use 352 * @return #MHD_SC_OK upon success; TODO: define failure modes 353 */ 354 MHD_EXTERN_ enum MHD_StatusCode 355 MHD_daemon_tls_mem_dhparams (struct MHD_Daemon *daemon, 356 const char *dh) 357 MHD_FN_PAR_NONNULL_ (1);