microhttpd.h (174223B)
1 /* 2 This file is part of libmicrohttpd 3 Copyright (C) 2006-2021 Christian Grothoff (and other contributing authors) 4 Copyright (C) 2014-2022 Evgeny Grin (Karlson2k) 5 6 This library is free software; you can redistribute it and/or 7 modify it under the terms of the GNU Lesser General Public 8 License as published by the Free Software Foundation; either 9 version 2.1 of the License, or (at your option) any later version. 10 11 This library is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 Lesser General Public License for more details. 15 16 You should have received a copy of the GNU Lesser General Public 17 License along with this library; if not, write to the Free Software 18 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 19 */ 20 21 /** 22 * @file microhttpd.h 23 * @brief public interface to libmicrohttpd 24 * @author Christian Grothoff 25 * @author Karlson2k (Evgeny Grin) 26 * @author Chris GauthierDickey 27 * 28 * All symbols defined in this header start with MHD. MHD is a small 29 * HTTP daemon library. As such, it does not have any API for logging 30 * errors (you can only enable or disable logging to stderr). Also, 31 * it may not support all of the HTTP features directly, where 32 * applicable, portions of HTTP may have to be handled by clients of 33 * the library. 34 * 35 * The library is supposed to handle everything that it must handle 36 * (because the API would not allow clients to do this), such as basic 37 * connection management; however, detailed interpretations of headers 38 * -- such as range requests -- and HTTP methods are left to clients. 39 * The library does understand HEAD and will only send the headers of 40 * the response and not the body, even if the client supplied a body. 41 * The library also understands headers that control connection 42 * management (specifically, "Connection: close" and "Expect: 100 43 * continue" are understood and handled automatically). 44 * 45 * MHD understands POST data and is able to decode certain formats 46 * (at the moment only "application/x-www-form-urlencoded" and 47 * "multipart/formdata"). Unsupported encodings and large POST 48 * submissions may require the application to manually process 49 * the stream, which is provided to the main application (and thus can be 50 * processed, just not conveniently by MHD). 51 * 52 * The header file defines various constants used by the HTTP protocol. 53 * This does not mean that MHD actually interprets all of these 54 * values. The provided constants are exported as a convenience 55 * for users of the library. MHD does not verify that transmitted 56 * HTTP headers are part of the standard specification; users of the 57 * library are free to define their own extensions of the HTTP 58 * standard and use those with MHD. 59 * 60 * All functions are guaranteed to be completely reentrant and 61 * thread-safe (with the exception of #MHD_set_connection_value, 62 * which must only be used in a particular context). 63 * 64 * 65 * @defgroup event event-loop control 66 * MHD API to start and stop the HTTP server and manage the event loop. 67 * @defgroup response generation of responses 68 * MHD API used to generate responses. 69 * @defgroup request handling of requests 70 * MHD API used to access information about requests. 71 * @defgroup authentication HTTP authentication 72 * MHD API related to basic and digest HTTP authentication. 73 * @defgroup logging logging 74 * MHD API to mange logging and error handling 75 * @defgroup specialized misc. specialized functions 76 * This group includes functions that do not fit into any particular 77 * category and that are rarely used. 78 */ 79 80 #ifndef MHD_MICROHTTPD_H 81 #define MHD_MICROHTTPD_H 82 83 #ifdef __cplusplus 84 extern "C" 85 { 86 #if 0 /* keep Emacsens' auto-indent happy */ 87 } 88 #endif 89 #endif 90 91 92 /** 93 * Current version of the library in packed BCD form. 94 * @note Version number components are coded as Simple Binary-Coded Decimal 95 * (also called Natural BCD or BCD 8421). While they are hexadecimal numbers, 96 * they are parsed as decimal numbers. 97 * Example: 0x01093001 = 1.9.30-1. 98 */ 99 #define MHD_VERSION 0x00097700 100 101 /* If generic headers don't work on your platform, include headers 102 which define 'va_list', 'size_t', 'ssize_t', 'intptr_t', 103 'uint16_t', 'uint32_t', 'uint64_t', 'off_t', 'struct sockaddr', 104 'socklen_t', 'fd_set' and "#define MHD_PLATFORM_H" before 105 including "microhttpd.h". Then the following "standard" 106 includes won't be used (which might be a good idea, especially 107 on platforms where they do not exist). 108 */ 109 #ifndef MHD_PLATFORM_H 110 #if defined(_WIN32) && ! defined(__CYGWIN__) && \ 111 ! defined(_CRT_DECLARE_NONSTDC_NAMES) 112 /* Declare POSIX-compatible names */ 113 #define _CRT_DECLARE_NONSTDC_NAMES 1 114 #endif /* _WIN32 && ! __CYGWIN__ && ! _CRT_DECLARE_NONSTDC_NAMES */ 115 #include <stdarg.h> 116 #include <stdint.h> 117 #include <sys/types.h> 118 #if ! defined(_WIN32) || defined(__CYGWIN__) 119 #include <unistd.h> 120 #include <sys/time.h> 121 #include <sys/socket.h> 122 #else /* _WIN32 && ! __CYGWIN__ */ 123 #include <ws2tcpip.h> 124 #if defined(_MSC_FULL_VER) && ! defined(_SSIZE_T_DEFINED) 125 #define _SSIZE_T_DEFINED 126 typedef intptr_t ssize_t; 127 #endif /* !_SSIZE_T_DEFINED */ 128 #endif /* _WIN32 && ! __CYGWIN__ */ 129 #endif 130 131 #if defined(__CYGWIN__) && ! defined(_SYS_TYPES_FD_SET) 132 /* Do not define __USE_W32_SOCKETS under Cygwin! */ 133 #error Cygwin with winsock fd_set is not supported 134 #endif 135 136 #ifdef __has_attribute 137 #if __has_attribute (flag_enum) 138 #define _MHD_FLAGS_ENUM __attribute__((flag_enum)) 139 #endif /* flag_enum */ 140 #if __has_attribute (enum_extensibility) 141 #define _MHD_FIXED_ENUM __attribute__((enum_extensibility (closed))) 142 #endif /* enum_extensibility */ 143 #endif /* __has_attribute */ 144 145 #ifndef _MHD_FLAGS_ENUM 146 #define _MHD_FLAGS_ENUM 147 #endif /* _MHD_FLAGS_ENUM */ 148 #ifndef _MHD_FIXED_ENUM 149 #define _MHD_FIXED_ENUM 150 #endif /* _MHD_FIXED_ENUM */ 151 152 #define _MHD_FIXED_FLAGS_ENUM _MHD_FIXED_ENUM _MHD_FLAGS_ENUM 153 154 /** 155 * Operational results from MHD calls. 156 */ 157 enum MHD_Result 158 { 159 /** 160 * MHD result code for "NO". 161 */ 162 MHD_NO = 0, 163 164 /** 165 * MHD result code for "YES". 166 */ 167 MHD_YES = 1 168 169 } _MHD_FIXED_ENUM; 170 171 172 /** 173 * MHD digest auth internal code for an invalid nonce. 174 */ 175 #define MHD_INVALID_NONCE -1 176 177 /** 178 * Constant used to indicate unknown size (use when 179 * creating a response). 180 */ 181 #ifdef UINT64_MAX 182 #define MHD_SIZE_UNKNOWN UINT64_MAX 183 #else 184 #define MHD_SIZE_UNKNOWN ((uint64_t) -1LL) 185 #endif 186 187 #define MHD_CONTENT_READER_END_OF_STREAM ((ssize_t) -1) 188 #define MHD_CONTENT_READER_END_WITH_ERROR ((ssize_t) -2) 189 190 #ifndef _MHD_EXTERN 191 #if defined(_WIN32) && defined(MHD_W32LIB) 192 #define _MHD_EXTERN extern 193 #elif defined(_WIN32) && defined(MHD_W32DLL) 194 /* Define MHD_W32DLL when using MHD as W32 .DLL to speed up linker a little */ 195 #define _MHD_EXTERN __declspec(dllimport) 196 #else 197 #define _MHD_EXTERN extern 198 #endif 199 #endif 200 201 #ifndef MHD_SOCKET_DEFINED 202 /** 203 * MHD_socket is type for socket FDs 204 */ 205 #if ! defined(_WIN32) || defined(_SYS_TYPES_FD_SET) 206 #define MHD_POSIX_SOCKETS 1 207 typedef int MHD_socket; 208 #define MHD_INVALID_SOCKET (-1) 209 #else /* !defined(_WIN32) || defined(_SYS_TYPES_FD_SET) */ 210 #define MHD_WINSOCK_SOCKETS 1 211 #include <winsock2.h> 212 typedef SOCKET MHD_socket; 213 #define MHD_INVALID_SOCKET (INVALID_SOCKET) 214 #endif /* !defined(_WIN32) || defined(_SYS_TYPES_FD_SET) */ 215 #define MHD_SOCKET_DEFINED 1 216 #endif /* MHD_SOCKET_DEFINED */ 217 218 /** 219 * Define MHD_NO_DEPRECATION before including "microhttpd.h" to disable deprecation messages 220 */ 221 #ifdef MHD_NO_DEPRECATION 222 #define _MHD_DEPR_MACRO(msg) 223 #define _MHD_NO_DEPR_IN_MACRO 1 224 #define _MHD_DEPR_IN_MACRO(msg) 225 #define _MHD_NO_DEPR_FUNC 1 226 #define _MHD_DEPR_FUNC(msg) 227 #endif /* MHD_NO_DEPRECATION */ 228 229 #ifndef _MHD_DEPR_MACRO 230 #if defined(_MSC_FULL_VER) && _MSC_VER + 0 >= 1500 231 /* VS 2008 or later */ 232 /* Stringify macros */ 233 #define _MHD_INSTRMACRO(a) #a 234 #define _MHD_STRMACRO(a) _MHD_INSTRMACRO (a) 235 /* deprecation message */ 236 #define _MHD_DEPR_MACRO(msg) \ 237 __pragma(message (__FILE__ "(" _MHD_STRMACRO ( __LINE__) "): warning: " msg)) 238 #define _MHD_DEPR_IN_MACRO(msg) _MHD_DEPR_MACRO (msg) 239 #elif defined(__clang__) || defined(__GNUC_PATCHLEVEL__) 240 /* clang or GCC since 3.0 */ 241 #define _MHD_GCC_PRAG(x) _Pragma(#x) 242 #if (defined(__clang__) && \ 243 (__clang_major__ + 0 >= 5 || \ 244 (! defined(__apple_build_version__) && \ 245 (__clang_major__ + 0 > 3 || \ 246 (__clang_major__ + 0 == 3 && __clang_minor__ >= 3))))) || \ 247 __GNUC__ + 0 > 4 || (__GNUC__ + 0 == 4 && __GNUC_MINOR__ + 0 >= 8) 248 /* clang >= 3.3 (or XCode's clang >= 5.0) or 249 GCC >= 4.8 */ 250 #define _MHD_DEPR_MACRO(msg) _MHD_GCC_PRAG (GCC warning msg) 251 #define _MHD_DEPR_IN_MACRO(msg) _MHD_DEPR_MACRO (msg) 252 #else /* older clang or GCC */ 253 /* clang < 3.3, XCode's clang < 5.0, 3.0 <= GCC < 4.8 */ 254 #define _MHD_DEPR_MACRO(msg) _MHD_GCC_PRAG (message msg) 255 #if (defined(__clang__) && \ 256 (__clang_major__ + 0 > 2 || \ 257 (__clang_major__ + 0 == 2 && __clang_minor__ >= 9))) /* clang >= 2.9 */ 258 /* clang handles inline pragmas better than GCC */ 259 #define _MHD_DEPR_IN_MACRO(msg) _MHD_DEPR_MACRO (msg) 260 #endif /* clang >= 2.9 */ 261 #endif /* older clang or GCC */ 262 /* #elif defined(SOMEMACRO) */ /* add compiler-specific macros here if required */ 263 #endif /* clang || GCC >= 3.0 */ 264 #endif /* !_MHD_DEPR_MACRO */ 265 266 #ifndef _MHD_DEPR_MACRO 267 #define _MHD_DEPR_MACRO(msg) 268 #endif /* !_MHD_DEPR_MACRO */ 269 270 #ifndef _MHD_DEPR_IN_MACRO 271 #define _MHD_NO_DEPR_IN_MACRO 1 272 #define _MHD_DEPR_IN_MACRO(msg) 273 #endif /* !_MHD_DEPR_IN_MACRO */ 274 275 #ifndef _MHD_DEPR_FUNC 276 #if defined(_MSC_FULL_VER) && _MSC_VER + 0 >= 1400 277 /* VS 2005 or later */ 278 #define _MHD_DEPR_FUNC(msg) __declspec(deprecated (msg)) 279 #elif defined(_MSC_FULL_VER) && _MSC_VER + 0 >= 1310 280 /* VS .NET 2003 deprecation does not support custom messages */ 281 #define _MHD_DEPR_FUNC(msg) __declspec(deprecated) 282 #elif (__GNUC__ + 0 >= 5) || (defined(__clang__) && \ 283 (__clang_major__ + 0 > 2 || \ 284 (__clang_major__ + 0 == 2 && __clang_minor__ >= 9))) 285 /* GCC >= 5.0 or clang >= 2.9 */ 286 #define _MHD_DEPR_FUNC(msg) __attribute__((deprecated (msg))) 287 #elif defined(__clang__) || __GNUC__ + 0 > 3 || \ 288 (__GNUC__ + 0 == 3 && __GNUC_MINOR__ + 0 >= 1) 289 /* 3.1 <= GCC < 5.0 or clang < 2.9 */ 290 /* old GCC-style deprecation does not support custom messages */ 291 #define _MHD_DEPR_FUNC(msg) __attribute__((__deprecated__)) 292 /* #elif defined(SOMEMACRO) */ /* add compiler-specific macros here if required */ 293 #endif /* clang < 2.9 || GCC >= 3.1 */ 294 #endif /* !_MHD_DEPR_FUNC */ 295 296 #ifndef _MHD_DEPR_FUNC 297 #define _MHD_NO_DEPR_FUNC 1 298 #define _MHD_DEPR_FUNC(msg) 299 #endif /* !_MHD_DEPR_FUNC */ 300 301 /** 302 * Not all architectures and `printf()`'s support the `long long` type. 303 * This gives the ability to replace `long long` with just a `long`, 304 * standard `int` or a `short`. 305 */ 306 #ifndef MHD_LONG_LONG 307 /** 308 * @deprecated use #MHD_UNSIGNED_LONG_LONG instead! 309 */ 310 #define MHD_LONG_LONG long long 311 #define MHD_UNSIGNED_LONG_LONG unsigned long long 312 #else /* MHD_LONG_LONG */ 313 _MHD_DEPR_MACRO ( \ 314 "Macro MHD_LONG_LONG is deprecated, use MHD_UNSIGNED_LONG_LONG") 315 #endif 316 /** 317 * Format string for printing a variable of type #MHD_LONG_LONG. 318 * You should only redefine this if you also define #MHD_LONG_LONG. 319 */ 320 #ifndef MHD_LONG_LONG_PRINTF 321 /** 322 * @deprecated use #MHD_UNSIGNED_LONG_LONG_PRINTF instead! 323 */ 324 #define MHD_LONG_LONG_PRINTF "ll" 325 #define MHD_UNSIGNED_LONG_LONG_PRINTF "%llu" 326 #else /* MHD_LONG_LONG_PRINTF */ 327 _MHD_DEPR_MACRO ( \ 328 "Macro MHD_LONG_LONG_PRINTF is deprecated, use MHD_UNSIGNED_LONG_LONG_PRINTF") 329 #endif 330 331 332 /** 333 * Length of the binary output of the MD5 hash function. 334 */ 335 #define MHD_MD5_DIGEST_SIZE 16 336 337 338 /** 339 * @defgroup httpcode HTTP response codes. 340 * These are the status codes defined for HTTP responses. 341 * See: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml 342 * Registry export date: 2021-12-19 343 * @{ 344 */ 345 346 /* 100 "Continue". RFC-ietf-httpbis-semantics, Section 15.2.1. */ 347 #define MHD_HTTP_CONTINUE 100 348 /* 101 "Switching Protocols". RFC-ietf-httpbis-semantics, Section 15.2.2. */ 349 #define MHD_HTTP_SWITCHING_PROTOCOLS 101 350 /* 102 "Processing". RFC2518. */ 351 #define MHD_HTTP_PROCESSING 102 352 /* 103 "Early Hints". RFC8297. */ 353 #define MHD_HTTP_EARLY_HINTS 103 354 355 /* 200 "OK". RFC-ietf-httpbis-semantics, Section 15.3.1. */ 356 #define MHD_HTTP_OK 200 357 /* 201 "Created". RFC-ietf-httpbis-semantics, Section 15.3.2. */ 358 #define MHD_HTTP_CREATED 201 359 /* 202 "Accepted". RFC-ietf-httpbis-semantics, Section 15.3.3. */ 360 #define MHD_HTTP_ACCEPTED 202 361 /* 203 "Non-Authoritative Information". RFC-ietf-httpbis-semantics, Section 15.3.4. */ 362 #define MHD_HTTP_NON_AUTHORITATIVE_INFORMATION 203 363 /* 204 "No Content". RFC-ietf-httpbis-semantics, Section 15.3.5. */ 364 #define MHD_HTTP_NO_CONTENT 204 365 /* 205 "Reset Content". RFC-ietf-httpbis-semantics, Section 15.3.6. */ 366 #define MHD_HTTP_RESET_CONTENT 205 367 /* 206 "Partial Content". RFC-ietf-httpbis-semantics, Section 15.3.7. */ 368 #define MHD_HTTP_PARTIAL_CONTENT 206 369 /* 207 "Multi-Status". RFC4918. */ 370 #define MHD_HTTP_MULTI_STATUS 207 371 /* 208 "Already Reported". RFC5842. */ 372 #define MHD_HTTP_ALREADY_REPORTED 208 373 374 /* 226 "IM Used". RFC3229. */ 375 #define MHD_HTTP_IM_USED 226 376 377 /* 300 "Multiple Choices". RFC-ietf-httpbis-semantics, Section 15.4.1. */ 378 #define MHD_HTTP_MULTIPLE_CHOICES 300 379 /* 301 "Moved Permanently". RFC-ietf-httpbis-semantics, Section 15.4.2. */ 380 #define MHD_HTTP_MOVED_PERMANENTLY 301 381 /* 302 "Found". RFC-ietf-httpbis-semantics, Section 15.4.3. */ 382 #define MHD_HTTP_FOUND 302 383 /* 303 "See Other". RFC-ietf-httpbis-semantics, Section 15.4.4. */ 384 #define MHD_HTTP_SEE_OTHER 303 385 /* 304 "Not Modified". RFC-ietf-httpbis-semantics, Section 15.4.5. */ 386 #define MHD_HTTP_NOT_MODIFIED 304 387 /* 305 "Use Proxy". RFC-ietf-httpbis-semantics, Section 15.4.6. */ 388 #define MHD_HTTP_USE_PROXY 305 389 /* 306 "Switch Proxy". Not used! RFC-ietf-httpbis-semantics, Section 15.4.7. */ 390 #define MHD_HTTP_SWITCH_PROXY 306 391 /* 307 "Temporary Redirect". RFC-ietf-httpbis-semantics, Section 15.4.8. */ 392 #define MHD_HTTP_TEMPORARY_REDIRECT 307 393 /* 308 "Permanent Redirect". RFC-ietf-httpbis-semantics, Section 15.4.9. */ 394 #define MHD_HTTP_PERMANENT_REDIRECT 308 395 396 /* 400 "Bad Request". RFC-ietf-httpbis-semantics, Section 15.5.1. */ 397 #define MHD_HTTP_BAD_REQUEST 400 398 /* 401 "Unauthorized". RFC-ietf-httpbis-semantics, Section 15.5.2. */ 399 #define MHD_HTTP_UNAUTHORIZED 401 400 /* 402 "Payment Required". RFC-ietf-httpbis-semantics, Section 15.5.3. */ 401 #define MHD_HTTP_PAYMENT_REQUIRED 402 402 /* 403 "Forbidden". RFC-ietf-httpbis-semantics, Section 15.5.4. */ 403 #define MHD_HTTP_FORBIDDEN 403 404 /* 404 "Not Found". RFC-ietf-httpbis-semantics, Section 15.5.5. */ 405 #define MHD_HTTP_NOT_FOUND 404 406 /* 405 "Method Not Allowed". RFC-ietf-httpbis-semantics, Section 15.5.6. */ 407 #define MHD_HTTP_METHOD_NOT_ALLOWED 405 408 /* 406 "Not Acceptable". RFC-ietf-httpbis-semantics, Section 15.5.7. */ 409 #define MHD_HTTP_NOT_ACCEPTABLE 406 410 /* 407 "Proxy Authentication Required". RFC-ietf-httpbis-semantics, Section 15.5.8. */ 411 #define MHD_HTTP_PROXY_AUTHENTICATION_REQUIRED 407 412 /* 408 "Request Timeout". RFC-ietf-httpbis-semantics, Section 15.5.9. */ 413 #define MHD_HTTP_REQUEST_TIMEOUT 408 414 /* 409 "Conflict". RFC-ietf-httpbis-semantics, Section 15.5.10. */ 415 #define MHD_HTTP_CONFLICT 409 416 /* 410 "Gone". RFC-ietf-httpbis-semantics, Section 15.5.11. */ 417 #define MHD_HTTP_GONE 410 418 /* 411 "Length Required". RFC-ietf-httpbis-semantics, Section 15.5.12. */ 419 #define MHD_HTTP_LENGTH_REQUIRED 411 420 /* 412 "Precondition Failed". RFC-ietf-httpbis-semantics, Section 15.5.13. */ 421 #define MHD_HTTP_PRECONDITION_FAILED 412 422 /* 413 "Content Too Large". RFC-ietf-httpbis-semantics, Section 15.5.14. */ 423 #define MHD_HTTP_CONTENT_TOO_LARGE 413 424 /* 414 "URI Too Long". RFC-ietf-httpbis-semantics, Section 15.5.15. */ 425 #define MHD_HTTP_URI_TOO_LONG 414 426 /* 415 "Unsupported Media Type". RFC-ietf-httpbis-semantics, Section 15.5.16. */ 427 #define MHD_HTTP_UNSUPPORTED_MEDIA_TYPE 415 428 /* 416 "Range Not Satisfiable". RFC-ietf-httpbis-semantics, Section 15.5.17. */ 429 #define MHD_HTTP_RANGE_NOT_SATISFIABLE 416 430 /* 417 "Expectation Failed". RFC-ietf-httpbis-semantics, Section 15.5.18. */ 431 #define MHD_HTTP_EXPECTATION_FAILED 417 432 433 434 /* 421 "Misdirected Request". RFC-ietf-httpbis-semantics, Section 15.5.20. */ 435 #define MHD_HTTP_MISDIRECTED_REQUEST 421 436 /* 422 "Unprocessable Content". RFC-ietf-httpbis-semantics, Section 15.5.21. */ 437 #define MHD_HTTP_UNPROCESSABLE_CONTENT 422 438 /* 423 "Locked". RFC4918. */ 439 #define MHD_HTTP_LOCKED 423 440 /* 424 "Failed Dependency". RFC4918. */ 441 #define MHD_HTTP_FAILED_DEPENDENCY 424 442 /* 425 "Too Early". RFC8470. */ 443 #define MHD_HTTP_TOO_EARLY 425 444 /* 426 "Upgrade Required". RFC-ietf-httpbis-semantics, Section 15.5.22. */ 445 #define MHD_HTTP_UPGRADE_REQUIRED 426 446 447 /* 428 "Precondition Required". RFC6585. */ 448 #define MHD_HTTP_PRECONDITION_REQUIRED 428 449 /* 429 "Too Many Requests". RFC6585. */ 450 #define MHD_HTTP_TOO_MANY_REQUESTS 429 451 452 /* 431 "Request Header Fields Too Large". RFC6585. */ 453 #define MHD_HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE 431 454 455 /* 451 "Unavailable For Legal Reasons". RFC7725. */ 456 #define MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS 451 457 458 /* 500 "Internal Server Error". RFC-ietf-httpbis-semantics, Section 15.6.1. */ 459 #define MHD_HTTP_INTERNAL_SERVER_ERROR 500 460 /* 501 "Not Implemented". RFC-ietf-httpbis-semantics, Section 15.6.2. */ 461 #define MHD_HTTP_NOT_IMPLEMENTED 501 462 /* 502 "Bad Gateway". RFC-ietf-httpbis-semantics, Section 15.6.3. */ 463 #define MHD_HTTP_BAD_GATEWAY 502 464 /* 503 "Service Unavailable". RFC-ietf-httpbis-semantics, Section 15.6.4. */ 465 #define MHD_HTTP_SERVICE_UNAVAILABLE 503 466 /* 504 "Gateway Timeout". RFC-ietf-httpbis-semantics, Section 15.6.5. */ 467 #define MHD_HTTP_GATEWAY_TIMEOUT 504 468 /* 505 "HTTP Version Not Supported". RFC-ietf-httpbis-semantics, Section 15.6.6. */ 469 #define MHD_HTTP_HTTP_VERSION_NOT_SUPPORTED 505 470 /* 506 "Variant Also Negotiates". RFC2295. */ 471 #define MHD_HTTP_VARIANT_ALSO_NEGOTIATES 506 472 /* 507 "Insufficient Storage". RFC4918. */ 473 #define MHD_HTTP_INSUFFICIENT_STORAGE 507 474 /* 508 "Loop Detected". RFC5842. */ 475 #define MHD_HTTP_LOOP_DETECTED 508 476 477 /* 510 "Not Extended". RFC2774. */ 478 #define MHD_HTTP_NOT_EXTENDED 510 479 /* 511 "Network Authentication Required". RFC6585. */ 480 #define MHD_HTTP_NETWORK_AUTHENTICATION_REQUIRED 511 481 482 483 /* Not registered non-standard codes */ 484 /* 449 "Reply With". MS IIS extension. */ 485 #define MHD_HTTP_RETRY_WITH 449 486 487 /* 450 "Blocked by Windows Parental Controls". MS extension. */ 488 #define MHD_HTTP_BLOCKED_BY_WINDOWS_PARENTAL_CONTROLS 450 489 490 /* 509 "Bandwidth Limit Exceeded". Apache extension. */ 491 #define MHD_HTTP_BANDWIDTH_LIMIT_EXCEEDED 509 492 493 /* Deprecated names and codes */ 494 /** @deprecated */ 495 #define MHD_HTTP_METHOD_NOT_ACCEPTABLE \ 496 _MHD_DEPR_IN_MACRO ( \ 497 "Value MHD_HTTP_METHOD_NOT_ACCEPTABLE is deprecated, use MHD_HTTP_NOT_ACCEPTABLE") \ 498 406 499 500 /** @deprecated */ 501 #define MHD_HTTP_REQUEST_ENTITY_TOO_LARGE \ 502 _MHD_DEPR_IN_MACRO ( \ 503 "Value MHD_HTTP_REQUEST_ENTITY_TOO_LARGE is deprecated, use MHD_HTTP_CONTENT_TOO_LARGE") \ 504 413 505 506 /** @deprecated */ 507 #define MHD_HTTP_PAYLOAD_TOO_LARGE \ 508 _MHD_DEPR_IN_MACRO ( \ 509 "Value MHD_HTTP_PAYLOAD_TOO_LARGE is deprecated, use MHD_HTTP_CONTENT_TOO_LARGE") \ 510 413 511 512 /** @deprecated */ 513 #define MHD_HTTP_REQUEST_URI_TOO_LONG \ 514 _MHD_DEPR_IN_MACRO ( \ 515 "Value MHD_HTTP_REQUEST_URI_TOO_LONG is deprecated, use MHD_HTTP_URI_TOO_LONG") \ 516 414 517 518 /** @deprecated */ 519 #define MHD_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE \ 520 _MHD_DEPR_IN_MACRO ( \ 521 "Value MHD_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE is deprecated, use MHD_HTTP_RANGE_NOT_SATISFIABLE") \ 522 416 523 524 /** @deprecated */ 525 #define MHD_HTTP_UNPROCESSABLE_ENTITY \ 526 _MHD_DEPR_IN_MACRO ( \ 527 "Value MHD_HTTP_UNPROCESSABLE_ENTITY is deprecated, use MHD_HTTP_UNPROCESSABLE_CONTENT") \ 528 422 529 530 /** @deprecated */ 531 #define MHD_HTTP_UNORDERED_COLLECTION \ 532 _MHD_DEPR_IN_MACRO ( \ 533 "Value MHD_HTTP_UNORDERED_COLLECTION is deprecated as it was removed from RFC") \ 534 425 535 536 /** @deprecated */ 537 #define MHD_HTTP_NO_RESPONSE \ 538 _MHD_DEPR_IN_MACRO ( \ 539 "Value MHD_HTTP_NO_RESPONSE is deprecated as it is nginx internal code for logs only") \ 540 444 541 542 543 /** @} */ /* end of group httpcode */ 544 545 /** 546 * Returns the string reason phrase for a response code. 547 * 548 * If message string is not available for a status code, 549 * "Unknown" string will be returned. 550 */ 551 _MHD_EXTERN const char * 552 MHD_get_reason_phrase_for (unsigned int code); 553 554 555 /** 556 * Returns the length of the string reason phrase for a response code. 557 * 558 * If message string is not available for a status code, 559 * 0 is returned. 560 */ 561 _MHD_EXTERN size_t 562 MHD_get_reason_phrase_len_for (unsigned int code); 563 564 /** 565 * Flag to be or-ed with MHD_HTTP status code for 566 * SHOUTcast. This will cause the response to begin 567 * with the SHOUTcast "ICY" line instead of "HTTP". 568 * @ingroup specialized 569 */ 570 #define MHD_ICY_FLAG ((uint32_t) (((uint32_t) 1) << 31)) 571 572 /** 573 * @defgroup headers HTTP headers 574 * These are the standard headers found in HTTP requests and responses. 575 * See: https://www.iana.org/assignments/http-fields/http-fields.xhtml 576 * Registry export date: 2021-12-19 577 * @{ 578 */ 579 580 /* Main HTTP headers. */ 581 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 12.5.1 */ 582 #define MHD_HTTP_HEADER_ACCEPT "Accept" 583 /* Deprecated. RFC-ietf-httpbis-semantics-19, Section 12.5.2 */ 584 #define MHD_HTTP_HEADER_ACCEPT_CHARSET "Accept-Charset" 585 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 12.5.3 */ 586 #define MHD_HTTP_HEADER_ACCEPT_ENCODING "Accept-Encoding" 587 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 12.5.4 */ 588 #define MHD_HTTP_HEADER_ACCEPT_LANGUAGE "Accept-Language" 589 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 14.3 */ 590 #define MHD_HTTP_HEADER_ACCEPT_RANGES "Accept-Ranges" 591 /* Permanent. RFC-ietf-httpbis-cache-19, Section 5.1 */ 592 #define MHD_HTTP_HEADER_AGE "Age" 593 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 10.2.1 */ 594 #define MHD_HTTP_HEADER_ALLOW "Allow" 595 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 11.6.3 */ 596 #define MHD_HTTP_HEADER_AUTHENTICATION_INFO "Authentication-Info" 597 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 11.6.2 */ 598 #define MHD_HTTP_HEADER_AUTHORIZATION "Authorization" 599 /* Permanent. RFC-ietf-httpbis-cache-19, Section 5.2 */ 600 #define MHD_HTTP_HEADER_CACHE_CONTROL "Cache-Control" 601 /* Permanent. RFC-ietf-httpbis-cache-header-10 */ 602 #define MHD_HTTP_HEADER_CACHE_STATUS "Cache-Status" 603 /* Permanent. RFC-ietf-httpbis-messaging-19, Section 9.6 */ 604 #define MHD_HTTP_HEADER_CLOSE "Close" 605 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 7.6.1 */ 606 #define MHD_HTTP_HEADER_CONNECTION "Connection" 607 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 8.4 */ 608 #define MHD_HTTP_HEADER_CONTENT_ENCODING "Content-Encoding" 609 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 8.5 */ 610 #define MHD_HTTP_HEADER_CONTENT_LANGUAGE "Content-Language" 611 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 8.6 */ 612 #define MHD_HTTP_HEADER_CONTENT_LENGTH "Content-Length" 613 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 8.7 */ 614 #define MHD_HTTP_HEADER_CONTENT_LOCATION "Content-Location" 615 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 14.4 */ 616 #define MHD_HTTP_HEADER_CONTENT_RANGE "Content-Range" 617 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 8.3 */ 618 #define MHD_HTTP_HEADER_CONTENT_TYPE "Content-Type" 619 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 6.6.1 */ 620 #define MHD_HTTP_HEADER_DATE "Date" 621 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 8.8.3 */ 622 #define MHD_HTTP_HEADER_ETAG "ETag" 623 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 10.1.1 */ 624 #define MHD_HTTP_HEADER_EXPECT "Expect" 625 /* Permanent. RFC-ietf-httpbis-expect-ct-08 */ 626 #define MHD_HTTP_HEADER_EXPECT_CT "Expect-CT" 627 /* Permanent. RFC-ietf-httpbis-cache-19, Section 5.3 */ 628 #define MHD_HTTP_HEADER_EXPIRES "Expires" 629 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 10.1.2 */ 630 #define MHD_HTTP_HEADER_FROM "From" 631 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 7.2 */ 632 #define MHD_HTTP_HEADER_HOST "Host" 633 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 13.1.1 */ 634 #define MHD_HTTP_HEADER_IF_MATCH "If-Match" 635 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 13.1.3 */ 636 #define MHD_HTTP_HEADER_IF_MODIFIED_SINCE "If-Modified-Since" 637 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 13.1.2 */ 638 #define MHD_HTTP_HEADER_IF_NONE_MATCH "If-None-Match" 639 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 13.1.5 */ 640 #define MHD_HTTP_HEADER_IF_RANGE "If-Range" 641 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 13.1.4 */ 642 #define MHD_HTTP_HEADER_IF_UNMODIFIED_SINCE "If-Unmodified-Since" 643 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 8.8.2 */ 644 #define MHD_HTTP_HEADER_LAST_MODIFIED "Last-Modified" 645 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 10.2.2 */ 646 #define MHD_HTTP_HEADER_LOCATION "Location" 647 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 7.6.2 */ 648 #define MHD_HTTP_HEADER_MAX_FORWARDS "Max-Forwards" 649 /* Permanent. RFC-ietf-httpbis-messaging-19, Appendix B.1 */ 650 #define MHD_HTTP_HEADER_MIME_VERSION "MIME-Version" 651 /* Permanent. RFC-ietf-httpbis-cache-19, Section 5.4 */ 652 #define MHD_HTTP_HEADER_PRAGMA "Pragma" 653 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 11.7.1 */ 654 #define MHD_HTTP_HEADER_PROXY_AUTHENTICATE "Proxy-Authenticate" 655 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 11.7.3 */ 656 #define MHD_HTTP_HEADER_PROXY_AUTHENTICATION_INFO "Proxy-Authentication-Info" 657 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 11.7.2 */ 658 #define MHD_HTTP_HEADER_PROXY_AUTHORIZATION "Proxy-Authorization" 659 /* Permanent. RFC-ietf-httpbis-proxy-status-08 */ 660 #define MHD_HTTP_HEADER_PROXY_STATUS "Proxy-Status" 661 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 14.2 */ 662 #define MHD_HTTP_HEADER_RANGE "Range" 663 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 10.1.3 */ 664 #define MHD_HTTP_HEADER_REFERER "Referer" 665 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 10.2.3 */ 666 #define MHD_HTTP_HEADER_RETRY_AFTER "Retry-After" 667 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 10.2.4 */ 668 #define MHD_HTTP_HEADER_SERVER "Server" 669 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 10.1.4 */ 670 #define MHD_HTTP_HEADER_TE "TE" 671 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 6.6.2 */ 672 #define MHD_HTTP_HEADER_TRAILER "Trailer" 673 /* Permanent. RFC-ietf-httpbis-messaging-19, Section 6.1 */ 674 #define MHD_HTTP_HEADER_TRANSFER_ENCODING "Transfer-Encoding" 675 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 7.8 */ 676 #define MHD_HTTP_HEADER_UPGRADE "Upgrade" 677 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 10.1.5 */ 678 #define MHD_HTTP_HEADER_USER_AGENT "User-Agent" 679 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 12.5.5 */ 680 #define MHD_HTTP_HEADER_VARY "Vary" 681 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 7.6.3 */ 682 #define MHD_HTTP_HEADER_VIA "Via" 683 /* Obsoleted. RFC-ietf-httpbis-cache-19, Section 5.5 */ 684 #define MHD_HTTP_HEADER_WARNING "Warning" 685 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 11.6.1 */ 686 #define MHD_HTTP_HEADER_WWW_AUTHENTICATE "WWW-Authenticate" 687 /* Permanent. RFC-ietf-httpbis-semantics-19, Section 12.5.5 */ 688 #define MHD_HTTP_HEADER_ASTERISK "*" 689 690 /* Additional HTTP headers. */ 691 /* Permanent. RFC4229 */ 692 #define MHD_HTTP_HEADER_A_IM "A-IM" 693 /* Permanent. RFC4229 */ 694 #define MHD_HTTP_HEADER_ACCEPT_ADDITIONS "Accept-Additions" 695 /* Permanent. RFC8942, Section 3.1 */ 696 #define MHD_HTTP_HEADER_ACCEPT_CH "Accept-CH" 697 /* Permanent. RFC7089 */ 698 #define MHD_HTTP_HEADER_ACCEPT_DATETIME "Accept-Datetime" 699 /* Permanent. RFC4229 */ 700 #define MHD_HTTP_HEADER_ACCEPT_FEATURES "Accept-Features" 701 /* Permanent. https://www.w3.org/TR/ldp/ */ 702 #define MHD_HTTP_HEADER_ACCEPT_POST "Accept-Post" 703 /* Permanent. https://fetch.spec.whatwg.org/#http-access-control-allow-credentials */ 704 #define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_CREDENTIALS \ 705 "Access-Control-Allow-Credentials" 706 /* Permanent. https://fetch.spec.whatwg.org/#http-access-control-allow-headers */ 707 #define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_HEADERS \ 708 "Access-Control-Allow-Headers" 709 /* Permanent. https://fetch.spec.whatwg.org/#http-access-control-allow-methods */ 710 #define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_METHODS \ 711 "Access-Control-Allow-Methods" 712 /* Permanent. https://fetch.spec.whatwg.org/#http-access-control-allow-origin */ 713 #define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN \ 714 "Access-Control-Allow-Origin" 715 /* Permanent. https://fetch.spec.whatwg.org/#http-access-control-expose-headers */ 716 #define MHD_HTTP_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS \ 717 "Access-Control-Expose-Headers" 718 /* Permanent. https://fetch.spec.whatwg.org/#http-access-control-max-age */ 719 #define MHD_HTTP_HEADER_ACCESS_CONTROL_MAX_AGE "Access-Control-Max-Age" 720 /* Permanent. https://fetch.spec.whatwg.org/#http-access-control-request-headers */ 721 #define MHD_HTTP_HEADER_ACCESS_CONTROL_REQUEST_HEADERS \ 722 "Access-Control-Request-Headers" 723 /* Permanent. https://fetch.spec.whatwg.org/#http-access-control-request-method */ 724 #define MHD_HTTP_HEADER_ACCESS_CONTROL_REQUEST_METHOD \ 725 "Access-Control-Request-Method" 726 /* Permanent. RFC7639, Section 2 */ 727 #define MHD_HTTP_HEADER_ALPN "ALPN" 728 /* Permanent. RFC7838 */ 729 #define MHD_HTTP_HEADER_ALT_SVC "Alt-Svc" 730 /* Permanent. RFC7838 */ 731 #define MHD_HTTP_HEADER_ALT_USED "Alt-Used" 732 /* Permanent. RFC4229 */ 733 #define MHD_HTTP_HEADER_ALTERNATES "Alternates" 734 /* Permanent. RFC4437 */ 735 #define MHD_HTTP_HEADER_APPLY_TO_REDIRECT_REF "Apply-To-Redirect-Ref" 736 /* Permanent. RFC8053, Section 4 */ 737 #define MHD_HTTP_HEADER_AUTHENTICATION_CONTROL "Authentication-Control" 738 /* Permanent. RFC4229 */ 739 #define MHD_HTTP_HEADER_C_EXT "C-Ext" 740 /* Permanent. RFC4229 */ 741 #define MHD_HTTP_HEADER_C_MAN "C-Man" 742 /* Permanent. RFC4229 */ 743 #define MHD_HTTP_HEADER_C_OPT "C-Opt" 744 /* Permanent. RFC4229 */ 745 #define MHD_HTTP_HEADER_C_PEP "C-PEP" 746 /* Permanent. RFC8607, Section 5.1 */ 747 #define MHD_HTTP_HEADER_CAL_MANAGED_ID "Cal-Managed-ID" 748 /* Permanent. RFC7809, Section 7.1 */ 749 #define MHD_HTTP_HEADER_CALDAV_TIMEZONES "CalDAV-Timezones" 750 /* Permanent. RFC8586 */ 751 #define MHD_HTTP_HEADER_CDN_LOOP "CDN-Loop" 752 /* Permanent. RFC8739, Section 3.3 */ 753 #define MHD_HTTP_HEADER_CERT_NOT_AFTER "Cert-Not-After" 754 /* Permanent. RFC8739, Section 3.3 */ 755 #define MHD_HTTP_HEADER_CERT_NOT_BEFORE "Cert-Not-Before" 756 /* Permanent. RFC6266 */ 757 #define MHD_HTTP_HEADER_CONTENT_DISPOSITION "Content-Disposition" 758 /* Permanent. RFC4229 */ 759 #define MHD_HTTP_HEADER_CONTENT_ID "Content-ID" 760 /* Permanent. RFC4229 */ 761 #define MHD_HTTP_HEADER_CONTENT_SCRIPT_TYPE "Content-Script-Type" 762 /* Permanent. https://www.w3.org/TR/CSP/#csp-header */ 763 #define MHD_HTTP_HEADER_CONTENT_SECURITY_POLICY "Content-Security-Policy" 764 /* Permanent. https://www.w3.org/TR/CSP/#cspro-header */ 765 #define MHD_HTTP_HEADER_CONTENT_SECURITY_POLICY_REPORT_ONLY \ 766 "Content-Security-Policy-Report-Only" 767 /* Permanent. RFC4229 */ 768 #define MHD_HTTP_HEADER_CONTENT_STYLE_TYPE "Content-Style-Type" 769 /* Permanent. RFC4229 */ 770 #define MHD_HTTP_HEADER_CONTENT_VERSION "Content-Version" 771 /* Permanent. RFC6265 */ 772 #define MHD_HTTP_HEADER_COOKIE "Cookie" 773 /* Permanent. https://html.spec.whatwg.org/multipage/origin.html#cross-origin-embedder-policy */ 774 #define MHD_HTTP_HEADER_CROSS_ORIGIN_EMBEDDER_POLICY \ 775 "Cross-Origin-Embedder-Policy" 776 /* Permanent. https://html.spec.whatwg.org/multipage/origin.html#cross-origin-embedder-policy-report-only */ 777 #define MHD_HTTP_HEADER_CROSS_ORIGIN_EMBEDDER_POLICY_REPORT_ONLY \ 778 "Cross-Origin-Embedder-Policy-Report-Only" 779 /* Permanent. https://html.spec.whatwg.org/multipage/origin.html#cross-origin-opener-policy-2 */ 780 #define MHD_HTTP_HEADER_CROSS_ORIGIN_OPENER_POLICY "Cross-Origin-Opener-Policy" 781 /* Permanent. https://html.spec.whatwg.org/multipage/origin.html#cross-origin-opener-policy-report-only */ 782 #define MHD_HTTP_HEADER_CROSS_ORIGIN_OPENER_POLICY_REPORT_ONLY \ 783 "Cross-Origin-Opener-Policy-Report-Only" 784 /* Permanent. https://fetch.spec.whatwg.org/#cross-origin-resource-policy-header */ 785 #define MHD_HTTP_HEADER_CROSS_ORIGIN_RESOURCE_POLICY \ 786 "Cross-Origin-Resource-Policy" 787 /* Permanent. RFC5323 */ 788 #define MHD_HTTP_HEADER_DASL "DASL" 789 /* Permanent. RFC4918 */ 790 #define MHD_HTTP_HEADER_DAV "DAV" 791 /* Permanent. RFC4229 */ 792 #define MHD_HTTP_HEADER_DEFAULT_STYLE "Default-Style" 793 /* Permanent. RFC4229 */ 794 #define MHD_HTTP_HEADER_DELTA_BASE "Delta-Base" 795 /* Permanent. RFC4918 */ 796 #define MHD_HTTP_HEADER_DEPTH "Depth" 797 /* Permanent. RFC4229 */ 798 #define MHD_HTTP_HEADER_DERIVED_FROM "Derived-From" 799 /* Permanent. RFC4918 */ 800 #define MHD_HTTP_HEADER_DESTINATION "Destination" 801 /* Permanent. RFC4229 */ 802 #define MHD_HTTP_HEADER_DIFFERENTIAL_ID "Differential-ID" 803 /* Permanent. RFC4229 */ 804 #define MHD_HTTP_HEADER_DIGEST "Digest" 805 /* Permanent. RFC8470 */ 806 #define MHD_HTTP_HEADER_EARLY_DATA "Early-Data" 807 /* Permanent. RFC4229 */ 808 #define MHD_HTTP_HEADER_EXT "Ext" 809 /* Permanent. RFC7239 */ 810 #define MHD_HTTP_HEADER_FORWARDED "Forwarded" 811 /* Permanent. RFC4229 */ 812 #define MHD_HTTP_HEADER_GETPROFILE "GetProfile" 813 /* Permanent. RFC7486, Section 6.1.1 */ 814 #define MHD_HTTP_HEADER_HOBAREG "Hobareg" 815 /* Permanent. RFC7540, Section 3.2.1 */ 816 #define MHD_HTTP_HEADER_HTTP2_SETTINGS "HTTP2-Settings" 817 /* Permanent. RFC4918 */ 818 #define MHD_HTTP_HEADER_IF "If" 819 /* Permanent. RFC6638 */ 820 #define MHD_HTTP_HEADER_IF_SCHEDULE_TAG_MATCH "If-Schedule-Tag-Match" 821 /* Permanent. RFC4229 */ 822 #define MHD_HTTP_HEADER_IM "IM" 823 /* Permanent. RFC8473 */ 824 #define MHD_HTTP_HEADER_INCLUDE_REFERRED_TOKEN_BINDING_ID \ 825 "Include-Referred-Token-Binding-ID" 826 /* Permanent. RFC4229 */ 827 #define MHD_HTTP_HEADER_KEEP_ALIVE "Keep-Alive" 828 /* Permanent. RFC4229 */ 829 #define MHD_HTTP_HEADER_LABEL "Label" 830 /* Permanent. https://html.spec.whatwg.org/multipage/server-sent-events.html#last-event-id */ 831 #define MHD_HTTP_HEADER_LAST_EVENT_ID "Last-Event-ID" 832 /* Permanent. RFC8288 */ 833 #define MHD_HTTP_HEADER_LINK "Link" 834 /* Permanent. RFC4918 */ 835 #define MHD_HTTP_HEADER_LOCK_TOKEN "Lock-Token" 836 /* Permanent. RFC4229 */ 837 #define MHD_HTTP_HEADER_MAN "Man" 838 /* Permanent. RFC7089 */ 839 #define MHD_HTTP_HEADER_MEMENTO_DATETIME "Memento-Datetime" 840 /* Permanent. RFC4229 */ 841 #define MHD_HTTP_HEADER_METER "Meter" 842 /* Permanent. RFC4229 */ 843 #define MHD_HTTP_HEADER_NEGOTIATE "Negotiate" 844 /* Permanent. OData Version 4.01 Part 1: Protocol; OASIS; Chet_Ensign */ 845 #define MHD_HTTP_HEADER_ODATA_ENTITYID "OData-EntityId" 846 /* Permanent. OData Version 4.01 Part 1: Protocol; OASIS; Chet_Ensign */ 847 #define MHD_HTTP_HEADER_ODATA_ISOLATION "OData-Isolation" 848 /* Permanent. OData Version 4.01 Part 1: Protocol; OASIS; Chet_Ensign */ 849 #define MHD_HTTP_HEADER_ODATA_MAXVERSION "OData-MaxVersion" 850 /* Permanent. OData Version 4.01 Part 1: Protocol; OASIS; Chet_Ensign */ 851 #define MHD_HTTP_HEADER_ODATA_VERSION "OData-Version" 852 /* Permanent. RFC4229 */ 853 #define MHD_HTTP_HEADER_OPT "Opt" 854 /* Permanent. RFC8053, Section 3 */ 855 #define MHD_HTTP_HEADER_OPTIONAL_WWW_AUTHENTICATE "Optional-WWW-Authenticate" 856 /* Permanent. RFC4229 */ 857 #define MHD_HTTP_HEADER_ORDERING_TYPE "Ordering-Type" 858 /* Permanent. RFC6454 */ 859 #define MHD_HTTP_HEADER_ORIGIN "Origin" 860 /* Permanent. https://html.spec.whatwg.org/multipage/origin.html#origin-agent-cluster */ 861 #define MHD_HTTP_HEADER_ORIGIN_AGENT_CLUSTER "Origin-Agent-Cluster" 862 /* Permanent. RFC8613, Section 11.1 */ 863 #define MHD_HTTP_HEADER_OSCORE "OSCORE" 864 /* Permanent. OASIS Project Specification 01; OASIS; Chet_Ensign */ 865 #define MHD_HTTP_HEADER_OSLC_CORE_VERSION "OSLC-Core-Version" 866 /* Permanent. RFC4918 */ 867 #define MHD_HTTP_HEADER_OVERWRITE "Overwrite" 868 /* Permanent. RFC4229 */ 869 #define MHD_HTTP_HEADER_P3P "P3P" 870 /* Permanent. RFC4229 */ 871 #define MHD_HTTP_HEADER_PEP "PEP" 872 /* Permanent. RFC4229 */ 873 #define MHD_HTTP_HEADER_PEP_INFO "Pep-Info" 874 /* Permanent. RFC4229 */ 875 #define MHD_HTTP_HEADER_PICS_LABEL "PICS-Label" 876 /* Permanent. https://html.spec.whatwg.org/multipage/links.html#ping-from */ 877 #define MHD_HTTP_HEADER_PING_FROM "Ping-From" 878 /* Permanent. https://html.spec.whatwg.org/multipage/links.html#ping-to */ 879 #define MHD_HTTP_HEADER_PING_TO "Ping-To" 880 /* Permanent. RFC4229 */ 881 #define MHD_HTTP_HEADER_POSITION "Position" 882 /* Permanent. RFC7240 */ 883 #define MHD_HTTP_HEADER_PREFER "Prefer" 884 /* Permanent. RFC7240 */ 885 #define MHD_HTTP_HEADER_PREFERENCE_APPLIED "Preference-Applied" 886 /* Permanent. RFC4229 */ 887 #define MHD_HTTP_HEADER_PROFILEOBJECT "ProfileObject" 888 /* Permanent. RFC4229 */ 889 #define MHD_HTTP_HEADER_PROTOCOL "Protocol" 890 /* Permanent. RFC4229 */ 891 #define MHD_HTTP_HEADER_PROTOCOL_REQUEST "Protocol-Request" 892 /* Permanent. RFC4229 */ 893 #define MHD_HTTP_HEADER_PROXY_FEATURES "Proxy-Features" 894 /* Permanent. RFC4229 */ 895 #define MHD_HTTP_HEADER_PROXY_INSTRUCTION "Proxy-Instruction" 896 /* Permanent. RFC4229 */ 897 #define MHD_HTTP_HEADER_PUBLIC "Public" 898 /* Permanent. RFC7469 */ 899 #define MHD_HTTP_HEADER_PUBLIC_KEY_PINS "Public-Key-Pins" 900 /* Permanent. RFC7469 */ 901 #define MHD_HTTP_HEADER_PUBLIC_KEY_PINS_REPORT_ONLY \ 902 "Public-Key-Pins-Report-Only" 903 /* Permanent. RFC4437 */ 904 #define MHD_HTTP_HEADER_REDIRECT_REF "Redirect-Ref" 905 /* Permanent. https://html.spec.whatwg.org/multipage/browsing-the-web.html#refresh */ 906 #define MHD_HTTP_HEADER_REFRESH "Refresh" 907 /* Permanent. RFC8555, Section 6.5.1 */ 908 #define MHD_HTTP_HEADER_REPLAY_NONCE "Replay-Nonce" 909 /* Permanent. RFC4229 */ 910 #define MHD_HTTP_HEADER_SAFE "Safe" 911 /* Permanent. RFC6638 */ 912 #define MHD_HTTP_HEADER_SCHEDULE_REPLY "Schedule-Reply" 913 /* Permanent. RFC6638 */ 914 #define MHD_HTTP_HEADER_SCHEDULE_TAG "Schedule-Tag" 915 /* Permanent. RFC8473 */ 916 #define MHD_HTTP_HEADER_SEC_TOKEN_BINDING "Sec-Token-Binding" 917 /* Permanent. RFC6455 */ 918 #define MHD_HTTP_HEADER_SEC_WEBSOCKET_ACCEPT "Sec-WebSocket-Accept" 919 /* Permanent. RFC6455 */ 920 #define MHD_HTTP_HEADER_SEC_WEBSOCKET_EXTENSIONS "Sec-WebSocket-Extensions" 921 /* Permanent. RFC6455 */ 922 #define MHD_HTTP_HEADER_SEC_WEBSOCKET_KEY "Sec-WebSocket-Key" 923 /* Permanent. RFC6455 */ 924 #define MHD_HTTP_HEADER_SEC_WEBSOCKET_PROTOCOL "Sec-WebSocket-Protocol" 925 /* Permanent. RFC6455 */ 926 #define MHD_HTTP_HEADER_SEC_WEBSOCKET_VERSION "Sec-WebSocket-Version" 927 /* Permanent. RFC4229 */ 928 #define MHD_HTTP_HEADER_SECURITY_SCHEME "Security-Scheme" 929 /* Permanent. https://www.w3.org/TR/server-timing/ */ 930 #define MHD_HTTP_HEADER_SERVER_TIMING "Server-Timing" 931 /* Permanent. RFC6265 */ 932 #define MHD_HTTP_HEADER_SET_COOKIE "Set-Cookie" 933 /* Permanent. RFC4229 */ 934 #define MHD_HTTP_HEADER_SETPROFILE "SetProfile" 935 /* Permanent. RFC5023 */ 936 #define MHD_HTTP_HEADER_SLUG "SLUG" 937 /* Permanent. RFC4229 */ 938 #define MHD_HTTP_HEADER_SOAPACTION "SoapAction" 939 /* Permanent. RFC4229 */ 940 #define MHD_HTTP_HEADER_STATUS_URI "Status-URI" 941 /* Permanent. RFC6797 */ 942 #define MHD_HTTP_HEADER_STRICT_TRANSPORT_SECURITY "Strict-Transport-Security" 943 /* Permanent. RFC8594 */ 944 #define MHD_HTTP_HEADER_SUNSET "Sunset" 945 /* Permanent. RFC4229 */ 946 #define MHD_HTTP_HEADER_SURROGATE_CAPABILITY "Surrogate-Capability" 947 /* Permanent. RFC4229 */ 948 #define MHD_HTTP_HEADER_SURROGATE_CONTROL "Surrogate-Control" 949 /* Permanent. RFC4229 */ 950 #define MHD_HTTP_HEADER_TCN "TCN" 951 /* Permanent. RFC4918 */ 952 #define MHD_HTTP_HEADER_TIMEOUT "Timeout" 953 /* Permanent. RFC8030, Section 5.4 */ 954 #define MHD_HTTP_HEADER_TOPIC "Topic" 955 /* Permanent. RFC8030, Section 5.2 */ 956 #define MHD_HTTP_HEADER_TTL "TTL" 957 /* Permanent. RFC8030, Section 5.3 */ 958 #define MHD_HTTP_HEADER_URGENCY "Urgency" 959 /* Permanent. RFC4229 */ 960 #define MHD_HTTP_HEADER_URI "URI" 961 /* Permanent. RFC4229 */ 962 #define MHD_HTTP_HEADER_VARIANT_VARY "Variant-Vary" 963 /* Permanent. RFC4229 */ 964 #define MHD_HTTP_HEADER_WANT_DIGEST "Want-Digest" 965 /* Permanent. https://fetch.spec.whatwg.org/#x-content-type-options-header */ 966 #define MHD_HTTP_HEADER_X_CONTENT_TYPE_OPTIONS "X-Content-Type-Options" 967 /* Permanent. https://html.spec.whatwg.org/multipage/browsing-the-web.html#x-frame-options */ 968 #define MHD_HTTP_HEADER_X_FRAME_OPTIONS "X-Frame-Options" 969 /* Provisional. RFC5789 */ 970 #define MHD_HTTP_HEADER_ACCEPT_PATCH "Accept-Patch" 971 /* Provisional. https://github.com/ampproject/amphtml/blob/master/spec/amp-cache-transform.md */ 972 #define MHD_HTTP_HEADER_AMP_CACHE_TRANSFORM "AMP-Cache-Transform" 973 /* Provisional. RFC4229 */ 974 #define MHD_HTTP_HEADER_COMPLIANCE "Compliance" 975 /* Provisional. https://docs.oasis-open-projects.org/oslc-op/config/v1.0/psd01/config-resources.html#configcontext */ 976 #define MHD_HTTP_HEADER_CONFIGURATION_CONTEXT "Configuration-Context" 977 /* Provisional. RFC4229 */ 978 #define MHD_HTTP_HEADER_CONTENT_TRANSFER_ENCODING "Content-Transfer-Encoding" 979 /* Provisional. RFC4229 */ 980 #define MHD_HTTP_HEADER_COST "Cost" 981 /* Provisional. RFC6017 */ 982 #define MHD_HTTP_HEADER_EDIINT_FEATURES "EDIINT-Features" 983 /* Provisional. OData Version 4.01 Part 1: Protocol; OASIS; Chet_Ensign */ 984 #define MHD_HTTP_HEADER_ISOLATION "Isolation" 985 /* Provisional. RFC4229 */ 986 #define MHD_HTTP_HEADER_MESSAGE_ID "Message-ID" 987 /* Provisional. RFC4229 */ 988 #define MHD_HTTP_HEADER_NON_COMPLIANCE "Non-Compliance" 989 /* Provisional. RFC4229 */ 990 #define MHD_HTTP_HEADER_OPTIONAL "Optional" 991 /* Provisional. Repeatable Requests Version 1.0; OASIS; Chet_Ensign */ 992 #define MHD_HTTP_HEADER_REPEATABILITY_CLIENT_ID "Repeatability-Client-ID" 993 /* Provisional. Repeatable Requests Version 1.0; OASIS; Chet_Ensign */ 994 #define MHD_HTTP_HEADER_REPEATABILITY_FIRST_SENT "Repeatability-First-Sent" 995 /* Provisional. Repeatable Requests Version 1.0; OASIS; Chet_Ensign */ 996 #define MHD_HTTP_HEADER_REPEATABILITY_REQUEST_ID "Repeatability-Request-ID" 997 /* Provisional. Repeatable Requests Version 1.0; OASIS; Chet_Ensign */ 998 #define MHD_HTTP_HEADER_REPEATABILITY_RESULT "Repeatability-Result" 999 /* Provisional. RFC4229 */ 1000 #define MHD_HTTP_HEADER_RESOLUTION_HINT "Resolution-Hint" 1001 /* Provisional. RFC4229 */ 1002 #define MHD_HTTP_HEADER_RESOLVER_LOCATION "Resolver-Location" 1003 /* Provisional. RFC4229 */ 1004 #define MHD_HTTP_HEADER_SUBOK "SubOK" 1005 /* Provisional. RFC4229 */ 1006 #define MHD_HTTP_HEADER_SUBST "Subst" 1007 /* Provisional. https://www.w3.org/TR/resource-timing-1/#timing-allow-origin */ 1008 #define MHD_HTTP_HEADER_TIMING_ALLOW_ORIGIN "Timing-Allow-Origin" 1009 /* Provisional. RFC4229 */ 1010 #define MHD_HTTP_HEADER_TITLE "Title" 1011 /* Provisional. https://www.w3.org/TR/trace-context/#traceparent-field */ 1012 #define MHD_HTTP_HEADER_TRACEPARENT "Traceparent" 1013 /* Provisional. https://www.w3.org/TR/trace-context/#tracestate-field */ 1014 #define MHD_HTTP_HEADER_TRACESTATE "Tracestate" 1015 /* Provisional. RFC4229 */ 1016 #define MHD_HTTP_HEADER_UA_COLOR "UA-Color" 1017 /* Provisional. RFC4229 */ 1018 #define MHD_HTTP_HEADER_UA_MEDIA "UA-Media" 1019 /* Provisional. RFC4229 */ 1020 #define MHD_HTTP_HEADER_UA_PIXELS "UA-Pixels" 1021 /* Provisional. RFC4229 */ 1022 #define MHD_HTTP_HEADER_UA_RESOLUTION "UA-Resolution" 1023 /* Provisional. RFC4229 */ 1024 #define MHD_HTTP_HEADER_UA_WINDOWPIXELS "UA-Windowpixels" 1025 /* Provisional. RFC4229 */ 1026 #define MHD_HTTP_HEADER_VERSION "Version" 1027 /* Provisional. W3C Mobile Web Best Practices Working Group */ 1028 #define MHD_HTTP_HEADER_X_DEVICE_ACCEPT "X-Device-Accept" 1029 /* Provisional. W3C Mobile Web Best Practices Working Group */ 1030 #define MHD_HTTP_HEADER_X_DEVICE_ACCEPT_CHARSET "X-Device-Accept-Charset" 1031 /* Provisional. W3C Mobile Web Best Practices Working Group */ 1032 #define MHD_HTTP_HEADER_X_DEVICE_ACCEPT_ENCODING "X-Device-Accept-Encoding" 1033 /* Provisional. W3C Mobile Web Best Practices Working Group */ 1034 #define MHD_HTTP_HEADER_X_DEVICE_ACCEPT_LANGUAGE "X-Device-Accept-Language" 1035 /* Provisional. W3C Mobile Web Best Practices Working Group */ 1036 #define MHD_HTTP_HEADER_X_DEVICE_USER_AGENT "X-Device-User-Agent" 1037 /* Deprecated. RFC4229 */ 1038 #define MHD_HTTP_HEADER_C_PEP_INFO "C-PEP-Info" 1039 /* Deprecated. RFC4229 */ 1040 #define MHD_HTTP_HEADER_PROTOCOL_INFO "Protocol-Info" 1041 /* Deprecated. RFC4229 */ 1042 #define MHD_HTTP_HEADER_PROTOCOL_QUERY "Protocol-Query" 1043 /* Obsoleted. https://www.w3.org/TR/2007/WD-access-control-20071126/#access-control0 */ 1044 #define MHD_HTTP_HEADER_ACCESS_CONTROL "Access-Control" 1045 /* Obsoleted. RFC2068; RFC2616 */ 1046 #define MHD_HTTP_HEADER_CONTENT_BASE "Content-Base" 1047 /* Obsoleted. RFC2616, Section 14.15; RFC7231, Appendix B */ 1048 #define MHD_HTTP_HEADER_CONTENT_MD5 "Content-MD5" 1049 /* Obsoleted. RFC2965; RFC6265 */ 1050 #define MHD_HTTP_HEADER_COOKIE2 "Cookie2" 1051 /* Obsoleted. https://www.w3.org/TR/2007/WD-access-control-20071126/#method-check */ 1052 #define MHD_HTTP_HEADER_METHOD_CHECK "Method-Check" 1053 /* Obsoleted. https://www.w3.org/TR/2007/WD-access-control-20071126/#method-check-expires */ 1054 #define MHD_HTTP_HEADER_METHOD_CHECK_EXPIRES "Method-Check-Expires" 1055 /* Obsoleted. https://www.w3.org/TR/2007/WD-access-control-20071126/#referer-root */ 1056 #define MHD_HTTP_HEADER_REFERER_ROOT "Referer-Root" 1057 /* Obsoleted. RFC2965; RFC6265 */ 1058 #define MHD_HTTP_HEADER_SET_COOKIE2 "Set-Cookie2" 1059 1060 /* Some provisional headers. */ 1061 #define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN \ 1062 "Access-Control-Allow-Origin" 1063 /** @} */ /* end of group headers */ 1064 1065 /** 1066 * @defgroup versions HTTP versions 1067 * These strings should be used to match against the first line of the 1068 * HTTP header. 1069 * @{ 1070 */ 1071 #define MHD_HTTP_VERSION_1_0 "HTTP/1.0" 1072 #define MHD_HTTP_VERSION_1_1 "HTTP/1.1" 1073 1074 /** @} */ /* end of group versions */ 1075 1076 /** 1077 * @defgroup methods HTTP methods 1078 * HTTP methods (as strings). 1079 * See: http://www.iana.org/assignments/http-methods/http-methods.xml 1080 * Registry export date: 2021-12-19 1081 * @{ 1082 */ 1083 1084 /* Main HTTP methods. */ 1085 /* Not safe. Not idempotent. RFC-ietf-httpbis-semantics, Section 9.3.6. */ 1086 #define MHD_HTTP_METHOD_CONNECT "CONNECT" 1087 /* Not safe. Idempotent. RFC-ietf-httpbis-semantics, Section 9.3.5. */ 1088 #define MHD_HTTP_METHOD_DELETE "DELETE" 1089 /* Safe. Idempotent. RFC-ietf-httpbis-semantics, Section 9.3.1. */ 1090 #define MHD_HTTP_METHOD_GET "GET" 1091 /* Safe. Idempotent. RFC-ietf-httpbis-semantics, Section 9.3.2. */ 1092 #define MHD_HTTP_METHOD_HEAD "HEAD" 1093 /* Safe. Idempotent. RFC-ietf-httpbis-semantics, Section 9.3.7. */ 1094 #define MHD_HTTP_METHOD_OPTIONS "OPTIONS" 1095 /* Not safe. Not idempotent. RFC-ietf-httpbis-semantics, Section 9.3.3. */ 1096 #define MHD_HTTP_METHOD_POST "POST" 1097 /* Not safe. Idempotent. RFC-ietf-httpbis-semantics, Section 9.3.4. */ 1098 #define MHD_HTTP_METHOD_PUT "PUT" 1099 /* Safe. Idempotent. RFC-ietf-httpbis-semantics, Section 9.3.8. */ 1100 #define MHD_HTTP_METHOD_TRACE "TRACE" 1101 /* Not safe. Not idempotent. RFC-ietf-httpbis-semantics, Section 18.2. */ 1102 #define MHD_HTTP_METHOD_ASTERISK "*" 1103 1104 /* Additional HTTP methods. */ 1105 /* Not safe. Idempotent. RFC3744, Section 8.1. */ 1106 #define MHD_HTTP_METHOD_ACL "ACL" 1107 /* Not safe. Idempotent. RFC3253, Section 12.6. */ 1108 #define MHD_HTTP_METHOD_BASELINE_CONTROL "BASELINE-CONTROL" 1109 /* Not safe. Idempotent. RFC5842, Section 4. */ 1110 #define MHD_HTTP_METHOD_BIND "BIND" 1111 /* Not safe. Idempotent. RFC3253, Section 4.4, Section 9.4. */ 1112 #define MHD_HTTP_METHOD_CHECKIN "CHECKIN" 1113 /* Not safe. Idempotent. RFC3253, Section 4.3, Section 8.8. */ 1114 #define MHD_HTTP_METHOD_CHECKOUT "CHECKOUT" 1115 /* Not safe. Idempotent. RFC4918, Section 9.8. */ 1116 #define MHD_HTTP_METHOD_COPY "COPY" 1117 /* Not safe. Idempotent. RFC3253, Section 8.2. */ 1118 #define MHD_HTTP_METHOD_LABEL "LABEL" 1119 /* Not safe. Idempotent. RFC2068, Section 19.6.1.2. */ 1120 #define MHD_HTTP_METHOD_LINK "LINK" 1121 /* Not safe. Not idempotent. RFC4918, Section 9.10. */ 1122 #define MHD_HTTP_METHOD_LOCK "LOCK" 1123 /* Not safe. Idempotent. RFC3253, Section 11.2. */ 1124 #define MHD_HTTP_METHOD_MERGE "MERGE" 1125 /* Not safe. Idempotent. RFC3253, Section 13.5. */ 1126 #define MHD_HTTP_METHOD_MKACTIVITY "MKACTIVITY" 1127 /* Not safe. Idempotent. RFC4791, Section 5.3.1; RFC8144, Section 2.3. */ 1128 #define MHD_HTTP_METHOD_MKCALENDAR "MKCALENDAR" 1129 /* Not safe. Idempotent. RFC4918, Section 9.3; RFC5689, Section 3; RFC8144, Section 2.3. */ 1130 #define MHD_HTTP_METHOD_MKCOL "MKCOL" 1131 /* Not safe. Idempotent. RFC4437, Section 6. */ 1132 #define MHD_HTTP_METHOD_MKREDIRECTREF "MKREDIRECTREF" 1133 /* Not safe. Idempotent. RFC3253, Section 6.3. */ 1134 #define MHD_HTTP_METHOD_MKWORKSPACE "MKWORKSPACE" 1135 /* Not safe. Idempotent. RFC4918, Section 9.9. */ 1136 #define MHD_HTTP_METHOD_MOVE "MOVE" 1137 /* Not safe. Idempotent. RFC3648, Section 7. */ 1138 #define MHD_HTTP_METHOD_ORDERPATCH "ORDERPATCH" 1139 /* Not safe. Not idempotent. RFC5789, Section 2. */ 1140 #define MHD_HTTP_METHOD_PATCH "PATCH" 1141 /* Safe. Idempotent. RFC7540, Section 3.5. */ 1142 #define MHD_HTTP_METHOD_PRI "PRI" 1143 /* Safe. Idempotent. RFC4918, Section 9.1; RFC8144, Section 2.1. */ 1144 #define MHD_HTTP_METHOD_PROPFIND "PROPFIND" 1145 /* Not safe. Idempotent. RFC4918, Section 9.2; RFC8144, Section 2.2. */ 1146 #define MHD_HTTP_METHOD_PROPPATCH "PROPPATCH" 1147 /* Not safe. Idempotent. RFC5842, Section 6. */ 1148 #define MHD_HTTP_METHOD_REBIND "REBIND" 1149 /* Safe. Idempotent. RFC3253, Section 3.6; RFC8144, Section 2.1. */ 1150 #define MHD_HTTP_METHOD_REPORT "REPORT" 1151 /* Safe. Idempotent. RFC5323, Section 2. */ 1152 #define MHD_HTTP_METHOD_SEARCH "SEARCH" 1153 /* Not safe. Idempotent. RFC5842, Section 5. */ 1154 #define MHD_HTTP_METHOD_UNBIND "UNBIND" 1155 /* Not safe. Idempotent. RFC3253, Section 4.5. */ 1156 #define MHD_HTTP_METHOD_UNCHECKOUT "UNCHECKOUT" 1157 /* Not safe. Idempotent. RFC2068, Section 19.6.1.3. */ 1158 #define MHD_HTTP_METHOD_UNLINK "UNLINK" 1159 /* Not safe. Idempotent. RFC4918, Section 9.11. */ 1160 #define MHD_HTTP_METHOD_UNLOCK "UNLOCK" 1161 /* Not safe. Idempotent. RFC3253, Section 7.1. */ 1162 #define MHD_HTTP_METHOD_UPDATE "UPDATE" 1163 /* Not safe. Idempotent. RFC4437, Section 7. */ 1164 #define MHD_HTTP_METHOD_UPDATEREDIRECTREF "UPDATEREDIRECTREF" 1165 /* Not safe. Idempotent. RFC3253, Section 3.5. */ 1166 #define MHD_HTTP_METHOD_VERSION_CONTROL "VERSION-CONTROL" 1167 1168 /** @} */ /* end of group methods */ 1169 1170 /** 1171 * @defgroup postenc HTTP POST encodings 1172 * See also: http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4 1173 * @{ 1174 */ 1175 #define MHD_HTTP_POST_ENCODING_FORM_URLENCODED \ 1176 "application/x-www-form-urlencoded" 1177 #define MHD_HTTP_POST_ENCODING_MULTIPART_FORMDATA "multipart/form-data" 1178 1179 /** @} */ /* end of group postenc */ 1180 1181 1182 /** 1183 * @brief Handle for the daemon (listening on a socket for HTTP traffic). 1184 * @ingroup event 1185 */ 1186 struct MHD_Daemon; 1187 1188 /** 1189 * @brief Handle for a connection / HTTP request. 1190 * 1191 * With HTTP/1.1, multiple requests can be run over the same 1192 * connection. However, MHD will only show one request per TCP 1193 * connection to the client at any given time. 1194 * @ingroup request 1195 */ 1196 struct MHD_Connection; 1197 1198 /** 1199 * @brief Handle for a response. 1200 * @ingroup response 1201 */ 1202 struct MHD_Response; 1203 1204 /** 1205 * @brief Handle for POST processing. 1206 * @ingroup response 1207 */ 1208 struct MHD_PostProcessor; 1209 1210 1211 /** 1212 * @brief Flags for the `struct MHD_Daemon`. 1213 * 1214 * Note that MHD will run automatically in background thread(s) only 1215 * if #MHD_USE_INTERNAL_POLLING_THREAD is used. Otherwise caller (application) 1216 * must use #MHD_run() or #MHD_run_from_select() to have MHD processed 1217 * network connections and data. 1218 * 1219 * Starting the daemon may also fail if a particular option is not 1220 * implemented or not supported on the target platform (i.e. no 1221 * support for TLS, epoll or IPv6). 1222 */ 1223 enum MHD_FLAG 1224 { 1225 /** 1226 * No options selected. 1227 */ 1228 MHD_NO_FLAG = 0, 1229 1230 /** 1231 * Print errors messages to custom error logger or to `stderr` if 1232 * custom error logger is not set. 1233 * @sa ::MHD_OPTION_EXTERNAL_LOGGER 1234 */ 1235 MHD_USE_ERROR_LOG = 1, 1236 1237 /** 1238 * Run in debug mode. If this flag is used, the library should 1239 * print error messages and warnings to `stderr`. 1240 */ 1241 MHD_USE_DEBUG = 1, 1242 1243 /** 1244 * Run in HTTPS mode. The modern protocol is called TLS. 1245 */ 1246 MHD_USE_TLS = 2, 1247 1248 /** @deprecated */ 1249 MHD_USE_SSL = 2, 1250 #if 0 1251 /* let's do this later once versions that define MHD_USE_TLS a more widely deployed. */ 1252 #define MHD_USE_SSL \ 1253 _MHD_DEPR_IN_MACRO ("Value MHD_USE_SSL is deprecated, use MHD_USE_TLS") \ 1254 MHD_USE_TLS 1255 #endif 1256 1257 /** 1258 * Run using one thread per connection. 1259 * Must be used only with #MHD_USE_INTERNAL_POLLING_THREAD. 1260 */ 1261 MHD_USE_THREAD_PER_CONNECTION = 4, 1262 1263 /** 1264 * Run using an internal thread (or thread pool) for sockets sending 1265 * and receiving and data processing. Without this flag MHD will not 1266 * run automatically in background thread(s). 1267 * If this flag is set, #MHD_run() and #MHD_run_from_select() couldn't 1268 * be used. 1269 * This flag is set explicitly by #MHD_USE_POLL_INTERNAL_THREAD and 1270 * by #MHD_USE_EPOLL_INTERNAL_THREAD. 1271 * When this flag is not set, MHD run in "external" polling mode. 1272 */ 1273 MHD_USE_INTERNAL_POLLING_THREAD = 8, 1274 1275 /** @deprecated */ 1276 MHD_USE_SELECT_INTERNALLY = 8, 1277 #if 0 /* Will be marked for real deprecation later. */ 1278 #define MHD_USE_SELECT_INTERNALLY \ 1279 _MHD_DEPR_IN_MACRO ( \ 1280 "Value MHD_USE_SELECT_INTERNALLY is deprecated, use MHD_USE_INTERNAL_POLLING_THREAD instead") \ 1281 MHD_USE_INTERNAL_POLLING_THREAD 1282 #endif /* 0 */ 1283 1284 /** 1285 * Run using the IPv6 protocol (otherwise, MHD will just support 1286 * IPv4). If you want MHD to support IPv4 and IPv6 using a single 1287 * socket, pass #MHD_USE_DUAL_STACK, otherwise, if you only pass 1288 * this option, MHD will try to bind to IPv6-only (resulting in 1289 * no IPv4 support). 1290 */ 1291 MHD_USE_IPv6 = 16, 1292 1293 /** 1294 * Be pedantic about the protocol (as opposed to as tolerant as 1295 * possible). Specifically, at the moment, this flag causes MHD to 1296 * reject HTTP 1.1 connections without a "Host" header. This is 1297 * required by the standard, but of course in violation of the "be 1298 * as liberal as possible in what you accept" norm. It is 1299 * recommended to turn this ON if you are testing clients against 1300 * MHD, and OFF in production. 1301 */ 1302 MHD_USE_PEDANTIC_CHECKS = 32, 1303 #if 0 /* Will be marked for real deprecation later. */ 1304 #define MHD_USE_PEDANTIC_CHECKS \ 1305 _MHD_DEPR_IN_MACRO ( \ 1306 "Flag MHD_USE_PEDANTIC_CHECKS is deprecated, use option MHD_OPTION_STRICT_FOR_CLIENT instead") \ 1307 32 1308 #endif /* 0 */ 1309 1310 /** 1311 * Use `poll()` instead of `select()` for polling sockets. 1312 * This allows sockets with `fd >= FD_SETSIZE`. 1313 * This option is not compatible with an "external" polling mode 1314 * (as there is no API to get the file descriptors for the external 1315 * poll() from MHD) and must also not be used in combination 1316 * with #MHD_USE_EPOLL. 1317 * @sa ::MHD_FEATURE_POLL, #MHD_USE_POLL_INTERNAL_THREAD 1318 */ 1319 MHD_USE_POLL = 64, 1320 1321 /** 1322 * Run using an internal thread (or thread pool) doing `poll()`. 1323 * @sa ::MHD_FEATURE_POLL, #MHD_USE_POLL, #MHD_USE_INTERNAL_POLLING_THREAD 1324 */ 1325 MHD_USE_POLL_INTERNAL_THREAD = MHD_USE_POLL | MHD_USE_INTERNAL_POLLING_THREAD, 1326 1327 /** @deprecated */ 1328 MHD_USE_POLL_INTERNALLY = MHD_USE_POLL | MHD_USE_INTERNAL_POLLING_THREAD, 1329 #if 0 /* Will be marked for real deprecation later. */ 1330 #define MHD_USE_POLL_INTERNALLY \ 1331 _MHD_DEPR_IN_MACRO ( \ 1332 "Value MHD_USE_POLL_INTERNALLY is deprecated, use MHD_USE_POLL_INTERNAL_THREAD instead") \ 1333 MHD_USE_POLL_INTERNAL_THREAD 1334 #endif /* 0 */ 1335 1336 /** 1337 * Suppress (automatically) adding the 'Date:' header to HTTP responses. 1338 * This option should ONLY be used on systems that do not have a clock 1339 * and that DO provide other mechanisms for cache control. See also 1340 * RFC 2616, section 14.18 (exception 3). 1341 */ 1342 MHD_USE_SUPPRESS_DATE_NO_CLOCK = 128, 1343 1344 /** @deprecated */ 1345 MHD_SUPPRESS_DATE_NO_CLOCK = 128, 1346 #if 0 /* Will be marked for real deprecation later. */ 1347 #define MHD_SUPPRESS_DATE_NO_CLOCK \ 1348 _MHD_DEPR_IN_MACRO ( \ 1349 "Value MHD_SUPPRESS_DATE_NO_CLOCK is deprecated, use MHD_USE_SUPPRESS_DATE_NO_CLOCK instead") \ 1350 MHD_USE_SUPPRESS_DATE_NO_CLOCK 1351 #endif /* 0 */ 1352 1353 /** 1354 * Run without a listen socket. This option only makes sense if 1355 * #MHD_add_connection is to be used exclusively to connect HTTP 1356 * clients to the HTTP server. This option is incompatible with 1357 * using a thread pool; if it is used, #MHD_OPTION_THREAD_POOL_SIZE 1358 * is ignored. 1359 */ 1360 MHD_USE_NO_LISTEN_SOCKET = 256, 1361 1362 /** 1363 * Use `epoll()` instead of `select()` or `poll()` for the event loop. 1364 * This option is only available on some systems; using the option on 1365 * systems without epoll will cause #MHD_start_daemon to fail. Using 1366 * this option is not supported with #MHD_USE_THREAD_PER_CONNECTION. 1367 * @sa ::MHD_FEATURE_EPOLL 1368 */ 1369 MHD_USE_EPOLL = 512, 1370 1371 /** @deprecated */ 1372 MHD_USE_EPOLL_LINUX_ONLY = 512, 1373 #if 0 /* Will be marked for real deprecation later. */ 1374 #define MHD_USE_EPOLL_LINUX_ONLY \ 1375 _MHD_DEPR_IN_MACRO ( \ 1376 "Value MHD_USE_EPOLL_LINUX_ONLY is deprecated, use MHD_USE_EPOLL") \ 1377 MHD_USE_EPOLL 1378 #endif /* 0 */ 1379 1380 /** 1381 * Run using an internal thread (or thread pool) doing `epoll` polling. 1382 * This option is only available on certain platforms; using the option on 1383 * platform without `epoll` support will cause #MHD_start_daemon to fail. 1384 * @sa ::MHD_FEATURE_EPOLL, #MHD_USE_EPOLL, #MHD_USE_INTERNAL_POLLING_THREAD 1385 */ 1386 MHD_USE_EPOLL_INTERNAL_THREAD = MHD_USE_EPOLL 1387 | MHD_USE_INTERNAL_POLLING_THREAD, 1388 1389 /** @deprecated */ 1390 MHD_USE_EPOLL_INTERNALLY = MHD_USE_EPOLL | MHD_USE_INTERNAL_POLLING_THREAD, 1391 /** @deprecated */ 1392 MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY = MHD_USE_EPOLL 1393 | MHD_USE_INTERNAL_POLLING_THREAD, 1394 #if 0 /* Will be marked for real deprecation later. */ 1395 #define MHD_USE_EPOLL_INTERNALLY \ 1396 _MHD_DEPR_IN_MACRO ( \ 1397 "Value MHD_USE_EPOLL_INTERNALLY is deprecated, use MHD_USE_EPOLL_INTERNAL_THREAD") \ 1398 MHD_USE_EPOLL_INTERNAL_THREAD 1399 /** @deprecated */ 1400 #define MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY \ 1401 _MHD_DEPR_IN_MACRO ( \ 1402 "Value MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY is deprecated, use MHD_USE_EPOLL_INTERNAL_THREAD") \ 1403 MHD_USE_EPOLL_INTERNAL_THREAD 1404 #endif /* 0 */ 1405 1406 /** 1407 * Use inter-thread communication channel. 1408 * #MHD_USE_ITC can be used with #MHD_USE_INTERNAL_POLLING_THREAD 1409 * and is ignored with any "external" sockets polling. 1410 * It's required for use of #MHD_quiesce_daemon 1411 * or #MHD_add_connection. 1412 * This option is enforced by #MHD_ALLOW_SUSPEND_RESUME or 1413 * #MHD_USE_NO_LISTEN_SOCKET. 1414 * #MHD_USE_ITC is always used automatically on platforms 1415 * where select()/poll()/other ignore shutdown of listen 1416 * socket. 1417 */ 1418 MHD_USE_ITC = 1024, 1419 1420 /** @deprecated */ 1421 MHD_USE_PIPE_FOR_SHUTDOWN = 1024, 1422 #if 0 /* Will be marked for real deprecation later. */ 1423 #define MHD_USE_PIPE_FOR_SHUTDOWN \ 1424 _MHD_DEPR_IN_MACRO ( \ 1425 "Value MHD_USE_PIPE_FOR_SHUTDOWN is deprecated, use MHD_USE_ITC") \ 1426 MHD_USE_ITC 1427 #endif /* 0 */ 1428 1429 /** 1430 * Use a single socket for IPv4 and IPv6. 1431 */ 1432 MHD_USE_DUAL_STACK = MHD_USE_IPv6 | 2048, 1433 1434 /** 1435 * Enable `turbo`. Disables certain calls to `shutdown()`, 1436 * enables aggressive non-blocking optimistic reads and 1437 * other potentially unsafe optimizations. 1438 * Most effects only happen with #MHD_USE_EPOLL. 1439 */ 1440 MHD_USE_TURBO = 4096, 1441 1442 /** @deprecated */ 1443 MHD_USE_EPOLL_TURBO = 4096, 1444 #if 0 /* Will be marked for real deprecation later. */ 1445 #define MHD_USE_EPOLL_TURBO \ 1446 _MHD_DEPR_IN_MACRO ( \ 1447 "Value MHD_USE_EPOLL_TURBO is deprecated, use MHD_USE_TURBO") \ 1448 MHD_USE_TURBO 1449 #endif /* 0 */ 1450 1451 /** 1452 * Enable suspend/resume functions, which also implies setting up 1453 * ITC to signal resume. 1454 */ 1455 MHD_ALLOW_SUSPEND_RESUME = 8192 | MHD_USE_ITC, 1456 1457 /** @deprecated */ 1458 MHD_USE_SUSPEND_RESUME = 8192 | MHD_USE_ITC, 1459 #if 0 /* Will be marked for real deprecation later. */ 1460 #define MHD_USE_SUSPEND_RESUME \ 1461 _MHD_DEPR_IN_MACRO ( \ 1462 "Value MHD_USE_SUSPEND_RESUME is deprecated, use MHD_ALLOW_SUSPEND_RESUME instead") \ 1463 MHD_ALLOW_SUSPEND_RESUME 1464 #endif /* 0 */ 1465 1466 /** 1467 * Enable TCP_FASTOPEN option. This option is only available on Linux with a 1468 * kernel >= 3.6. On other systems, using this option cases #MHD_start_daemon 1469 * to fail. 1470 */ 1471 MHD_USE_TCP_FASTOPEN = 16384, 1472 1473 /** 1474 * You need to set this option if you want to use HTTP "Upgrade". 1475 * "Upgrade" may require usage of additional internal resources, 1476 * which we do not want to use unless necessary. 1477 */ 1478 MHD_ALLOW_UPGRADE = 32768, 1479 1480 /** 1481 * Automatically use best available polling function. 1482 * Choice of polling function is also depend on other daemon options. 1483 * If #MHD_USE_INTERNAL_POLLING_THREAD is specified then epoll, poll() or 1484 * select() will be used (listed in decreasing preference order, first 1485 * function available on system will be used). 1486 * If #MHD_USE_THREAD_PER_CONNECTION is specified then poll() or select() 1487 * will be used. 1488 * If those flags are not specified then epoll or select() will be 1489 * used (as the only suitable for MHD_get_fdset()) 1490 */ 1491 MHD_USE_AUTO = 65536, 1492 1493 /** 1494 * Run using an internal thread (or thread pool) with best available on 1495 * system polling function. 1496 * This is combination of #MHD_USE_AUTO and #MHD_USE_INTERNAL_POLLING_THREAD 1497 * flags. 1498 */ 1499 MHD_USE_AUTO_INTERNAL_THREAD = MHD_USE_AUTO | MHD_USE_INTERNAL_POLLING_THREAD, 1500 1501 /** 1502 * Flag set to enable post-handshake client authentication 1503 * (only useful in combination with #MHD_USE_TLS). 1504 */ 1505 MHD_USE_POST_HANDSHAKE_AUTH_SUPPORT = 1U << 17, 1506 1507 /** 1508 * Flag set to enable TLS 1.3 early data. This has 1509 * security implications, be VERY careful when using this. 1510 */ 1511 MHD_USE_INSECURE_TLS_EARLY_DATA = 1U << 18 1512 1513 }; 1514 1515 1516 /** 1517 * Type of a callback function used for logging by MHD. 1518 * 1519 * @param cls closure 1520 * @param fm format string (`printf()`-style) 1521 * @param ap arguments to @a fm 1522 * @ingroup logging 1523 */ 1524 typedef void 1525 (*MHD_LogCallback)(void *cls, 1526 const char *fm, 1527 va_list ap); 1528 1529 1530 /** 1531 * Function called to lookup the pre shared key (@a psk) for a given 1532 * HTTP connection based on the @a username. 1533 * 1534 * @param cls closure 1535 * @param connection the HTTPS connection 1536 * @param username the user name claimed by the other side 1537 * @param[out] psk to be set to the pre-shared-key; should be allocated with malloc(), 1538 * will be freed by MHD 1539 * @param[out] psk_size to be set to the number of bytes in @a psk 1540 * @return 0 on success, -1 on errors 1541 */ 1542 typedef int 1543 (*MHD_PskServerCredentialsCallback)(void *cls, 1544 const struct MHD_Connection *connection, 1545 const char *username, 1546 void **psk, 1547 size_t *psk_size); 1548 1549 /** 1550 * @brief MHD options. 1551 * 1552 * Passed in the varargs portion of #MHD_start_daemon. 1553 */ 1554 enum MHD_OPTION 1555 { 1556 1557 /** 1558 * No more options / last option. This is used 1559 * to terminate the VARARGs list. 1560 */ 1561 MHD_OPTION_END = 0, 1562 1563 /** 1564 * Maximum memory size per connection (followed by a `size_t`). 1565 * Default is 32 kb (#MHD_POOL_SIZE_DEFAULT). 1566 * Values above 128k are unlikely to result in much benefit, as half 1567 * of the memory will be typically used for IO, and TCP buffers are 1568 * unlikely to support window sizes above 64k on most systems. 1569 */ 1570 MHD_OPTION_CONNECTION_MEMORY_LIMIT = 1, 1571 1572 /** 1573 * Maximum number of concurrent connections to 1574 * accept (followed by an `unsigned int`). 1575 */ 1576 MHD_OPTION_CONNECTION_LIMIT = 2, 1577 1578 /** 1579 * After how many seconds of inactivity should a 1580 * connection automatically be timed out? (followed 1581 * by an `unsigned int`; use zero for no timeout). 1582 * Values larger than (UINT64_MAX / 2000 - 1) will 1583 * be clipped to this number. 1584 */ 1585 MHD_OPTION_CONNECTION_TIMEOUT = 3, 1586 1587 /** 1588 * Register a function that should be called whenever a request has 1589 * been completed (this can be used for application-specific clean 1590 * up). Requests that have never been presented to the application 1591 * (via #MHD_AccessHandlerCallback) will not result in 1592 * notifications. 1593 * 1594 * This option should be followed by TWO pointers. First a pointer 1595 * to a function of type #MHD_RequestCompletedCallback and second a 1596 * pointer to a closure to pass to the request completed callback. 1597 * The second pointer may be NULL. 1598 */ 1599 MHD_OPTION_NOTIFY_COMPLETED = 4, 1600 1601 /** 1602 * Limit on the number of (concurrent) connections made to the 1603 * server from the same IP address. Can be used to prevent one 1604 * IP from taking over all of the allowed connections. If the 1605 * same IP tries to establish more than the specified number of 1606 * connections, they will be immediately rejected. The option 1607 * should be followed by an `unsigned int`. The default is 1608 * zero, which means no limit on the number of connections 1609 * from the same IP address. 1610 */ 1611 MHD_OPTION_PER_IP_CONNECTION_LIMIT = 5, 1612 1613 /** 1614 * Bind daemon to the supplied `struct sockaddr`. This option should 1615 * be followed by a `struct sockaddr *`. If #MHD_USE_IPv6 is 1616 * specified, the `struct sockaddr*` should point to a `struct 1617 * sockaddr_in6`, otherwise to a `struct sockaddr_in`. 1618 */ 1619 MHD_OPTION_SOCK_ADDR = 6, 1620 1621 /** 1622 * Specify a function that should be called before parsing the URI from 1623 * the client. The specified callback function can be used for processing 1624 * the URI (including the options) before it is parsed. The URI after 1625 * parsing will no longer contain the options, which maybe inconvenient for 1626 * logging. This option should be followed by two arguments, the first 1627 * one must be of the form 1628 * 1629 * void * my_logger(void *cls, const char *uri, struct MHD_Connection *con) 1630 * 1631 * where the return value will be passed as 1632 * (`* con_cls`) in calls to the #MHD_AccessHandlerCallback 1633 * when this request is processed later; returning a 1634 * value of NULL has no special significance (however, 1635 * note that if you return non-NULL, you can no longer 1636 * rely on the first call to the access handler having 1637 * `NULL == *con_cls` on entry;) 1638 * "cls" will be set to the second argument following 1639 * #MHD_OPTION_URI_LOG_CALLBACK. Finally, uri will 1640 * be the 0-terminated URI of the request. 1641 * 1642 * Note that during the time of this call, most of the connection's 1643 * state is not initialized (as we have not yet parsed the headers). 1644 * However, information about the connecting client (IP, socket) 1645 * is available. 1646 * 1647 * The specified function is called only once per request, therefore some 1648 * programmers may use it to instantiate their own request objects, freeing 1649 * them in the notifier #MHD_OPTION_NOTIFY_COMPLETED. 1650 */ 1651 MHD_OPTION_URI_LOG_CALLBACK = 7, 1652 1653 /** 1654 * Memory pointer for the private key (key.pem) to be used by the 1655 * HTTPS daemon. This option should be followed by a 1656 * `const char *` argument. 1657 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_CERT. 1658 */ 1659 MHD_OPTION_HTTPS_MEM_KEY = 8, 1660 1661 /** 1662 * Memory pointer for the certificate (cert.pem) to be used by the 1663 * HTTPS daemon. This option should be followed by a 1664 * `const char *` argument. 1665 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY. 1666 */ 1667 MHD_OPTION_HTTPS_MEM_CERT = 9, 1668 1669 /** 1670 * Daemon credentials type. 1671 * Followed by an argument of type 1672 * `gnutls_credentials_type_t`. 1673 */ 1674 MHD_OPTION_HTTPS_CRED_TYPE = 10, 1675 1676 /** 1677 * Memory pointer to a `const char *` specifying the 1678 * cipher algorithm (default: "NORMAL"). 1679 */ 1680 MHD_OPTION_HTTPS_PRIORITIES = 11, 1681 1682 /** 1683 * Pass a listen socket for MHD to use (systemd-style). If this 1684 * option is used, MHD will not open its own listen socket(s). The 1685 * argument passed must be of type `MHD_socket` and refer to an 1686 * existing socket that has been bound to a port and is listening. 1687 */ 1688 MHD_OPTION_LISTEN_SOCKET = 12, 1689 1690 /** 1691 * Use the given function for logging error messages. This option 1692 * must be followed by two arguments; the first must be a pointer to 1693 * a function of type #MHD_LogCallback and the second a pointer 1694 * `void *` which will be passed as the first argument to the log 1695 * callback. 1696 * Should be specified as the first option, otherwise some messages 1697 * may be printed by standard MHD logger during daemon startup. 1698 * 1699 * Note that MHD will not generate any log messages 1700 * if it was compiled without the "--enable-messages" 1701 * flag being set. 1702 */ 1703 MHD_OPTION_EXTERNAL_LOGGER = 13, 1704 1705 /** 1706 * Number (`unsigned int`) of threads in thread pool. Enable 1707 * thread pooling by setting this value to to something 1708 * greater than 1. Currently, thread mode must be 1709 * #MHD_USE_INTERNAL_POLLING_THREAD if thread pooling is enabled 1710 * (#MHD_start_daemon returns NULL for an unsupported thread 1711 * mode). 1712 */ 1713 MHD_OPTION_THREAD_POOL_SIZE = 14, 1714 1715 /** 1716 * Additional options given in an array of `struct MHD_OptionItem`. 1717 * The array must be terminated with an entry `{MHD_OPTION_END, 0, NULL}`. 1718 * An example for code using #MHD_OPTION_ARRAY is: 1719 * 1720 * struct MHD_OptionItem ops[] = { 1721 * { MHD_OPTION_CONNECTION_LIMIT, 100, NULL }, 1722 * { MHD_OPTION_CONNECTION_TIMEOUT, 10, NULL }, 1723 * { MHD_OPTION_END, 0, NULL } 1724 * }; 1725 * d = MHD_start_daemon (0, 8080, NULL, NULL, dh, NULL, 1726 * MHD_OPTION_ARRAY, ops, 1727 * MHD_OPTION_END); 1728 * 1729 * For options that expect a single pointer argument, the 1730 * second member of the `struct MHD_OptionItem` is ignored. 1731 * For options that expect two pointer arguments, the first 1732 * argument must be cast to `intptr_t`. 1733 */ 1734 MHD_OPTION_ARRAY = 15, 1735 1736 /** 1737 * Specify a function that should be called for unescaping escape 1738 * sequences in URIs and URI arguments. Note that this function 1739 * will NOT be used by the `struct MHD_PostProcessor`. If this 1740 * option is not specified, the default method will be used which 1741 * decodes escape sequences of the form "%HH". This option should 1742 * be followed by two arguments, the first one must be of the form 1743 * 1744 * size_t my_unescaper(void *cls, 1745 * struct MHD_Connection *c, 1746 * char *s) 1747 * 1748 * where the return value must be the length of the value left in 1749 * "s" (without the 0-terminator) and "s" should be updated. Note 1750 * that the unescape function must not lengthen "s" (the result must 1751 * be shorter than the input and must still be 0-terminated). 1752 * However, it may also include binary zeros before the 1753 * 0-termination. "cls" will be set to the second argument 1754 * following #MHD_OPTION_UNESCAPE_CALLBACK. 1755 */ 1756 MHD_OPTION_UNESCAPE_CALLBACK = 16, 1757 1758 /** 1759 * Memory pointer for the random values to be used by the Digest 1760 * Auth module. This option should be followed by two arguments. 1761 * First an integer of type `size_t` which specifies the size 1762 * of the buffer pointed to by the second argument in bytes. 1763 * Note that the application must ensure that the buffer of the 1764 * second argument remains allocated and unmodified while the 1765 * daemon is running. 1766 */ 1767 MHD_OPTION_DIGEST_AUTH_RANDOM = 17, 1768 1769 /** 1770 * Size of the internal array holding the map of the nonce and 1771 * the nonce counter. This option should be followed by an `unsigend int` 1772 * argument. 1773 */ 1774 MHD_OPTION_NONCE_NC_SIZE = 18, 1775 1776 /** 1777 * Desired size of the stack for threads created by MHD. Followed 1778 * by an argument of type `size_t`. Use 0 for system default. 1779 */ 1780 MHD_OPTION_THREAD_STACK_SIZE = 19, 1781 1782 /** 1783 * Memory pointer for the certificate (ca.pem) to be used by the 1784 * HTTPS daemon for client authentication. 1785 * This option should be followed by a `const char *` argument. 1786 */ 1787 MHD_OPTION_HTTPS_MEM_TRUST = 20, 1788 1789 /** 1790 * Increment to use for growing the read buffer (followed by a 1791 * `size_t`). Must fit within #MHD_OPTION_CONNECTION_MEMORY_LIMIT. 1792 */ 1793 MHD_OPTION_CONNECTION_MEMORY_INCREMENT = 21, 1794 1795 /** 1796 * Use a callback to determine which X.509 certificate should be 1797 * used for a given HTTPS connection. This option should be 1798 * followed by a argument of type `gnutls_certificate_retrieve_function2 *`. 1799 * This option provides an 1800 * alternative to #MHD_OPTION_HTTPS_MEM_KEY, 1801 * #MHD_OPTION_HTTPS_MEM_CERT. You must use this version if 1802 * multiple domains are to be hosted at the same IP address using 1803 * TLS's Server Name Indication (SNI) extension. In this case, 1804 * the callback is expected to select the correct certificate 1805 * based on the SNI information provided. The callback is expected 1806 * to access the SNI data using `gnutls_server_name_get()`. 1807 * Using this option requires GnuTLS 3.0 or higher. 1808 */ 1809 MHD_OPTION_HTTPS_CERT_CALLBACK = 22, 1810 1811 /** 1812 * When using #MHD_USE_TCP_FASTOPEN, this option changes the default TCP 1813 * fastopen queue length of 50. Note that having a larger queue size can 1814 * cause resource exhaustion attack as the TCP stack has to now allocate 1815 * resources for the SYN packet along with its DATA. This option should be 1816 * followed by an `unsigned int` argument. 1817 */ 1818 MHD_OPTION_TCP_FASTOPEN_QUEUE_SIZE = 23, 1819 1820 /** 1821 * Memory pointer for the Diffie-Hellman parameters (dh.pem) to be used by the 1822 * HTTPS daemon for key exchange. 1823 * This option must be followed by a `const char *` argument. 1824 */ 1825 MHD_OPTION_HTTPS_MEM_DHPARAMS = 24, 1826 1827 /** 1828 * If present and set to true, allow reusing address:port socket 1829 * (by using SO_REUSEPORT on most platform, or platform-specific ways). 1830 * If present and set to false, disallow reusing address:port socket 1831 * (does nothing on most platform, but uses SO_EXCLUSIVEADDRUSE on Windows). 1832 * This option must be followed by a `unsigned int` argument. 1833 */ 1834 MHD_OPTION_LISTENING_ADDRESS_REUSE = 25, 1835 1836 /** 1837 * Memory pointer for a password that decrypts the private key (key.pem) 1838 * to be used by the HTTPS daemon. This option should be followed by a 1839 * `const char *` argument. 1840 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY. 1841 * @sa ::MHD_FEATURE_HTTPS_KEY_PASSWORD 1842 */ 1843 MHD_OPTION_HTTPS_KEY_PASSWORD = 26, 1844 1845 /** 1846 * Register a function that should be called whenever a connection is 1847 * started or closed. 1848 * 1849 * This option should be followed by TWO pointers. First a pointer 1850 * to a function of type #MHD_NotifyConnectionCallback and second a 1851 * pointer to a closure to pass to the request completed callback. 1852 * The second pointer may be NULL. 1853 */ 1854 MHD_OPTION_NOTIFY_CONNECTION = 27, 1855 1856 /** 1857 * Allow to change maximum length of the queue of pending connections on 1858 * listen socket. If not present than default platform-specific SOMAXCONN 1859 * value is used. This option should be followed by an `unsigned int` 1860 * argument. 1861 */ 1862 MHD_OPTION_LISTEN_BACKLOG_SIZE = 28, 1863 1864 /** 1865 * If set to 1 - be strict about the protocol. Use -1 to be 1866 * as tolerant as possible. 1867 * 1868 * Specifically, at the moment, at 1 this flag 1869 * causes MHD to reject HTTP 1.1 connections without a "Host" header, 1870 * and to disallow spaces in the URL or (at -1) in HTTP header key strings. 1871 * 1872 * These are required by some versions of the standard, but of 1873 * course in violation of the "be as liberal as possible in what you 1874 * accept" norm. It is recommended to set this to 1 if you are 1875 * testing clients against MHD, and 0 in production. This option 1876 * should be followed by an `int` argument. 1877 */ 1878 MHD_OPTION_STRICT_FOR_CLIENT = 29, 1879 1880 /** 1881 * This should be a pointer to callback of type 1882 * gnutls_psk_server_credentials_function that will be given to 1883 * gnutls_psk_set_server_credentials_function. It is used to 1884 * retrieve the shared key for a given username. 1885 */ 1886 MHD_OPTION_GNUTLS_PSK_CRED_HANDLER = 30, 1887 1888 /** 1889 * Use a callback to determine which X.509 certificate should be 1890 * used for a given HTTPS connection. This option should be 1891 * followed by a argument of type `gnutls_certificate_retrieve_function3 *`. 1892 * This option provides an 1893 * alternative/extension to #MHD_OPTION_HTTPS_CERT_CALLBACK. 1894 * You must use this version if you want to use OCSP stapling. 1895 * Using this option requires GnuTLS 3.6.3 or higher. 1896 */ 1897 MHD_OPTION_HTTPS_CERT_CALLBACK2 = 31, 1898 1899 /** 1900 * Allows the application to disable certain sanity precautions 1901 * in MHD. With these, the client can break the HTTP protocol, 1902 * so this should never be used in production. The options are, 1903 * however, useful for testing HTTP clients against "broken" 1904 * server implementations. 1905 * This argument must be followed by an "unsigned int", corresponding 1906 * to an `enum MHD_DisableSanityCheck`. 1907 */ 1908 MHD_OPTION_SERVER_INSANITY = 32, 1909 1910 /** 1911 * If followed by value '1' informs MHD that SIGPIPE is suppressed or 1912 * handled by application. Allows MHD to use network functions that could 1913 * generate SIGPIPE, like `sendfile()`. 1914 * Valid only for daemons without #MHD_USE_INTERNAL_POLLING_THREAD as 1915 * MHD automatically suppresses SIGPIPE for threads started by MHD. 1916 * This option should be followed by an `int` argument. 1917 * @note Available since #MHD_VERSION 0x00097205 1918 */ 1919 MHD_OPTION_SIGPIPE_HANDLED_BY_APP = 33, 1920 1921 /** 1922 * If followed by 'int' with value '1' disables usage of ALPN for TLS 1923 * connections even if supported by TLS library. 1924 * Valid only for daemons with #MHD_USE_TLS. 1925 * This option should be followed by an `int` argument. 1926 * @note Available since #MHD_VERSION 0x00097207 1927 */ 1928 MHD_OPTION_TLS_NO_ALPN = 34 1929 } _MHD_FIXED_ENUM; 1930 1931 1932 /** 1933 * Bitfield for the #MHD_OPTION_SERVER_INSANITY specifying 1934 * which santiy checks should be disabled. 1935 */ 1936 enum MHD_DisableSanityCheck 1937 { 1938 /** 1939 * All sanity checks are enabled. 1940 */ 1941 MHD_DSC_SANE = 0 1942 1943 } _MHD_FIXED_FLAGS_ENUM; 1944 1945 1946 /** 1947 * Entry in an #MHD_OPTION_ARRAY. 1948 */ 1949 struct MHD_OptionItem 1950 { 1951 /** 1952 * Which option is being given. Use #MHD_OPTION_END 1953 * to terminate the array. 1954 */ 1955 enum MHD_OPTION option; 1956 1957 /** 1958 * Option value (for integer arguments, and for options requiring 1959 * two pointer arguments); should be 0 for options that take no 1960 * arguments or only a single pointer argument. 1961 */ 1962 intptr_t value; 1963 1964 /** 1965 * Pointer option value (use NULL for options taking no arguments 1966 * or only an integer option). 1967 */ 1968 void *ptr_value; 1969 1970 }; 1971 1972 1973 /** 1974 * The `enum MHD_ValueKind` specifies the source of 1975 * the key-value pairs in the HTTP protocol. 1976 */ 1977 enum MHD_ValueKind 1978 { 1979 1980 /** 1981 * Response header 1982 * @deprecated 1983 */ 1984 MHD_RESPONSE_HEADER_KIND = 0, 1985 #define MHD_RESPONSE_HEADER_KIND \ 1986 _MHD_DEPR_IN_MACRO ( \ 1987 "Value MHD_RESPONSE_HEADER_KIND is deprecated and not used") \ 1988 MHD_RESPONSE_HEADER_KIND 1989 1990 /** 1991 * HTTP header (request/response). 1992 */ 1993 MHD_HEADER_KIND = 1, 1994 1995 /** 1996 * Cookies. Note that the original HTTP header containing 1997 * the cookie(s) will still be available and intact. 1998 */ 1999 MHD_COOKIE_KIND = 2, 2000 2001 /** 2002 * POST data. This is available only if a content encoding 2003 * supported by MHD is used (currently only URL encoding), 2004 * and only if the posted content fits within the available 2005 * memory pool. Note that in that case, the upload data 2006 * given to the #MHD_AccessHandlerCallback will be 2007 * empty (since it has already been processed). 2008 */ 2009 MHD_POSTDATA_KIND = 4, 2010 2011 /** 2012 * GET (URI) arguments. 2013 */ 2014 MHD_GET_ARGUMENT_KIND = 8, 2015 2016 /** 2017 * HTTP footer (only for HTTP 1.1 chunked encodings). 2018 */ 2019 MHD_FOOTER_KIND = 16 2020 } _MHD_FIXED_ENUM; 2021 2022 2023 /** 2024 * The `enum MHD_RequestTerminationCode` specifies reasons 2025 * why a request has been terminated (or completed). 2026 * @ingroup request 2027 */ 2028 enum MHD_RequestTerminationCode 2029 { 2030 2031 /** 2032 * We finished sending the response. 2033 * @ingroup request 2034 */ 2035 MHD_REQUEST_TERMINATED_COMPLETED_OK = 0, 2036 2037 /** 2038 * Error handling the connection (resources 2039 * exhausted, application error accepting request, 2040 * decrypt error (for HTTPS), connection died when 2041 * sending the response etc.) 2042 * @ingroup request 2043 */ 2044 MHD_REQUEST_TERMINATED_WITH_ERROR = 1, 2045 2046 /** 2047 * No activity on the connection for the number 2048 * of seconds specified using 2049 * #MHD_OPTION_CONNECTION_TIMEOUT. 2050 * @ingroup request 2051 */ 2052 MHD_REQUEST_TERMINATED_TIMEOUT_REACHED = 2, 2053 2054 /** 2055 * We had to close the session since MHD was being 2056 * shut down. 2057 * @ingroup request 2058 */ 2059 MHD_REQUEST_TERMINATED_DAEMON_SHUTDOWN = 3, 2060 2061 /** 2062 * We tried to read additional data, but the connection became broken or 2063 * the other side hard closed the connection. 2064 * This error is similar to #MHD_REQUEST_TERMINATED_WITH_ERROR, but 2065 * specific to the case where the connection died before request completely 2066 * received. 2067 * @ingroup request 2068 */ 2069 MHD_REQUEST_TERMINATED_READ_ERROR = 4, 2070 2071 /** 2072 * The client terminated the connection by closing the socket 2073 * for writing (TCP half-closed) while still sending request. 2074 * @ingroup request 2075 */ 2076 MHD_REQUEST_TERMINATED_CLIENT_ABORT = 5 2077 2078 } _MHD_FIXED_ENUM; 2079 2080 2081 /** 2082 * The `enum MHD_ConnectionNotificationCode` specifies types 2083 * of connection notifications. 2084 * @ingroup request 2085 */ 2086 enum MHD_ConnectionNotificationCode 2087 { 2088 2089 /** 2090 * A new connection has been started. 2091 * @ingroup request 2092 */ 2093 MHD_CONNECTION_NOTIFY_STARTED = 0, 2094 2095 /** 2096 * A connection is closed. 2097 * @ingroup request 2098 */ 2099 MHD_CONNECTION_NOTIFY_CLOSED = 1 2100 2101 } _MHD_FIXED_ENUM; 2102 2103 2104 /** 2105 * Information about a connection. 2106 */ 2107 union MHD_ConnectionInfo 2108 { 2109 2110 /** 2111 * Cipher algorithm used, of type "enum gnutls_cipher_algorithm". 2112 */ 2113 int /* enum gnutls_cipher_algorithm */ cipher_algorithm; 2114 2115 /** 2116 * Protocol used, of type "enum gnutls_protocol". 2117 */ 2118 int /* enum gnutls_protocol */ protocol; 2119 2120 /** 2121 * The suspended status of a connection. 2122 */ 2123 int /* MHD_YES or MHD_NO */ suspended; 2124 2125 /** 2126 * Amount of second that connection could spend in idle state 2127 * before automatically disconnected. 2128 * Zero for no timeout (unlimited idle time). 2129 */ 2130 unsigned int connection_timeout; 2131 2132 /** 2133 * HTTP status queued with the response, for #MHD_CONNECTION_INFO_HTTP_STATUS. 2134 */ 2135 unsigned int http_status; 2136 2137 /** 2138 * Connect socket 2139 */ 2140 MHD_socket connect_fd; 2141 2142 /** 2143 * Size of the client's HTTP header. 2144 */ 2145 size_t header_size; 2146 2147 /** 2148 * GNUtls session handle, of type "gnutls_session_t". 2149 */ 2150 void * /* gnutls_session_t */ tls_session; 2151 2152 /** 2153 * GNUtls client certificate handle, of type "gnutls_x509_crt_t". 2154 */ 2155 void * /* gnutls_x509_crt_t */ client_cert; 2156 2157 /** 2158 * Address information for the client. 2159 */ 2160 struct sockaddr *client_addr; 2161 2162 /** 2163 * Which daemon manages this connection (useful in case there are many 2164 * daemons running). 2165 */ 2166 struct MHD_Daemon *daemon; 2167 2168 /** 2169 * Socket-specific client context. Points to the same address as 2170 * the "socket_context" of the #MHD_NotifyConnectionCallback. 2171 */ 2172 void *socket_context; 2173 }; 2174 2175 2176 /** 2177 * I/O vector type. Provided for use with #MHD_create_response_from_iovec(). 2178 * @note Available since #MHD_VERSION 0x00097204 2179 */ 2180 struct MHD_IoVec 2181 { 2182 /** 2183 * The pointer to the memory region for I/O. 2184 */ 2185 const void *iov_base; 2186 2187 /** 2188 * The size in bytes of the memory region for I/O. 2189 */ 2190 size_t iov_len; 2191 }; 2192 2193 2194 /** 2195 * Values of this enum are used to specify what 2196 * information about a connection is desired. 2197 * @ingroup request 2198 */ 2199 enum MHD_ConnectionInfoType 2200 { 2201 /** 2202 * What cipher algorithm is being used. 2203 * Takes no extra arguments. 2204 * @ingroup request 2205 */ 2206 MHD_CONNECTION_INFO_CIPHER_ALGO, 2207 2208 /** 2209 * 2210 * Takes no extra arguments. 2211 * @ingroup request 2212 */ 2213 MHD_CONNECTION_INFO_PROTOCOL, 2214 2215 /** 2216 * Obtain IP address of the client. Takes no extra arguments. 2217 * Returns essentially a `struct sockaddr **` (since the API returns 2218 * a `union MHD_ConnectionInfo *` and that union contains a `struct 2219 * sockaddr *`). 2220 * @ingroup request 2221 */ 2222 MHD_CONNECTION_INFO_CLIENT_ADDRESS, 2223 2224 /** 2225 * Get the gnuTLS session handle. 2226 * @ingroup request 2227 */ 2228 MHD_CONNECTION_INFO_GNUTLS_SESSION, 2229 2230 /** 2231 * Get the gnuTLS client certificate handle. Dysfunctional (never 2232 * implemented, deprecated). Use #MHD_CONNECTION_INFO_GNUTLS_SESSION 2233 * to get the `gnutls_session_t` and then call 2234 * gnutls_certificate_get_peers(). 2235 */ 2236 MHD_CONNECTION_INFO_GNUTLS_CLIENT_CERT, 2237 2238 /** 2239 * Get the `struct MHD_Daemon *` responsible for managing this connection. 2240 * @ingroup request 2241 */ 2242 MHD_CONNECTION_INFO_DAEMON, 2243 2244 /** 2245 * Request the file descriptor for the connection socket. 2246 * MHD sockets are always in non-blocking mode. 2247 * No extra arguments should be passed. 2248 * @ingroup request 2249 */ 2250 MHD_CONNECTION_INFO_CONNECTION_FD, 2251 2252 /** 2253 * Returns the client-specific pointer to a `void *` that was (possibly) 2254 * set during a #MHD_NotifyConnectionCallback when the socket was 2255 * first accepted. Note that this is NOT the same as the "con_cls" 2256 * argument of the #MHD_AccessHandlerCallback. The "con_cls" is 2257 * fresh for each HTTP request, while the "socket_context" is fresh 2258 * for each socket. 2259 */ 2260 MHD_CONNECTION_INFO_SOCKET_CONTEXT, 2261 2262 /** 2263 * Check whether the connection is suspended. 2264 * @ingroup request 2265 */ 2266 MHD_CONNECTION_INFO_CONNECTION_SUSPENDED, 2267 2268 /** 2269 * Get connection timeout 2270 * @ingroup request 2271 */ 2272 MHD_CONNECTION_INFO_CONNECTION_TIMEOUT, 2273 2274 /** 2275 * Return length of the client's HTTP request header. 2276 * @ingroup request 2277 */ 2278 MHD_CONNECTION_INFO_REQUEST_HEADER_SIZE, 2279 2280 /** 2281 * Return HTTP status queued with the response. NULL 2282 * if no HTTP response has been queued yet. 2283 */ 2284 MHD_CONNECTION_INFO_HTTP_STATUS 2285 2286 } _MHD_FIXED_ENUM; 2287 2288 2289 /** 2290 * Values of this enum are used to specify what 2291 * information about a daemon is desired. 2292 */ 2293 enum MHD_DaemonInfoType 2294 { 2295 /** 2296 * No longer supported (will return NULL). 2297 */ 2298 MHD_DAEMON_INFO_KEY_SIZE, 2299 2300 /** 2301 * No longer supported (will return NULL). 2302 */ 2303 MHD_DAEMON_INFO_MAC_KEY_SIZE, 2304 2305 /** 2306 * Request the file descriptor for the listening socket. 2307 * No extra arguments should be passed. 2308 */ 2309 MHD_DAEMON_INFO_LISTEN_FD, 2310 2311 /** 2312 * Request the file descriptor for the "external" sockets polling 2313 * when 'epoll' mode is used. 2314 * No extra arguments should be passed. 2315 * 2316 * Waiting on epoll FD must not block longer than value 2317 * returned by #MHD_get_timeout() otherwise connections 2318 * will "hung" with unprocessed data in network buffers 2319 * and timed-out connections will not be closed. 2320 * 2321 * @sa #MHD_get_timeout(), #MHD_run() 2322 */ 2323 MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY, 2324 MHD_DAEMON_INFO_EPOLL_FD = MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY, 2325 2326 /** 2327 * Request the number of current connections handled by the daemon. 2328 * No extra arguments should be passed. 2329 * Note: when using MHD in "external" polling mode, this type of request 2330 * could be used only when #MHD_run()/#MHD_run_from_select is not 2331 * working in other thread at the same time. 2332 */ 2333 MHD_DAEMON_INFO_CURRENT_CONNECTIONS, 2334 2335 /** 2336 * Request the daemon flags. 2337 * No extra arguments should be passed. 2338 * Note: flags may differ from original 'flags' specified for 2339 * daemon, especially if #MHD_USE_AUTO was set. 2340 */ 2341 MHD_DAEMON_INFO_FLAGS, 2342 2343 /** 2344 * Request the port number of daemon's listen socket. 2345 * No extra arguments should be passed. 2346 * Note: if port '0' was specified for #MHD_start_daemon(), returned 2347 * value will be real port number. 2348 */ 2349 MHD_DAEMON_INFO_BIND_PORT 2350 } _MHD_FIXED_ENUM; 2351 2352 2353 /** 2354 * Callback for serious error condition. The default action is to print 2355 * an error message and `abort()`. 2356 * 2357 * @param cls user specified value 2358 * @param file where the error occurred 2359 * @param line where the error occurred 2360 * @param reason error detail, may be NULL 2361 * @ingroup logging 2362 */ 2363 typedef void 2364 (*MHD_PanicCallback) (void *cls, 2365 const char *file, 2366 unsigned int line, 2367 const char *reason); 2368 2369 /** 2370 * Allow or deny a client to connect. 2371 * 2372 * @param cls closure 2373 * @param addr address information from the client 2374 * @param addrlen length of @a addr 2375 * @return #MHD_YES if connection is allowed, #MHD_NO if not 2376 */ 2377 typedef enum MHD_Result 2378 (*MHD_AcceptPolicyCallback)(void *cls, 2379 const struct sockaddr *addr, 2380 socklen_t addrlen); 2381 2382 2383 /** 2384 * A client has requested the given @a url using the given @a method 2385 * (#MHD_HTTP_METHOD_GET, #MHD_HTTP_METHOD_PUT, #MHD_HTTP_METHOD_DELETE, 2386 * #MHD_HTTP_METHOD_POST, etc). 2387 * 2388 * The callback must call MHD function MHD_queue_response() to provide content 2389 * to give back to the client and return an HTTP status code (i.e. 2390 * #MHD_HTTP_OK, #MHD_HTTP_NOT_FOUND, etc.). The response can be created 2391 * in this callback or prepared in advance. 2392 * Alternatively, callback may call MHD_suspend_connection() to temporarily 2393 * suspend data processing for this connection. 2394 * 2395 * As soon as response is provided this callback will not be called anymore 2396 * for the current request. 2397 * 2398 * For each HTTP request this callback is called several times: 2399 * * after request headers are fully received and decoded, 2400 * * for each received part of request body (optional, if request has body), 2401 * * when request is fully received. 2402 * 2403 * If response is provided before request is fully received, the rest 2404 * of the request is discarded and connection is automatically closed 2405 * after sending response. 2406 * 2407 * If the request is fully received, but response hasn't been provided and 2408 * connection is not suspended, the callback can be called again immediately. 2409 * 2410 * The response cannot be queued when this callback is called to process 2411 * the client upload data (when @a upload_data is not NULL). 2412 * 2413 * @param cls argument given together with the function 2414 * pointer when the handler was registered with MHD 2415 * @param url the requested url 2416 * @param method the HTTP method used (#MHD_HTTP_METHOD_GET, 2417 * #MHD_HTTP_METHOD_PUT, etc.) 2418 * @param version the HTTP version string (i.e. 2419 * #MHD_HTTP_VERSION_1_1) 2420 * @param upload_data the data being uploaded (excluding HEADERS, 2421 * for a POST that fits into memory and that is encoded 2422 * with a supported encoding, the POST data will NOT be 2423 * given in upload_data and is instead available as 2424 * part of #MHD_get_connection_values; very large POST 2425 * data *will* be made available incrementally in 2426 * @a upload_data) 2427 * @param[in,out] upload_data_size set initially to the size of the 2428 * @a upload_data provided; the method must update this 2429 * value to the number of bytes NOT processed; 2430 * @param[in,out] con_cls pointer that the callback can set to some 2431 * address and that will be preserved by MHD for future 2432 * calls for this request; since the access handler may 2433 * be called many times (i.e., for a PUT/POST operation 2434 * with plenty of upload data) this allows the application 2435 * to easily associate some request-specific state. 2436 * If necessary, this state can be cleaned up in the 2437 * global #MHD_RequestCompletedCallback (which 2438 * can be set with the #MHD_OPTION_NOTIFY_COMPLETED). 2439 * Initially, `*con_cls` will be NULL. 2440 * @return #MHD_YES if the connection was handled successfully, 2441 * #MHD_NO if the socket must be closed due to a serious 2442 * error while handling the request 2443 * 2444 * @sa #MHD_queue_response() 2445 */ 2446 typedef enum MHD_Result 2447 (*MHD_AccessHandlerCallback)(void *cls, 2448 struct MHD_Connection *connection, 2449 const char *url, 2450 const char *method, 2451 const char *version, 2452 const char *upload_data, 2453 size_t *upload_data_size, 2454 void **con_cls); 2455 2456 2457 /** 2458 * Signature of the callback used by MHD to notify the 2459 * application about completed requests. 2460 * 2461 * @param cls client-defined closure 2462 * @param connection connection handle 2463 * @param con_cls value as set by the last call to 2464 * the #MHD_AccessHandlerCallback 2465 * @param toe reason for request termination 2466 * @see #MHD_OPTION_NOTIFY_COMPLETED 2467 * @ingroup request 2468 */ 2469 typedef void 2470 (*MHD_RequestCompletedCallback) (void *cls, 2471 struct MHD_Connection *connection, 2472 void **con_cls, 2473 enum MHD_RequestTerminationCode toe); 2474 2475 2476 /** 2477 * Signature of the callback used by MHD to notify the 2478 * application about started/stopped connections 2479 * 2480 * @param cls client-defined closure 2481 * @param connection connection handle 2482 * @param socket_context socket-specific pointer where the 2483 * client can associate some state specific 2484 * to the TCP connection; note that this is 2485 * different from the "con_cls" which is per 2486 * HTTP request. The client can initialize 2487 * during #MHD_CONNECTION_NOTIFY_STARTED and 2488 * cleanup during #MHD_CONNECTION_NOTIFY_CLOSED 2489 * and access in the meantime using 2490 * #MHD_CONNECTION_INFO_SOCKET_CONTEXT. 2491 * @param toe reason for connection notification 2492 * @see #MHD_OPTION_NOTIFY_CONNECTION 2493 * @ingroup request 2494 */ 2495 typedef void 2496 (*MHD_NotifyConnectionCallback) (void *cls, 2497 struct MHD_Connection *connection, 2498 void **socket_context, 2499 enum MHD_ConnectionNotificationCode toe); 2500 2501 2502 /** 2503 * Iterator over key-value pairs. This iterator 2504 * can be used to iterate over all of the cookies, 2505 * headers, or POST-data fields of a request, and 2506 * also to iterate over the headers that have been 2507 * added to a response. 2508 * 2509 * @param cls closure 2510 * @param kind kind of the header we are looking at 2511 * @param key key for the value, can be an empty string 2512 * @param value corresponding value, can be NULL 2513 * @return #MHD_YES to continue iterating, 2514 * #MHD_NO to abort the iteration 2515 * @ingroup request 2516 */ 2517 typedef enum MHD_Result 2518 (*MHD_KeyValueIterator)(void *cls, 2519 enum MHD_ValueKind kind, 2520 const char *key, 2521 const char *value); 2522 2523 2524 /** 2525 * Iterator over key-value pairs with size parameters. 2526 * This iterator can be used to iterate over all of 2527 * the cookies, headers, or POST-data fields of a 2528 * request, and also to iterate over the headers that 2529 * have been added to a response. 2530 * @note Available since #MHD_VERSION 0x00096303 2531 * 2532 * @param cls closure 2533 * @param kind kind of the header we are looking at 2534 * @param key key for the value, can be an empty string 2535 * @param value corresponding value, can be NULL 2536 * @param value_size number of bytes in @a value; 2537 * for C-strings, the length excludes the 0-terminator 2538 * @return #MHD_YES to continue iterating, 2539 * #MHD_NO to abort the iteration 2540 * @ingroup request 2541 */ 2542 typedef enum MHD_Result 2543 (*MHD_KeyValueIteratorN)(void *cls, 2544 enum MHD_ValueKind kind, 2545 const char *key, 2546 size_t key_size, 2547 const char *value, 2548 size_t value_size); 2549 2550 2551 /** 2552 * Callback used by libmicrohttpd in order to obtain content. 2553 * 2554 * The callback is to copy at most @a max bytes of content into @a buf. 2555 * The total number of bytes that has been placed into @a buf should be 2556 * returned. 2557 * 2558 * Note that returning zero will cause libmicrohttpd to try again. 2559 * Thus, returning zero should only be used in conjunction 2560 * with MHD_suspend_connection() to avoid busy waiting. 2561 * 2562 * @param cls extra argument to the callback 2563 * @param pos position in the datastream to access; 2564 * note that if a `struct MHD_Response` object is re-used, 2565 * it is possible for the same content reader to 2566 * be queried multiple times for the same data; 2567 * however, if a `struct MHD_Response` is not re-used, 2568 * libmicrohttpd guarantees that "pos" will be 2569 * the sum of all non-negative return values 2570 * obtained from the content reader so far. 2571 * @param buf where to copy the data 2572 * @param max maximum number of bytes to copy to @a buf (size of @a buf) 2573 * @return number of bytes written to @a buf; 2574 * 0 is legal unless MHD is started in "internal" sockets polling mode 2575 * (since this would cause busy-waiting); 0 in "external" sockets 2576 * polling mode will cause this function to be called again once 2577 * any MHD_run*() function is called; 2578 * #MHD_CONTENT_READER_END_OF_STREAM (-1) for the regular 2579 * end of transmission (with chunked encoding, MHD will then 2580 * terminate the chunk and send any HTTP footers that might be 2581 * present; without chunked encoding and given an unknown 2582 * response size, MHD will simply close the connection; note 2583 * that while returning #MHD_CONTENT_READER_END_OF_STREAM is not technically 2584 * legal if a response size was specified, MHD accepts this 2585 * and treats it just as #MHD_CONTENT_READER_END_WITH_ERROR; 2586 * #MHD_CONTENT_READER_END_WITH_ERROR (-2) to indicate a server 2587 * error generating the response; this will cause MHD to simply 2588 * close the connection immediately. If a response size was 2589 * given or if chunked encoding is in use, this will indicate 2590 * an error to the client. Note, however, that if the client 2591 * does not know a response size and chunked encoding is not in 2592 * use, then clients will not be able to tell the difference between 2593 * #MHD_CONTENT_READER_END_WITH_ERROR and #MHD_CONTENT_READER_END_OF_STREAM. 2594 * This is not a limitation of MHD but rather of the HTTP protocol. 2595 */ 2596 typedef ssize_t 2597 (*MHD_ContentReaderCallback) (void *cls, 2598 uint64_t pos, 2599 char *buf, 2600 size_t max); 2601 2602 2603 /** 2604 * This method is called by libmicrohttpd if we 2605 * are done with a content reader. It should 2606 * be used to free resources associated with the 2607 * content reader. 2608 * 2609 * @param cls closure 2610 * @ingroup response 2611 */ 2612 typedef void 2613 (*MHD_ContentReaderFreeCallback) (void *cls); 2614 2615 2616 /** 2617 * Iterator over key-value pairs where the value 2618 * may be made available in increments and/or may 2619 * not be zero-terminated. Used for processing 2620 * POST data. 2621 * 2622 * @param cls user-specified closure 2623 * @param kind type of the value, always #MHD_POSTDATA_KIND when called from MHD 2624 * @param key 0-terminated key for the value 2625 * @param filename name of the uploaded file, NULL if not known 2626 * @param content_type mime-type of the data, NULL if not known 2627 * @param transfer_encoding encoding of the data, NULL if not known 2628 * @param data pointer to @a size bytes of data at the 2629 * specified offset 2630 * @param off offset of data in the overall value 2631 * @param size number of bytes in @a data available 2632 * @return #MHD_YES to continue iterating, 2633 * #MHD_NO to abort the iteration 2634 */ 2635 typedef enum MHD_Result 2636 (*MHD_PostDataIterator)(void *cls, 2637 enum MHD_ValueKind kind, 2638 const char *key, 2639 const char *filename, 2640 const char *content_type, 2641 const char *transfer_encoding, 2642 const char *data, 2643 uint64_t off, 2644 size_t size); 2645 2646 /* **************** Daemon handling functions ***************** */ 2647 2648 /** 2649 * Start a webserver on the given port. 2650 * 2651 * @param flags combination of `enum MHD_FLAG` values 2652 * @param port port to bind to (in host byte order), 2653 * use '0' to bind to random free port, 2654 * ignored if MHD_OPTION_SOCK_ADDR or 2655 * MHD_OPTION_LISTEN_SOCKET is provided 2656 * or MHD_USE_NO_LISTEN_SOCKET is specified 2657 * @param apc callback to call to check which clients 2658 * will be allowed to connect; you can pass NULL 2659 * in which case connections from any IP will be 2660 * accepted 2661 * @param apc_cls extra argument to apc 2662 * @param dh handler called for all requests (repeatedly) 2663 * @param dh_cls extra argument to @a dh 2664 * @param ap list of options (type-value pairs, 2665 * terminated with #MHD_OPTION_END). 2666 * @return NULL on error, handle to daemon on success 2667 * @ingroup event 2668 */ 2669 _MHD_EXTERN struct MHD_Daemon * 2670 MHD_start_daemon_va (unsigned int flags, 2671 uint16_t port, 2672 MHD_AcceptPolicyCallback apc, void *apc_cls, 2673 MHD_AccessHandlerCallback dh, void *dh_cls, 2674 va_list ap); 2675 2676 2677 /** 2678 * Start a webserver on the given port. Variadic version of 2679 * #MHD_start_daemon_va. 2680 * 2681 * @param flags combination of `enum MHD_FLAG` values 2682 * @param port port to bind to (in host byte order), 2683 * use '0' to bind to random free port, 2684 * ignored if MHD_OPTION_SOCK_ADDR or 2685 * MHD_OPTION_LISTEN_SOCKET is provided 2686 * or MHD_USE_NO_LISTEN_SOCKET is specified 2687 * @param apc callback to call to check which clients 2688 * will be allowed to connect; you can pass NULL 2689 * in which case connections from any IP will be 2690 * accepted 2691 * @param apc_cls extra argument to apc 2692 * @param dh handler called for all requests (repeatedly) 2693 * @param dh_cls extra argument to @a dh 2694 * @return NULL on error, handle to daemon on success 2695 * @ingroup event 2696 */ 2697 _MHD_EXTERN struct MHD_Daemon * 2698 MHD_start_daemon (unsigned int flags, 2699 uint16_t port, 2700 MHD_AcceptPolicyCallback apc, void *apc_cls, 2701 MHD_AccessHandlerCallback dh, void *dh_cls, 2702 ...); 2703 2704 2705 /** 2706 * Stop accepting connections from the listening socket. Allows 2707 * clients to continue processing, but stops accepting new 2708 * connections. Note that the caller is responsible for closing the 2709 * returned socket; however, if MHD is run using threads (anything but 2710 * "external" sockets polling mode), it must not be closed until AFTER 2711 * #MHD_stop_daemon has been called (as it is theoretically possible 2712 * that an existing thread is still using it). 2713 * 2714 * Note that some thread modes require the caller to have passed 2715 * #MHD_USE_ITC when using this API. If this daemon is 2716 * in one of those modes and this option was not given to 2717 * #MHD_start_daemon, this function will return #MHD_INVALID_SOCKET. 2718 * 2719 * @param daemon daemon to stop accepting new connections for 2720 * @return old listen socket on success, #MHD_INVALID_SOCKET if 2721 * the daemon was already not listening anymore 2722 * @ingroup specialized 2723 */ 2724 _MHD_EXTERN MHD_socket 2725 MHD_quiesce_daemon (struct MHD_Daemon *daemon); 2726 2727 2728 /** 2729 * Shutdown an HTTP daemon. 2730 * 2731 * @param daemon daemon to stop 2732 * @ingroup event 2733 */ 2734 _MHD_EXTERN void 2735 MHD_stop_daemon (struct MHD_Daemon *daemon); 2736 2737 2738 /** 2739 * Add another client connection to the set of connections managed by 2740 * MHD. This API is usually not needed (since MHD will accept inbound 2741 * connections on the server socket). Use this API in special cases, 2742 * for example if your HTTP server is behind NAT and needs to connect 2743 * out to the HTTP client, or if you are building a proxy. 2744 * 2745 * If you use this API in conjunction with an "internal" socket polling, 2746 * you must set the option #MHD_USE_ITC to ensure that the freshly added 2747 * connection is immediately processed by MHD. 2748 * 2749 * The given client socket will be managed (and closed!) by MHD after 2750 * this call and must no longer be used directly by the application 2751 * afterwards. 2752 * 2753 * @param daemon daemon that manages the connection 2754 * @param client_socket socket to manage (MHD will expect 2755 * to receive an HTTP request from this socket next). 2756 * @param addr IP address of the client 2757 * @param addrlen number of bytes in @a addr 2758 * @return #MHD_YES on success, #MHD_NO if this daemon could 2759 * not handle the connection (i.e. `malloc()` failed, etc). 2760 * The socket will be closed in any case; `errno` is 2761 * set to indicate further details about the error. 2762 * @ingroup specialized 2763 */ 2764 _MHD_EXTERN enum MHD_Result 2765 MHD_add_connection (struct MHD_Daemon *daemon, 2766 MHD_socket client_socket, 2767 const struct sockaddr *addr, 2768 socklen_t addrlen); 2769 2770 2771 /** 2772 * Obtain the `select()` sets for this daemon. 2773 * Daemon's FDs will be added to fd_sets. To get only 2774 * daemon FDs in fd_sets, call FD_ZERO for each fd_set 2775 * before calling this function. FD_SETSIZE is assumed 2776 * to be platform's default. 2777 * 2778 * This function should be called only when MHD is configured to 2779 * use "external" sockets polling with 'select()' or with 'epoll'. 2780 * In the latter case, it will only add the single 'epoll' file 2781 * descriptor used by MHD to the sets. 2782 * It's necessary to use #MHD_get_timeout() to get maximum timeout 2783 * value for `select()`. Usage of `select()` with indefinite timeout 2784 * (or timeout larger than returned by #MHD_get_timeout()) will 2785 * violate MHD API and may results in pending unprocessed data. 2786 * 2787 * This function must be called only for daemon started 2788 * without #MHD_USE_INTERNAL_POLLING_THREAD flag. 2789 * 2790 * @param daemon daemon to get sets from 2791 * @param read_fd_set read set 2792 * @param write_fd_set write set 2793 * @param except_fd_set except set 2794 * @param max_fd increased to largest FD added (if larger 2795 * than existing value); can be NULL 2796 * @return #MHD_YES on success, #MHD_NO if this 2797 * daemon was not started with the right 2798 * options for this call or any FD didn't 2799 * fit fd_set. 2800 * @ingroup event 2801 */ 2802 _MHD_EXTERN enum MHD_Result 2803 MHD_get_fdset (struct MHD_Daemon *daemon, 2804 fd_set *read_fd_set, 2805 fd_set *write_fd_set, 2806 fd_set *except_fd_set, 2807 MHD_socket *max_fd); 2808 2809 2810 /** 2811 * Obtain the `select()` sets for this daemon. 2812 * Daemon's FDs will be added to fd_sets. To get only 2813 * daemon FDs in fd_sets, call FD_ZERO for each fd_set 2814 * before calling this function. 2815 * 2816 * Passing custom FD_SETSIZE as @a fd_setsize allow usage of 2817 * larger/smaller than platform's default fd_sets. 2818 * 2819 * This function should be called only when MHD is configured to 2820 * use "external" sockets polling with 'select()' or with 'epoll'. 2821 * In the latter case, it will only add the single 'epoll' file 2822 * descriptor used by MHD to the sets. 2823 * It's necessary to use #MHD_get_timeout() to get maximum timeout 2824 * value for `select()`. Usage of `select()` with indefinite timeout 2825 * (or timeout larger than returned by #MHD_get_timeout()) will 2826 * violate MHD API and may results in pending unprocessed data. 2827 * 2828 * This function must be called only for daemon started 2829 * without #MHD_USE_INTERNAL_POLLING_THREAD flag. 2830 * 2831 * @param daemon daemon to get sets from 2832 * @param read_fd_set read set 2833 * @param write_fd_set write set 2834 * @param except_fd_set except set 2835 * @param max_fd increased to largest FD added (if larger 2836 * than existing value); can be NULL 2837 * @param fd_setsize value of FD_SETSIZE 2838 * @return #MHD_YES on success, #MHD_NO if this 2839 * daemon was not started with the right 2840 * options for this call or any FD didn't 2841 * fit fd_set. 2842 * @ingroup event 2843 */ 2844 _MHD_EXTERN enum MHD_Result 2845 MHD_get_fdset2 (struct MHD_Daemon *daemon, 2846 fd_set *read_fd_set, 2847 fd_set *write_fd_set, 2848 fd_set *except_fd_set, 2849 MHD_socket *max_fd, 2850 unsigned int fd_setsize); 2851 2852 2853 /** 2854 * Obtain the `select()` sets for this daemon. 2855 * Daemon's FDs will be added to fd_sets. To get only 2856 * daemon FDs in fd_sets, call FD_ZERO for each fd_set 2857 * before calling this function. Size of fd_set is 2858 * determined by current value of FD_SETSIZE. 2859 * 2860 * This function should be called only when MHD is configured to 2861 * use "external" sockets polling with 'select()' or with 'epoll'. 2862 * In the latter case, it will only add the single 'epoll' file 2863 * descriptor used by MHD to the sets. 2864 * It's necessary to use #MHD_get_timeout() to get maximum timeout 2865 * value for `select()`. Usage of `select()` with indefinite timeout 2866 * (or timeout larger than returned by #MHD_get_timeout()) will 2867 * violate MHD API and may results in pending unprocessed data. 2868 * 2869 * This function must be called only for daemon started 2870 * without #MHD_USE_INTERNAL_POLLING_THREAD flag. 2871 * 2872 * @param daemon daemon to get sets from 2873 * @param read_fd_set read set 2874 * @param write_fd_set write set 2875 * @param except_fd_set except set 2876 * @param max_fd increased to largest FD added (if larger 2877 * than existing value); can be NULL 2878 * @return #MHD_YES on success, #MHD_NO if this 2879 * daemon was not started with the right 2880 * options for this call or any FD didn't 2881 * fit fd_set. 2882 * @ingroup event 2883 */ 2884 #define MHD_get_fdset(daemon,read_fd_set,write_fd_set,except_fd_set,max_fd) \ 2885 MHD_get_fdset2 ((daemon),(read_fd_set),(write_fd_set),(except_fd_set), \ 2886 (max_fd),FD_SETSIZE) 2887 2888 2889 /** 2890 * Obtain timeout value for polling function for this daemon. 2891 * 2892 * This function set value to the amount of milliseconds for which polling 2893 * function (`select()`, `poll()` or epoll) should at most block, not the 2894 * timeout value set for connections. 2895 * 2896 * Any "external" sockets polling function must be called with the timeout 2897 * value provided by this function. Smaller timeout values can be used for 2898 * polling function if it is required for any reason, but using larger 2899 * timeout value or no timeout (indefinite timeout) when this function 2900 * return #MHD_YES will break MHD processing logic and result in "hung" 2901 * connections with data pending in network buffers and other problems. 2902 * 2903 * It is important to always use this function when "external" polling is 2904 * used. If this function returns #MHD_YES then #MHD_run() (or 2905 * #MHD_run_from_select()) must be called right after return from polling 2906 * function, regardless of the states of MHD fds. 2907 * 2908 * In practice, if #MHD_YES is returned then #MHD_run() (or 2909 * #MHD_run_from_select()) must be called not later than @a timeout 2910 * millisecond even if not activity is detected on sockets by 2911 * sockets polling function. 2912 * 2913 * @param daemon daemon to query for timeout 2914 * @param timeout set to the timeout (in milliseconds) 2915 * @return #MHD_YES on success, #MHD_NO if timeouts are 2916 * not used and no data processing is pending. 2917 * @ingroup event 2918 */ 2919 _MHD_EXTERN enum MHD_Result 2920 MHD_get_timeout (struct MHD_Daemon *daemon, 2921 MHD_UNSIGNED_LONG_LONG *timeout); 2922 2923 2924 /** 2925 * Run webserver operations (without blocking unless in client callbacks). 2926 * 2927 * This method should be called by clients in combination with 2928 * #MHD_get_fdset() (or #MHD_get_daemon_info() with MHD_DAEMON_INFO_EPOLL_FD 2929 * if epoll is used) and #MHD_get_timeout() if the client-controlled 2930 * connection polling method is used (i.e. daemon was started without 2931 * #MHD_USE_INTERNAL_POLLING_THREAD flag). 2932 * 2933 * This function is a convenience method, which is useful if the 2934 * fd_sets from #MHD_get_fdset were not directly passed to `select()`; 2935 * with this function, MHD will internally do the appropriate `select()` 2936 * call itself again. While it is acceptable to call #MHD_run (if 2937 * #MHD_USE_INTERNAL_POLLING_THREAD is not set) at any moment, you should 2938 * call #MHD_run_from_select() if performance is important (as it saves an 2939 * expensive call to `select()`). 2940 * 2941 * If #MHD_get_timeout() returned #MHD_YES, than this function must be called 2942 * right after polling function returns regardless of detected activity on 2943 * the daemon's FDs. 2944 * 2945 * @param daemon daemon to run 2946 * @return #MHD_YES on success, #MHD_NO if this 2947 * daemon was not started with the right 2948 * options for this call. 2949 * @ingroup event 2950 */ 2951 _MHD_EXTERN enum MHD_Result 2952 MHD_run (struct MHD_Daemon *daemon); 2953 2954 2955 /** 2956 * Run websever operation with possible blocking. 2957 * 2958 * This function does the following: waits for any network event not more than 2959 * specified number of milliseconds, processes all incoming and outgoing data, 2960 * processes new connections, processes any timed-out connection, and does 2961 * other things required to run webserver. 2962 * Once all connections are processed, function returns. 2963 * 2964 * This function is useful for quick and simple (lazy) webserver implementation 2965 * if application needs to run a single thread only and does not have any other 2966 * network activity. 2967 * 2968 * This function calls MHD_get_timeout() internally and use returned value as 2969 * maximum wait time if it less than value of @a millisec parameter. 2970 * 2971 * It is expected that the "external" socket polling function is not used in 2972 * conjunction with this function unless the @a millisec is set to zero. 2973 * 2974 * @param daemon the daemon to run 2975 * @param millisec the maximum time in milliseconds to wait for network and 2976 * other events. Note: there is no guarantee that function 2977 * blocks for the specified amount of time. The real processing 2978 * time can be shorter (if some data or connection timeout 2979 * comes earlier) or longer (if data processing requires more 2980 * time, especially in user callbacks). 2981 * If set to '0' then function does not block and processes 2982 * only already available data (if any). 2983 * If set to '-1' then function waits for events 2984 * indefinitely (blocks until next network activity or 2985 * connection timeout). 2986 * @return #MHD_YES on success, #MHD_NO if this 2987 * daemon was not started with the right 2988 * options for this call or some serious 2989 * unrecoverable error occurs. 2990 * @note Available since #MHD_VERSION 0x00097206 2991 * @ingroup event 2992 */ 2993 _MHD_EXTERN enum MHD_Result 2994 MHD_run_wait (struct MHD_Daemon *daemon, 2995 int32_t millisec); 2996 2997 2998 /** 2999 * Run webserver operations. This method should be called by clients 3000 * in combination with #MHD_get_fdset and #MHD_get_timeout() if the 3001 * client-controlled select method is used. 3002 * 3003 * You can use this function instead of #MHD_run if you called 3004 * `select()` on the result from #MHD_get_fdset. File descriptors in 3005 * the sets that are not controlled by MHD will be ignored. Calling 3006 * this function instead of #MHD_run is more efficient as MHD will 3007 * not have to call `select()` again to determine which operations are 3008 * ready. 3009 * 3010 * If #MHD_get_timeout() returned #MHD_YES, than this function must be 3011 * called right after `select()` returns regardless of detected activity 3012 * on the daemon's FDs. 3013 * 3014 * This function cannot be used with daemon started with 3015 * #MHD_USE_INTERNAL_POLLING_THREAD flag. 3016 * 3017 * @param daemon daemon to run select loop for 3018 * @param read_fd_set read set 3019 * @param write_fd_set write set 3020 * @param except_fd_set except set 3021 * @return #MHD_NO on serious errors, #MHD_YES on success 3022 * @ingroup event 3023 */ 3024 _MHD_EXTERN enum MHD_Result 3025 MHD_run_from_select (struct MHD_Daemon *daemon, 3026 const fd_set *read_fd_set, 3027 const fd_set *write_fd_set, 3028 const fd_set *except_fd_set); 3029 3030 3031 /* **************** Connection handling functions ***************** */ 3032 3033 /** 3034 * Get all of the headers from the request. 3035 * 3036 * @param connection connection to get values from 3037 * @param kind types of values to iterate over, can be a bitmask 3038 * @param iterator callback to call on each header; 3039 * may be NULL (then just count headers) 3040 * @param iterator_cls extra argument to @a iterator 3041 * @return number of entries iterated over, 3042 * -1 if connection is NULL. 3043 * @ingroup request 3044 */ 3045 _MHD_EXTERN int 3046 MHD_get_connection_values (struct MHD_Connection *connection, 3047 enum MHD_ValueKind kind, 3048 MHD_KeyValueIterator iterator, 3049 void *iterator_cls); 3050 3051 3052 /** 3053 * Get all of the headers from the request. 3054 * 3055 * @param connection connection to get values from 3056 * @param kind types of values to iterate over, can be a bitmask 3057 * @param iterator callback to call on each header; 3058 * may be NULL (then just count headers) 3059 * @param iterator_cls extra argument to @a iterator 3060 * @return number of entries iterated over, 3061 * -1 if connection is NULL. 3062 * @note Available since #MHD_VERSION 0x00096400 3063 * @ingroup request 3064 */ 3065 _MHD_EXTERN int 3066 MHD_get_connection_values_n (struct MHD_Connection *connection, 3067 enum MHD_ValueKind kind, 3068 MHD_KeyValueIteratorN iterator, 3069 void *iterator_cls); 3070 3071 3072 /** 3073 * This function can be used to add an entry to the HTTP headers of a 3074 * connection (so that the #MHD_get_connection_values function will 3075 * return them -- and the `struct MHD_PostProcessor` will also see 3076 * them). This maybe required in certain situations (see Mantis 3077 * #1399) where (broken) HTTP implementations fail to supply values 3078 3079 * needed by the post processor (or other parts of the application). 3080 * 3081 * This function MUST only be called from within the 3082 * #MHD_AccessHandlerCallback (otherwise, access maybe improperly 3083 * synchronized). Furthermore, the client must guarantee that the key 3084 * and value arguments are 0-terminated strings that are NOT freed 3085 * until the connection is closed. (The easiest way to do this is by 3086 * passing only arguments to permanently allocated strings.). 3087 * 3088 * @param connection the connection for which a 3089 * value should be set 3090 * @param kind kind of the value 3091 * @param key key for the value 3092 * @param value the value itself 3093 * @return #MHD_NO if the operation could not be 3094 * performed due to insufficient memory; 3095 * #MHD_YES on success 3096 * @ingroup request 3097 */ 3098 _MHD_EXTERN enum MHD_Result 3099 MHD_set_connection_value (struct MHD_Connection *connection, 3100 enum MHD_ValueKind kind, 3101 const char *key, 3102 const char *value); 3103 3104 3105 /** 3106 * This function can be used to add an arbitrary entry to connection. 3107 * This function could add entry with binary zero, which is allowed 3108 * for #MHD_GET_ARGUMENT_KIND. For other kind on entries it is 3109 * recommended to use #MHD_set_connection_value. 3110 * 3111 * This function MUST only be called from within the 3112 * #MHD_AccessHandlerCallback (otherwise, access maybe improperly 3113 * synchronized). Furthermore, the client must guarantee that the key 3114 * and value arguments are 0-terminated strings that are NOT freed 3115 * until the connection is closed. (The easiest way to do this is by 3116 * passing only arguments to permanently allocated strings.). 3117 * 3118 * @param connection the connection for which a 3119 * value should be set 3120 * @param kind kind of the value 3121 * @param key key for the value, must be zero-terminated 3122 * @param key_size number of bytes in @a key (excluding 0-terminator) 3123 * @param value the value itself, must be zero-terminated 3124 * @param value_size number of bytes in @a value (excluding 0-terminator) 3125 * @return #MHD_NO if the operation could not be 3126 * performed due to insufficient memory; 3127 * #MHD_YES on success 3128 * @note Available since #MHD_VERSION 0x00096400 3129 * @ingroup request 3130 */ 3131 _MHD_EXTERN enum MHD_Result 3132 MHD_set_connection_value_n (struct MHD_Connection *connection, 3133 enum MHD_ValueKind kind, 3134 const char *key, 3135 size_t key_size, 3136 const char *value, 3137 size_t value_size); 3138 3139 3140 /** 3141 * Sets the global error handler to a different implementation. @a cb 3142 * will only be called in the case of typically fatal, serious 3143 * internal consistency issues. These issues should only arise in the 3144 * case of serious memory corruption or similar problems with the 3145 * architecture. While @a cb is allowed to return and MHD will then 3146 * try to continue, this is never safe. 3147 * 3148 * The default implementation that is used if no panic function is set 3149 * simply prints an error message and calls `abort()`. Alternative 3150 * implementations might call `exit()` or other similar functions. 3151 * 3152 * @param cb new error handler 3153 * @param cls passed to @a cb 3154 * @ingroup logging 3155 */ 3156 _MHD_EXTERN void 3157 MHD_set_panic_func (MHD_PanicCallback cb, void *cls); 3158 3159 3160 /** 3161 * Process escape sequences ('%HH') Updates val in place; the 3162 * result should be UTF-8 encoded and cannot be larger than the input. 3163 * The result must also still be 0-terminated. 3164 * 3165 * @param val value to unescape (modified in the process) 3166 * @return length of the resulting val (`strlen(val)` may be 3167 * shorter afterwards due to elimination of escape sequences) 3168 */ 3169 _MHD_EXTERN size_t 3170 MHD_http_unescape (char *val); 3171 3172 3173 /** 3174 * Get a particular header value. If multiple 3175 * values match the kind, return any one of them. 3176 * 3177 * @param connection connection to get values from 3178 * @param kind what kind of value are we looking for 3179 * @param key the header to look for, NULL to lookup 'trailing' value without a key 3180 * @return NULL if no such item was found 3181 * @ingroup request 3182 */ 3183 _MHD_EXTERN const char * 3184 MHD_lookup_connection_value (struct MHD_Connection *connection, 3185 enum MHD_ValueKind kind, 3186 const char *key); 3187 3188 3189 /** 3190 * Get a particular header value. If multiple 3191 * values match the kind, return any one of them. 3192 * @note Since MHD_VERSION 0x00096304 3193 * 3194 * @param connection connection to get values from 3195 * @param kind what kind of value are we looking for 3196 * @param key the header to look for, NULL to lookup 'trailing' value without a key 3197 * @param key_size the length of @a key in bytes 3198 * @param[out] value_ptr the pointer to variable, which will be set to found value, 3199 * will not be updated if key not found, 3200 * could be NULL to just check for presence of @a key 3201 * @param[out] value_size_ptr the pointer variable, which will set to found value, 3202 * will not be updated if key not found, 3203 * could be NULL 3204 * @return #MHD_YES if key is found, 3205 * #MHD_NO otherwise. 3206 * @ingroup request 3207 */ 3208 _MHD_EXTERN enum MHD_Result 3209 MHD_lookup_connection_value_n (struct MHD_Connection *connection, 3210 enum MHD_ValueKind kind, 3211 const char *key, 3212 size_t key_size, 3213 const char **value_ptr, 3214 size_t *value_size_ptr); 3215 3216 3217 /** 3218 * Queue a response to be transmitted to the client (as soon as 3219 * possible but after #MHD_AccessHandlerCallback returns). 3220 * 3221 * For any active connection this function must be called 3222 * only by #MHD_AccessHandlerCallback callback. 3223 * For suspended connection this function can be called at any moment. Response 3224 * will be sent as soon as connection is resumed. 3225 * 3226 * @param connection the connection identifying the client 3227 * @param status_code HTTP status code (i.e. #MHD_HTTP_OK) 3228 * @param response response to transmit 3229 * @return #MHD_NO on error (i.e. reply already sent), 3230 * #MHD_YES on success or if message has been queued 3231 * @ingroup response 3232 * @sa #MHD_AccessHandlerCallback 3233 */ 3234 _MHD_EXTERN enum MHD_Result 3235 MHD_queue_response (struct MHD_Connection *connection, 3236 unsigned int status_code, 3237 struct MHD_Response *response); 3238 3239 3240 /** 3241 * Suspend handling of network data for a given connection. 3242 * This can be used to dequeue a connection from MHD's event loop 3243 * (not applicable to thread-per-connection!) for a while. 3244 * 3245 * If you use this API in conjunction with an "internal" socket polling, 3246 * you must set the option #MHD_USE_ITC to ensure that a resumed 3247 * connection is immediately processed by MHD. 3248 * 3249 * Suspended connections continue to count against the total number of 3250 * connections allowed (per daemon, as well as per IP, if such limits 3251 * are set). Suspended connections will NOT time out; timeouts will 3252 * restart when the connection handling is resumed. While a 3253 * connection is suspended, MHD will not detect disconnects by the 3254 * client. 3255 * 3256 * The only safe way to call this function is to call it from the 3257 * #MHD_AccessHandlerCallback or #MHD_ContentReaderCallback. 3258 * 3259 * Finally, it is an API violation to call #MHD_stop_daemon while 3260 * having suspended connections (this will at least create memory and 3261 * socket leaks or lead to undefined behavior). You must explicitly 3262 * resume all connections before stopping the daemon. 3263 * 3264 * @param connection the connection to suspend 3265 * 3266 * @sa #MHD_AccessHandlerCallback 3267 */ 3268 _MHD_EXTERN void 3269 MHD_suspend_connection (struct MHD_Connection *connection); 3270 3271 3272 /** 3273 * Resume handling of network data for suspended connection. It is 3274 * safe to resume a suspended connection at any time. Calling this 3275 * function on a connection that was not previously suspended will 3276 * result in undefined behavior. 3277 * 3278 * If you are using this function in "external" sockets polling mode, you must 3279 * make sure to run #MHD_run() and #MHD_get_timeout() afterwards (before 3280 * again calling #MHD_get_fdset()), as otherwise the change may not be 3281 * reflected in the set returned by #MHD_get_fdset() and you may end up 3282 * with a connection that is stuck until the next network activity. 3283 * 3284 * @param connection the connection to resume 3285 */ 3286 _MHD_EXTERN void 3287 MHD_resume_connection (struct MHD_Connection *connection); 3288 3289 3290 /* **************** Response manipulation functions ***************** */ 3291 3292 3293 /** 3294 * Flags for special handling of responses. 3295 */ 3296 enum MHD_ResponseFlags 3297 { 3298 /** 3299 * Default: no special flags. 3300 * @note Available since #MHD_VERSION 0x00093701 3301 */ 3302 MHD_RF_NONE = 0, 3303 3304 /** 3305 * Only respond in conservative (dumb) HTTP/1.0-compatible mode. 3306 * Response still use HTTP/1.1 version in header, but always close 3307 * the connection after sending the response and do not use chunked 3308 * encoding for the response. 3309 * You can also set the #MHD_RF_HTTP_1_0_SERVER flag to force 3310 * HTTP/1.0 version in the response. 3311 * Responses are still compatible with HTTP/1.1. 3312 * This option can be used to communicate with some broken client, which 3313 * does not implement HTTP/1.1 features, but advertises HTTP/1.1 support. 3314 * @note Available since #MHD_VERSION 0x00097308 3315 */ 3316 MHD_RF_HTTP_1_0_COMPATIBLE_STRICT = 1 << 0, 3317 /** 3318 * The same as #MHD_RF_HTTP_1_0_COMPATIBLE_STRICT 3319 * @note Available since #MHD_VERSION 0x00093701 3320 */ 3321 MHD_RF_HTTP_VERSION_1_0_ONLY = 1 << 0, 3322 3323 /** 3324 * Only respond in HTTP 1.0-mode. 3325 * Contrary to the #MHD_RF_HTTP_1_0_COMPATIBLE_STRICT flag, the response's 3326 * HTTP version will always be set to 1.0 and keep-alive connections 3327 * will be used if explicitly requested by the client. 3328 * The "Connection:" header will be added for both "close" and "keep-alive" 3329 * connections. 3330 * Chunked encoding will not be used for the response. 3331 * Due to backward compatibility, responses still can be used with 3332 * HTTP/1.1 clients. 3333 * This option can be used to emulate HTTP/1.0 server (for response part 3334 * only as chunked encoding in requests (if any) is processed by MHD). 3335 * @note Available since #MHD_VERSION 0x00097308 3336 */ 3337 MHD_RF_HTTP_1_0_SERVER = 1 << 1, 3338 /** 3339 * The same as #MHD_RF_HTTP_1_0_SERVER 3340 * @note Available since #MHD_VERSION 0x00096000 3341 */ 3342 MHD_RF_HTTP_VERSION_1_0_RESPONSE = 1 << 1, 3343 3344 /** 3345 * Disable sanity check preventing clients from manually 3346 * setting the HTTP content length option. 3347 * @note Available since #MHD_VERSION 0x00096702 3348 */ 3349 MHD_RF_INSANITY_HEADER_CONTENT_LENGTH = 1 << 2, 3350 3351 /** 3352 * Enable sending of "Connection: keep-alive" header even for 3353 * HTTP/1.1 clients when "Keep-Alive" connection is used. 3354 * Disabled by default for HTTP/1.1 clients as per RFC. 3355 * @note Available since #MHD_VERSION 0x00097310 3356 */ 3357 MHD_RF_SEND_KEEP_ALIVE_HEADER = 1 << 3 3358 } _MHD_FIXED_FLAGS_ENUM; 3359 3360 3361 /** 3362 * MHD options (for future extensions). 3363 */ 3364 enum MHD_ResponseOptions 3365 { 3366 /** 3367 * End of the list of options. 3368 */ 3369 MHD_RO_END = 0 3370 } _MHD_FIXED_ENUM; 3371 3372 3373 /** 3374 * Set special flags and options for a response. 3375 * 3376 * @param response the response to modify 3377 * @param flags to set for the response 3378 * @param ... #MHD_RO_END terminated list of options 3379 * @return #MHD_YES on success, #MHD_NO on error 3380 */ 3381 _MHD_EXTERN enum MHD_Result 3382 MHD_set_response_options (struct MHD_Response *response, 3383 enum MHD_ResponseFlags flags, 3384 ...); 3385 3386 3387 /** 3388 * Create a response object. The response object can be extended with 3389 * header information and then be used any number of times. 3390 * 3391 * @param size size of the data portion of the response, #MHD_SIZE_UNKNOWN for unknown 3392 * @param block_size preferred block size for querying crc (advisory only, 3393 * MHD may still call @a crc using smaller chunks); this 3394 * is essentially the buffer size used for IO, clients 3395 * should pick a value that is appropriate for IO and 3396 * memory performance requirements 3397 * @param crc callback to use to obtain response data 3398 * @param crc_cls extra argument to @a crc 3399 * @param crfc callback to call to free @a crc_cls resources 3400 * @return NULL on error (i.e. invalid arguments, out of memory) 3401 * @ingroup response 3402 */ 3403 _MHD_EXTERN struct MHD_Response * 3404 MHD_create_response_from_callback (uint64_t size, 3405 size_t block_size, 3406 MHD_ContentReaderCallback crc, void *crc_cls, 3407 MHD_ContentReaderFreeCallback crfc); 3408 3409 3410 /** 3411 * Create a response object. The response object can be extended with 3412 * header information and then be used any number of times. 3413 * 3414 * @param size size of the @a data portion of the response 3415 * @param data the data itself 3416 * @param must_free libmicrohttpd should free data when done 3417 * @param must_copy libmicrohttpd must make a copy of @a data 3418 * right away, the data may be released anytime after 3419 * this call returns 3420 * @return NULL on error (i.e. invalid arguments, out of memory) 3421 * @deprecated use #MHD_create_response_from_buffer instead 3422 * @ingroup response 3423 */ 3424 _MHD_DEPR_FUNC ( 3425 "MHD_create_response_from_data() is deprecated, use MHD_create_response_from_buffer()") \ 3426 _MHD_EXTERN struct MHD_Response * 3427 MHD_create_response_from_data (size_t size, 3428 void *data, 3429 int must_free, 3430 int must_copy); 3431 3432 3433 /** 3434 * Specification for how MHD should treat the memory buffer 3435 * given for the response. 3436 * @ingroup response 3437 */ 3438 enum MHD_ResponseMemoryMode 3439 { 3440 3441 /** 3442 * Buffer is a persistent (static/global) buffer that won't change 3443 * for at least the lifetime of the response, MHD should just use 3444 * it, not free it, not copy it, just keep an alias to it. 3445 * @ingroup response 3446 */ 3447 MHD_RESPMEM_PERSISTENT, 3448 3449 /** 3450 * Buffer is heap-allocated with `malloc()` (or equivalent) and 3451 * should be freed by MHD after processing the response has 3452 * concluded (response reference counter reaches zero). 3453 * @ingroup response 3454 */ 3455 MHD_RESPMEM_MUST_FREE, 3456 3457 /** 3458 * Buffer is in transient memory, but not on the heap (for example, 3459 * on the stack or non-`malloc()` allocated) and only valid during the 3460 * call to #MHD_create_response_from_buffer. MHD must make its 3461 * own private copy of the data for processing. 3462 * @ingroup response 3463 */ 3464 MHD_RESPMEM_MUST_COPY 3465 3466 } _MHD_FIXED_ENUM; 3467 3468 3469 /** 3470 * Create a response object with the content of provided buffer used as 3471 * the response body. 3472 * 3473 * The response object can be extended with header information and then 3474 * be used any number of times. 3475 * 3476 * If response object is used to answer HEAD request then the body 3477 * of the response is not used, while all headers (including automatic 3478 * headers) are used. 3479 * 3480 * @param size size of the data portion of the response 3481 * @param buffer size bytes containing the response's data portion 3482 * @param mode flags for buffer management 3483 * @return NULL on error (i.e. invalid arguments, out of memory) 3484 * @ingroup response 3485 */ 3486 _MHD_EXTERN struct MHD_Response * 3487 MHD_create_response_from_buffer (size_t size, 3488 void *buffer, 3489 enum MHD_ResponseMemoryMode mode); 3490 3491 3492 /** 3493 * Create a response object with the content of provided buffer used as 3494 * the response body. 3495 * 3496 * The response object can be extended with header information and then 3497 * be used any number of times. 3498 * 3499 * If response object is used to answer HEAD request then the body 3500 * of the response is not used, while all headers (including automatic 3501 * headers) are used. 3502 * 3503 * @param size size of the data portion of the response 3504 * @param buffer size bytes containing the response's data portion 3505 * @param crfc function to call to free the @a buffer 3506 * @return NULL on error (i.e. invalid arguments, out of memory) 3507 * @note Available since #MHD_VERSION 0x00096000 3508 * @ingroup response 3509 */ 3510 _MHD_EXTERN struct MHD_Response * 3511 MHD_create_response_from_buffer_with_free_callback (size_t size, 3512 void *buffer, 3513 MHD_ContentReaderFreeCallback 3514 crfc); 3515 3516 3517 /** 3518 * Create a response object with the content of provided buffer used as 3519 * the response body. 3520 * 3521 * The response object can be extended with header information and then 3522 * be used any number of times. 3523 * 3524 * If response object is used to answer HEAD request then the body 3525 * of the response is not used, while all headers (including automatic 3526 * headers) are used. 3527 * 3528 * @param size size of the data portion of the response 3529 * @param buffer size bytes containing the response's data portion 3530 * @param crfc function to call to cleanup, if set to NULL then callback 3531 * is not called 3532 * @param crfc_cls an argument for @a crfc 3533 * @return NULL on error (i.e. invalid arguments, out of memory) 3534 * @note Available since #MHD_VERSION 0x00097302 3535 * @ingroup response 3536 */ 3537 _MHD_EXTERN struct MHD_Response * 3538 MHD_create_response_from_buffer_with_free_callback_cls (size_t size, 3539 void *buffer, 3540 MHD_ContentReaderFreeCallback 3541 crfc, 3542 void *crfc_cls); 3543 3544 3545 /** 3546 * Create a response object with the content of provided file used as 3547 * the response body. 3548 * 3549 * The response object can be extended with header information and then 3550 * be used any number of times. 3551 * 3552 * If response object is used to answer HEAD request then the body 3553 * of the response is not used, while all headers (including automatic 3554 * headers) are used. 3555 * 3556 * @param size size of the data portion of the response 3557 * @param fd file descriptor referring to a file on disk with the 3558 * data; will be closed when response is destroyed; 3559 * fd should be in 'blocking' mode 3560 * @return NULL on error (i.e. invalid arguments, out of memory) 3561 * @ingroup response 3562 */ 3563 _MHD_EXTERN struct MHD_Response * 3564 MHD_create_response_from_fd (size_t size, 3565 int fd); 3566 3567 3568 /** 3569 * Create a response object with the response body created by reading 3570 * the provided pipe. 3571 * 3572 * The response object can be extended with header information and 3573 * then be used ONLY ONCE. 3574 * 3575 * If response object is used to answer HEAD request then the body 3576 * of the response is not used, while all headers (including automatic 3577 * headers) are used. 3578 * 3579 * @param fd file descriptor referring to a read-end of a pipe with the 3580 * data; will be closed when response is destroyed; 3581 * fd should be in 'blocking' mode 3582 * @return NULL on error (i.e. invalid arguments, out of memory) 3583 * @note Available since #MHD_VERSION 0x00097102 3584 * @ingroup response 3585 */ 3586 _MHD_EXTERN struct MHD_Response * 3587 MHD_create_response_from_pipe (int fd); 3588 3589 3590 /** 3591 * Create a response object with the content of provided file used as 3592 * the response body. 3593 * 3594 * The response object can be extended with header information and then 3595 * be used any number of times. 3596 * 3597 * If response object is used to answer HEAD request then the body 3598 * of the response is not used, while all headers (including automatic 3599 * headers) are used. 3600 * 3601 * @param size size of the data portion of the response; 3602 * sizes larger than 2 GiB may be not supported by OS or 3603 * MHD build; see ::MHD_FEATURE_LARGE_FILE 3604 * @param fd file descriptor referring to a file on disk with the 3605 * data; will be closed when response is destroyed; 3606 * fd should be in 'blocking' mode 3607 * @return NULL on error (i.e. invalid arguments, out of memory) 3608 * @ingroup response 3609 */ 3610 _MHD_EXTERN struct MHD_Response * 3611 MHD_create_response_from_fd64 (uint64_t size, 3612 int fd); 3613 3614 3615 /** 3616 * Create a response object with the content of provided file with 3617 * specified offset used as the response body. 3618 * 3619 * The response object can be extended with header information and then 3620 * be used any number of times. 3621 * 3622 * If response object is used to answer HEAD request then the body 3623 * of the response is not used, while all headers (including automatic 3624 * headers) are used. 3625 * 3626 * @param size size of the data portion of the response 3627 * @param fd file descriptor referring to a file on disk with the 3628 * data; will be closed when response is destroyed; 3629 * fd should be in 'blocking' mode 3630 * @param offset offset to start reading from in the file; 3631 * Be careful! `off_t` may have been compiled to be a 3632 * 64-bit variable for MHD, in which case your application 3633 * also has to be compiled using the same options! Read 3634 * the MHD manual for more details. 3635 * @return NULL on error (i.e. invalid arguments, out of memory) 3636 * @ingroup response 3637 */ 3638 _MHD_DEPR_FUNC ( 3639 "Function MHD_create_response_from_fd_at_offset() is deprecated, use MHD_create_response_from_fd_at_offset64()") \ 3640 _MHD_EXTERN struct MHD_Response * 3641 MHD_create_response_from_fd_at_offset (size_t size, 3642 int fd, 3643 off_t offset); 3644 3645 #if ! defined(_MHD_NO_DEPR_IN_MACRO) || defined(_MHD_NO_DEPR_FUNC) 3646 /* Substitute MHD_create_response_from_fd_at_offset64() instead of MHD_create_response_from_fd_at_offset() 3647 to minimize potential problems with different off_t sizes */ 3648 #define MHD_create_response_from_fd_at_offset(size,fd,offset) \ 3649 _MHD_DEPR_IN_MACRO ( \ 3650 "Usage of MHD_create_response_from_fd_at_offset() is deprecated, use MHD_create_response_from_fd_at_offset64()") \ 3651 MHD_create_response_from_fd_at_offset64 ((size),(fd),(offset)) 3652 #endif /* !_MHD_NO_DEPR_IN_MACRO || _MHD_NO_DEPR_FUNC */ 3653 3654 3655 /** 3656 * Create a response object with the content of provided file with 3657 * specified offset used as the response body. 3658 * 3659 * The response object can be extended with header information and then 3660 * be used any number of times. 3661 * 3662 * If response object is used to answer HEAD request then the body 3663 * of the response is not used, while all headers (including automatic 3664 * headers) are used. 3665 * 3666 * @param size size of the data portion of the response; 3667 * sizes larger than 2 GiB may be not supported by OS or 3668 * MHD build; see ::MHD_FEATURE_LARGE_FILE 3669 * @param fd file descriptor referring to a file on disk with the 3670 * data; will be closed when response is destroyed; 3671 * fd should be in 'blocking' mode 3672 * @param offset offset to start reading from in the file; 3673 * reading file beyond 2 GiB may be not supported by OS or 3674 * MHD build; see ::MHD_FEATURE_LARGE_FILE 3675 * @return NULL on error (i.e. invalid arguments, out of memory) 3676 * @ingroup response 3677 */ 3678 _MHD_EXTERN struct MHD_Response * 3679 MHD_create_response_from_fd_at_offset64 (uint64_t size, 3680 int fd, 3681 uint64_t offset); 3682 3683 3684 /** 3685 * Create a response object with an array of memory buffers 3686 * used as the response body. 3687 * 3688 * The response object can be extended with header information and then 3689 * be used any number of times. 3690 * 3691 * If response object is used to answer HEAD request then the body 3692 * of the response is not used, while all headers (including automatic 3693 * headers) are used. 3694 * 3695 * @param iov the array for response data buffers, an internal copy of this 3696 * will be made 3697 * @param iovcnt the number of elements in @a iov 3698 * @param free_cb the callback to clean up any data associated with @a iov when 3699 * the response is destroyed. 3700 * @param cls the argument passed to @a free_cb 3701 * @return NULL on error (i.e. invalid arguments, out of memory) 3702 * @note Available since #MHD_VERSION 0x00097204 3703 * @ingroup response 3704 */ 3705 _MHD_EXTERN struct MHD_Response * 3706 MHD_create_response_from_iovec (const struct MHD_IoVec *iov, 3707 unsigned int iovcnt, 3708 MHD_ContentReaderFreeCallback free_cb, 3709 void *cls); 3710 3711 3712 /** 3713 * Enumeration for actions MHD should perform on the underlying socket 3714 * of the upgrade. This API is not finalized, and in particular 3715 * the final set of actions is yet to be decided. This is just an 3716 * idea for what we might want. 3717 */ 3718 enum MHD_UpgradeAction 3719 { 3720 3721 /** 3722 * Close the socket, the application is done with it. 3723 * 3724 * Takes no extra arguments. 3725 */ 3726 MHD_UPGRADE_ACTION_CLOSE = 0, 3727 3728 /** 3729 * Enable CORKing on the underlying socket. 3730 */ 3731 MHD_UPGRADE_ACTION_CORK_ON = 1, 3732 3733 /** 3734 * Disable CORKing on the underlying socket. 3735 */ 3736 MHD_UPGRADE_ACTION_CORK_OFF = 2 3737 3738 } _MHD_FIXED_ENUM; 3739 3740 3741 /** 3742 * Handle given to the application to manage special 3743 * actions relating to MHD responses that "upgrade" 3744 * the HTTP protocol (i.e. to WebSockets). 3745 */ 3746 struct MHD_UpgradeResponseHandle; 3747 3748 3749 /** 3750 * This connection-specific callback is provided by MHD to 3751 * applications (unusual) during the #MHD_UpgradeHandler. 3752 * It allows applications to perform 'special' actions on 3753 * the underlying socket from the upgrade. 3754 * 3755 * @param urh the handle identifying the connection to perform 3756 * the upgrade @a action on. 3757 * @param action which action should be performed 3758 * @param ... arguments to the action (depends on the action) 3759 * @return #MHD_NO on error, #MHD_YES on success 3760 */ 3761 _MHD_EXTERN enum MHD_Result 3762 MHD_upgrade_action (struct MHD_UpgradeResponseHandle *urh, 3763 enum MHD_UpgradeAction action, 3764 ...); 3765 3766 3767 /** 3768 * Function called after a protocol "upgrade" response was sent 3769 * successfully and the socket should now be controlled by some 3770 * protocol other than HTTP. 3771 * 3772 * Any data already received on the socket will be made available in 3773 * @e extra_in. This can happen if the application sent extra data 3774 * before MHD send the upgrade response. The application should 3775 * treat data from @a extra_in as if it had read it from the socket. 3776 * 3777 * Note that the application must not close() @a sock directly, 3778 * but instead use #MHD_upgrade_action() for special operations 3779 * on @a sock. 3780 * 3781 * Data forwarding to "upgraded" @a sock will be started as soon 3782 * as this function return. 3783 * 3784 * Except when in 'thread-per-connection' mode, implementations 3785 * of this function should never block (as it will still be called 3786 * from within the main event loop). 3787 * 3788 * @param cls closure, whatever was given to #MHD_create_response_for_upgrade(). 3789 * @param connection original HTTP connection handle, 3790 * giving the function a last chance 3791 * to inspect the original HTTP request 3792 * @param con_cls last value left in `con_cls` of the `MHD_AccessHandlerCallback` 3793 * @param extra_in if we happened to have read bytes after the 3794 * HTTP header already (because the client sent 3795 * more than the HTTP header of the request before 3796 * we sent the upgrade response), 3797 * these are the extra bytes already read from @a sock 3798 * by MHD. The application should treat these as if 3799 * it had read them from @a sock. 3800 * @param extra_in_size number of bytes in @a extra_in 3801 * @param sock socket to use for bi-directional communication 3802 * with the client. For HTTPS, this may not be a socket 3803 * that is directly connected to the client and thus certain 3804 * operations (TCP-specific setsockopt(), getsockopt(), etc.) 3805 * may not work as expected (as the socket could be from a 3806 * socketpair() or a TCP-loopback). The application is expected 3807 * to perform read()/recv() and write()/send() calls on the socket. 3808 * The application may also call shutdown(), but must not call 3809 * close() directly. 3810 * @param urh argument for #MHD_upgrade_action()s on this @a connection. 3811 * Applications must eventually use this callback to (indirectly) 3812 * perform the close() action on the @a sock. 3813 */ 3814 typedef void 3815 (*MHD_UpgradeHandler)(void *cls, 3816 struct MHD_Connection *connection, 3817 void *con_cls, 3818 const char *extra_in, 3819 size_t extra_in_size, 3820 MHD_socket sock, 3821 struct MHD_UpgradeResponseHandle *urh); 3822 3823 3824 /** 3825 * Create a response object that can be used for 101 UPGRADE 3826 * responses, for example to implement WebSockets. After sending the 3827 * response, control over the data stream is given to the callback (which 3828 * can then, for example, start some bi-directional communication). 3829 * If the response is queued for multiple connections, the callback 3830 * will be called for each connection. The callback 3831 * will ONLY be called after the response header was successfully passed 3832 * to the OS; if there are communication errors before, the usual MHD 3833 * connection error handling code will be performed. 3834 * 3835 * Setting the correct HTTP code (i.e. MHD_HTTP_SWITCHING_PROTOCOLS) 3836 * and setting correct HTTP headers for the upgrade must be done 3837 * manually (this way, it is possible to implement most existing 3838 * WebSocket versions using this API; in fact, this API might be useful 3839 * for any protocol switch, not just WebSockets). Note that 3840 * draft-ietf-hybi-thewebsocketprotocol-00 cannot be implemented this 3841 * way as the header "HTTP/1.1 101 WebSocket Protocol Handshake" 3842 * cannot be generated; instead, MHD will always produce "HTTP/1.1 101 3843 * Switching Protocols" (if the response code 101 is used). 3844 * 3845 * As usual, the response object can be extended with header 3846 * information and then be used any number of times (as long as the 3847 * header information is not connection-specific). 3848 * 3849 * @param upgrade_handler function to call with the "upgraded" socket 3850 * @param upgrade_handler_cls closure for @a upgrade_handler 3851 * @return NULL on error (i.e. invalid arguments, out of memory) 3852 */ 3853 _MHD_EXTERN struct MHD_Response * 3854 MHD_create_response_for_upgrade (MHD_UpgradeHandler upgrade_handler, 3855 void *upgrade_handler_cls); 3856 3857 3858 /** 3859 * Destroy a response object and associated resources. Note that 3860 * libmicrohttpd may keep some of the resources around if the response 3861 * is still in the queue for some clients, so the memory may not 3862 * necessarily be freed immediately. 3863 * 3864 * @param response response to destroy 3865 * @ingroup response 3866 */ 3867 _MHD_EXTERN void 3868 MHD_destroy_response (struct MHD_Response *response); 3869 3870 3871 /** 3872 * Add a header line to the response. 3873 * 3874 * When reply is generated with queued response, some headers are generated 3875 * automatically. Automatically generated headers are only sent to the client, 3876 * but not added back to the response object. 3877 * 3878 * The list of automatic headers: 3879 * + "Date" header is added automatically unless already set by 3880 * this function 3881 * @see #MHD_USE_SUPPRESS_DATE_NO_CLOCK 3882 * + "Content-Length" is added automatically when required, attempt to set 3883 * it manually by this function is ignored. 3884 * @see #MHD_RF_INSANITY_HEADER_CONTENT_LENGTH 3885 * + "Transfer-Encoding" with value "chunked" is added automatically, 3886 * when chunked transfer encoding is used automatically. Same header with 3887 * the same value can be set manually by this function to enforce chunked 3888 * encoding, however for HTTP/1.0 clients chunked encoding will not be used 3889 * and manually set "Transfer-Encoding" header is automatically removed 3890 * for HTTP/1.0 clients 3891 * + "Connection" may be added automatically with value "Keep-Alive" (only 3892 * for HTTP/1.0 clients) or "Close". The header "Connection" with value 3893 * "Close" could be set by this function to enforce closure of 3894 * the connection after sending this response. "Keep-Alive" cannot be 3895 * enforced and will be removed automatically. 3896 * @see #MHD_RF_SEND_KEEP_ALIVE_HEADER 3897 * 3898 * Some headers are pre-processed by this function: 3899 * * "Connection" headers are combined into single header entry, value is 3900 * normilised, "Keep-Alive" tokens are removed. 3901 * * "Transfer-Encoding" header: the only one header is allowed, the only 3902 * allowed value is "chunked". 3903 * * "Date" header: the only one header is allowed, the second added header 3904 * replaces the first one. 3905 * * "Content-Length" application-defined header is not allowed. 3906 * @see #MHD_RF_INSANITY_HEADER_CONTENT_LENGTH 3907 * 3908 * Headers are used in order as they were added. 3909 * 3910 * @param response the response to add a header to 3911 * @param header the header name to add, no need to be static, an internal copy 3912 * will be created automatically 3913 * @param content the header value to add, no need to be static, an internal 3914 * copy will be created automatically 3915 * @return #MHD_YES on success, 3916 * #MHD_NO on error (i.e. invalid header or content format), 3917 * or out of memory 3918 * @ingroup response 3919 */ 3920 _MHD_EXTERN enum MHD_Result 3921 MHD_add_response_header (struct MHD_Response *response, 3922 const char *header, 3923 const char *content); 3924 3925 3926 /** 3927 * Add a footer line to the response. 3928 * 3929 * @param response response to remove a header from 3930 * @param footer the footer to delete 3931 * @param content value to delete 3932 * @return #MHD_NO on error (i.e. invalid footer or content format). 3933 * @ingroup response 3934 */ 3935 _MHD_EXTERN enum MHD_Result 3936 MHD_add_response_footer (struct MHD_Response *response, 3937 const char *footer, 3938 const char *content); 3939 3940 3941 /** 3942 * Delete a header (or footer) line from the response. 3943 * 3944 * For "Connection" headers this function remove all tokens from existing 3945 * value. Successful result means that at least one token has been removed. 3946 * If all tokens are removed from "Connection" header, the empty "Connection" 3947 * header removed. 3948 * 3949 * @param response response to remove a header from 3950 * @param header the header to delete 3951 * @param content value to delete 3952 * @return #MHD_NO on error (no such header known) 3953 * @ingroup response 3954 */ 3955 _MHD_EXTERN enum MHD_Result 3956 MHD_del_response_header (struct MHD_Response *response, 3957 const char *header, 3958 const char *content); 3959 3960 3961 /** 3962 * Get all of the headers (and footers) added to a response. 3963 * 3964 * @param response response to query 3965 * @param iterator callback to call on each header; 3966 * may be NULL (then just count headers) 3967 * @param iterator_cls extra argument to @a iterator 3968 * @return number of entries iterated over 3969 * @ingroup response 3970 */ 3971 _MHD_EXTERN int 3972 MHD_get_response_headers (struct MHD_Response *response, 3973 MHD_KeyValueIterator iterator, 3974 void *iterator_cls); 3975 3976 3977 /** 3978 * Get a particular header (or footer) from the response. 3979 * 3980 * @param response response to query 3981 * @param key which header to get 3982 * @return NULL if header does not exist 3983 * @ingroup response 3984 */ 3985 _MHD_EXTERN const char * 3986 MHD_get_response_header (struct MHD_Response *response, 3987 const char *key); 3988 3989 3990 /* ********************** PostProcessor functions ********************** */ 3991 3992 /** 3993 * Create a `struct MHD_PostProcessor`. 3994 * 3995 * A `struct MHD_PostProcessor` can be used to (incrementally) parse 3996 * the data portion of a POST request. Note that some buggy browsers 3997 * fail to set the encoding type. If you want to support those, you 3998 * may have to call #MHD_set_connection_value with the proper encoding 3999 * type before creating a post processor (if no supported encoding 4000 * type is set, this function will fail). 4001 * 4002 * @param connection the connection on which the POST is 4003 * happening (used to determine the POST format) 4004 * @param buffer_size maximum number of bytes to use for 4005 * internal buffering (used only for the parsing, 4006 * specifically the parsing of the keys). A 4007 * tiny value (256-1024) should be sufficient. 4008 * Do NOT use a value smaller than 256. For good 4009 * performance, use 32 or 64k (i.e. 65536). 4010 * @param iter iterator to be called with the parsed data, 4011 * Must NOT be NULL. 4012 * @param iter_cls first argument to @a iter 4013 * @return NULL on error (out of memory, unsupported encoding), 4014 * otherwise a PP handle 4015 * @ingroup request 4016 */ 4017 _MHD_EXTERN struct MHD_PostProcessor * 4018 MHD_create_post_processor (struct MHD_Connection *connection, 4019 size_t buffer_size, 4020 MHD_PostDataIterator iter, void *iter_cls); 4021 4022 4023 /** 4024 * Parse and process POST data. Call this function when POST data is 4025 * available (usually during an #MHD_AccessHandlerCallback) with the 4026 * "upload_data" and "upload_data_size". Whenever possible, this will 4027 * then cause calls to the #MHD_PostDataIterator. 4028 * 4029 * @param pp the post processor 4030 * @param post_data @a post_data_len bytes of POST data 4031 * @param post_data_len length of @a post_data 4032 * @return #MHD_YES on success, #MHD_NO on error 4033 * (out-of-memory, iterator aborted, parse error) 4034 * @ingroup request 4035 */ 4036 _MHD_EXTERN enum MHD_Result 4037 MHD_post_process (struct MHD_PostProcessor *pp, 4038 const char *post_data, 4039 size_t post_data_len); 4040 4041 4042 /** 4043 * Release PostProcessor resources. 4044 * 4045 * @param pp the PostProcessor to destroy 4046 * @return #MHD_YES if processing completed nicely, 4047 * #MHD_NO if there were spurious characters / formatting 4048 * problems; it is common to ignore the return 4049 * value of this function 4050 * @ingroup request 4051 */ 4052 _MHD_EXTERN enum MHD_Result 4053 MHD_destroy_post_processor (struct MHD_PostProcessor *pp); 4054 4055 4056 /* ********************* Digest Authentication functions *************** */ 4057 4058 4059 /** 4060 * Constant to indicate that the nonce of the provided 4061 * authentication code was wrong. 4062 * @ingroup authentication 4063 */ 4064 #define MHD_INVALID_NONCE -1 4065 4066 4067 /** 4068 * Get the username from the authorization header sent by the client 4069 * 4070 * @param connection The MHD connection structure 4071 * @return NULL if no username could be found, a pointer 4072 * to the username if found, free using #MHD_free(). 4073 * @ingroup authentication 4074 */ 4075 _MHD_EXTERN char * 4076 MHD_digest_auth_get_username (struct MHD_Connection *connection); 4077 4078 4079 /** 4080 * Free the memory given by @a ptr. Calls "free(ptr)". This function 4081 * should be used to free the username returned by 4082 * #MHD_digest_auth_get_username(). 4083 * @note Available since #MHD_VERSION 0x00095600 4084 * 4085 * @param ptr pointer to free. 4086 */ 4087 _MHD_EXTERN void 4088 MHD_free (void *ptr); 4089 4090 4091 /** 4092 * Which digest algorithm should MHD use for HTTP digest authentication? 4093 */ 4094 enum MHD_DigestAuthAlgorithm 4095 { 4096 4097 /** 4098 * MHD should pick (currently defaults to SHA-256). 4099 */ 4100 MHD_DIGEST_ALG_AUTO = 0, 4101 4102 /** 4103 * Force use of MD5. 4104 */ 4105 MHD_DIGEST_ALG_MD5, 4106 4107 /** 4108 * Force use of SHA-256. 4109 */ 4110 MHD_DIGEST_ALG_SHA256 4111 4112 } _MHD_FIXED_ENUM; 4113 4114 4115 /** 4116 * Authenticates the authorization header sent by the client. 4117 * 4118 * @param connection The MHD connection structure 4119 * @param realm The realm presented to the client 4120 * @param username The username needs to be authenticated 4121 * @param password The password used in the authentication 4122 * @param nonce_timeout The amount of time for a nonce to be 4123 * invalid in seconds 4124 * @param algo digest algorithms allowed for verification 4125 * @return #MHD_YES if authenticated, #MHD_NO if not, 4126 * #MHD_INVALID_NONCE if nonce is invalid 4127 * @note Available since #MHD_VERSION 0x00096200 4128 * @ingroup authentication 4129 */ 4130 _MHD_EXTERN int 4131 MHD_digest_auth_check2 (struct MHD_Connection *connection, 4132 const char *realm, 4133 const char *username, 4134 const char *password, 4135 unsigned int nonce_timeout, 4136 enum MHD_DigestAuthAlgorithm algo); 4137 4138 4139 /** 4140 * Authenticates the authorization header sent by the client. 4141 * Uses #MHD_DIGEST_ALG_MD5 (for now, for backwards-compatibility). 4142 * Note that this MAY change to #MHD_DIGEST_ALG_AUTO in the future. 4143 * If you want to be sure you get MD5, use #MHD_digest_auth_check2() 4144 * and specify MD5 explicitly. 4145 * 4146 * @param connection The MHD connection structure 4147 * @param realm The realm presented to the client 4148 * @param username The username needs to be authenticated 4149 * @param password The password used in the authentication 4150 * @param nonce_timeout The amount of time for a nonce to be 4151 * invalid in seconds 4152 * @return #MHD_YES if authenticated, #MHD_NO if not, 4153 * #MHD_INVALID_NONCE if nonce is invalid 4154 * @ingroup authentication 4155 * @deprecated use MHD_digest_auth_check2() 4156 */ 4157 _MHD_EXTERN int 4158 MHD_digest_auth_check (struct MHD_Connection *connection, 4159 const char *realm, 4160 const char *username, 4161 const char *password, 4162 unsigned int nonce_timeout); 4163 4164 4165 /** 4166 * Authenticates the authorization header sent by the client. 4167 * 4168 * @param connection The MHD connection structure 4169 * @param realm The realm presented to the client 4170 * @param username The username needs to be authenticated 4171 * @param digest An `unsigned char *' pointer to the binary MD5 sum 4172 * for the precalculated hash value "username:realm:password" 4173 * of @a digest_size bytes 4174 * @param digest_size number of bytes in @a digest (size must match @a algo!) 4175 * @param nonce_timeout The amount of time for a nonce to be 4176 * invalid in seconds 4177 * @param algo digest algorithms allowed for verification 4178 * @return #MHD_YES if authenticated, #MHD_NO if not, 4179 * #MHD_INVALID_NONCE if nonce is invalid 4180 * @note Available since #MHD_VERSION 0x00096200 4181 * @ingroup authentication 4182 */ 4183 _MHD_EXTERN int 4184 MHD_digest_auth_check_digest2 (struct MHD_Connection *connection, 4185 const char *realm, 4186 const char *username, 4187 const uint8_t *digest, 4188 size_t digest_size, 4189 unsigned int nonce_timeout, 4190 enum MHD_DigestAuthAlgorithm algo); 4191 4192 4193 /** 4194 * Authenticates the authorization header sent by the client 4195 * Uses #MHD_DIGEST_ALG_MD5 (required, as @a digest is of fixed 4196 * size). 4197 * 4198 * @param connection The MHD connection structure 4199 * @param realm The realm presented to the client 4200 * @param username The username needs to be authenticated 4201 * @param digest An `unsigned char *' pointer to the binary hash 4202 * for the precalculated hash value "username:realm:password"; 4203 * length must be #MHD_MD5_DIGEST_SIZE bytes 4204 * @param nonce_timeout The amount of time for a nonce to be 4205 * invalid in seconds 4206 * @return #MHD_YES if authenticated, #MHD_NO if not, 4207 * #MHD_INVALID_NONCE if nonce is invalid 4208 * @note Available since #MHD_VERSION 0x00096000 4209 * @ingroup authentication 4210 * @deprecated use #MHD_digest_auth_check_digest2() 4211 */ 4212 _MHD_EXTERN int 4213 MHD_digest_auth_check_digest (struct MHD_Connection *connection, 4214 const char *realm, 4215 const char *username, 4216 const uint8_t digest[MHD_MD5_DIGEST_SIZE], 4217 unsigned int nonce_timeout); 4218 4219 4220 /** 4221 * Queues a response to request authentication from the client 4222 * 4223 * @param connection The MHD connection structure 4224 * @param realm the realm presented to the client 4225 * @param opaque string to user for opaque value 4226 * @param response reply to send; should contain the "access denied" 4227 * body; note that this function will set the "WWW Authenticate" 4228 * header and that the caller should not do this 4229 * @param signal_stale #MHD_YES if the nonce is invalid to add 4230 * 'stale=true' to the authentication header 4231 * @param algo digest algorithm to use 4232 * @return #MHD_YES on success, #MHD_NO otherwise 4233 * @note Available since #MHD_VERSION 0x00096200 4234 * @ingroup authentication 4235 */ 4236 _MHD_EXTERN enum MHD_Result 4237 MHD_queue_auth_fail_response2 (struct MHD_Connection *connection, 4238 const char *realm, 4239 const char *opaque, 4240 struct MHD_Response *response, 4241 int signal_stale, 4242 enum MHD_DigestAuthAlgorithm algo); 4243 4244 4245 /** 4246 * Queues a response to request authentication from the client 4247 * For now uses MD5 (for backwards-compatibility). Still, if you 4248 * need to be sure, use #MHD_queue_fail_auth_response2(). 4249 * 4250 * @param connection The MHD connection structure 4251 * @param realm The realm presented to the client 4252 * @param opaque string to user for opaque value 4253 * @param response reply to send; should contain the "access denied" 4254 * body; note that this function will set the "WWW Authenticate" 4255 * header and that the caller should not do this 4256 * @param signal_stale #MHD_YES if the nonce is invalid to add 4257 * 'stale=true' to the authentication header 4258 * @return #MHD_YES on success, #MHD_NO otherwise 4259 * @ingroup authentication 4260 * @deprecated use MHD_queue_auth_fail_response2() 4261 */ 4262 _MHD_EXTERN enum MHD_Result 4263 MHD_queue_auth_fail_response (struct MHD_Connection *connection, 4264 const char *realm, 4265 const char *opaque, 4266 struct MHD_Response *response, 4267 int signal_stale); 4268 4269 4270 /** 4271 * Get the username and password from the basic authorization header sent by the client 4272 * 4273 * @param connection The MHD connection structure 4274 * @param[out] password a pointer for the password, free using #MHD_free(). 4275 * @return NULL if no username could be found, a pointer 4276 * to the username if found, free using #MHD_free(). 4277 * @ingroup authentication 4278 */ 4279 _MHD_EXTERN char * 4280 MHD_basic_auth_get_username_password (struct MHD_Connection *connection, 4281 char **password); 4282 4283 4284 /** 4285 * Queues a response to request basic authentication from the client 4286 * The given response object is expected to include the payload for 4287 * the response; the "WWW-Authenticate" header will be added and the 4288 * response queued with the 'UNAUTHORIZED' status code. 4289 * 4290 * @param connection The MHD connection structure 4291 * @param realm the realm presented to the client 4292 * @param response response object to modify and queue 4293 * @return #MHD_YES on success, #MHD_NO otherwise 4294 * @ingroup authentication 4295 */ 4296 _MHD_EXTERN enum MHD_Result 4297 MHD_queue_basic_auth_fail_response (struct MHD_Connection *connection, 4298 const char *realm, 4299 struct MHD_Response *response); 4300 4301 /* ********************** generic query functions ********************** */ 4302 4303 4304 /** 4305 * Obtain information about the given connection. 4306 * 4307 * @param connection what connection to get information about 4308 * @param info_type what information is desired? 4309 * @param ... depends on @a info_type 4310 * @return NULL if this information is not available 4311 * (or if the @a info_type is unknown) 4312 * @ingroup specialized 4313 */ 4314 _MHD_EXTERN const union MHD_ConnectionInfo * 4315 MHD_get_connection_info (struct MHD_Connection *connection, 4316 enum MHD_ConnectionInfoType info_type, 4317 ...); 4318 4319 4320 /** 4321 * MHD connection options. Given to #MHD_set_connection_option to 4322 * set custom options for a particular connection. 4323 */ 4324 enum MHD_CONNECTION_OPTION 4325 { 4326 4327 /** 4328 * Set a custom timeout for the given connection. Specified 4329 * as the number of seconds, given as an `unsigned int`. Use 4330 * zero for no timeout. 4331 * If timeout was set to zero (or unset) before, setup of new value by 4332 * MHD_set_connection_option() will reset timeout timer. 4333 * Values larger than (UINT64_MAX / 2000 - 1) will 4334 * be clipped to this number. 4335 */ 4336 MHD_CONNECTION_OPTION_TIMEOUT 4337 4338 } _MHD_FIXED_ENUM; 4339 4340 4341 /** 4342 * Set a custom option for the given connection, overriding defaults. 4343 * 4344 * @param connection connection to modify 4345 * @param option option to set 4346 * @param ... arguments to the option, depending on the option type 4347 * @return #MHD_YES on success, #MHD_NO if setting the option failed 4348 * @ingroup specialized 4349 */ 4350 _MHD_EXTERN enum MHD_Result 4351 MHD_set_connection_option (struct MHD_Connection *connection, 4352 enum MHD_CONNECTION_OPTION option, 4353 ...); 4354 4355 4356 /** 4357 * Information about an MHD daemon. 4358 */ 4359 union MHD_DaemonInfo 4360 { 4361 /** 4362 * Size of the key, no longer supported. 4363 * @deprecated 4364 */ 4365 size_t key_size; 4366 4367 /** 4368 * Size of the mac key, no longer supported. 4369 * @deprecated 4370 */ 4371 size_t mac_key_size; 4372 4373 /** 4374 * Socket, returned for #MHD_DAEMON_INFO_LISTEN_FD. 4375 */ 4376 MHD_socket listen_fd; 4377 4378 /** 4379 * Bind port number, returned for #MHD_DAEMON_INFO_BIND_PORT. 4380 */ 4381 uint16_t port; 4382 4383 /** 4384 * epoll FD, returned for #MHD_DAEMON_INFO_EPOLL_FD. 4385 */ 4386 int epoll_fd; 4387 4388 /** 4389 * Number of active connections, for #MHD_DAEMON_INFO_CURRENT_CONNECTIONS. 4390 */ 4391 unsigned int num_connections; 4392 4393 /** 4394 * Combination of #MHD_FLAG values, for #MHD_DAEMON_INFO_FLAGS. 4395 * This value is actually a bitfield. 4396 * Note: flags may differ from original 'flags' specified for 4397 * daemon, especially if #MHD_USE_AUTO was set. 4398 */ 4399 enum MHD_FLAG flags; 4400 }; 4401 4402 4403 /** 4404 * Obtain information about the given daemon 4405 * (not fully implemented!). 4406 * 4407 * @param daemon what daemon to get information about 4408 * @param info_type what information is desired? 4409 * @param ... depends on @a info_type 4410 * @return NULL if this information is not available 4411 * (or if the @a info_type is unknown) 4412 * @ingroup specialized 4413 */ 4414 _MHD_EXTERN const union MHD_DaemonInfo * 4415 MHD_get_daemon_info (struct MHD_Daemon *daemon, 4416 enum MHD_DaemonInfoType info_type, 4417 ...); 4418 4419 4420 /** 4421 * Obtain the version of this library 4422 * 4423 * @return static version string, e.g. "0.9.9" 4424 * @ingroup specialized 4425 */ 4426 _MHD_EXTERN const char * 4427 MHD_get_version (void); 4428 4429 4430 /** 4431 * Obtain the version of this library as a binary value. 4432 * 4433 * @return version binary value, e.g. "0x00090900" (#MHD_VERSION of 4434 * compiled MHD binary) 4435 * @note Available since #MHD_VERSION 0x00097602 4436 * @ingroup specialized 4437 */ 4438 _MHD_EXTERN uint32_t 4439 MHD_get_version_bin (void); 4440 4441 4442 /** 4443 * Types of information about MHD features, 4444 * used by #MHD_is_feature_supported(). 4445 */ 4446 enum MHD_FEATURE 4447 { 4448 /** 4449 * Get whether messages are supported. If supported then in debug 4450 * mode messages can be printed to stderr or to external logger. 4451 */ 4452 MHD_FEATURE_MESSAGES = 1, 4453 4454 /** 4455 * Get whether HTTPS is supported. If supported then flag 4456 * #MHD_USE_TLS and options #MHD_OPTION_HTTPS_MEM_KEY, 4457 * #MHD_OPTION_HTTPS_MEM_CERT, #MHD_OPTION_HTTPS_MEM_TRUST, 4458 * #MHD_OPTION_HTTPS_MEM_DHPARAMS, #MHD_OPTION_HTTPS_CRED_TYPE, 4459 * #MHD_OPTION_HTTPS_PRIORITIES can be used. 4460 */ 4461 MHD_FEATURE_TLS = 2, 4462 MHD_FEATURE_SSL = 2, 4463 4464 /** 4465 * Get whether option #MHD_OPTION_HTTPS_CERT_CALLBACK is 4466 * supported. 4467 */ 4468 MHD_FEATURE_HTTPS_CERT_CALLBACK = 3, 4469 4470 /** 4471 * Get whether IPv6 is supported. If supported then flag 4472 * #MHD_USE_IPv6 can be used. 4473 */ 4474 MHD_FEATURE_IPv6 = 4, 4475 4476 /** 4477 * Get whether IPv6 without IPv4 is supported. If not supported 4478 * then IPv4 is always enabled in IPv6 sockets and 4479 * flag #MHD_USE_DUAL_STACK is always used when #MHD_USE_IPv6 is 4480 * specified. 4481 */ 4482 MHD_FEATURE_IPv6_ONLY = 5, 4483 4484 /** 4485 * Get whether `poll()` is supported. If supported then flag 4486 * #MHD_USE_POLL can be used. 4487 */ 4488 MHD_FEATURE_POLL = 6, 4489 4490 /** 4491 * Get whether `epoll()` is supported. If supported then Flags 4492 * #MHD_USE_EPOLL and 4493 * #MHD_USE_EPOLL_INTERNAL_THREAD can be used. 4494 */ 4495 MHD_FEATURE_EPOLL = 7, 4496 4497 /** 4498 * Get whether shutdown on listen socket to signal other 4499 * threads is supported. If not supported flag 4500 * #MHD_USE_ITC is automatically forced. 4501 */ 4502 MHD_FEATURE_SHUTDOWN_LISTEN_SOCKET = 8, 4503 4504 /** 4505 * Get whether socketpair is used internally instead of pipe to 4506 * signal other threads. 4507 */ 4508 MHD_FEATURE_SOCKETPAIR = 9, 4509 4510 /** 4511 * Get whether TCP Fast Open is supported. If supported then 4512 * flag #MHD_USE_TCP_FASTOPEN and option 4513 * #MHD_OPTION_TCP_FASTOPEN_QUEUE_SIZE can be used. 4514 */ 4515 MHD_FEATURE_TCP_FASTOPEN = 10, 4516 4517 /** 4518 * Get whether HTTP Basic authorization is supported. If supported 4519 * then functions #MHD_basic_auth_get_username_password and 4520 * #MHD_queue_basic_auth_fail_response can be used. 4521 */ 4522 MHD_FEATURE_BASIC_AUTH = 11, 4523 4524 /** 4525 * Get whether HTTP Digest authorization is supported. If 4526 * supported then options #MHD_OPTION_DIGEST_AUTH_RANDOM, 4527 * #MHD_OPTION_NONCE_NC_SIZE and 4528 * #MHD_digest_auth_check() can be used. 4529 */ 4530 MHD_FEATURE_DIGEST_AUTH = 12, 4531 4532 /** 4533 * Get whether postprocessor is supported. If supported then 4534 * functions #MHD_create_post_processor(), #MHD_post_process() and 4535 * #MHD_destroy_post_processor() can 4536 * be used. 4537 */ 4538 MHD_FEATURE_POSTPROCESSOR = 13, 4539 4540 /** 4541 * Get whether password encrypted private key for HTTPS daemon is 4542 * supported. If supported then option 4543 * ::MHD_OPTION_HTTPS_KEY_PASSWORD can be used. 4544 */ 4545 MHD_FEATURE_HTTPS_KEY_PASSWORD = 14, 4546 4547 /** 4548 * Get whether reading files beyond 2 GiB boundary is supported. 4549 * If supported then #MHD_create_response_from_fd(), 4550 * #MHD_create_response_from_fd64 #MHD_create_response_from_fd_at_offset() 4551 * and #MHD_create_response_from_fd_at_offset64() can be used with sizes and 4552 * offsets larger than 2 GiB. If not supported value of size+offset is 4553 * limited to 2 GiB. 4554 */ 4555 MHD_FEATURE_LARGE_FILE = 15, 4556 4557 /** 4558 * Get whether MHD set names on generated threads. 4559 */ 4560 MHD_FEATURE_THREAD_NAMES = 16, 4561 MHD_THREAD_NAMES = 16, 4562 4563 /** 4564 * Get whether HTTP "Upgrade" is supported. 4565 * If supported then #MHD_ALLOW_UPGRADE, #MHD_upgrade_action() and 4566 * #MHD_create_response_for_upgrade() can be used. 4567 */ 4568 MHD_FEATURE_UPGRADE = 17, 4569 4570 /** 4571 * Get whether it's safe to use same FD for multiple calls of 4572 * #MHD_create_response_from_fd() and whether it's safe to use single 4573 * response generated by #MHD_create_response_from_fd() with multiple 4574 * connections at same time. 4575 * If #MHD_is_feature_supported() return #MHD_NO for this feature then 4576 * usage of responses with same file FD in multiple parallel threads may 4577 * results in incorrect data sent to remote client. 4578 * It's always safe to use same file FD in multiple responses if MHD 4579 * is run in any single thread mode. 4580 */ 4581 MHD_FEATURE_RESPONSES_SHARED_FD = 18, 4582 4583 /** 4584 * Get whether MHD support automatic detection of bind port number. 4585 * @sa #MHD_DAEMON_INFO_BIND_PORT 4586 */ 4587 MHD_FEATURE_AUTODETECT_BIND_PORT = 19, 4588 4589 /** 4590 * Get whether MHD supports automatic SIGPIPE suppression. 4591 * If SIGPIPE suppression is not supported, application must handle 4592 * SIGPIPE signal by itself. 4593 */ 4594 MHD_FEATURE_AUTOSUPPRESS_SIGPIPE = 20, 4595 4596 /** 4597 * Get whether MHD use system's sendfile() function to send 4598 * file-FD based responses over non-TLS connections. 4599 * @note Since v0.9.56 4600 */ 4601 MHD_FEATURE_SENDFILE = 21, 4602 4603 /** 4604 * Get whether MHD supports threads. 4605 */ 4606 MHD_FEATURE_THREADS = 22, 4607 4608 /** 4609 * Get whether option #MHD_OPTION_HTTPS_CERT_CALLBACK2 is 4610 * supported. 4611 */ 4612 MHD_FEATURE_HTTPS_CERT_CALLBACK2 = 23 4613 } _MHD_FIXED_ENUM; 4614 4615 4616 /** 4617 * Get information about supported MHD features. 4618 * Indicate that MHD was compiled with or without support for 4619 * particular feature. Some features require additional support 4620 * by kernel. Kernel support is not checked by this function. 4621 * 4622 * @param feature type of requested information 4623 * @return #MHD_YES if feature is supported by MHD, #MHD_NO if 4624 * feature is not supported or feature is unknown. 4625 * @ingroup specialized 4626 */ 4627 _MHD_EXTERN enum MHD_Result 4628 MHD_is_feature_supported (enum MHD_FEATURE feature); 4629 4630 4631 #ifdef __cplusplus 4632 #if 0 /* keep Emacsens' auto-indent happy */ 4633 { 4634 #endif 4635 } 4636 #endif 4637 4638 #endif