microhttpd.h (256144B)
1 /* 2 This file is part of libmicrohttpd 3 Copyright (C) 2006-2021 Christian Grothoff (and other contributing authors) 4 Copyright (C) 2014-2023 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 #ifndef __cplusplus 84 # define MHD_C_DECLRATIONS_START_HERE_ /* Empty */ 85 # define MHD_C_DECLRATIONS_FINISH_HERE_ /* Empty */ 86 #else /* __cplusplus */ 87 /* *INDENT-OFF* */ 88 # define MHD_C_DECLRATIONS_START_HERE_ extern "C" { 89 # define MHD_C_DECLRATIONS_FINISH_HERE_ } 90 /* *INDENT-ON* */ 91 #endif /* __cplusplus */ 92 93 94 MHD_C_DECLRATIONS_START_HERE_ 95 96 97 /** 98 * Current version of the library in packed BCD form. 99 * @note Version number components are coded as Simple Binary-Coded Decimal 100 * (also called Natural BCD or BCD 8421). While they are hexadecimal numbers, 101 * they are parsed as decimal numbers. 102 * Example: 0x01093001 = 1.9.30-1. 103 */ 104 #define MHD_VERSION 0x01000201 105 106 /* If generic headers don't work on your platform, include headers 107 which define 'va_list', 'size_t', 'ssize_t', 'intptr_t', 'off_t', 108 'uint8_t', 'uint16_t', 'int32_t', 'uint32_t', 'int64_t', 'uint64_t', 109 'struct sockaddr', 'socklen_t', 'fd_set' and "#define MHD_PLATFORM_H" before 110 including "microhttpd.h". Then the following "standard" 111 includes won't be used (which might be a good idea, especially 112 on platforms where they do not exist). 113 */ 114 #ifndef MHD_PLATFORM_H 115 #if defined(_WIN32) && ! defined(__CYGWIN__) && \ 116 ! defined(_CRT_DECLARE_NONSTDC_NAMES) 117 /* Declare POSIX-compatible names */ 118 #define _CRT_DECLARE_NONSTDC_NAMES 1 119 #endif /* _WIN32 && ! __CYGWIN__ && ! _CRT_DECLARE_NONSTDC_NAMES */ 120 #include <stdarg.h> 121 #include <stdint.h> 122 #include <sys/types.h> 123 #if ! defined(_WIN32) || defined(__CYGWIN__) 124 #include <unistd.h> 125 #include <sys/time.h> 126 #include <sys/socket.h> 127 #else /* _WIN32 && ! __CYGWIN__ */ 128 #include <ws2tcpip.h> 129 #if defined(_MSC_FULL_VER) && ! defined(_SSIZE_T_DEFINED) 130 #define _SSIZE_T_DEFINED 131 typedef intptr_t ssize_t; 132 #endif /* !_SSIZE_T_DEFINED */ 133 #endif /* _WIN32 && ! __CYGWIN__ */ 134 #endif 135 136 #if defined(__CYGWIN__) && ! defined(_SYS_TYPES_FD_SET) 137 /* Do not define __USE_W32_SOCKETS under Cygwin! */ 138 #error Cygwin with winsock fd_set is not supported 139 #endif 140 141 #ifdef __has_attribute 142 #if __has_attribute (flag_enum) 143 #define _MHD_FLAGS_ENUM __attribute__((flag_enum)) 144 #endif /* flag_enum */ 145 #if __has_attribute (enum_extensibility) 146 #define _MHD_FIXED_ENUM __attribute__((enum_extensibility (closed))) 147 #endif /* enum_extensibility */ 148 #endif /* __has_attribute */ 149 150 #ifndef _MHD_FLAGS_ENUM 151 #define _MHD_FLAGS_ENUM 152 #endif /* _MHD_FLAGS_ENUM */ 153 #ifndef _MHD_FIXED_ENUM 154 #define _MHD_FIXED_ENUM 155 #endif /* _MHD_FIXED_ENUM */ 156 157 #define _MHD_FIXED_FLAGS_ENUM _MHD_FIXED_ENUM _MHD_FLAGS_ENUM 158 159 /** 160 * Operational results from MHD calls. 161 */ 162 enum MHD_Result 163 { 164 /** 165 * MHD result code for "NO". 166 */ 167 MHD_NO = 0, 168 169 /** 170 * MHD result code for "YES". 171 */ 172 MHD_YES = 1 173 174 } _MHD_FIXED_ENUM; 175 176 /** 177 * Constant used to indicate unknown size (use when 178 * creating a response). 179 */ 180 #ifdef UINT64_MAX 181 #define MHD_SIZE_UNKNOWN UINT64_MAX 182 #else 183 #define MHD_SIZE_UNKNOWN ((uint64_t) -1LL) 184 #endif 185 186 #define MHD_CONTENT_READER_END_OF_STREAM ((ssize_t) -1) 187 #define MHD_CONTENT_READER_END_WITH_ERROR ((ssize_t) -2) 188 189 #ifndef _MHD_EXTERN 190 #if defined(_WIN32) && defined(MHD_W32LIB) 191 #define _MHD_EXTERN extern 192 #elif defined(_WIN32) && defined(MHD_W32DLL) 193 /* Define MHD_W32DLL when using MHD as W32 .DLL to speed up linker a little */ 194 #define _MHD_EXTERN __declspec(dllimport) 195 #else 196 #define _MHD_EXTERN extern 197 #endif 198 #endif 199 200 #ifndef MHD_SOCKET_DEFINED 201 /** 202 * MHD_socket is type for socket FDs 203 */ 204 #if ! defined(_WIN32) || defined(_SYS_TYPES_FD_SET) 205 #define MHD_POSIX_SOCKETS 1 206 typedef int MHD_socket; 207 #define MHD_INVALID_SOCKET (-1) 208 #else /* !defined(_WIN32) || defined(_SYS_TYPES_FD_SET) */ 209 #define MHD_WINSOCK_SOCKETS 1 210 #include <winsock2.h> 211 typedef SOCKET MHD_socket; 212 #define MHD_INVALID_SOCKET (INVALID_SOCKET) 213 #endif /* !defined(_WIN32) || defined(_SYS_TYPES_FD_SET) */ 214 #define MHD_SOCKET_DEFINED 1 215 #endif /* MHD_SOCKET_DEFINED */ 216 217 /** 218 * Define MHD_NO_DEPRECATION before including "microhttpd.h" to disable deprecation messages 219 */ 220 #ifdef MHD_NO_DEPRECATION 221 #define _MHD_DEPR_MACRO(msg) 222 #define _MHD_NO_DEPR_IN_MACRO 1 223 #define _MHD_DEPR_IN_MACRO(msg) 224 #define _MHD_NO_DEPR_FUNC 1 225 #define _MHD_DEPR_FUNC(msg) 226 #endif /* MHD_NO_DEPRECATION */ 227 228 #ifndef _MHD_DEPR_MACRO 229 #if defined(_MSC_FULL_VER) && _MSC_VER + 0 >= 1500 230 /* VS 2008 or later */ 231 /* Stringify macros */ 232 #define _MHD_INSTRMACRO(a) #a 233 #define _MHD_STRMACRO(a) _MHD_INSTRMACRO (a) 234 /* deprecation message */ 235 #define _MHD_DEPR_MACRO(msg) \ 236 __pragma \ 237 (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 * @defgroup httpcode HTTP response codes. 334 * These are the status codes defined for HTTP responses. 335 * See: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml 336 * Registry export date: 2023-09-29 337 * @{ 338 */ 339 340 /* 100 "Continue". RFC9110, Section 15.2.1. */ 341 #define MHD_HTTP_CONTINUE 100 342 /* 101 "Switching Protocols". RFC9110, Section 15.2.2. */ 343 #define MHD_HTTP_SWITCHING_PROTOCOLS 101 344 /* 102 "Processing". RFC2518. */ 345 #define MHD_HTTP_PROCESSING 102 346 /* 103 "Early Hints". RFC8297. */ 347 #define MHD_HTTP_EARLY_HINTS 103 348 349 /* 200 "OK". RFC9110, Section 15.3.1. */ 350 #define MHD_HTTP_OK 200 351 /* 201 "Created". RFC9110, Section 15.3.2. */ 352 #define MHD_HTTP_CREATED 201 353 /* 202 "Accepted". RFC9110, Section 15.3.3. */ 354 #define MHD_HTTP_ACCEPTED 202 355 /* 203 "Non-Authoritative Information". RFC9110, Section 15.3.4. */ 356 #define MHD_HTTP_NON_AUTHORITATIVE_INFORMATION 203 357 /* 204 "No Content". RFC9110, Section 15.3.5. */ 358 #define MHD_HTTP_NO_CONTENT 204 359 /* 205 "Reset Content". RFC9110, Section 15.3.6. */ 360 #define MHD_HTTP_RESET_CONTENT 205 361 /* 206 "Partial Content". RFC9110, Section 15.3.7. */ 362 #define MHD_HTTP_PARTIAL_CONTENT 206 363 /* 207 "Multi-Status". RFC4918. */ 364 #define MHD_HTTP_MULTI_STATUS 207 365 /* 208 "Already Reported". RFC5842. */ 366 #define MHD_HTTP_ALREADY_REPORTED 208 367 368 /* 226 "IM Used". RFC3229. */ 369 #define MHD_HTTP_IM_USED 226 370 371 /* 300 "Multiple Choices". RFC9110, Section 15.4.1. */ 372 #define MHD_HTTP_MULTIPLE_CHOICES 300 373 /* 301 "Moved Permanently". RFC9110, Section 15.4.2. */ 374 #define MHD_HTTP_MOVED_PERMANENTLY 301 375 /* 302 "Found". RFC9110, Section 15.4.3. */ 376 #define MHD_HTTP_FOUND 302 377 /* 303 "See Other". RFC9110, Section 15.4.4. */ 378 #define MHD_HTTP_SEE_OTHER 303 379 /* 304 "Not Modified". RFC9110, Section 15.4.5. */ 380 #define MHD_HTTP_NOT_MODIFIED 304 381 /* 305 "Use Proxy". RFC9110, Section 15.4.6. */ 382 #define MHD_HTTP_USE_PROXY 305 383 /* 306 "Switch Proxy". Not used! RFC9110, Section 15.4.7. */ 384 #define MHD_HTTP_SWITCH_PROXY 306 385 /* 307 "Temporary Redirect". RFC9110, Section 15.4.8. */ 386 #define MHD_HTTP_TEMPORARY_REDIRECT 307 387 /* 308 "Permanent Redirect". RFC9110, Section 15.4.9. */ 388 #define MHD_HTTP_PERMANENT_REDIRECT 308 389 390 /* 400 "Bad Request". RFC9110, Section 15.5.1. */ 391 #define MHD_HTTP_BAD_REQUEST 400 392 /* 401 "Unauthorized". RFC9110, Section 15.5.2. */ 393 #define MHD_HTTP_UNAUTHORIZED 401 394 /* 402 "Payment Required". RFC9110, Section 15.5.3. */ 395 #define MHD_HTTP_PAYMENT_REQUIRED 402 396 /* 403 "Forbidden". RFC9110, Section 15.5.4. */ 397 #define MHD_HTTP_FORBIDDEN 403 398 /* 404 "Not Found". RFC9110, Section 15.5.5. */ 399 #define MHD_HTTP_NOT_FOUND 404 400 /* 405 "Method Not Allowed". RFC9110, Section 15.5.6. */ 401 #define MHD_HTTP_METHOD_NOT_ALLOWED 405 402 /* 406 "Not Acceptable". RFC9110, Section 15.5.7. */ 403 #define MHD_HTTP_NOT_ACCEPTABLE 406 404 /* 407 "Proxy Authentication Required". RFC9110, Section 15.5.8. */ 405 #define MHD_HTTP_PROXY_AUTHENTICATION_REQUIRED 407 406 /* 408 "Request Timeout". RFC9110, Section 15.5.9. */ 407 #define MHD_HTTP_REQUEST_TIMEOUT 408 408 /* 409 "Conflict". RFC9110, Section 15.5.10. */ 409 #define MHD_HTTP_CONFLICT 409 410 /* 410 "Gone". RFC9110, Section 15.5.11. */ 411 #define MHD_HTTP_GONE 410 412 /* 411 "Length Required". RFC9110, Section 15.5.12. */ 413 #define MHD_HTTP_LENGTH_REQUIRED 411 414 /* 412 "Precondition Failed". RFC9110, Section 15.5.13. */ 415 #define MHD_HTTP_PRECONDITION_FAILED 412 416 /* 413 "Content Too Large". RFC9110, Section 15.5.14. */ 417 #define MHD_HTTP_CONTENT_TOO_LARGE 413 418 /* 414 "URI Too Long". RFC9110, Section 15.5.15. */ 419 #define MHD_HTTP_URI_TOO_LONG 414 420 /* 415 "Unsupported Media Type". RFC9110, Section 15.5.16. */ 421 #define MHD_HTTP_UNSUPPORTED_MEDIA_TYPE 415 422 /* 416 "Range Not Satisfiable". RFC9110, Section 15.5.17. */ 423 #define MHD_HTTP_RANGE_NOT_SATISFIABLE 416 424 /* 417 "Expectation Failed". RFC9110, Section 15.5.18. */ 425 #define MHD_HTTP_EXPECTATION_FAILED 417 426 427 428 /* 421 "Misdirected Request". RFC9110, Section 15.5.20. */ 429 #define MHD_HTTP_MISDIRECTED_REQUEST 421 430 /* 422 "Unprocessable Content". RFC9110, Section 15.5.21. */ 431 #define MHD_HTTP_UNPROCESSABLE_CONTENT 422 432 /* 423 "Locked". RFC4918. */ 433 #define MHD_HTTP_LOCKED 423 434 /* 424 "Failed Dependency". RFC4918. */ 435 #define MHD_HTTP_FAILED_DEPENDENCY 424 436 /* 425 "Too Early". RFC8470. */ 437 #define MHD_HTTP_TOO_EARLY 425 438 /* 426 "Upgrade Required". RFC9110, Section 15.5.22. */ 439 #define MHD_HTTP_UPGRADE_REQUIRED 426 440 441 /* 428 "Precondition Required". RFC6585. */ 442 #define MHD_HTTP_PRECONDITION_REQUIRED 428 443 /* 429 "Too Many Requests". RFC6585. */ 444 #define MHD_HTTP_TOO_MANY_REQUESTS 429 445 446 /* 431 "Request Header Fields Too Large". RFC6585. */ 447 #define MHD_HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE 431 448 449 /* 451 "Unavailable For Legal Reasons". RFC7725. */ 450 #define MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS 451 451 452 /* 500 "Internal Server Error". RFC9110, Section 15.6.1. */ 453 #define MHD_HTTP_INTERNAL_SERVER_ERROR 500 454 /* 501 "Not Implemented". RFC9110, Section 15.6.2. */ 455 #define MHD_HTTP_NOT_IMPLEMENTED 501 456 /* 502 "Bad Gateway". RFC9110, Section 15.6.3. */ 457 #define MHD_HTTP_BAD_GATEWAY 502 458 /* 503 "Service Unavailable". RFC9110, Section 15.6.4. */ 459 #define MHD_HTTP_SERVICE_UNAVAILABLE 503 460 /* 504 "Gateway Timeout". RFC9110, Section 15.6.5. */ 461 #define MHD_HTTP_GATEWAY_TIMEOUT 504 462 /* 505 "HTTP Version Not Supported". RFC9110, Section 15.6.6. */ 463 #define MHD_HTTP_HTTP_VERSION_NOT_SUPPORTED 505 464 /* 506 "Variant Also Negotiates". RFC2295. */ 465 #define MHD_HTTP_VARIANT_ALSO_NEGOTIATES 506 466 /* 507 "Insufficient Storage". RFC4918. */ 467 #define MHD_HTTP_INSUFFICIENT_STORAGE 507 468 /* 508 "Loop Detected". RFC5842. */ 469 #define MHD_HTTP_LOOP_DETECTED 508 470 471 /* 510 "Not Extended". (OBSOLETED) RFC2774; status-change-http-experiments-to-historic. */ 472 #define MHD_HTTP_NOT_EXTENDED 510 473 /* 511 "Network Authentication Required". RFC6585. */ 474 #define MHD_HTTP_NETWORK_AUTHENTICATION_REQUIRED 511 475 476 477 /* Not registered non-standard codes */ 478 /* 449 "Reply With". MS IIS extension. */ 479 #define MHD_HTTP_RETRY_WITH 449 480 481 /* 450 "Blocked by Windows Parental Controls". MS extension. */ 482 #define MHD_HTTP_BLOCKED_BY_WINDOWS_PARENTAL_CONTROLS 450 483 484 /* 509 "Bandwidth Limit Exceeded". Apache extension. */ 485 #define MHD_HTTP_BANDWIDTH_LIMIT_EXCEEDED 509 486 487 /* Deprecated names and codes */ 488 /** @deprecated */ 489 #define MHD_HTTP_METHOD_NOT_ACCEPTABLE _MHD_DEPR_IN_MACRO ( \ 490 "Value MHD_HTTP_METHOD_NOT_ACCEPTABLE is deprecated, use MHD_HTTP_NOT_ACCEPTABLE" \ 491 ) 406 492 493 /** @deprecated */ 494 #define MHD_HTTP_REQUEST_ENTITY_TOO_LARGE _MHD_DEPR_IN_MACRO ( \ 495 "Value MHD_HTTP_REQUEST_ENTITY_TOO_LARGE is deprecated, use MHD_HTTP_CONTENT_TOO_LARGE" \ 496 ) 413 497 498 /** @deprecated */ 499 #define MHD_HTTP_PAYLOAD_TOO_LARGE _MHD_DEPR_IN_MACRO ( \ 500 "Value MHD_HTTP_PAYLOAD_TOO_LARGE is deprecated use MHD_HTTP_CONTENT_TOO_LARGE" \ 501 ) 413 502 503 /** @deprecated */ 504 #define MHD_HTTP_REQUEST_URI_TOO_LONG _MHD_DEPR_IN_MACRO ( \ 505 "Value MHD_HTTP_REQUEST_URI_TOO_LONG is deprecated, use MHD_HTTP_URI_TOO_LONG" \ 506 ) 414 507 508 /** @deprecated */ 509 #define MHD_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE _MHD_DEPR_IN_MACRO ( \ 510 "Value MHD_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE is deprecated, use MHD_HTTP_RANGE_NOT_SATISFIABLE" \ 511 ) 416 512 513 /** @deprecated */ 514 #define MHD_HTTP_UNPROCESSABLE_ENTITY _MHD_DEPR_IN_MACRO ( \ 515 "Value MHD_HTTP_UNPROCESSABLE_ENTITY is deprecated, use MHD_HTTP_UNPROCESSABLE_CONTENT" \ 516 ) 422 517 518 /** @deprecated */ 519 #define MHD_HTTP_UNORDERED_COLLECTION _MHD_DEPR_IN_MACRO ( \ 520 "Value MHD_HTTP_UNORDERED_COLLECTION is deprecated as it was removed from RFC" \ 521 ) 425 522 523 /** @deprecated */ 524 #define MHD_HTTP_NO_RESPONSE _MHD_DEPR_IN_MACRO ( \ 525 "Value MHD_HTTP_NO_RESPONSE is deprecated as it is nginx internal code for logs only" \ 526 ) 444 527 528 529 /** @} */ /* end of group httpcode */ 530 531 /** 532 * Returns the string reason phrase for a response code. 533 * 534 * If message string is not available for a status code, 535 * "Unknown" string will be returned. 536 */ 537 _MHD_EXTERN const char * 538 MHD_get_reason_phrase_for (unsigned int code); 539 540 541 /** 542 * Returns the length of the string reason phrase for a response code. 543 * 544 * If message string is not available for a status code, 545 * 0 is returned. 546 */ 547 _MHD_EXTERN size_t 548 MHD_get_reason_phrase_len_for (unsigned int code); 549 550 /** 551 * Flag to be or-ed with MHD_HTTP status code for 552 * SHOUTcast. This will cause the response to begin 553 * with the SHOUTcast "ICY" line instead of "HTTP/1.x". 554 * @ingroup specialized 555 */ 556 #define MHD_ICY_FLAG ((uint32_t) (((uint32_t) 1) << 31)) 557 558 /** 559 * @defgroup headers HTTP headers 560 * The standard headers found in HTTP requests and responses. 561 * See: https://www.iana.org/assignments/http-fields/http-fields.xhtml 562 * Registry export date: 2023-10-02 563 * @{ 564 */ 565 566 /* Main HTTP headers. */ 567 /* Permanent. RFC9110, Section 12.5.1: HTTP Semantics */ 568 #define MHD_HTTP_HEADER_ACCEPT "Accept" 569 /* Deprecated. RFC9110, Section 12.5.2: HTTP Semantics */ 570 #define MHD_HTTP_HEADER_ACCEPT_CHARSET "Accept-Charset" 571 /* Permanent. RFC9110, Section 12.5.3: HTTP Semantics */ 572 #define MHD_HTTP_HEADER_ACCEPT_ENCODING "Accept-Encoding" 573 /* Permanent. RFC9110, Section 12.5.4: HTTP Semantics */ 574 #define MHD_HTTP_HEADER_ACCEPT_LANGUAGE "Accept-Language" 575 /* Permanent. RFC9110, Section 14.3: HTTP Semantics */ 576 #define MHD_HTTP_HEADER_ACCEPT_RANGES "Accept-Ranges" 577 /* Permanent. RFC9111, Section 5.1: HTTP Caching */ 578 #define MHD_HTTP_HEADER_AGE "Age" 579 /* Permanent. RFC9110, Section 10.2.1: HTTP Semantics */ 580 #define MHD_HTTP_HEADER_ALLOW "Allow" 581 /* Permanent. RFC9110, Section 11.6.3: HTTP Semantics */ 582 #define MHD_HTTP_HEADER_AUTHENTICATION_INFO "Authentication-Info" 583 /* Permanent. RFC9110, Section 11.6.2: HTTP Semantics */ 584 #define MHD_HTTP_HEADER_AUTHORIZATION "Authorization" 585 /* Permanent. RFC9111, Section 5.2 */ 586 #define MHD_HTTP_HEADER_CACHE_CONTROL "Cache-Control" 587 /* Permanent. RFC9112, Section 9.6: HTTP/1.1 */ 588 #define MHD_HTTP_HEADER_CLOSE "Close" 589 /* Permanent. RFC9110, Section 7.6.1: HTTP Semantics */ 590 #define MHD_HTTP_HEADER_CONNECTION "Connection" 591 /* Permanent. RFC9110, Section 8.4: HTTP Semantics */ 592 #define MHD_HTTP_HEADER_CONTENT_ENCODING "Content-Encoding" 593 /* Permanent. RFC9110, Section 8.5: HTTP Semantics */ 594 #define MHD_HTTP_HEADER_CONTENT_LANGUAGE "Content-Language" 595 /* Permanent. RFC9110, Section 8.6: HTTP Semantics */ 596 #define MHD_HTTP_HEADER_CONTENT_LENGTH "Content-Length" 597 /* Permanent. RFC9110, Section 8.7: HTTP Semantics */ 598 #define MHD_HTTP_HEADER_CONTENT_LOCATION "Content-Location" 599 /* Permanent. RFC9110, Section 14.4: HTTP Semantics */ 600 #define MHD_HTTP_HEADER_CONTENT_RANGE "Content-Range" 601 /* Permanent. RFC9110, Section 8.3: HTTP Semantics */ 602 #define MHD_HTTP_HEADER_CONTENT_TYPE "Content-Type" 603 /* Permanent. RFC9110, Section 6.6.1: HTTP Semantics */ 604 #define MHD_HTTP_HEADER_DATE "Date" 605 /* Permanent. RFC9110, Section 8.8.3: HTTP Semantics */ 606 #define MHD_HTTP_HEADER_ETAG "ETag" 607 /* Permanent. RFC9110, Section 10.1.1: HTTP Semantics */ 608 #define MHD_HTTP_HEADER_EXPECT "Expect" 609 /* Permanent. RFC9111, Section 5.3: HTTP Caching */ 610 #define MHD_HTTP_HEADER_EXPIRES "Expires" 611 /* Permanent. RFC9110, Section 10.1.2: HTTP Semantics */ 612 #define MHD_HTTP_HEADER_FROM "From" 613 /* Permanent. RFC9110, Section 7.2: HTTP Semantics */ 614 #define MHD_HTTP_HEADER_HOST "Host" 615 /* Permanent. RFC9110, Section 13.1.1: HTTP Semantics */ 616 #define MHD_HTTP_HEADER_IF_MATCH "If-Match" 617 /* Permanent. RFC9110, Section 13.1.3: HTTP Semantics */ 618 #define MHD_HTTP_HEADER_IF_MODIFIED_SINCE "If-Modified-Since" 619 /* Permanent. RFC9110, Section 13.1.2: HTTP Semantics */ 620 #define MHD_HTTP_HEADER_IF_NONE_MATCH "If-None-Match" 621 /* Permanent. RFC9110, Section 13.1.5: HTTP Semantics */ 622 #define MHD_HTTP_HEADER_IF_RANGE "If-Range" 623 /* Permanent. RFC9110, Section 13.1.4: HTTP Semantics */ 624 #define MHD_HTTP_HEADER_IF_UNMODIFIED_SINCE "If-Unmodified-Since" 625 /* Permanent. RFC9110, Section 8.8.2: HTTP Semantics */ 626 #define MHD_HTTP_HEADER_LAST_MODIFIED "Last-Modified" 627 /* Permanent. RFC9110, Section 10.2.2: HTTP Semantics */ 628 #define MHD_HTTP_HEADER_LOCATION "Location" 629 /* Permanent. RFC9110, Section 7.6.2: HTTP Semantics */ 630 #define MHD_HTTP_HEADER_MAX_FORWARDS "Max-Forwards" 631 /* Permanent. RFC9112, Appendix B.1: HTTP/1.1 */ 632 #define MHD_HTTP_HEADER_MIME_VERSION "MIME-Version" 633 /* Deprecated. RFC9111, Section 5.4: HTTP Caching */ 634 #define MHD_HTTP_HEADER_PRAGMA "Pragma" 635 /* Permanent. RFC9110, Section 11.7.1: HTTP Semantics */ 636 #define MHD_HTTP_HEADER_PROXY_AUTHENTICATE "Proxy-Authenticate" 637 /* Permanent. RFC9110, Section 11.7.3: HTTP Semantics */ 638 #define MHD_HTTP_HEADER_PROXY_AUTHENTICATION_INFO "Proxy-Authentication-Info" 639 /* Permanent. RFC9110, Section 11.7.2: HTTP Semantics */ 640 #define MHD_HTTP_HEADER_PROXY_AUTHORIZATION "Proxy-Authorization" 641 /* Permanent. RFC9110, Section 14.2: HTTP Semantics */ 642 #define MHD_HTTP_HEADER_RANGE "Range" 643 /* Permanent. RFC9110, Section 10.1.3: HTTP Semantics */ 644 #define MHD_HTTP_HEADER_REFERER "Referer" 645 /* Permanent. RFC9110, Section 10.2.3: HTTP Semantics */ 646 #define MHD_HTTP_HEADER_RETRY_AFTER "Retry-After" 647 /* Permanent. RFC9110, Section 10.2.4: HTTP Semantics */ 648 #define MHD_HTTP_HEADER_SERVER "Server" 649 /* Permanent. RFC9110, Section 10.1.4: HTTP Semantics */ 650 #define MHD_HTTP_HEADER_TE "TE" 651 /* Permanent. RFC9110, Section 6.6.2: HTTP Semantics */ 652 #define MHD_HTTP_HEADER_TRAILER "Trailer" 653 /* Permanent. RFC9112, Section 6.1: HTTP Semantics */ 654 #define MHD_HTTP_HEADER_TRANSFER_ENCODING "Transfer-Encoding" 655 /* Permanent. RFC9110, Section 7.8: HTTP Semantics */ 656 #define MHD_HTTP_HEADER_UPGRADE "Upgrade" 657 /* Permanent. RFC9110, Section 10.1.5: HTTP Semantics */ 658 #define MHD_HTTP_HEADER_USER_AGENT "User-Agent" 659 /* Permanent. RFC9110, Section 12.5.5: HTTP Semantics */ 660 #define MHD_HTTP_HEADER_VARY "Vary" 661 /* Permanent. RFC9110, Section 7.6.3: HTTP Semantics */ 662 #define MHD_HTTP_HEADER_VIA "Via" 663 /* Permanent. RFC9110, Section 11.6.1: HTTP Semantics */ 664 #define MHD_HTTP_HEADER_WWW_AUTHENTICATE "WWW-Authenticate" 665 /* Permanent. RFC9110, Section 12.5.5: HTTP Semantics */ 666 #define MHD_HTTP_HEADER_ASTERISK "*" 667 668 /* Additional HTTP headers. */ 669 /* Permanent. RFC 3229: Delta encoding in HTTP */ 670 #define MHD_HTTP_HEADER_A_IM "A-IM" 671 /* Permanent. RFC 2324: Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0) */ 672 #define MHD_HTTP_HEADER_ACCEPT_ADDITIONS "Accept-Additions" 673 /* Permanent. RFC 8942, Section 3.1: HTTP Client Hints */ 674 #define MHD_HTTP_HEADER_ACCEPT_CH "Accept-CH" 675 /* Permanent. RFC 7089: HTTP Framework for Time-Based Access to Resource States -- Memento */ 676 #define MHD_HTTP_HEADER_ACCEPT_DATETIME "Accept-Datetime" 677 /* Permanent. RFC 2295: Transparent Content Negotiation in HTTP */ 678 #define MHD_HTTP_HEADER_ACCEPT_FEATURES "Accept-Features" 679 /* Permanent. RFC 5789: PATCH Method for HTTP */ 680 #define MHD_HTTP_HEADER_ACCEPT_PATCH "Accept-Patch" 681 /* Permanent. Linked Data Platform 1.0 */ 682 #define MHD_HTTP_HEADER_ACCEPT_POST "Accept-Post" 683 /* Permanent. RFC-ietf-httpbis-message-signatures-19, Section 5.1: HTTP Message Signatures */ 684 #define MHD_HTTP_HEADER_ACCEPT_SIGNATURE "Accept-Signature" 685 /* Permanent. Fetch */ 686 #define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_CREDENTIALS \ 687 "Access-Control-Allow-Credentials" 688 /* Permanent. Fetch */ 689 #define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_HEADERS \ 690 "Access-Control-Allow-Headers" 691 /* Permanent. Fetch */ 692 #define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_METHODS \ 693 "Access-Control-Allow-Methods" 694 /* Permanent. Fetch */ 695 #define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN \ 696 "Access-Control-Allow-Origin" 697 /* Permanent. Fetch */ 698 #define MHD_HTTP_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS \ 699 "Access-Control-Expose-Headers" 700 /* Permanent. Fetch */ 701 #define MHD_HTTP_HEADER_ACCESS_CONTROL_MAX_AGE "Access-Control-Max-Age" 702 /* Permanent. Fetch */ 703 #define MHD_HTTP_HEADER_ACCESS_CONTROL_REQUEST_HEADERS \ 704 "Access-Control-Request-Headers" 705 /* Permanent. Fetch */ 706 #define MHD_HTTP_HEADER_ACCESS_CONTROL_REQUEST_METHOD \ 707 "Access-Control-Request-Method" 708 /* Permanent. RFC 7639, Section 2: The ALPN HTTP Header Field */ 709 #define MHD_HTTP_HEADER_ALPN "ALPN" 710 /* Permanent. RFC 7838: HTTP Alternative Services */ 711 #define MHD_HTTP_HEADER_ALT_SVC "Alt-Svc" 712 /* Permanent. RFC 7838: HTTP Alternative Services */ 713 #define MHD_HTTP_HEADER_ALT_USED "Alt-Used" 714 /* Permanent. RFC 2295: Transparent Content Negotiation in HTTP */ 715 #define MHD_HTTP_HEADER_ALTERNATES "Alternates" 716 /* Permanent. RFC 4437: Web Distributed Authoring and Versioning (WebDAV) Redirect Reference Resources */ 717 #define MHD_HTTP_HEADER_APPLY_TO_REDIRECT_REF "Apply-To-Redirect-Ref" 718 /* Permanent. RFC 8053, Section 4: HTTP Authentication Extensions for Interactive Clients */ 719 #define MHD_HTTP_HEADER_AUTHENTICATION_CONTROL "Authentication-Control" 720 /* Permanent. RFC9211: The Cache-Status HTTP Response Header Field */ 721 #define MHD_HTTP_HEADER_CACHE_STATUS "Cache-Status" 722 /* Permanent. RFC 8607, Section 5.1: Calendaring Extensions to WebDAV (CalDAV): Managed Attachments */ 723 #define MHD_HTTP_HEADER_CAL_MANAGED_ID "Cal-Managed-ID" 724 /* Permanent. RFC 7809, Section 7.1: Calendaring Extensions to WebDAV (CalDAV): Time Zones by Reference */ 725 #define MHD_HTTP_HEADER_CALDAV_TIMEZONES "CalDAV-Timezones" 726 /* Permanent. RFC9297 */ 727 #define MHD_HTTP_HEADER_CAPSULE_PROTOCOL "Capsule-Protocol" 728 /* Permanent. RFC9213: Targeted HTTP Cache Control */ 729 #define MHD_HTTP_HEADER_CDN_CACHE_CONTROL "CDN-Cache-Control" 730 /* Permanent. RFC 8586: Loop Detection in Content Delivery Networks (CDNs) */ 731 #define MHD_HTTP_HEADER_CDN_LOOP "CDN-Loop" 732 /* Permanent. RFC 8739, Section 3.3: Support for Short-Term, Automatically Renewed (STAR) Certificates in the Automated Certificate Management Environment (ACME) */ 733 #define MHD_HTTP_HEADER_CERT_NOT_AFTER "Cert-Not-After" 734 /* Permanent. RFC 8739, Section 3.3: Support for Short-Term, Automatically Renewed (STAR) Certificates in the Automated Certificate Management Environment (ACME) */ 735 #define MHD_HTTP_HEADER_CERT_NOT_BEFORE "Cert-Not-Before" 736 /* Permanent. Clear Site Data */ 737 #define MHD_HTTP_HEADER_CLEAR_SITE_DATA "Clear-Site-Data" 738 /* Permanent. RFC9440, Section 2: Client-Cert HTTP Header Field */ 739 #define MHD_HTTP_HEADER_CLIENT_CERT "Client-Cert" 740 /* Permanent. RFC9440, Section 2: Client-Cert HTTP Header Field */ 741 #define MHD_HTTP_HEADER_CLIENT_CERT_CHAIN "Client-Cert-Chain" 742 /* Permanent. RFC-ietf-httpbis-digest-headers-13, Section 2: Digest Fields */ 743 #define MHD_HTTP_HEADER_CONTENT_DIGEST "Content-Digest" 744 /* Permanent. RFC 6266: Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP) */ 745 #define MHD_HTTP_HEADER_CONTENT_DISPOSITION "Content-Disposition" 746 /* Permanent. The HTTP Distribution and Replication Protocol */ 747 #define MHD_HTTP_HEADER_CONTENT_ID "Content-ID" 748 /* Permanent. Content Security Policy Level 3 */ 749 #define MHD_HTTP_HEADER_CONTENT_SECURITY_POLICY "Content-Security-Policy" 750 /* Permanent. Content Security Policy Level 3 */ 751 #define MHD_HTTP_HEADER_CONTENT_SECURITY_POLICY_REPORT_ONLY \ 752 "Content-Security-Policy-Report-Only" 753 /* Permanent. RFC 6265: HTTP State Management Mechanism */ 754 #define MHD_HTTP_HEADER_COOKIE "Cookie" 755 /* Permanent. HTML */ 756 #define MHD_HTTP_HEADER_CROSS_ORIGIN_EMBEDDER_POLICY \ 757 "Cross-Origin-Embedder-Policy" 758 /* Permanent. HTML */ 759 #define MHD_HTTP_HEADER_CROSS_ORIGIN_EMBEDDER_POLICY_REPORT_ONLY \ 760 "Cross-Origin-Embedder-Policy-Report-Only" 761 /* Permanent. HTML */ 762 #define MHD_HTTP_HEADER_CROSS_ORIGIN_OPENER_POLICY "Cross-Origin-Opener-Policy" 763 /* Permanent. HTML */ 764 #define MHD_HTTP_HEADER_CROSS_ORIGIN_OPENER_POLICY_REPORT_ONLY \ 765 "Cross-Origin-Opener-Policy-Report-Only" 766 /* Permanent. Fetch */ 767 #define MHD_HTTP_HEADER_CROSS_ORIGIN_RESOURCE_POLICY \ 768 "Cross-Origin-Resource-Policy" 769 /* Permanent. RFC 5323: Web Distributed Authoring and Versioning (WebDAV) SEARCH */ 770 #define MHD_HTTP_HEADER_DASL "DASL" 771 /* Permanent. RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) */ 772 #define MHD_HTTP_HEADER_DAV "DAV" 773 /* Permanent. RFC 3229: Delta encoding in HTTP */ 774 #define MHD_HTTP_HEADER_DELTA_BASE "Delta-Base" 775 /* Permanent. RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) */ 776 #define MHD_HTTP_HEADER_DEPTH "Depth" 777 /* Permanent. RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) */ 778 #define MHD_HTTP_HEADER_DESTINATION "Destination" 779 /* Permanent. The HTTP Distribution and Replication Protocol */ 780 #define MHD_HTTP_HEADER_DIFFERENTIAL_ID "Differential-ID" 781 /* Permanent. RFC9449: OAuth 2.0 Demonstrating Proof of Possession (DPoP) */ 782 #define MHD_HTTP_HEADER_DPOP "DPoP" 783 /* Permanent. RFC9449: OAuth 2.0 Demonstrating Proof of Possession (DPoP) */ 784 #define MHD_HTTP_HEADER_DPOP_NONCE "DPoP-Nonce" 785 /* Permanent. RFC 8470: Using Early Data in HTTP */ 786 #define MHD_HTTP_HEADER_EARLY_DATA "Early-Data" 787 /* Permanent. RFC9163: Expect-CT Extension for HTTP */ 788 #define MHD_HTTP_HEADER_EXPECT_CT "Expect-CT" 789 /* Permanent. RFC 7239: Forwarded HTTP Extension */ 790 #define MHD_HTTP_HEADER_FORWARDED "Forwarded" 791 /* Permanent. RFC 7486, Section 6.1.1: HTTP Origin-Bound Authentication (HOBA) */ 792 #define MHD_HTTP_HEADER_HOBAREG "Hobareg" 793 /* Permanent. RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) */ 794 #define MHD_HTTP_HEADER_IF "If" 795 /* Permanent. RFC 6338: Scheduling Extensions to CalDAV */ 796 #define MHD_HTTP_HEADER_IF_SCHEDULE_TAG_MATCH "If-Schedule-Tag-Match" 797 /* Permanent. RFC 3229: Delta encoding in HTTP */ 798 #define MHD_HTTP_HEADER_IM "IM" 799 /* Permanent. RFC 8473: Token Binding over HTTP */ 800 #define MHD_HTTP_HEADER_INCLUDE_REFERRED_TOKEN_BINDING_ID \ 801 "Include-Referred-Token-Binding-ID" 802 /* Permanent. RFC 2068: Hypertext Transfer Protocol -- HTTP/1.1 */ 803 #define MHD_HTTP_HEADER_KEEP_ALIVE "Keep-Alive" 804 /* Permanent. RFC 3253: Versioning Extensions to WebDAV: (Web Distributed Authoring and Versioning) */ 805 #define MHD_HTTP_HEADER_LABEL "Label" 806 /* Permanent. HTML */ 807 #define MHD_HTTP_HEADER_LAST_EVENT_ID "Last-Event-ID" 808 /* Permanent. RFC 8288: Web Linking */ 809 #define MHD_HTTP_HEADER_LINK "Link" 810 /* Permanent. RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) */ 811 #define MHD_HTTP_HEADER_LOCK_TOKEN "Lock-Token" 812 /* Permanent. RFC 7089: HTTP Framework for Time-Based Access to Resource States -- Memento */ 813 #define MHD_HTTP_HEADER_MEMENTO_DATETIME "Memento-Datetime" 814 /* Permanent. RFC 2227: Simple Hit-Metering and Usage-Limiting for HTTP */ 815 #define MHD_HTTP_HEADER_METER "Meter" 816 /* Permanent. RFC 2295: Transparent Content Negotiation in HTTP */ 817 #define MHD_HTTP_HEADER_NEGOTIATE "Negotiate" 818 /* Permanent. Network Error Logging */ 819 #define MHD_HTTP_HEADER_NEL "NEL" 820 /* Permanent. OData Version 4.01 Part 1: Protocol; OASIS; Chet_Ensign */ 821 #define MHD_HTTP_HEADER_ODATA_ENTITYID "OData-EntityId" 822 /* Permanent. OData Version 4.01 Part 1: Protocol; OASIS; Chet_Ensign */ 823 #define MHD_HTTP_HEADER_ODATA_ISOLATION "OData-Isolation" 824 /* Permanent. OData Version 4.01 Part 1: Protocol; OASIS; Chet_Ensign */ 825 #define MHD_HTTP_HEADER_ODATA_MAXVERSION "OData-MaxVersion" 826 /* Permanent. OData Version 4.01 Part 1: Protocol; OASIS; Chet_Ensign */ 827 #define MHD_HTTP_HEADER_ODATA_VERSION "OData-Version" 828 /* Permanent. RFC 8053, Section 3: HTTP Authentication Extensions for Interactive Clients */ 829 #define MHD_HTTP_HEADER_OPTIONAL_WWW_AUTHENTICATE "Optional-WWW-Authenticate" 830 /* Permanent. RFC 3648: Web Distributed Authoring and Versioning (WebDAV) Ordered Collections Protocol */ 831 #define MHD_HTTP_HEADER_ORDERING_TYPE "Ordering-Type" 832 /* Permanent. RFC 6454: The Web Origin Concept */ 833 #define MHD_HTTP_HEADER_ORIGIN "Origin" 834 /* Permanent. HTML */ 835 #define MHD_HTTP_HEADER_ORIGIN_AGENT_CLUSTER "Origin-Agent-Cluster" 836 /* Permanent. RFC 8613, Section 11.1: Object Security for Constrained RESTful Environments (OSCORE) */ 837 #define MHD_HTTP_HEADER_OSCORE "OSCORE" 838 /* Permanent. OASIS Project Specification 01; OASIS; Chet_Ensign */ 839 #define MHD_HTTP_HEADER_OSLC_CORE_VERSION "OSLC-Core-Version" 840 /* Permanent. RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) */ 841 #define MHD_HTTP_HEADER_OVERWRITE "Overwrite" 842 /* Permanent. HTML */ 843 #define MHD_HTTP_HEADER_PING_FROM "Ping-From" 844 /* Permanent. HTML */ 845 #define MHD_HTTP_HEADER_PING_TO "Ping-To" 846 /* Permanent. RFC 3648: Web Distributed Authoring and Versioning (WebDAV) Ordered Collections Protocol */ 847 #define MHD_HTTP_HEADER_POSITION "Position" 848 /* Permanent. RFC 7240: Prefer Header for HTTP */ 849 #define MHD_HTTP_HEADER_PREFER "Prefer" 850 /* Permanent. RFC 7240: Prefer Header for HTTP */ 851 #define MHD_HTTP_HEADER_PREFERENCE_APPLIED "Preference-Applied" 852 /* Permanent. RFC9218: Extensible Prioritization Scheme for HTTP */ 853 #define MHD_HTTP_HEADER_PRIORITY "Priority" 854 /* Permanent. RFC9209: The Proxy-Status HTTP Response Header Field */ 855 #define MHD_HTTP_HEADER_PROXY_STATUS "Proxy-Status" 856 /* Permanent. RFC 7469: Public Key Pinning Extension for HTTP */ 857 #define MHD_HTTP_HEADER_PUBLIC_KEY_PINS "Public-Key-Pins" 858 /* Permanent. RFC 7469: Public Key Pinning Extension for HTTP */ 859 #define MHD_HTTP_HEADER_PUBLIC_KEY_PINS_REPORT_ONLY \ 860 "Public-Key-Pins-Report-Only" 861 /* Permanent. RFC 4437: Web Distributed Authoring and Versioning (WebDAV) Redirect Reference Resources */ 862 #define MHD_HTTP_HEADER_REDIRECT_REF "Redirect-Ref" 863 /* Permanent. HTML */ 864 #define MHD_HTTP_HEADER_REFRESH "Refresh" 865 /* Permanent. RFC 8555, Section 6.5.1: Automatic Certificate Management Environment (ACME) */ 866 #define MHD_HTTP_HEADER_REPLAY_NONCE "Replay-Nonce" 867 /* Permanent. RFC-ietf-httpbis-digest-headers-13, Section 3: Digest Fields */ 868 #define MHD_HTTP_HEADER_REPR_DIGEST "Repr-Digest" 869 /* Permanent. RFC 6638: Scheduling Extensions to CalDAV */ 870 #define MHD_HTTP_HEADER_SCHEDULE_REPLY "Schedule-Reply" 871 /* Permanent. RFC 6338: Scheduling Extensions to CalDAV */ 872 #define MHD_HTTP_HEADER_SCHEDULE_TAG "Schedule-Tag" 873 /* Permanent. Fetch */ 874 #define MHD_HTTP_HEADER_SEC_PURPOSE "Sec-Purpose" 875 /* Permanent. RFC 8473: Token Binding over HTTP */ 876 #define MHD_HTTP_HEADER_SEC_TOKEN_BINDING "Sec-Token-Binding" 877 /* Permanent. RFC 6455: The WebSocket Protocol */ 878 #define MHD_HTTP_HEADER_SEC_WEBSOCKET_ACCEPT "Sec-WebSocket-Accept" 879 /* Permanent. RFC 6455: The WebSocket Protocol */ 880 #define MHD_HTTP_HEADER_SEC_WEBSOCKET_EXTENSIONS "Sec-WebSocket-Extensions" 881 /* Permanent. RFC 6455: The WebSocket Protocol */ 882 #define MHD_HTTP_HEADER_SEC_WEBSOCKET_KEY "Sec-WebSocket-Key" 883 /* Permanent. RFC 6455: The WebSocket Protocol */ 884 #define MHD_HTTP_HEADER_SEC_WEBSOCKET_PROTOCOL "Sec-WebSocket-Protocol" 885 /* Permanent. RFC 6455: The WebSocket Protocol */ 886 #define MHD_HTTP_HEADER_SEC_WEBSOCKET_VERSION "Sec-WebSocket-Version" 887 /* Permanent. Server Timing */ 888 #define MHD_HTTP_HEADER_SERVER_TIMING "Server-Timing" 889 /* Permanent. RFC 6265: HTTP State Management Mechanism */ 890 #define MHD_HTTP_HEADER_SET_COOKIE "Set-Cookie" 891 /* Permanent. RFC-ietf-httpbis-message-signatures-19, Section 4.2: HTTP Message Signatures */ 892 #define MHD_HTTP_HEADER_SIGNATURE "Signature" 893 /* Permanent. RFC-ietf-httpbis-message-signatures-19, Section 4.1: HTTP Message Signatures */ 894 #define MHD_HTTP_HEADER_SIGNATURE_INPUT "Signature-Input" 895 /* Permanent. RFC 5023: The Atom Publishing Protocol */ 896 #define MHD_HTTP_HEADER_SLUG "SLUG" 897 /* Permanent. Simple Object Access Protocol (SOAP) 1.1 */ 898 #define MHD_HTTP_HEADER_SOAPACTION "SoapAction" 899 /* Permanent. RFC 2518: HTTP Extensions for Distributed Authoring -- WEBDAV */ 900 #define MHD_HTTP_HEADER_STATUS_URI "Status-URI" 901 /* Permanent. RFC 6797: HTTP Strict Transport Security (HSTS) */ 902 #define MHD_HTTP_HEADER_STRICT_TRANSPORT_SECURITY "Strict-Transport-Security" 903 /* Permanent. RFC 8594: The Sunset HTTP Header Field */ 904 #define MHD_HTTP_HEADER_SUNSET "Sunset" 905 /* Permanent. Edge Architecture Specification */ 906 #define MHD_HTTP_HEADER_SURROGATE_CAPABILITY "Surrogate-Capability" 907 /* Permanent. Edge Architecture Specification */ 908 #define MHD_HTTP_HEADER_SURROGATE_CONTROL "Surrogate-Control" 909 /* Permanent. RFC 2295: Transparent Content Negotiation in HTTP */ 910 #define MHD_HTTP_HEADER_TCN "TCN" 911 /* Permanent. RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) */ 912 #define MHD_HTTP_HEADER_TIMEOUT "Timeout" 913 /* Permanent. RFC 8030, Section 5.4: Generic Event Delivery Using HTTP Push */ 914 #define MHD_HTTP_HEADER_TOPIC "Topic" 915 /* Permanent. Trace Context */ 916 #define MHD_HTTP_HEADER_TRACEPARENT "Traceparent" 917 /* Permanent. Trace Context */ 918 #define MHD_HTTP_HEADER_TRACESTATE "Tracestate" 919 /* Permanent. RFC 8030, Section 5.2: Generic Event Delivery Using HTTP Push */ 920 #define MHD_HTTP_HEADER_TTL "TTL" 921 /* Permanent. RFC 8030, Section 5.3: Generic Event Delivery Using HTTP Push */ 922 #define MHD_HTTP_HEADER_URGENCY "Urgency" 923 /* Permanent. RFC 2295: Transparent Content Negotiation in HTTP */ 924 #define MHD_HTTP_HEADER_VARIANT_VARY "Variant-Vary" 925 /* Permanent. RFC-ietf-httpbis-digest-headers-13, Section 4: Digest Fields */ 926 #define MHD_HTTP_HEADER_WANT_CONTENT_DIGEST "Want-Content-Digest" 927 /* Permanent. RFC-ietf-httpbis-digest-headers-13, Section 4: Digest Fields */ 928 #define MHD_HTTP_HEADER_WANT_REPR_DIGEST "Want-Repr-Digest" 929 /* Permanent. Fetch */ 930 #define MHD_HTTP_HEADER_X_CONTENT_TYPE_OPTIONS "X-Content-Type-Options" 931 /* Permanent. HTML */ 932 #define MHD_HTTP_HEADER_X_FRAME_OPTIONS "X-Frame-Options" 933 /* Provisional. AMP-Cache-Transform HTTP request header */ 934 #define MHD_HTTP_HEADER_AMP_CACHE_TRANSFORM "AMP-Cache-Transform" 935 /* Provisional. OSLC Configuration Management Version 1.0. Part 3: Configuration Specification */ 936 #define MHD_HTTP_HEADER_CONFIGURATION_CONTEXT "Configuration-Context" 937 /* Provisional. RFC 6017: Electronic Data Interchange - Internet Integration (EDIINT) Features Header Field */ 938 #define MHD_HTTP_HEADER_EDIINT_FEATURES "EDIINT-Features" 939 /* Provisional. OData Version 4.01 Part 1: Protocol; OASIS; Chet_Ensign */ 940 #define MHD_HTTP_HEADER_ISOLATION "Isolation" 941 /* Provisional. Permissions Policy */ 942 #define MHD_HTTP_HEADER_PERMISSIONS_POLICY "Permissions-Policy" 943 /* Provisional. Repeatable Requests Version 1.0; OASIS; Chet_Ensign */ 944 #define MHD_HTTP_HEADER_REPEATABILITY_CLIENT_ID "Repeatability-Client-ID" 945 /* Provisional. Repeatable Requests Version 1.0; OASIS; Chet_Ensign */ 946 #define MHD_HTTP_HEADER_REPEATABILITY_FIRST_SENT "Repeatability-First-Sent" 947 /* Provisional. Repeatable Requests Version 1.0; OASIS; Chet_Ensign */ 948 #define MHD_HTTP_HEADER_REPEATABILITY_REQUEST_ID "Repeatability-Request-ID" 949 /* Provisional. Repeatable Requests Version 1.0; OASIS; Chet_Ensign */ 950 #define MHD_HTTP_HEADER_REPEATABILITY_RESULT "Repeatability-Result" 951 /* Provisional. Reporting API */ 952 #define MHD_HTTP_HEADER_REPORTING_ENDPOINTS "Reporting-Endpoints" 953 /* Provisional. Global Privacy Control (GPC) */ 954 #define MHD_HTTP_HEADER_SEC_GPC "Sec-GPC" 955 /* Provisional. Resource Timing Level 1 */ 956 #define MHD_HTTP_HEADER_TIMING_ALLOW_ORIGIN "Timing-Allow-Origin" 957 /* Deprecated. PEP - an Extension Mechanism for HTTP; status-change-http-experiments-to-historic */ 958 #define MHD_HTTP_HEADER_C_PEP_INFO "C-PEP-Info" 959 /* Deprecated. White Paper: Joint Electronic Payment Initiative */ 960 #define MHD_HTTP_HEADER_PROTOCOL_INFO "Protocol-Info" 961 /* Deprecated. White Paper: Joint Electronic Payment Initiative */ 962 #define MHD_HTTP_HEADER_PROTOCOL_QUERY "Protocol-Query" 963 /* Obsoleted. Access Control for Cross-site Requests */ 964 #define MHD_HTTP_HEADER_ACCESS_CONTROL "Access-Control" 965 /* Obsoleted. RFC 2774: An HTTP Extension Framework; status-change-http-experiments-to-historic */ 966 #define MHD_HTTP_HEADER_C_EXT "C-Ext" 967 /* Obsoleted. RFC 2774: An HTTP Extension Framework; status-change-http-experiments-to-historic */ 968 #define MHD_HTTP_HEADER_C_MAN "C-Man" 969 /* Obsoleted. RFC 2774: An HTTP Extension Framework; status-change-http-experiments-to-historic */ 970 #define MHD_HTTP_HEADER_C_OPT "C-Opt" 971 /* Obsoleted. PEP - an Extension Mechanism for HTTP; status-change-http-experiments-to-historic */ 972 #define MHD_HTTP_HEADER_C_PEP "C-PEP" 973 /* Obsoleted. RFC 2068: Hypertext Transfer Protocol -- HTTP/1.1; RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1 */ 974 #define MHD_HTTP_HEADER_CONTENT_BASE "Content-Base" 975 /* Obsoleted. RFC 2616, Section 14.15: Hypertext Transfer Protocol -- HTTP/1.1; RFC 7231, Appendix B: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content */ 976 #define MHD_HTTP_HEADER_CONTENT_MD5 "Content-MD5" 977 /* Obsoleted. HTML 4.01 Specification */ 978 #define MHD_HTTP_HEADER_CONTENT_SCRIPT_TYPE "Content-Script-Type" 979 /* Obsoleted. HTML 4.01 Specification */ 980 #define MHD_HTTP_HEADER_CONTENT_STYLE_TYPE "Content-Style-Type" 981 /* Obsoleted. RFC 2068: Hypertext Transfer Protocol -- HTTP/1.1 */ 982 #define MHD_HTTP_HEADER_CONTENT_VERSION "Content-Version" 983 /* Obsoleted. RFC 2965: HTTP State Management Mechanism; RFC 6265: HTTP State Management Mechanism */ 984 #define MHD_HTTP_HEADER_COOKIE2 "Cookie2" 985 /* Obsoleted. HTML 4.01 Specification */ 986 #define MHD_HTTP_HEADER_DEFAULT_STYLE "Default-Style" 987 /* Obsoleted. RFC 2068: Hypertext Transfer Protocol -- HTTP/1.1 */ 988 #define MHD_HTTP_HEADER_DERIVED_FROM "Derived-From" 989 /* Obsoleted. RFC 3230: Instance Digests in HTTP; RFC-ietf-httpbis-digest-headers-13, Section 1.3: Digest Fields */ 990 #define MHD_HTTP_HEADER_DIGEST "Digest" 991 /* Obsoleted. RFC 2774: An HTTP Extension Framework; status-change-http-experiments-to-historic */ 992 #define MHD_HTTP_HEADER_EXT "Ext" 993 /* Obsoleted. Implementation of OPS Over HTTP */ 994 #define MHD_HTTP_HEADER_GETPROFILE "GetProfile" 995 /* Obsoleted. RFC 7540, Section 3.2.1: Hypertext Transfer Protocol Version 2 (HTTP/2) */ 996 #define MHD_HTTP_HEADER_HTTP2_SETTINGS "HTTP2-Settings" 997 /* Obsoleted. RFC 2774: An HTTP Extension Framework; status-change-http-experiments-to-historic */ 998 #define MHD_HTTP_HEADER_MAN "Man" 999 /* Obsoleted. Access Control for Cross-site Requests */ 1000 #define MHD_HTTP_HEADER_METHOD_CHECK "Method-Check" 1001 /* Obsoleted. Access Control for Cross-site Requests */ 1002 #define MHD_HTTP_HEADER_METHOD_CHECK_EXPIRES "Method-Check-Expires" 1003 /* Obsoleted. RFC 2774: An HTTP Extension Framework; status-change-http-experiments-to-historic */ 1004 #define MHD_HTTP_HEADER_OPT "Opt" 1005 /* Obsoleted. The Platform for Privacy Preferences 1.0 (P3P1.0) Specification */ 1006 #define MHD_HTTP_HEADER_P3P "P3P" 1007 /* Obsoleted. PEP - an Extension Mechanism for HTTP */ 1008 #define MHD_HTTP_HEADER_PEP "PEP" 1009 /* Obsoleted. PEP - an Extension Mechanism for HTTP */ 1010 #define MHD_HTTP_HEADER_PEP_INFO "Pep-Info" 1011 /* Obsoleted. PICS Label Distribution Label Syntax and Communication Protocols */ 1012 #define MHD_HTTP_HEADER_PICS_LABEL "PICS-Label" 1013 /* Obsoleted. Implementation of OPS Over HTTP */ 1014 #define MHD_HTTP_HEADER_PROFILEOBJECT "ProfileObject" 1015 /* Obsoleted. PICS Label Distribution Label Syntax and Communication Protocols */ 1016 #define MHD_HTTP_HEADER_PROTOCOL "Protocol" 1017 /* Obsoleted. PICS Label Distribution Label Syntax and Communication Protocols */ 1018 #define MHD_HTTP_HEADER_PROTOCOL_REQUEST "Protocol-Request" 1019 /* Obsoleted. Notification for Proxy Caches */ 1020 #define MHD_HTTP_HEADER_PROXY_FEATURES "Proxy-Features" 1021 /* Obsoleted. Notification for Proxy Caches */ 1022 #define MHD_HTTP_HEADER_PROXY_INSTRUCTION "Proxy-Instruction" 1023 /* Obsoleted. RFC 2068: Hypertext Transfer Protocol -- HTTP/1.1 */ 1024 #define MHD_HTTP_HEADER_PUBLIC "Public" 1025 /* Obsoleted. Access Control for Cross-site Requests */ 1026 #define MHD_HTTP_HEADER_REFERER_ROOT "Referer-Root" 1027 /* Obsoleted. RFC 2310: The Safe Response Header Field; status-change-http-experiments-to-historic */ 1028 #define MHD_HTTP_HEADER_SAFE "Safe" 1029 /* Obsoleted. RFC 2660: The Secure HyperText Transfer Protocol; status-change-http-experiments-to-historic */ 1030 #define MHD_HTTP_HEADER_SECURITY_SCHEME "Security-Scheme" 1031 /* Obsoleted. RFC 2965: HTTP State Management Mechanism; RFC 6265: HTTP State Management Mechanism */ 1032 #define MHD_HTTP_HEADER_SET_COOKIE2 "Set-Cookie2" 1033 /* Obsoleted. Implementation of OPS Over HTTP */ 1034 #define MHD_HTTP_HEADER_SETPROFILE "SetProfile" 1035 /* Obsoleted. RFC 2068: Hypertext Transfer Protocol -- HTTP/1.1 */ 1036 #define MHD_HTTP_HEADER_URI "URI" 1037 /* Obsoleted. RFC 3230: Instance Digests in HTTP; RFC-ietf-httpbis-digest-headers-13, Section 1.3: Digest Fields */ 1038 #define MHD_HTTP_HEADER_WANT_DIGEST "Want-Digest" 1039 /* Obsoleted. RFC9111, Section 5.5: HTTP Caching */ 1040 #define MHD_HTTP_HEADER_WARNING "Warning" 1041 1042 /* Headers removed from the registry. Do not use! */ 1043 /* Obsoleted. RFC4229 */ 1044 #define MHD_HTTP_HEADER_COMPLIANCE "Compliance" 1045 /* Obsoleted. RFC4229 */ 1046 #define MHD_HTTP_HEADER_CONTENT_TRANSFER_ENCODING "Content-Transfer-Encoding" 1047 /* Obsoleted. RFC4229 */ 1048 #define MHD_HTTP_HEADER_COST "Cost" 1049 /* Obsoleted. RFC4229 */ 1050 #define MHD_HTTP_HEADER_MESSAGE_ID "Message-ID" 1051 /* Obsoleted. RFC4229 */ 1052 #define MHD_HTTP_HEADER_NON_COMPLIANCE "Non-Compliance" 1053 /* Obsoleted. RFC4229 */ 1054 #define MHD_HTTP_HEADER_OPTIONAL "Optional" 1055 /* Obsoleted. RFC4229 */ 1056 #define MHD_HTTP_HEADER_RESOLUTION_HINT "Resolution-Hint" 1057 /* Obsoleted. RFC4229 */ 1058 #define MHD_HTTP_HEADER_RESOLVER_LOCATION "Resolver-Location" 1059 /* Obsoleted. RFC4229 */ 1060 #define MHD_HTTP_HEADER_SUBOK "SubOK" 1061 /* Obsoleted. RFC4229 */ 1062 #define MHD_HTTP_HEADER_SUBST "Subst" 1063 /* Obsoleted. RFC4229 */ 1064 #define MHD_HTTP_HEADER_TITLE "Title" 1065 /* Obsoleted. RFC4229 */ 1066 #define MHD_HTTP_HEADER_UA_COLOR "UA-Color" 1067 /* Obsoleted. RFC4229 */ 1068 #define MHD_HTTP_HEADER_UA_MEDIA "UA-Media" 1069 /* Obsoleted. RFC4229 */ 1070 #define MHD_HTTP_HEADER_UA_PIXELS "UA-Pixels" 1071 /* Obsoleted. RFC4229 */ 1072 #define MHD_HTTP_HEADER_UA_RESOLUTION "UA-Resolution" 1073 /* Obsoleted. RFC4229 */ 1074 #define MHD_HTTP_HEADER_UA_WINDOWPIXELS "UA-Windowpixels" 1075 /* Obsoleted. RFC4229 */ 1076 #define MHD_HTTP_HEADER_VERSION "Version" 1077 /* Obsoleted. W3C Mobile Web Best Practices Working Group */ 1078 #define MHD_HTTP_HEADER_X_DEVICE_ACCEPT "X-Device-Accept" 1079 /* Obsoleted. W3C Mobile Web Best Practices Working Group */ 1080 #define MHD_HTTP_HEADER_X_DEVICE_ACCEPT_CHARSET "X-Device-Accept-Charset" 1081 /* Obsoleted. W3C Mobile Web Best Practices Working Group */ 1082 #define MHD_HTTP_HEADER_X_DEVICE_ACCEPT_ENCODING "X-Device-Accept-Encoding" 1083 /* Obsoleted. W3C Mobile Web Best Practices Working Group */ 1084 #define MHD_HTTP_HEADER_X_DEVICE_ACCEPT_LANGUAGE "X-Device-Accept-Language" 1085 /* Obsoleted. W3C Mobile Web Best Practices Working Group */ 1086 #define MHD_HTTP_HEADER_X_DEVICE_USER_AGENT "X-Device-User-Agent" 1087 1088 /** @} */ /* end of group headers */ 1089 1090 /** 1091 * @defgroup versions HTTP versions 1092 * These strings should be used to match against the first line of the 1093 * HTTP header. 1094 * @{ 1095 */ 1096 #define MHD_HTTP_VERSION_1_0 "HTTP/1.0" 1097 #define MHD_HTTP_VERSION_1_1 "HTTP/1.1" 1098 1099 /** @} */ /* end of group versions */ 1100 1101 /** 1102 * @defgroup methods HTTP methods 1103 * HTTP methods (as strings). 1104 * See: https://www.iana.org/assignments/http-methods/http-methods.xml 1105 * Registry export date: 2023-10-02 1106 * @{ 1107 */ 1108 1109 /* Main HTTP methods. */ 1110 /* Safe. Idempotent. RFC9110, Section 9.3.1. */ 1111 #define MHD_HTTP_METHOD_GET "GET" 1112 /* Safe. Idempotent. RFC9110, Section 9.3.2. */ 1113 #define MHD_HTTP_METHOD_HEAD "HEAD" 1114 /* Not safe. Not idempotent. RFC9110, Section 9.3.3. */ 1115 #define MHD_HTTP_METHOD_POST "POST" 1116 /* Not safe. Idempotent. RFC9110, Section 9.3.4. */ 1117 #define MHD_HTTP_METHOD_PUT "PUT" 1118 /* Not safe. Idempotent. RFC9110, Section 9.3.5. */ 1119 #define MHD_HTTP_METHOD_DELETE "DELETE" 1120 /* Not safe. Not idempotent. RFC9110, Section 9.3.6. */ 1121 #define MHD_HTTP_METHOD_CONNECT "CONNECT" 1122 /* Safe. Idempotent. RFC9110, Section 9.3.7. */ 1123 #define MHD_HTTP_METHOD_OPTIONS "OPTIONS" 1124 /* Safe. Idempotent. RFC9110, Section 9.3.8. */ 1125 #define MHD_HTTP_METHOD_TRACE "TRACE" 1126 1127 /* Additional HTTP methods. */ 1128 /* Not safe. Idempotent. RFC3744, Section 8.1. */ 1129 #define MHD_HTTP_METHOD_ACL "ACL" 1130 /* Not safe. Idempotent. RFC3253, Section 12.6. */ 1131 #define MHD_HTTP_METHOD_BASELINE_CONTROL "BASELINE-CONTROL" 1132 /* Not safe. Idempotent. RFC5842, Section 4. */ 1133 #define MHD_HTTP_METHOD_BIND "BIND" 1134 /* Not safe. Idempotent. RFC3253, Section 4.4, Section 9.4. */ 1135 #define MHD_HTTP_METHOD_CHECKIN "CHECKIN" 1136 /* Not safe. Idempotent. RFC3253, Section 4.3, Section 8.8. */ 1137 #define MHD_HTTP_METHOD_CHECKOUT "CHECKOUT" 1138 /* Not safe. Idempotent. RFC4918, Section 9.8. */ 1139 #define MHD_HTTP_METHOD_COPY "COPY" 1140 /* Not safe. Idempotent. RFC3253, Section 8.2. */ 1141 #define MHD_HTTP_METHOD_LABEL "LABEL" 1142 /* Not safe. Idempotent. RFC2068, Section 19.6.1.2. */ 1143 #define MHD_HTTP_METHOD_LINK "LINK" 1144 /* Not safe. Not idempotent. RFC4918, Section 9.10. */ 1145 #define MHD_HTTP_METHOD_LOCK "LOCK" 1146 /* Not safe. Idempotent. RFC3253, Section 11.2. */ 1147 #define MHD_HTTP_METHOD_MERGE "MERGE" 1148 /* Not safe. Idempotent. RFC3253, Section 13.5. */ 1149 #define MHD_HTTP_METHOD_MKACTIVITY "MKACTIVITY" 1150 /* Not safe. Idempotent. RFC4791, Section 5.3.1; RFC8144, Section 2.3. */ 1151 #define MHD_HTTP_METHOD_MKCALENDAR "MKCALENDAR" 1152 /* Not safe. Idempotent. RFC4918, Section 9.3; RFC5689, Section 3; RFC8144, Section 2.3. */ 1153 #define MHD_HTTP_METHOD_MKCOL "MKCOL" 1154 /* Not safe. Idempotent. RFC4437, Section 6. */ 1155 #define MHD_HTTP_METHOD_MKREDIRECTREF "MKREDIRECTREF" 1156 /* Not safe. Idempotent. RFC3253, Section 6.3. */ 1157 #define MHD_HTTP_METHOD_MKWORKSPACE "MKWORKSPACE" 1158 /* Not safe. Idempotent. RFC4918, Section 9.9. */ 1159 #define MHD_HTTP_METHOD_MOVE "MOVE" 1160 /* Not safe. Idempotent. RFC3648, Section 7. */ 1161 #define MHD_HTTP_METHOD_ORDERPATCH "ORDERPATCH" 1162 /* Not safe. Not idempotent. RFC5789, Section 2. */ 1163 #define MHD_HTTP_METHOD_PATCH "PATCH" 1164 /* Safe. Idempotent. RFC9113, Section 3.4. */ 1165 #define MHD_HTTP_METHOD_PRI "PRI" 1166 /* Safe. Idempotent. RFC4918, Section 9.1; RFC8144, Section 2.1. */ 1167 #define MHD_HTTP_METHOD_PROPFIND "PROPFIND" 1168 /* Not safe. Idempotent. RFC4918, Section 9.2; RFC8144, Section 2.2. */ 1169 #define MHD_HTTP_METHOD_PROPPATCH "PROPPATCH" 1170 /* Not safe. Idempotent. RFC5842, Section 6. */ 1171 #define MHD_HTTP_METHOD_REBIND "REBIND" 1172 /* Safe. Idempotent. RFC3253, Section 3.6; RFC8144, Section 2.1. */ 1173 #define MHD_HTTP_METHOD_REPORT "REPORT" 1174 /* Safe. Idempotent. RFC5323, Section 2. */ 1175 #define MHD_HTTP_METHOD_SEARCH "SEARCH" 1176 /* Not safe. Idempotent. RFC5842, Section 5. */ 1177 #define MHD_HTTP_METHOD_UNBIND "UNBIND" 1178 /* Not safe. Idempotent. RFC3253, Section 4.5. */ 1179 #define MHD_HTTP_METHOD_UNCHECKOUT "UNCHECKOUT" 1180 /* Not safe. Idempotent. RFC2068, Section 19.6.1.3. */ 1181 #define MHD_HTTP_METHOD_UNLINK "UNLINK" 1182 /* Not safe. Idempotent. RFC4918, Section 9.11. */ 1183 #define MHD_HTTP_METHOD_UNLOCK "UNLOCK" 1184 /* Not safe. Idempotent. RFC3253, Section 7.1. */ 1185 #define MHD_HTTP_METHOD_UPDATE "UPDATE" 1186 /* Not safe. Idempotent. RFC4437, Section 7. */ 1187 #define MHD_HTTP_METHOD_UPDATEREDIRECTREF "UPDATEREDIRECTREF" 1188 /* Not safe. Idempotent. RFC3253, Section 3.5. */ 1189 #define MHD_HTTP_METHOD_VERSION_CONTROL "VERSION-CONTROL" 1190 /* Not safe. Not idempotent. RFC9110, Section 18.2. */ 1191 #define MHD_HTTP_METHOD_ASTERISK "*" 1192 1193 /** @} */ /* end of group methods */ 1194 1195 /** 1196 * @defgroup postenc HTTP POST encodings 1197 * See also: http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4 1198 * @{ 1199 */ 1200 #define MHD_HTTP_POST_ENCODING_FORM_URLENCODED \ 1201 "application/x-www-form-urlencoded" 1202 #define MHD_HTTP_POST_ENCODING_MULTIPART_FORMDATA "multipart/form-data" 1203 1204 /** @} */ /* end of group postenc */ 1205 1206 1207 /** 1208 * @brief Handle for the daemon (listening on a socket for HTTP traffic). 1209 * @ingroup event 1210 */ 1211 struct MHD_Daemon; 1212 1213 /** 1214 * @brief Handle for a connection / HTTP request. 1215 * 1216 * With HTTP/1.1, multiple requests can be run over the same 1217 * connection. However, MHD will only show one request per TCP 1218 * connection to the client at any given time. 1219 * @ingroup request 1220 */ 1221 struct MHD_Connection; 1222 1223 /** 1224 * @brief Handle for a response. 1225 * @ingroup response 1226 */ 1227 struct MHD_Response; 1228 1229 /** 1230 * @brief Handle for POST processing. 1231 * @ingroup response 1232 */ 1233 struct MHD_PostProcessor; 1234 1235 1236 /** 1237 * @brief Flags for the `struct MHD_Daemon`. 1238 * 1239 * Note that MHD will run automatically in background thread(s) only 1240 * if #MHD_USE_INTERNAL_POLLING_THREAD is used. Otherwise caller (application) 1241 * must use #MHD_run() or #MHD_run_from_select() to have MHD processed 1242 * network connections and data. 1243 * 1244 * Starting the daemon may also fail if a particular option is not 1245 * implemented or not supported on the target platform (i.e. no 1246 * support for TLS, epoll or IPv6). 1247 */ 1248 enum MHD_FLAG 1249 { 1250 /** 1251 * No options selected. 1252 */ 1253 MHD_NO_FLAG = 0, 1254 1255 /** 1256 * Print errors messages to custom error logger or to `stderr` if 1257 * custom error logger is not set. 1258 * @sa ::MHD_OPTION_EXTERNAL_LOGGER 1259 */ 1260 MHD_USE_ERROR_LOG = 1, 1261 1262 /** 1263 * Run in debug mode. If this flag is used, the library should 1264 * print error messages and warnings to `stderr`. 1265 */ 1266 MHD_USE_DEBUG = 1, 1267 1268 /** 1269 * Run in HTTPS mode. The modern protocol is called TLS. 1270 */ 1271 MHD_USE_TLS = 2, 1272 1273 /** @deprecated */ 1274 MHD_USE_SSL = 2, 1275 #if 0 1276 /* let's do this later once versions that define MHD_USE_TLS a more widely deployed. */ 1277 #define MHD_USE_SSL \ 1278 _MHD_DEPR_IN_MACRO ("Value MHD_USE_SSL is deprecated, use MHD_USE_TLS") \ 1279 MHD_USE_TLS 1280 #endif 1281 1282 /** 1283 * Run using one thread per connection. 1284 * Must be used only with #MHD_USE_INTERNAL_POLLING_THREAD. 1285 * 1286 * If #MHD_USE_ITC is also not used, closed and expired connections may only 1287 * be cleaned up internally when a new connection is received. 1288 * Consider adding of #MHD_USE_ITC flag to have faster internal cleanups 1289 * at very minor increase in system resources usage. 1290 */ 1291 MHD_USE_THREAD_PER_CONNECTION = 4, 1292 1293 /** 1294 * Run using an internal thread (or thread pool) for sockets sending 1295 * and receiving and data processing. Without this flag MHD will not 1296 * run automatically in background thread(s). 1297 * If this flag is set, #MHD_run() and #MHD_run_from_select() couldn't 1298 * be used. 1299 * This flag is set explicitly by #MHD_USE_POLL_INTERNAL_THREAD and 1300 * by #MHD_USE_EPOLL_INTERNAL_THREAD. 1301 * When this flag is not set, MHD run in "external" polling mode. 1302 */ 1303 MHD_USE_INTERNAL_POLLING_THREAD = 8, 1304 1305 /** @deprecated */ 1306 MHD_USE_SELECT_INTERNALLY = 8, 1307 #if 0 /* Will be marked for real deprecation later. */ 1308 #define MHD_USE_SELECT_INTERNALLY \ 1309 _MHD_DEPR_IN_MACRO ( \ 1310 "Value MHD_USE_SELECT_INTERNALLY is deprecated, use MHD_USE_INTERNAL_POLLING_THREAD instead") \ 1311 MHD_USE_INTERNAL_POLLING_THREAD 1312 #endif /* 0 */ 1313 1314 /** 1315 * Run using the IPv6 protocol (otherwise, MHD will just support 1316 * IPv4). If you want MHD to support IPv4 and IPv6 using a single 1317 * socket, pass #MHD_USE_DUAL_STACK, otherwise, if you only pass 1318 * this option, MHD will try to bind to IPv6-only (resulting in 1319 * no IPv4 support). 1320 */ 1321 MHD_USE_IPv6 = 16, 1322 1323 /** 1324 * Be pedantic about the protocol (as opposed to as tolerant as 1325 * possible). 1326 * This flag is equivalent to setting 1 as #MHD_OPTION_CLIENT_DISCIPLINE_LVL 1327 * value. 1328 * @sa #MHD_OPTION_CLIENT_DISCIPLINE_LVL 1329 */ 1330 MHD_USE_PEDANTIC_CHECKS = 32, 1331 #if 0 /* Will be marked for real deprecation later. */ 1332 #define MHD_USE_PEDANTIC_CHECKS \ 1333 _MHD_DEPR_IN_MACRO ( \ 1334 "Flag MHD_USE_PEDANTIC_CHECKS is deprecated, " \ 1335 "use option MHD_OPTION_CLIENT_DISCIPLINE_LVL instead") \ 1336 32 1337 #endif /* 0 */ 1338 1339 /** 1340 * Use `poll()` instead of `select()` for polling sockets. 1341 * This allows sockets with `fd >= FD_SETSIZE`. 1342 * This option is not compatible with an "external" polling mode 1343 * (as there is no API to get the file descriptors for the external 1344 * poll() from MHD) and must also not be used in combination 1345 * with #MHD_USE_EPOLL. 1346 * @sa ::MHD_FEATURE_POLL, #MHD_USE_POLL_INTERNAL_THREAD 1347 */ 1348 MHD_USE_POLL = 64, 1349 1350 /** 1351 * Run using an internal thread (or thread pool) doing `poll()`. 1352 * @sa ::MHD_FEATURE_POLL, #MHD_USE_POLL, #MHD_USE_INTERNAL_POLLING_THREAD 1353 */ 1354 MHD_USE_POLL_INTERNAL_THREAD = MHD_USE_POLL | MHD_USE_INTERNAL_POLLING_THREAD, 1355 1356 /** @deprecated */ 1357 MHD_USE_POLL_INTERNALLY = MHD_USE_POLL | MHD_USE_INTERNAL_POLLING_THREAD, 1358 #if 0 /* Will be marked for real deprecation later. */ 1359 #define MHD_USE_POLL_INTERNALLY \ 1360 _MHD_DEPR_IN_MACRO ( \ 1361 "Value MHD_USE_POLL_INTERNALLY is deprecated, use MHD_USE_POLL_INTERNAL_THREAD instead") \ 1362 MHD_USE_POLL_INTERNAL_THREAD 1363 #endif /* 0 */ 1364 1365 /** 1366 * Suppress (automatically) adding the 'Date:' header to HTTP responses. 1367 * This option should ONLY be used on systems that do not have a clock 1368 * and that DO provide other mechanisms for cache control. See also 1369 * RFC 2616, section 14.18 (exception 3). 1370 */ 1371 MHD_USE_SUPPRESS_DATE_NO_CLOCK = 128, 1372 1373 /** @deprecated */ 1374 MHD_SUPPRESS_DATE_NO_CLOCK = 128, 1375 #if 0 /* Will be marked for real deprecation later. */ 1376 #define MHD_SUPPRESS_DATE_NO_CLOCK \ 1377 _MHD_DEPR_IN_MACRO ( \ 1378 "Value MHD_SUPPRESS_DATE_NO_CLOCK is deprecated, use MHD_USE_SUPPRESS_DATE_NO_CLOCK instead") \ 1379 MHD_USE_SUPPRESS_DATE_NO_CLOCK 1380 #endif /* 0 */ 1381 1382 /** 1383 * Run without a listen socket. This option only makes sense if 1384 * #MHD_add_connection is to be used exclusively to connect HTTP 1385 * clients to the HTTP server. This option is incompatible with 1386 * using a thread pool; if it is used, #MHD_OPTION_THREAD_POOL_SIZE 1387 * is ignored. 1388 */ 1389 MHD_USE_NO_LISTEN_SOCKET = 256, 1390 1391 /** 1392 * Use `epoll()` instead of `select()` or `poll()` for the event loop. 1393 * This option is only available on some systems; using the option on 1394 * systems without epoll will cause #MHD_start_daemon to fail. Using 1395 * this option is not supported with #MHD_USE_THREAD_PER_CONNECTION. 1396 * @sa ::MHD_FEATURE_EPOLL 1397 */ 1398 MHD_USE_EPOLL = 512, 1399 1400 /** @deprecated */ 1401 MHD_USE_EPOLL_LINUX_ONLY = 512, 1402 #if 0 /* Will be marked for real deprecation later. */ 1403 #define MHD_USE_EPOLL_LINUX_ONLY \ 1404 _MHD_DEPR_IN_MACRO ( \ 1405 "Value MHD_USE_EPOLL_LINUX_ONLY is deprecated, use MHD_USE_EPOLL") \ 1406 MHD_USE_EPOLL 1407 #endif /* 0 */ 1408 1409 /** 1410 * Run using an internal thread (or thread pool) doing `epoll` polling. 1411 * This option is only available on certain platforms; using the option on 1412 * platform without `epoll` support will cause #MHD_start_daemon to fail. 1413 * @sa ::MHD_FEATURE_EPOLL, #MHD_USE_EPOLL, #MHD_USE_INTERNAL_POLLING_THREAD 1414 */ 1415 MHD_USE_EPOLL_INTERNAL_THREAD = MHD_USE_EPOLL 1416 | MHD_USE_INTERNAL_POLLING_THREAD, 1417 1418 /** @deprecated */ 1419 MHD_USE_EPOLL_INTERNALLY = MHD_USE_EPOLL | MHD_USE_INTERNAL_POLLING_THREAD, 1420 /** @deprecated */ 1421 MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY = MHD_USE_EPOLL 1422 | MHD_USE_INTERNAL_POLLING_THREAD, 1423 #if 0 /* Will be marked for real deprecation later. */ 1424 #define MHD_USE_EPOLL_INTERNALLY \ 1425 _MHD_DEPR_IN_MACRO ( \ 1426 "Value MHD_USE_EPOLL_INTERNALLY is deprecated, use MHD_USE_EPOLL_INTERNAL_THREAD") \ 1427 MHD_USE_EPOLL_INTERNAL_THREAD 1428 /** @deprecated */ 1429 #define MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY \ 1430 _MHD_DEPR_IN_MACRO ( \ 1431 "Value MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY is deprecated, use MHD_USE_EPOLL_INTERNAL_THREAD") \ 1432 MHD_USE_EPOLL_INTERNAL_THREAD 1433 #endif /* 0 */ 1434 1435 /** 1436 * Use inter-thread communication channel. 1437 * #MHD_USE_ITC can be used with #MHD_USE_INTERNAL_POLLING_THREAD 1438 * and is ignored with any "external" sockets polling. 1439 * It's required for use of #MHD_quiesce_daemon 1440 * or #MHD_add_connection. 1441 * This option is enforced by #MHD_ALLOW_SUSPEND_RESUME or 1442 * #MHD_USE_NO_LISTEN_SOCKET. 1443 * #MHD_USE_ITC is always used automatically on platforms 1444 * where select()/poll()/other ignore shutdown of listen 1445 * socket. 1446 */ 1447 MHD_USE_ITC = 1024, 1448 1449 /** @deprecated */ 1450 MHD_USE_PIPE_FOR_SHUTDOWN = 1024, 1451 #if 0 /* Will be marked for real deprecation later. */ 1452 #define MHD_USE_PIPE_FOR_SHUTDOWN \ 1453 _MHD_DEPR_IN_MACRO ( \ 1454 "Value MHD_USE_PIPE_FOR_SHUTDOWN is deprecated, use MHD_USE_ITC") \ 1455 MHD_USE_ITC 1456 #endif /* 0 */ 1457 1458 /** 1459 * Use a single socket for IPv4 and IPv6. 1460 */ 1461 MHD_USE_DUAL_STACK = MHD_USE_IPv6 | 2048, 1462 1463 /** 1464 * Enable `turbo`. Disables certain calls to `shutdown()`, 1465 * enables aggressive non-blocking optimistic reads and 1466 * other potentially unsafe optimizations. 1467 * Most effects only happen with #MHD_USE_EPOLL. 1468 */ 1469 MHD_USE_TURBO = 4096, 1470 1471 /** @deprecated */ 1472 MHD_USE_EPOLL_TURBO = 4096, 1473 #if 0 /* Will be marked for real deprecation later. */ 1474 #define MHD_USE_EPOLL_TURBO \ 1475 _MHD_DEPR_IN_MACRO ( \ 1476 "Value MHD_USE_EPOLL_TURBO is deprecated, use MHD_USE_TURBO") \ 1477 MHD_USE_TURBO 1478 #endif /* 0 */ 1479 1480 /** 1481 * Enable suspend/resume functions, which also implies setting up 1482 * ITC to signal resume. 1483 */ 1484 MHD_ALLOW_SUSPEND_RESUME = 8192 | MHD_USE_ITC, 1485 1486 /** @deprecated */ 1487 MHD_USE_SUSPEND_RESUME = 8192 | MHD_USE_ITC, 1488 #if 0 /* Will be marked for real deprecation later. */ 1489 #define MHD_USE_SUSPEND_RESUME \ 1490 _MHD_DEPR_IN_MACRO ( \ 1491 "Value MHD_USE_SUSPEND_RESUME is deprecated, use MHD_ALLOW_SUSPEND_RESUME instead") \ 1492 MHD_ALLOW_SUSPEND_RESUME 1493 #endif /* 0 */ 1494 1495 /** 1496 * Enable TCP_FASTOPEN option. This option is only available on Linux with a 1497 * kernel >= 3.6. On other systems, using this option cases #MHD_start_daemon 1498 * to fail. 1499 */ 1500 MHD_USE_TCP_FASTOPEN = 16384, 1501 1502 /** 1503 * You need to set this option if you want to use HTTP "Upgrade". 1504 * "Upgrade" may require usage of additional internal resources, 1505 * which we do not want to use unless necessary. 1506 */ 1507 MHD_ALLOW_UPGRADE = 32768, 1508 1509 /** 1510 * Automatically use best available polling function. 1511 * Choice of polling function is also depend on other daemon options. 1512 * If #MHD_USE_INTERNAL_POLLING_THREAD is specified then epoll, poll() or 1513 * select() will be used (listed in decreasing preference order, first 1514 * function available on system will be used). 1515 * If #MHD_USE_THREAD_PER_CONNECTION is specified then poll() or select() 1516 * will be used. 1517 * If those flags are not specified then epoll or select() will be 1518 * used (as the only suitable for MHD_get_fdset()) 1519 */ 1520 MHD_USE_AUTO = 65536, 1521 1522 /** 1523 * Run using an internal thread (or thread pool) with best available on 1524 * system polling function. 1525 * This is combination of #MHD_USE_AUTO and #MHD_USE_INTERNAL_POLLING_THREAD 1526 * flags. 1527 */ 1528 MHD_USE_AUTO_INTERNAL_THREAD = MHD_USE_AUTO | MHD_USE_INTERNAL_POLLING_THREAD, 1529 1530 /** 1531 * Flag set to enable post-handshake client authentication 1532 * (only useful in combination with #MHD_USE_TLS). 1533 */ 1534 MHD_USE_POST_HANDSHAKE_AUTH_SUPPORT = 1U << 17, 1535 1536 /** 1537 * Flag set to enable TLS 1.3 early data. This has 1538 * security implications, be VERY careful when using this. 1539 */ 1540 MHD_USE_INSECURE_TLS_EARLY_DATA = 1U << 18, 1541 1542 /** 1543 * Indicates that MHD daemon will be used by application in single-threaded 1544 * mode only. When this flag is set then application must call any MHD 1545 * function only within a single thread. 1546 * This flag turns off some internal thread-safety and allows MHD making 1547 * some of the internal optimisations suitable only for single-threaded 1548 * environment. 1549 * Not compatible with #MHD_USE_INTERNAL_POLLING_THREAD. 1550 * @note Available since #MHD_VERSION 0x00097707 1551 */ 1552 MHD_USE_NO_THREAD_SAFETY = 1U << 19 1553 1554 }; 1555 1556 1557 /** 1558 * Type of a callback function used for logging by MHD. 1559 * 1560 * @param cls closure 1561 * @param fm format string (`printf()`-style) 1562 * @param ap arguments to @a fm 1563 * @ingroup logging 1564 */ 1565 typedef void 1566 (*MHD_LogCallback)(void *cls, 1567 const char *fm, 1568 va_list ap); 1569 1570 1571 /** 1572 * Function called to lookup the pre shared key (@a psk) for a given 1573 * HTTP connection based on the @a username. 1574 * 1575 * @param cls closure 1576 * @param connection the HTTPS connection 1577 * @param username the user name claimed by the other side 1578 * @param[out] psk to be set to the pre-shared-key; should be allocated with malloc(), 1579 * will be freed by MHD 1580 * @param[out] psk_size to be set to the number of bytes in @a psk 1581 * @return 0 on success, -1 on errors 1582 */ 1583 typedef int 1584 (*MHD_PskServerCredentialsCallback)(void *cls, 1585 const struct MHD_Connection *connection, 1586 const char *username, 1587 void **psk, 1588 size_t *psk_size); 1589 1590 /** 1591 * Values for #MHD_OPTION_DIGEST_AUTH_NONCE_BIND_TYPE. 1592 * 1593 * These values can limit the scope of validity of MHD-generated nonces. 1594 * Values can be combined with bitwise OR. 1595 * Any value, except #MHD_DAUTH_BIND_NONCE_NONE, enforce function 1596 * #MHD_digest_auth_check3() (and similar functions) to check nonce by 1597 * re-generating it again with the same parameters, which is CPU-intensive 1598 * operation. 1599 * @note Available since #MHD_VERSION 0x00097701 1600 */ 1601 enum MHD_DAuthBindNonce 1602 { 1603 /** 1604 * Generated nonces are valid for any request from any client until expired. 1605 * This is default and recommended value. 1606 * #MHD_digest_auth_check3() (and similar functions) would check only whether 1607 * the nonce value that is used by client has been generated by MHD and not 1608 * expired yet. 1609 * It is recommended because RFC 7616 allows clients to use the same nonce 1610 * for any request in the same "protection space". 1611 * When checking client's authorisation requests CPU is loaded less if this 1612 * value is used. 1613 * This mode gives MHD maximum flexibility for nonces generation and can 1614 * prevent possible nonce collisions (and corresponding log warning messages) 1615 * when clients' requests are intensive. 1616 * This value cannot be biwise-OR combined with other values. 1617 */ 1618 MHD_DAUTH_BIND_NONCE_NONE = 0, 1619 1620 /** 1621 * Generated nonces are valid only for the same realm. 1622 */ 1623 MHD_DAUTH_BIND_NONCE_REALM = 1 << 0, 1624 1625 /** 1626 * Generated nonces are valid only for the same URI (excluding parameters 1627 * after '?' in URI) and request method (GET, POST etc). 1628 * Not recommended unless "protection space" is limited to a single URI as 1629 * RFC 7616 allows clients to re-use server-generated nonces for any URI 1630 * in the same "protection space" which by default consists of all server 1631 * URIs. 1632 * Before #MHD_VERSION 0x00097701 this was default (and only supported) 1633 * nonce bind type. 1634 */ 1635 MHD_DAUTH_BIND_NONCE_URI = 1 << 1, 1636 1637 /** 1638 * Generated nonces are valid only for the same URI including URI parameters 1639 * and request method (GET, POST etc). 1640 * This value implies #MHD_DAUTH_BIND_NONCE_URI. 1641 * Not recommended for that same reasons as #MHD_DAUTH_BIND_NONCE_URI. 1642 */ 1643 MHD_DAUTH_BIND_NONCE_URI_PARAMS = 1 << 2, 1644 1645 /** 1646 * Generated nonces are valid only for the single client's IP. 1647 * While it looks like security improvement, in practice the same client may 1648 * jump from one IP to another (mobile or Wi-Fi handover, DHCP re-assignment, 1649 * Multi-NAT, different proxy chain and other reasons), while IP address 1650 * spoofing could be used relatively easily. 1651 */ 1652 MHD_DAUTH_BIND_NONCE_CLIENT_IP = 1 << 3 1653 } _MHD_FLAGS_ENUM; 1654 1655 /** 1656 * @brief MHD options. 1657 * 1658 * Passed in the varargs portion of #MHD_start_daemon. 1659 */ 1660 enum MHD_OPTION 1661 { 1662 1663 /** 1664 * No more options / last option. This is used 1665 * to terminate the VARARGs list. 1666 */ 1667 MHD_OPTION_END = 0, 1668 1669 /** 1670 * Maximum memory size per connection (followed by a `size_t`). 1671 * Default is 32 kb (#MHD_POOL_SIZE_DEFAULT). 1672 * Values above 128k are unlikely to result in much benefit, as half 1673 * of the memory will be typically used for IO, and TCP buffers are 1674 * unlikely to support window sizes above 64k on most systems. 1675 * Values below 64 bytes are completely unusable. 1676 * Since #MHD_VERSION 0x00097710 silently ignored if followed by zero value. 1677 */ 1678 MHD_OPTION_CONNECTION_MEMORY_LIMIT = 1, 1679 1680 /** 1681 * Maximum number of concurrent connections to 1682 * accept (followed by an `unsigned int`). 1683 */ 1684 MHD_OPTION_CONNECTION_LIMIT = 2, 1685 1686 /** 1687 * After how many seconds of inactivity should a 1688 * connection automatically be timed out? (followed 1689 * by an `unsigned int`; use zero for no timeout). 1690 * Values larger than (UINT64_MAX / 2000 - 1) will 1691 * be clipped to this number. 1692 */ 1693 MHD_OPTION_CONNECTION_TIMEOUT = 3, 1694 1695 /** 1696 * Register a function that should be called whenever a request has 1697 * been completed (this can be used for application-specific clean 1698 * up). Requests that have never been presented to the application 1699 * (via #MHD_AccessHandlerCallback) will not result in 1700 * notifications. 1701 * 1702 * This option should be followed by TWO pointers. First a pointer 1703 * to a function of type #MHD_RequestCompletedCallback and second a 1704 * pointer to a closure to pass to the request completed callback. 1705 * The second pointer may be NULL. 1706 */ 1707 MHD_OPTION_NOTIFY_COMPLETED = 4, 1708 1709 /** 1710 * Limit on the number of (concurrent) connections made to the 1711 * server from the same IP address. Can be used to prevent one 1712 * IP from taking over all of the allowed connections. If the 1713 * same IP tries to establish more than the specified number of 1714 * connections, they will be immediately rejected. The option 1715 * should be followed by an `unsigned int`. The default is 1716 * zero, which means no limit on the number of connections 1717 * from the same IP address. 1718 */ 1719 MHD_OPTION_PER_IP_CONNECTION_LIMIT = 5, 1720 1721 /** 1722 * Bind daemon to the supplied `struct sockaddr`. This option should 1723 * be followed by a `struct sockaddr *`. If #MHD_USE_IPv6 is 1724 * specified, the `struct sockaddr*` should point to a `struct 1725 * sockaddr_in6`, otherwise to a `struct sockaddr_in`. 1726 * Silently ignored if followed by NULL pointer. 1727 * @deprecated Use #MHD_OPTION_SOCK_ADDR_LEN 1728 */ 1729 MHD_OPTION_SOCK_ADDR = 6, 1730 1731 /** 1732 * Specify a function that should be called before parsing the URI from 1733 * the client. The specified callback function can be used for processing 1734 * the URI (including the options) before it is parsed. The URI after 1735 * parsing will no longer contain the options, which maybe inconvenient for 1736 * logging. This option should be followed by two arguments, the first 1737 * one must be of the form 1738 * 1739 * void * my_logger(void *cls, const char *uri, struct MHD_Connection *con) 1740 * 1741 * where the return value will be passed as 1742 * (`* req_cls`) in calls to the #MHD_AccessHandlerCallback 1743 * when this request is processed later; returning a 1744 * value of NULL has no special significance (however, 1745 * note that if you return non-NULL, you can no longer 1746 * rely on the first call to the access handler having 1747 * `NULL == *req_cls` on entry;) 1748 * "cls" will be set to the second argument following 1749 * #MHD_OPTION_URI_LOG_CALLBACK. Finally, uri will 1750 * be the 0-terminated URI of the request. 1751 * 1752 * Note that during the time of this call, most of the connection's 1753 * state is not initialized (as we have not yet parsed the headers). 1754 * However, information about the connecting client (IP, socket) 1755 * is available. 1756 * 1757 * The specified function is called only once per request, therefore some 1758 * programmers may use it to instantiate their own request objects, freeing 1759 * them in the notifier #MHD_OPTION_NOTIFY_COMPLETED. 1760 */ 1761 MHD_OPTION_URI_LOG_CALLBACK = 7, 1762 1763 /** 1764 * Memory pointer for the private key (key.pem) to be used by the 1765 * HTTPS daemon. This option should be followed by a 1766 * `const char *` argument. 1767 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_CERT. 1768 */ 1769 MHD_OPTION_HTTPS_MEM_KEY = 8, 1770 1771 /** 1772 * Memory pointer for the certificate (cert.pem) to be used by the 1773 * HTTPS daemon. This option should be followed by a 1774 * `const char *` argument. 1775 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY. 1776 */ 1777 MHD_OPTION_HTTPS_MEM_CERT = 9, 1778 1779 /** 1780 * Daemon credentials type. 1781 * Followed by an argument of type 1782 * `gnutls_credentials_type_t`. 1783 */ 1784 MHD_OPTION_HTTPS_CRED_TYPE = 10, 1785 1786 /** 1787 * Memory pointer to a `const char *` specifying the GnuTLS priorities string. 1788 * If this options is not specified, then MHD will try the following strings: 1789 * * "@LIBMICROHTTPD" (application-specific system-wide configuration) 1790 * * "@SYSTEM" (system-wide configuration) 1791 * * default GnuTLS priorities string 1792 * * "NORMAL" 1793 * The first configuration accepted by GnuTLS will be used. 1794 * For more details see GnuTLS documentation for "Application-specific 1795 * priority strings". 1796 */ 1797 MHD_OPTION_HTTPS_PRIORITIES = 11, 1798 1799 /** 1800 * Pass a listen socket for MHD to use (systemd-style). If this 1801 * option is used, MHD will not open its own listen socket(s). The 1802 * argument passed must be of type `MHD_socket` and refer to an 1803 * existing socket that has been bound to a port and is listening. 1804 * If followed by MHD_INVALID_SOCKET value, MHD ignores this option 1805 * and creates socket by itself. 1806 */ 1807 MHD_OPTION_LISTEN_SOCKET = 12, 1808 1809 /** 1810 * Use the given function for logging error messages. This option 1811 * must be followed by two arguments; the first must be a pointer to 1812 * a function of type #MHD_LogCallback and the second a pointer 1813 * `void *` which will be passed as the first argument to the log 1814 * callback. 1815 * Should be specified as the first option, otherwise some messages 1816 * may be printed by standard MHD logger during daemon startup. 1817 * 1818 * Note that MHD will not generate any log messages 1819 * if it was compiled without the "--enable-messages" 1820 * flag being set. 1821 */ 1822 MHD_OPTION_EXTERNAL_LOGGER = 13, 1823 1824 /** 1825 * Number (`unsigned int`) of threads in thread pool. Enable 1826 * thread pooling by setting this value to to something 1827 * greater than 1. 1828 * Can be used only for daemons started with #MHD_USE_INTERNAL_POLLING_THREAD. 1829 * Ignored if followed by zero value. 1830 */ 1831 MHD_OPTION_THREAD_POOL_SIZE = 14, 1832 1833 /** 1834 * Additional options given in an array of `struct MHD_OptionItem`. 1835 * The array must be terminated with an entry `{MHD_OPTION_END, 0, NULL}`. 1836 * An example for code using #MHD_OPTION_ARRAY is: 1837 * 1838 * struct MHD_OptionItem ops[] = { 1839 * { MHD_OPTION_CONNECTION_LIMIT, 100, NULL }, 1840 * { MHD_OPTION_CONNECTION_TIMEOUT, 10, NULL }, 1841 * { MHD_OPTION_END, 0, NULL } 1842 * }; 1843 * d = MHD_start_daemon (0, 8080, NULL, NULL, dh, NULL, 1844 * MHD_OPTION_ARRAY, ops, 1845 * MHD_OPTION_END); 1846 * 1847 * For options that expect a single pointer argument, the 1848 * 'value' member of the `struct MHD_OptionItem` is ignored. 1849 * For options that expect two pointer arguments, the first 1850 * argument must be cast to `intptr_t`. 1851 */ 1852 MHD_OPTION_ARRAY = 15, 1853 1854 /** 1855 * Specify a function that should be called for unescaping escape 1856 * sequences in URIs and URI arguments. Note that this function 1857 * will NOT be used by the `struct MHD_PostProcessor`. If this 1858 * option is not specified, the default method will be used which 1859 * decodes escape sequences of the form "%HH". This option should 1860 * be followed by two arguments, the first one must be of the form 1861 * 1862 * size_t my_unescaper(void *cls, 1863 * struct MHD_Connection *c, 1864 * char *s) 1865 * 1866 * where the return value must be the length of the value left in 1867 * "s" (without the 0-terminator) and "s" should be updated. Note 1868 * that the unescape function must not lengthen "s" (the result must 1869 * be shorter than the input and must still be 0-terminated). 1870 * However, it may also include binary zeros before the 1871 * 0-termination. "cls" will be set to the second argument 1872 * following #MHD_OPTION_UNESCAPE_CALLBACK. 1873 */ 1874 MHD_OPTION_UNESCAPE_CALLBACK = 16, 1875 1876 /** 1877 * Memory pointer for the random values to be used by the Digest 1878 * Auth module. This option should be followed by two arguments. 1879 * First an integer of type `size_t` which specifies the size 1880 * of the buffer pointed to by the second argument in bytes. 1881 * The recommended size is between 8 and 32. If size is four or less 1882 * then security could be lowered. Sizes more then 32 (or, probably 1883 * more than 16 - debatable) will not increase security. 1884 * Note that the application must ensure that the buffer of the 1885 * second argument remains allocated and unmodified while the 1886 * daemon is running. 1887 * @sa #MHD_OPTION_DIGEST_AUTH_RANDOM_COPY 1888 */ 1889 MHD_OPTION_DIGEST_AUTH_RANDOM = 17, 1890 1891 /** 1892 * Size of the internal array holding the map of the nonce and 1893 * the nonce counter. This option should be followed by an `unsigend int` 1894 * argument. 1895 * The map size is 4 by default, which is enough to communicate with 1896 * a single client at any given moment of time, but not enough to 1897 * handle several clients simultaneously. 1898 * If Digest Auth is not used, this option can be set to zero to minimise 1899 * memory allocation. 1900 */ 1901 MHD_OPTION_NONCE_NC_SIZE = 18, 1902 1903 /** 1904 * Desired size of the stack for threads created by MHD. Followed 1905 * by an argument of type `size_t`. Use 0 for system default. 1906 */ 1907 MHD_OPTION_THREAD_STACK_SIZE = 19, 1908 1909 /** 1910 * Memory pointer for the certificate (ca.pem) to be used by the 1911 * HTTPS daemon for client authentication. 1912 * This option should be followed by a `const char *` argument. 1913 */ 1914 MHD_OPTION_HTTPS_MEM_TRUST = 20, 1915 1916 /** 1917 * Increment to use for growing the read buffer (followed by a 1918 * `size_t`). 1919 * Must not be higher than 1/4 of #MHD_OPTION_CONNECTION_MEMORY_LIMIT. 1920 * Since #MHD_VERSION 0x00097710 silently ignored if followed by zero value. 1921 */ 1922 MHD_OPTION_CONNECTION_MEMORY_INCREMENT = 21, 1923 1924 /** 1925 * Use a callback to determine which X.509 certificate should be 1926 * used for a given HTTPS connection. This option should be 1927 * followed by a argument of type `gnutls_certificate_retrieve_function2 *`. 1928 * This option provides an 1929 * alternative to #MHD_OPTION_HTTPS_MEM_KEY, 1930 * #MHD_OPTION_HTTPS_MEM_CERT. You must use this version if 1931 * multiple domains are to be hosted at the same IP address using 1932 * TLS's Server Name Indication (SNI) extension. In this case, 1933 * the callback is expected to select the correct certificate 1934 * based on the SNI information provided. The callback is expected 1935 * to access the SNI data using `gnutls_server_name_get()`. 1936 * Using this option requires GnuTLS 3.0 or higher. 1937 */ 1938 MHD_OPTION_HTTPS_CERT_CALLBACK = 22, 1939 1940 /** 1941 * When using #MHD_USE_TCP_FASTOPEN, this option changes the default TCP 1942 * fastopen queue length of 50. Note that having a larger queue size can 1943 * cause resource exhaustion attack as the TCP stack has to now allocate 1944 * resources for the SYN packet along with its DATA. This option should be 1945 * followed by an `unsigned int` argument. 1946 */ 1947 MHD_OPTION_TCP_FASTOPEN_QUEUE_SIZE = 23, 1948 1949 /** 1950 * Memory pointer for the Diffie-Hellman parameters (dh.pem) to be used by the 1951 * HTTPS daemon for key exchange. 1952 * This option must be followed by a `const char *` argument. 1953 */ 1954 MHD_OPTION_HTTPS_MEM_DHPARAMS = 24, 1955 1956 /** 1957 * If present and set to true, allow reusing address:port socket 1958 * (by using SO_REUSEPORT on most platform, or platform-specific ways). 1959 * If present and set to false, disallow reusing address:port socket 1960 * (does nothing on most platform, but uses SO_EXCLUSIVEADDRUSE on Windows). 1961 * This option must be followed by a `unsigned int` argument. 1962 */ 1963 MHD_OPTION_LISTENING_ADDRESS_REUSE = 25, 1964 1965 /** 1966 * Memory pointer for a password that decrypts the private key (key.pem) 1967 * to be used by the HTTPS daemon. This option should be followed by a 1968 * `const char *` argument. 1969 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY. 1970 * @sa ::MHD_FEATURE_HTTPS_KEY_PASSWORD 1971 */ 1972 MHD_OPTION_HTTPS_KEY_PASSWORD = 26, 1973 1974 /** 1975 * Register a function that should be called whenever a connection is 1976 * started or closed. 1977 * 1978 * This option should be followed by TWO pointers. First a pointer 1979 * to a function of type #MHD_NotifyConnectionCallback and second a 1980 * pointer to a closure to pass to the request completed callback. 1981 * The second pointer may be NULL. 1982 */ 1983 MHD_OPTION_NOTIFY_CONNECTION = 27, 1984 1985 /** 1986 * Allow to change maximum length of the queue of pending connections on 1987 * listen socket. If not present than default platform-specific SOMAXCONN 1988 * value is used. This option should be followed by an `unsigned int` 1989 * argument. 1990 */ 1991 MHD_OPTION_LISTEN_BACKLOG_SIZE = 28, 1992 1993 /** 1994 * If set to 1 - be strict about the protocol. Use -1 to be 1995 * as tolerant as possible. 1996 * 1997 * The more flexible option #MHD_OPTION_CLIENT_DISCIPLINE_LVL is recommended 1998 * instead of this option. 1999 * 2000 * The values mapping table: 2001 * #MHD_OPTION_STRICT_FOR_CLIENT | #MHD_OPTION_CLIENT_DISCIPLINE_LVL 2002 * -----------------------------:|:--------------------------------- 2003 * 1 | 1 2004 * 0 | 0 2005 * -1 | -3 2006 * 2007 * This option should be followed by an `int` argument. 2008 * @sa #MHD_OPTION_CLIENT_DISCIPLINE_LVL 2009 */ 2010 MHD_OPTION_STRICT_FOR_CLIENT = 29, 2011 2012 /** 2013 * This should be a pointer to callback of type 2014 * gnutls_psk_server_credentials_function that will be given to 2015 * gnutls_psk_set_server_credentials_function. It is used to 2016 * retrieve the shared key for a given username. 2017 */ 2018 MHD_OPTION_GNUTLS_PSK_CRED_HANDLER = 30, 2019 2020 /** 2021 * Use a callback to determine which X.509 certificate should be 2022 * used for a given HTTPS connection. This option should be 2023 * followed by a argument of type `gnutls_certificate_retrieve_function3 *`. 2024 * This option provides an 2025 * alternative/extension to #MHD_OPTION_HTTPS_CERT_CALLBACK. 2026 * You must use this version if you want to use OCSP stapling. 2027 * Using this option requires GnuTLS 3.6.3 or higher. 2028 */ 2029 MHD_OPTION_HTTPS_CERT_CALLBACK2 = 31, 2030 2031 /** 2032 * Allows the application to disable certain sanity precautions 2033 * in MHD. With these, the client can break the HTTP protocol, 2034 * so this should never be used in production. The options are, 2035 * however, useful for testing HTTP clients against "broken" 2036 * server implementations. 2037 * This argument must be followed by an "unsigned int", corresponding 2038 * to an `enum MHD_DisableSanityCheck`. 2039 */ 2040 MHD_OPTION_SERVER_INSANITY = 32, 2041 2042 /** 2043 * If followed by value '1' informs MHD that SIGPIPE is suppressed or 2044 * handled by application. Allows MHD to use network functions that could 2045 * generate SIGPIPE, like `sendfile()`. 2046 * Valid only for daemons without #MHD_USE_INTERNAL_POLLING_THREAD as 2047 * MHD automatically suppresses SIGPIPE for threads started by MHD. 2048 * This option should be followed by an `int` argument. 2049 * @note Available since #MHD_VERSION 0x00097205 2050 */ 2051 MHD_OPTION_SIGPIPE_HANDLED_BY_APP = 33, 2052 2053 /** 2054 * If followed by 'int' with value '1' disables usage of ALPN for TLS 2055 * connections even if supported by TLS library. 2056 * Valid only for daemons with #MHD_USE_TLS. 2057 * This option should be followed by an `int` argument. 2058 * @note Available since #MHD_VERSION 0x00097207 2059 */ 2060 MHD_OPTION_TLS_NO_ALPN = 34, 2061 2062 /** 2063 * Memory pointer for the random values to be used by the Digest 2064 * Auth module. This option should be followed by two arguments. 2065 * First an integer of type `size_t` which specifies the size 2066 * of the buffer pointed to by the second argument in bytes. 2067 * The recommended size is between 8 and 32. If size is four or less 2068 * then security could be lowered. Sizes more then 32 (or, probably 2069 * more than 16 - debatable) will not increase security. 2070 * An internal copy of the buffer will be made, the data do not 2071 * need to be static. 2072 * @sa #MHD_OPTION_DIGEST_AUTH_RANDOM 2073 * @note Available since #MHD_VERSION 0x00097701 2074 */ 2075 MHD_OPTION_DIGEST_AUTH_RANDOM_COPY = 35, 2076 2077 /** 2078 * Allow to controls the scope of validity of MHD-generated nonces. 2079 * This regulates how "nonces" are generated and how "nonces" are checked by 2080 * #MHD_digest_auth_check3() and similar functions. 2081 * This option should be followed by an 'unsigned int` argument with value 2082 * formed as bitwise OR combination of #MHD_DAuthBindNonce values. 2083 * When not specified, default value #MHD_DAUTH_BIND_NONCE_NONE is used. 2084 * @note Available since #MHD_VERSION 0x00097701 2085 */ 2086 MHD_OPTION_DIGEST_AUTH_NONCE_BIND_TYPE = 36, 2087 2088 /** 2089 * Memory pointer to a `const char *` specifying the GnuTLS priorities to be 2090 * appended to default priorities. 2091 * This allow some specific options to be enabled/disabled, while leaving 2092 * the rest of the settings to their defaults. 2093 * The string does not have to start with a colon ':' character. 2094 * See #MHD_OPTION_HTTPS_PRIORITIES description for details of automatic 2095 * default priorities. 2096 * @note Available since #MHD_VERSION 0x00097701 2097 */ 2098 MHD_OPTION_HTTPS_PRIORITIES_APPEND = 37, 2099 2100 /** 2101 * Sets specified client discipline level (i.e. HTTP protocol parsing 2102 * strictness level). 2103 * 2104 * The following basic values are supported: 2105 * 0 - default MHD level, a balance between extra security and broader 2106 * compatibility, as allowed by RFCs for HTTP servers; 2107 * 1 - more strict protocol interpretation, within the limits set by 2108 * RFCs for HTTP servers; 2109 * -1 - more lenient protocol interpretation, within the limits set by 2110 * RFCs for HTTP servers. 2111 * The following extended values could be used as well: 2112 * 2 - stricter protocol interpretation, even stricter then allowed 2113 * by RFCs for HTTP servers, however it should be absolutely compatible 2114 * with clients following at least RFCs' "MUST" type of requirements 2115 * for HTTP clients; 2116 * 3 - strictest protocol interpretation, even stricter then allowed 2117 * by RFCs for HTTP servers, however it should be absolutely compatible 2118 * with clients following RFCs' "SHOULD" and "MUST" types of requirements 2119 * for HTTP clients; 2120 * -2 - more relaxed protocol interpretation, violating RFCs' "SHOULD" type 2121 * of requirements for HTTP servers; 2122 * -3 - the most flexible protocol interpretation, beyond RFCs' "MUST" type of 2123 * requirements for HTTP server. 2124 * Values higher than "3" or lower than "-3" are interpreted as "3" or "-3" 2125 * respectively. 2126 * 2127 * Higher values are more secure, lower values are more compatible with 2128 * various HTTP clients. 2129 * 2130 * The default value ("0") could be used in most cases. 2131 * Value "1" is suitable for highly loaded public servers. 2132 * Values "2" and "3" are generally recommended only for testing of HTTP 2133 * clients against MHD. 2134 * Value "2" may be used for security-centric application, however it is 2135 * slight violation of RFCs' requirements. 2136 * Negative values are not recommended for public servers. 2137 * Values "-1" and "-2" could be used for servers in isolated environment. 2138 * Value "-3" is not recommended unless it is absolutely necessary to 2139 * communicate with some client(s) with badly broken HTTP implementation. 2140 * 2141 * This option should be followed by an `int` argument. 2142 * @note Available since #MHD_VERSION 0x00097701 2143 */ 2144 MHD_OPTION_CLIENT_DISCIPLINE_LVL = 38, 2145 2146 /** 2147 * Specifies value of FD_SETSIZE used by application. Only For external 2148 * polling modes (without MHD internal threads). 2149 * Some platforms (FreeBSD, Solaris, W32 etc.) allow overriding of FD_SETSIZE 2150 * value. When polling by select() is used, MHD rejects sockets with numbers 2151 * equal or higher than FD_SETSIZE. If this option is used, MHD treats this 2152 * value as a limitation for socket number instead of FD_SETSIZE value which 2153 * was used for building MHD. 2154 * When external polling is used with #MHD_get_fdset2() (or #MHD_get_fdset() 2155 * macro) and #MHD_run_from_select() interfaces, it is recommended to always 2156 * use this option. 2157 * It is safe to use this option on platforms with fixed FD_SETSIZE (like 2158 * GNU/Linux) if system value of FD_SETSIZE is used as the argument. 2159 * Can be used only for daemons without #MHD_USE_INTERNAL_POLLING_THREAD, i.e. 2160 * only when external sockets polling is used. 2161 * On W32 it is silently ignored, as W32 does not limit the socket number in 2162 * fd_sets. 2163 * This option should be followed by a positive 'int' argument. 2164 * @note Available since #MHD_VERSION 0x00097705 2165 */ 2166 MHD_OPTION_APP_FD_SETSIZE = 39, 2167 2168 /** 2169 * Bind daemon to the supplied 'struct sockaddr'. This option should 2170 * be followed by two parameters: 'socklen_t' the size of memory at the next 2171 * pointer and the pointer 'const struct sockaddr *'. 2172 * Note: the order of the arguments is not the same as for system bind() and 2173 * other network functions. 2174 * If #MHD_USE_IPv6 is specified, the 'struct sockaddr*' should 2175 * point to a 'struct sockaddr_in6'. 2176 * The socket domain (protocol family) is detected from provided 2177 * 'struct sockaddr'. IP, IPv6 and UNIX sockets are supported (if supported 2178 * by the platform). Other types may work occasionally. 2179 * Silently ignored if followed by zero size and NULL pointer. 2180 * @note Available since #MHD_VERSION 0x00097706 2181 */ 2182 MHD_OPTION_SOCK_ADDR_LEN = 40 2183 , 2184 /** 2185 * Default nonce timeout value used for Digest Auth. 2186 * This option should be followed by an 'unsigned int' argument. 2187 * Silently ignored if followed by zero value. 2188 * @see #MHD_digest_auth_check3(), MHD_digest_auth_check_digest3() 2189 * @note Available since #MHD_VERSION 0x00097709 2190 */ 2191 MHD_OPTION_DIGEST_AUTH_DEFAULT_NONCE_TIMEOUT = 41 2192 , 2193 /** 2194 * Default maximum nc (nonce count) value used for Digest Auth. 2195 * This option should be followed by an 'uint32_t' argument. 2196 * Silently ignored if followed by zero value. 2197 * @see #MHD_digest_auth_check3(), MHD_digest_auth_check_digest3() 2198 * @note Available since #MHD_VERSION 0x00097709 2199 */ 2200 MHD_OPTION_DIGEST_AUTH_DEFAULT_MAX_NC = 42 2201 , 2202 /** 2203 * Default maximum nc (nonce count) value used for Digest Auth. 2204 * This option must be followed by an 'int' argument. 2205 * If followed by '0' (default) then: 2206 * + requests are rejected if request URI has binary zero (the result 2207 * of %00 decoding) in the path part of the URI. 2208 * If followed by '1' then: 2209 * + binary zero is allowed in request URI path; 2210 * + #MHD_AccessHandlerCallback called with NULL in @a url parameter when 2211 * request URI path has binary zero, the full @a url is available only 2212 * via #MHD_get_connection_URI_path_n() 2213 * If followed by '2' (unsafe!) then: 2214 * + binary zero is allowed in request URI path; 2215 * + #MHD_AccessHandlerCallback called with truncated (unsafe!) @a url 2216 * parameter when request URI path has binary zero. 2217 * @see #MHD_get_connection_URI_path_n() 2218 * @note Available since #MHD_VERSION 0x01000201 2219 */ 2220 MHD_OPTION_ALLOW_BIN_ZERO_IN_URI_PATH = 43 2221 2222 } _MHD_FIXED_ENUM; 2223 2224 2225 /** 2226 * Bitfield for the #MHD_OPTION_SERVER_INSANITY specifying 2227 * which santiy checks should be disabled. 2228 */ 2229 enum MHD_DisableSanityCheck 2230 { 2231 /** 2232 * All sanity checks are enabled. 2233 */ 2234 MHD_DSC_SANE = 0 2235 2236 } _MHD_FIXED_FLAGS_ENUM; 2237 2238 2239 /** 2240 * Entry in an #MHD_OPTION_ARRAY. 2241 */ 2242 struct MHD_OptionItem 2243 { 2244 /** 2245 * Which option is being given. Use #MHD_OPTION_END 2246 * to terminate the array. 2247 */ 2248 enum MHD_OPTION option; 2249 2250 /** 2251 * Option value (for integer arguments, and for options requiring 2252 * two pointer arguments); should be 0 for options that take no 2253 * arguments or only a single pointer argument. 2254 */ 2255 intptr_t value; 2256 2257 /** 2258 * Pointer option value (use NULL for options taking no arguments 2259 * or only an integer option). 2260 */ 2261 void *ptr_value; 2262 2263 }; 2264 2265 2266 /** 2267 * The `enum MHD_ValueKind` specifies the source of 2268 * the key-value pairs in the HTTP protocol. 2269 */ 2270 enum MHD_ValueKind 2271 { 2272 2273 /** 2274 * Response header 2275 * @deprecated 2276 */ 2277 MHD_RESPONSE_HEADER_KIND = 0, 2278 #define MHD_RESPONSE_HEADER_KIND \ 2279 _MHD_DEPR_IN_MACRO ( \ 2280 "Value MHD_RESPONSE_HEADER_KIND is deprecated and not used") \ 2281 MHD_RESPONSE_HEADER_KIND 2282 2283 /** 2284 * HTTP header (request/response). 2285 */ 2286 MHD_HEADER_KIND = 1, 2287 2288 /** 2289 * Cookies. Note that the original HTTP header containing 2290 * the cookie(s) will still be available and intact. 2291 */ 2292 MHD_COOKIE_KIND = 2, 2293 2294 /** 2295 * POST data. This is available only if a content encoding 2296 * supported by MHD is used (currently only URL encoding), 2297 * and only if the posted content fits within the available 2298 * memory pool. Note that in that case, the upload data 2299 * given to the #MHD_AccessHandlerCallback will be 2300 * empty (since it has already been processed). 2301 */ 2302 MHD_POSTDATA_KIND = 4, 2303 2304 /** 2305 * GET (URI) arguments. 2306 */ 2307 MHD_GET_ARGUMENT_KIND = 8, 2308 2309 /** 2310 * HTTP footer (only for HTTP 1.1 chunked encodings). 2311 */ 2312 MHD_FOOTER_KIND = 16 2313 } _MHD_FIXED_ENUM; 2314 2315 2316 /** 2317 * The `enum MHD_RequestTerminationCode` specifies reasons 2318 * why a request has been terminated (or completed). 2319 * @ingroup request 2320 */ 2321 enum MHD_RequestTerminationCode 2322 { 2323 2324 /** 2325 * We finished sending the response. 2326 * @ingroup request 2327 */ 2328 MHD_REQUEST_TERMINATED_COMPLETED_OK = 0, 2329 2330 /** 2331 * Error handling the connection (resources 2332 * exhausted, application error accepting request, 2333 * decrypt error (for HTTPS), connection died when 2334 * sending the response etc.) 2335 * @ingroup request 2336 */ 2337 MHD_REQUEST_TERMINATED_WITH_ERROR = 1, 2338 2339 /** 2340 * No activity on the connection for the number 2341 * of seconds specified using 2342 * #MHD_OPTION_CONNECTION_TIMEOUT. 2343 * @ingroup request 2344 */ 2345 MHD_REQUEST_TERMINATED_TIMEOUT_REACHED = 2, 2346 2347 /** 2348 * We had to close the session since MHD was being 2349 * shut down. 2350 * @ingroup request 2351 */ 2352 MHD_REQUEST_TERMINATED_DAEMON_SHUTDOWN = 3, 2353 2354 /** 2355 * We tried to read additional data, but the connection became broken or 2356 * the other side hard closed the connection. 2357 * This error is similar to #MHD_REQUEST_TERMINATED_WITH_ERROR, but 2358 * specific to the case where the connection died before request completely 2359 * received. 2360 * @ingroup request 2361 */ 2362 MHD_REQUEST_TERMINATED_READ_ERROR = 4, 2363 2364 /** 2365 * The client terminated the connection by closing the socket 2366 * for writing (TCP half-closed) while still sending request. 2367 * @ingroup request 2368 */ 2369 MHD_REQUEST_TERMINATED_CLIENT_ABORT = 5 2370 2371 } _MHD_FIXED_ENUM; 2372 2373 2374 /** 2375 * The `enum MHD_ConnectionNotificationCode` specifies types 2376 * of connection notifications. 2377 * @ingroup request 2378 */ 2379 enum MHD_ConnectionNotificationCode 2380 { 2381 2382 /** 2383 * A new connection has been started. 2384 * @ingroup request 2385 */ 2386 MHD_CONNECTION_NOTIFY_STARTED = 0, 2387 2388 /** 2389 * A connection is closed. 2390 * @ingroup request 2391 */ 2392 MHD_CONNECTION_NOTIFY_CLOSED = 1 2393 2394 } _MHD_FIXED_ENUM; 2395 2396 2397 /** 2398 * Information about a connection. 2399 */ 2400 union MHD_ConnectionInfo 2401 { 2402 2403 /** 2404 * Cipher algorithm used, of type "enum gnutls_cipher_algorithm". 2405 */ 2406 int /* enum gnutls_cipher_algorithm */ cipher_algorithm; 2407 2408 /** 2409 * Protocol used, of type "enum gnutls_protocol". 2410 */ 2411 int /* enum gnutls_protocol */ protocol; 2412 2413 /** 2414 * The suspended status of a connection. 2415 */ 2416 int /* MHD_YES or MHD_NO */ suspended; 2417 2418 /** 2419 * Amount of second that connection could spend in idle state 2420 * before automatically disconnected. 2421 * Zero for no timeout (unlimited idle time). 2422 */ 2423 unsigned int connection_timeout; 2424 2425 /** 2426 * HTTP status queued with the response, for #MHD_CONNECTION_INFO_HTTP_STATUS. 2427 */ 2428 unsigned int http_status; 2429 2430 /** 2431 * Connect socket 2432 */ 2433 MHD_socket connect_fd; 2434 2435 /** 2436 * Size of the client's HTTP header. 2437 * It includes the request line, all request headers, the header section 2438 * terminating empty line, with all CRLF (or LF) characters. 2439 */ 2440 size_t header_size; 2441 2442 /** 2443 * GNUtls session handle, of type "gnutls_session_t". 2444 */ 2445 void * /* gnutls_session_t */ tls_session; 2446 2447 /** 2448 * GNUtls client certificate handle, of type "gnutls_x509_crt_t". 2449 */ 2450 void * /* gnutls_x509_crt_t */ client_cert; 2451 2452 /** 2453 * Address information for the client. 2454 */ 2455 struct sockaddr *client_addr; 2456 2457 /** 2458 * Which daemon manages this connection (useful in case there are many 2459 * daemons running). 2460 */ 2461 struct MHD_Daemon *daemon; 2462 2463 /** 2464 * Socket-specific client context. Points to the same address as 2465 * the "socket_context" of the #MHD_NotifyConnectionCallback. 2466 */ 2467 void *socket_context; 2468 }; 2469 2470 2471 /** 2472 * I/O vector type. Provided for use with #MHD_create_response_from_iovec(). 2473 * @note Available since #MHD_VERSION 0x00097204 2474 */ 2475 struct MHD_IoVec 2476 { 2477 /** 2478 * The pointer to the memory region for I/O. 2479 */ 2480 const void *iov_base; 2481 2482 /** 2483 * The size in bytes of the memory region for I/O. 2484 */ 2485 size_t iov_len; 2486 }; 2487 2488 2489 /** 2490 * Values of this enum are used to specify what 2491 * information about a connection is desired. 2492 * @ingroup request 2493 */ 2494 enum MHD_ConnectionInfoType 2495 { 2496 /** 2497 * What cipher algorithm is being used. 2498 * Takes no extra arguments. 2499 * @ingroup request 2500 */ 2501 MHD_CONNECTION_INFO_CIPHER_ALGO, 2502 2503 /** 2504 * 2505 * Takes no extra arguments. 2506 * @ingroup request 2507 */ 2508 MHD_CONNECTION_INFO_PROTOCOL, 2509 2510 /** 2511 * Obtain IP address of the client. Takes no extra arguments. 2512 * Returns essentially a `struct sockaddr **` (since the API returns 2513 * a `union MHD_ConnectionInfo *` and that union contains a `struct 2514 * sockaddr *`). 2515 * @ingroup request 2516 */ 2517 MHD_CONNECTION_INFO_CLIENT_ADDRESS, 2518 2519 /** 2520 * Get the gnuTLS session handle. 2521 * @ingroup request 2522 */ 2523 MHD_CONNECTION_INFO_GNUTLS_SESSION, 2524 2525 /** 2526 * Get the gnuTLS client certificate handle. Dysfunctional (never 2527 * implemented, deprecated). Use #MHD_CONNECTION_INFO_GNUTLS_SESSION 2528 * to get the `gnutls_session_t` and then call 2529 * gnutls_certificate_get_peers(). 2530 */ 2531 MHD_CONNECTION_INFO_GNUTLS_CLIENT_CERT, 2532 2533 /** 2534 * Get the `struct MHD_Daemon *` responsible for managing this connection. 2535 * @ingroup request 2536 */ 2537 MHD_CONNECTION_INFO_DAEMON, 2538 2539 /** 2540 * Request the file descriptor for the connection socket. 2541 * MHD sockets are always in non-blocking mode. 2542 * No extra arguments should be passed. 2543 * @ingroup request 2544 */ 2545 MHD_CONNECTION_INFO_CONNECTION_FD, 2546 2547 /** 2548 * Returns the client-specific pointer to a `void *` that was (possibly) 2549 * set during a #MHD_NotifyConnectionCallback when the socket was 2550 * first accepted. 2551 * Note that this is NOT the same as the "req_cls" argument of 2552 * the #MHD_AccessHandlerCallback. The "req_cls" is fresh for each 2553 * HTTP request, while the "socket_context" is fresh for each socket. 2554 */ 2555 MHD_CONNECTION_INFO_SOCKET_CONTEXT, 2556 2557 /** 2558 * Check whether the connection is suspended. 2559 * @ingroup request 2560 */ 2561 MHD_CONNECTION_INFO_CONNECTION_SUSPENDED, 2562 2563 /** 2564 * Get connection timeout 2565 * @ingroup request 2566 */ 2567 MHD_CONNECTION_INFO_CONNECTION_TIMEOUT, 2568 2569 /** 2570 * Return length of the client's HTTP request header. 2571 * @ingroup request 2572 */ 2573 MHD_CONNECTION_INFO_REQUEST_HEADER_SIZE, 2574 2575 /** 2576 * Return HTTP status queued with the response. NULL 2577 * if no HTTP response has been queued yet. 2578 */ 2579 MHD_CONNECTION_INFO_HTTP_STATUS 2580 2581 } _MHD_FIXED_ENUM; 2582 2583 2584 /** 2585 * Values of this enum are used to specify what 2586 * information about a daemon is desired. 2587 */ 2588 enum MHD_DaemonInfoType 2589 { 2590 /** 2591 * No longer supported (will return NULL). 2592 */ 2593 MHD_DAEMON_INFO_KEY_SIZE, 2594 2595 /** 2596 * No longer supported (will return NULL). 2597 */ 2598 MHD_DAEMON_INFO_MAC_KEY_SIZE, 2599 2600 /** 2601 * Request the file descriptor for the listening socket. 2602 * No extra arguments should be passed. 2603 */ 2604 MHD_DAEMON_INFO_LISTEN_FD, 2605 2606 /** 2607 * Request the file descriptor for the "external" sockets polling 2608 * when 'epoll' mode is used. 2609 * No extra arguments should be passed. 2610 * 2611 * Waiting on epoll FD must not block longer than value 2612 * returned by #MHD_get_timeout() otherwise connections 2613 * will "hung" with unprocessed data in network buffers 2614 * and timed-out connections will not be closed. 2615 * 2616 * @sa #MHD_get_timeout(), #MHD_run() 2617 */ 2618 MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY, 2619 MHD_DAEMON_INFO_EPOLL_FD = MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY, 2620 2621 /** 2622 * Request the number of current connections handled by the daemon. 2623 * No extra arguments should be passed. 2624 * Note: when using MHD in "external" polling mode, this type of request 2625 * could be used only when #MHD_run()/#MHD_run_from_select is not 2626 * working in other thread at the same time. 2627 */ 2628 MHD_DAEMON_INFO_CURRENT_CONNECTIONS, 2629 2630 /** 2631 * Request the daemon flags. 2632 * No extra arguments should be passed. 2633 * Note: flags may differ from original 'flags' specified for 2634 * daemon, especially if #MHD_USE_AUTO was set. 2635 */ 2636 MHD_DAEMON_INFO_FLAGS, 2637 2638 /** 2639 * Request the port number of daemon's listen socket. 2640 * No extra arguments should be passed. 2641 * Note: if port '0' was specified for #MHD_start_daemon(), returned 2642 * value will be real port number. 2643 */ 2644 MHD_DAEMON_INFO_BIND_PORT 2645 } _MHD_FIXED_ENUM; 2646 2647 2648 /** 2649 * Callback for serious error condition. The default action is to print 2650 * an error message and `abort()`. 2651 * 2652 * @param cls user specified value 2653 * @param file where the error occurred, may be NULL if MHD was built without 2654 * messages support 2655 * @param line where the error occurred 2656 * @param reason error detail, may be NULL 2657 * @ingroup logging 2658 */ 2659 typedef void 2660 (*MHD_PanicCallback) (void *cls, 2661 const char *file, 2662 unsigned int line, 2663 const char *reason); 2664 2665 /** 2666 * Allow or deny a client to connect. 2667 * 2668 * @param cls closure 2669 * @param addr address information from the client 2670 * @param addrlen length of @a addr 2671 * @return #MHD_YES if connection is allowed, #MHD_NO if not 2672 */ 2673 typedef enum MHD_Result 2674 (*MHD_AcceptPolicyCallback)(void *cls, 2675 const struct sockaddr *addr, 2676 socklen_t addrlen); 2677 2678 2679 /** 2680 * A client has requested the given @a url using the given @a method 2681 * (#MHD_HTTP_METHOD_GET, #MHD_HTTP_METHOD_PUT, #MHD_HTTP_METHOD_DELETE, 2682 * #MHD_HTTP_METHOD_POST, etc). 2683 * 2684 * The callback must call MHD function MHD_queue_response() to provide content 2685 * to give back to the client and return an HTTP status code (i.e. 2686 * #MHD_HTTP_OK, #MHD_HTTP_NOT_FOUND, etc.). The response can be created 2687 * in this callback or prepared in advance. 2688 * Alternatively, callback may call MHD_suspend_connection() to temporarily 2689 * suspend data processing for this connection. 2690 * 2691 * As soon as response is provided this callback will not be called anymore 2692 * for the current request. 2693 * 2694 * For each HTTP request this callback is called several times: 2695 * * after request headers are fully received and decoded, 2696 * * for each received part of request body (optional, if request has body), 2697 * * when request is fully received. 2698 * 2699 * If response is provided before request is fully received, the rest 2700 * of the request is discarded and connection is automatically closed 2701 * after sending response. 2702 * 2703 * If the request is fully received, but response hasn't been provided and 2704 * connection is not suspended, the callback can be called again immediately. 2705 * 2706 * The response cannot be queued when this callback is called to process 2707 * the client upload data (when @a upload_data is not NULL). 2708 * 2709 * @param cls argument given together with the function 2710 * pointer when the handler was registered with MHD 2711 * @param connection the connection handle 2712 * @param url the requested url, can be truncated or can be NULL, depending 2713 * on #MHD_OPTION_ALLOW_BIN_ZERO_IN_URI_PATH option, 2714 * see #MHD_get_connection_URI_path_n() 2715 * @param method the HTTP method used (#MHD_HTTP_METHOD_GET, 2716 * #MHD_HTTP_METHOD_PUT, etc.) 2717 * @param version the HTTP version string (i.e. 2718 * #MHD_HTTP_VERSION_1_1) 2719 * @param upload_data the data being uploaded (excluding HEADERS, 2720 * for a POST that fits into memory and that is encoded 2721 * with a supported encoding, the POST data will NOT be 2722 * given in upload_data and is instead available as 2723 * part of #MHD_get_connection_values; very large POST 2724 * data *will* be made available incrementally in 2725 * @a upload_data) 2726 * @param[in,out] upload_data_size set initially to the size of the 2727 * @a upload_data provided; the method must update this 2728 * value to the number of bytes NOT processed; 2729 * @param[in,out] req_cls pointer that the callback can set to some 2730 * address and that will be preserved by MHD for future 2731 * calls for this request; since the access handler may 2732 * be called many times (i.e., for a PUT/POST operation 2733 * with plenty of upload data) this allows the application 2734 * to easily associate some request-specific state. 2735 * If necessary, this state can be cleaned up in the 2736 * global #MHD_RequestCompletedCallback (which 2737 * can be set with the #MHD_OPTION_NOTIFY_COMPLETED). 2738 * Initially, `*req_cls` will be NULL. 2739 * @return #MHD_YES if the connection was handled successfully, 2740 * #MHD_NO if the socket must be closed due to a serious 2741 * error while handling the request 2742 * 2743 * @sa #MHD_queue_response(), #MHD_get_connection_URI_path_n() 2744 */ 2745 typedef enum MHD_Result 2746 (*MHD_AccessHandlerCallback)(void *cls, 2747 struct MHD_Connection *connection, 2748 const char *url, 2749 const char *method, 2750 const char *version, 2751 const char *upload_data, 2752 size_t *upload_data_size, 2753 void **req_cls); 2754 2755 2756 /** 2757 * Signature of the callback used by MHD to notify the 2758 * application about completed requests. 2759 * 2760 * @param cls client-defined closure 2761 * @param connection connection handle 2762 * @param req_cls value as set by the last call to 2763 * the #MHD_AccessHandlerCallback 2764 * @param toe reason for request termination 2765 * @see #MHD_OPTION_NOTIFY_COMPLETED 2766 * @ingroup request 2767 */ 2768 typedef void 2769 (*MHD_RequestCompletedCallback) (void *cls, 2770 struct MHD_Connection *connection, 2771 void **req_cls, 2772 enum MHD_RequestTerminationCode toe); 2773 2774 2775 /** 2776 * Signature of the callback used by MHD to notify the 2777 * application about started/stopped connections 2778 * 2779 * @param cls client-defined closure 2780 * @param connection connection handle 2781 * @param socket_context socket-specific pointer where the 2782 * client can associate some state specific 2783 * to the TCP connection; note that this is 2784 * different from the "req_cls" which is per 2785 * HTTP request. The client can initialize 2786 * during #MHD_CONNECTION_NOTIFY_STARTED and 2787 * cleanup during #MHD_CONNECTION_NOTIFY_CLOSED 2788 * and access in the meantime using 2789 * #MHD_CONNECTION_INFO_SOCKET_CONTEXT. 2790 * @param toe reason for connection notification 2791 * @see #MHD_OPTION_NOTIFY_CONNECTION 2792 * @ingroup request 2793 */ 2794 typedef void 2795 (*MHD_NotifyConnectionCallback) (void *cls, 2796 struct MHD_Connection *connection, 2797 void **socket_context, 2798 enum MHD_ConnectionNotificationCode toe); 2799 2800 2801 /** 2802 * Iterator over key-value pairs. This iterator 2803 * can be used to iterate over all of the cookies, 2804 * headers, or POST-data fields of a request, and 2805 * also to iterate over the headers that have been 2806 * added to a response. 2807 * 2808 * @param cls closure 2809 * @param kind kind of the header we are looking at 2810 * @param key key for the value, can be an empty string 2811 * @param value corresponding value, can be NULL 2812 * @return #MHD_YES to continue iterating, 2813 * #MHD_NO to abort the iteration 2814 * @ingroup request 2815 */ 2816 typedef enum MHD_Result 2817 (*MHD_KeyValueIterator)(void *cls, 2818 enum MHD_ValueKind kind, 2819 const char *key, 2820 const char *value); 2821 2822 2823 /** 2824 * Iterator over key-value pairs with size parameters. 2825 * This iterator can be used to iterate over all of 2826 * the cookies, headers, or POST-data fields of a 2827 * request, and also to iterate over the headers that 2828 * have been added to a response. 2829 * @note Available since #MHD_VERSION 0x00096303 2830 * 2831 * @param cls closure 2832 * @param kind kind of the header we are looking at 2833 * @param key key for the value, can be an empty string 2834 * @param value corresponding value, can be NULL 2835 * @param value_size number of bytes in @a value; 2836 * for C-strings, the length excludes the 0-terminator 2837 * @return #MHD_YES to continue iterating, 2838 * #MHD_NO to abort the iteration 2839 * @ingroup request 2840 */ 2841 typedef enum MHD_Result 2842 (*MHD_KeyValueIteratorN)(void *cls, 2843 enum MHD_ValueKind kind, 2844 const char *key, 2845 size_t key_size, 2846 const char *value, 2847 size_t value_size); 2848 2849 2850 /** 2851 * Callback used by libmicrohttpd in order to obtain content. 2852 * 2853 * The callback is to copy at most @a max bytes of content into @a buf. 2854 * The total number of bytes that has been placed into @a buf should be 2855 * returned. 2856 * 2857 * Note that returning zero will cause libmicrohttpd to try again. 2858 * Thus, returning zero should only be used in conjunction 2859 * with MHD_suspend_connection() to avoid busy waiting. 2860 * 2861 * @param cls extra argument to the callback 2862 * @param pos position in the datastream to access; 2863 * note that if a `struct MHD_Response` object is re-used, 2864 * it is possible for the same content reader to 2865 * be queried multiple times for the same data; 2866 * however, if a `struct MHD_Response` is not re-used, 2867 * libmicrohttpd guarantees that "pos" will be 2868 * the sum of all non-negative return values 2869 * obtained from the content reader so far. 2870 * @param buf where to copy the data 2871 * @param max maximum number of bytes to copy to @a buf (size of @a buf) 2872 * @return number of bytes written to @a buf; 2873 * 0 is legal unless MHD is started in "internal" sockets polling mode 2874 * (since this would cause busy-waiting); 0 in "external" sockets 2875 * polling mode will cause this function to be called again once 2876 * any MHD_run*() function is called; 2877 * #MHD_CONTENT_READER_END_OF_STREAM (-1) for the regular 2878 * end of transmission (with chunked encoding, MHD will then 2879 * terminate the chunk and send any HTTP footers that might be 2880 * present; without chunked encoding and given an unknown 2881 * response size, MHD will simply close the connection; note 2882 * that while returning #MHD_CONTENT_READER_END_OF_STREAM is not technically 2883 * legal if a response size was specified, MHD accepts this 2884 * and treats it just as #MHD_CONTENT_READER_END_WITH_ERROR; 2885 * #MHD_CONTENT_READER_END_WITH_ERROR (-2) to indicate a server 2886 * error generating the response; this will cause MHD to simply 2887 * close the connection immediately. If a response size was 2888 * given or if chunked encoding is in use, this will indicate 2889 * an error to the client. Note, however, that if the client 2890 * does not know a response size and chunked encoding is not in 2891 * use, then clients will not be able to tell the difference between 2892 * #MHD_CONTENT_READER_END_WITH_ERROR and #MHD_CONTENT_READER_END_OF_STREAM. 2893 * This is not a limitation of MHD but rather of the HTTP protocol. 2894 */ 2895 typedef ssize_t 2896 (*MHD_ContentReaderCallback) (void *cls, 2897 uint64_t pos, 2898 char *buf, 2899 size_t max); 2900 2901 2902 /** 2903 * This method is called by libmicrohttpd if we 2904 * are done with a content reader. It should 2905 * be used to free resources associated with the 2906 * content reader. 2907 * 2908 * @param cls closure 2909 * @ingroup response 2910 */ 2911 typedef void 2912 (*MHD_ContentReaderFreeCallback) (void *cls); 2913 2914 2915 /** 2916 * Iterator over key-value pairs where the value 2917 * may be made available in increments and/or may 2918 * not be zero-terminated. Used for processing 2919 * POST data. 2920 * 2921 * @param cls user-specified closure 2922 * @param kind type of the value, always #MHD_POSTDATA_KIND when called from MHD 2923 * @param key 0-terminated key for the value, NULL if not known. This value 2924 * is never NULL for url-encoded POST data. 2925 * @param filename name of the uploaded file, NULL if not known 2926 * @param content_type mime-type of the data, NULL if not known 2927 * @param transfer_encoding encoding of the data, NULL if not known 2928 * @param data pointer to @a size bytes of data at the 2929 * specified offset 2930 * @param off offset of data in the overall value 2931 * @param size number of bytes in @a data available 2932 * @return #MHD_YES to continue iterating, 2933 * #MHD_NO to abort the iteration 2934 */ 2935 typedef enum MHD_Result 2936 (*MHD_PostDataIterator)(void *cls, 2937 enum MHD_ValueKind kind, 2938 const char *key, 2939 const char *filename, 2940 const char *content_type, 2941 const char *transfer_encoding, 2942 const char *data, 2943 uint64_t off, 2944 size_t size); 2945 2946 /* **************** Daemon handling functions ***************** */ 2947 2948 /** 2949 * Start a webserver on the given port. 2950 * 2951 * @param flags combination of `enum MHD_FLAG` values 2952 * @param port port to bind to (in host byte order), 2953 * use '0' to bind to random free port, 2954 * ignored if MHD_OPTION_SOCK_ADDR or 2955 * MHD_OPTION_LISTEN_SOCKET is provided 2956 * or MHD_USE_NO_LISTEN_SOCKET is specified 2957 * @param apc callback to call to check which clients 2958 * will be allowed to connect; you can pass NULL 2959 * in which case connections from any IP will be 2960 * accepted 2961 * @param apc_cls extra argument to apc 2962 * @param dh handler called for all requests (repeatedly) 2963 * @param dh_cls extra argument to @a dh 2964 * @param ap list of options (type-value pairs, 2965 * terminated with #MHD_OPTION_END). 2966 * @return NULL on error, handle to daemon on success 2967 * @ingroup event 2968 */ 2969 _MHD_EXTERN struct MHD_Daemon * 2970 MHD_start_daemon_va (unsigned int flags, 2971 uint16_t port, 2972 MHD_AcceptPolicyCallback apc, void *apc_cls, 2973 MHD_AccessHandlerCallback dh, void *dh_cls, 2974 va_list ap); 2975 2976 2977 /** 2978 * Start a webserver on the given port. Variadic version of 2979 * #MHD_start_daemon_va. 2980 * 2981 * @param flags combination of `enum MHD_FLAG` values 2982 * @param port port to bind to (in host byte order), 2983 * use '0' to bind to random free port, 2984 * ignored if MHD_OPTION_SOCK_ADDR or 2985 * MHD_OPTION_LISTEN_SOCKET is provided 2986 * or MHD_USE_NO_LISTEN_SOCKET is specified 2987 * @param apc callback to call to check which clients 2988 * will be allowed to connect; you can pass NULL 2989 * in which case connections from any IP will be 2990 * accepted 2991 * @param apc_cls extra argument to apc 2992 * @param dh handler called for all requests (repeatedly) 2993 * @param dh_cls extra argument to @a dh 2994 * @return NULL on error, handle to daemon on success 2995 * @ingroup event 2996 */ 2997 _MHD_EXTERN struct MHD_Daemon * 2998 MHD_start_daemon (unsigned int flags, 2999 uint16_t port, 3000 MHD_AcceptPolicyCallback apc, void *apc_cls, 3001 MHD_AccessHandlerCallback dh, void *dh_cls, 3002 ...); 3003 3004 3005 /** 3006 * Stop accepting connections from the listening socket. Allows 3007 * clients to continue processing, but stops accepting new 3008 * connections. Note that the caller is responsible for closing the 3009 * returned socket; however, if MHD is run using threads (anything but 3010 * "external" sockets polling mode), it must not be closed until AFTER 3011 * #MHD_stop_daemon has been called (as it is theoretically possible 3012 * that an existing thread is still using it). 3013 * 3014 * Note that some thread modes require the caller to have passed 3015 * #MHD_USE_ITC when using this API. If this daemon is 3016 * in one of those modes and this option was not given to 3017 * #MHD_start_daemon, this function will return #MHD_INVALID_SOCKET. 3018 * 3019 * @param daemon daemon to stop accepting new connections for 3020 * @return old listen socket on success, #MHD_INVALID_SOCKET if 3021 * the daemon was already not listening anymore 3022 * @ingroup specialized 3023 */ 3024 _MHD_EXTERN MHD_socket 3025 MHD_quiesce_daemon (struct MHD_Daemon *daemon); 3026 3027 3028 /** 3029 * Shutdown an HTTP daemon. 3030 * 3031 * @param daemon daemon to stop 3032 * @ingroup event 3033 */ 3034 _MHD_EXTERN void 3035 MHD_stop_daemon (struct MHD_Daemon *daemon); 3036 3037 3038 /** 3039 * Add another client connection to the set of connections managed by 3040 * MHD. This API is usually not needed (since MHD will accept inbound 3041 * connections on the server socket). Use this API in special cases, 3042 * for example if your HTTP server is behind NAT and needs to connect 3043 * out to the HTTP client, or if you are building a proxy. 3044 * 3045 * If you use this API in conjunction with an "internal" socket polling, 3046 * you must set the option #MHD_USE_ITC to ensure that the freshly added 3047 * connection is immediately processed by MHD. 3048 * 3049 * The given client socket will be managed (and closed!) by MHD after 3050 * this call and must no longer be used directly by the application 3051 * afterwards. 3052 * 3053 * @param daemon daemon that manages the connection 3054 * @param client_socket socket to manage (MHD will expect 3055 * to receive an HTTP request from this socket next). 3056 * @param addr IP address of the client 3057 * @param addrlen number of bytes in @a addr 3058 * @return #MHD_YES on success, #MHD_NO if this daemon could 3059 * not handle the connection (i.e. `malloc()` failed, etc). 3060 * The socket will be closed in any case; `errno` is 3061 * set to indicate further details about the error. 3062 * @ingroup specialized 3063 */ 3064 _MHD_EXTERN enum MHD_Result 3065 MHD_add_connection (struct MHD_Daemon *daemon, 3066 MHD_socket client_socket, 3067 const struct sockaddr *addr, 3068 socklen_t addrlen); 3069 3070 3071 /** 3072 * Obtain the `select()` sets for this daemon. 3073 * Daemon's FDs will be added to fd_sets. To get only 3074 * daemon FDs in fd_sets, call FD_ZERO for each fd_set 3075 * before calling this function. FD_SETSIZE is assumed 3076 * to be platform's default. 3077 * 3078 * This function should be called only when MHD is configured to 3079 * use "external" sockets polling with 'select()' or with 'epoll'. 3080 * In the latter case, it will only add the single 'epoll' file 3081 * descriptor used by MHD to the sets. 3082 * It's necessary to use #MHD_get_timeout() to get maximum timeout 3083 * value for `select()`. Usage of `select()` with indefinite timeout 3084 * (or timeout larger than returned by #MHD_get_timeout()) will 3085 * violate MHD API and may results in pending unprocessed data. 3086 * 3087 * This function must be called only for daemon started 3088 * without #MHD_USE_INTERNAL_POLLING_THREAD flag. 3089 * 3090 * @param daemon daemon to get sets from 3091 * @param read_fd_set read set 3092 * @param write_fd_set write set 3093 * @param except_fd_set except set 3094 * @param max_fd increased to largest FD added (if larger 3095 * than existing value); can be NULL 3096 * @return #MHD_YES on success, #MHD_NO if this 3097 * daemon was not started with the right 3098 * options for this call or any FD didn't 3099 * fit fd_set. 3100 * @ingroup event 3101 */ 3102 _MHD_EXTERN enum MHD_Result 3103 MHD_get_fdset (struct MHD_Daemon *daemon, 3104 fd_set *read_fd_set, 3105 fd_set *write_fd_set, 3106 fd_set *except_fd_set, 3107 MHD_socket *max_fd); 3108 3109 3110 /** 3111 * Obtain the `select()` sets for this daemon. 3112 * Daemon's FDs will be added to fd_sets. To get only 3113 * daemon FDs in fd_sets, call FD_ZERO for each fd_set 3114 * before calling this function. 3115 * 3116 * Passing custom FD_SETSIZE as @a fd_setsize allow usage of 3117 * larger/smaller than platform's default fd_sets. 3118 * 3119 * This function should be called only when MHD is configured to 3120 * use "external" sockets polling with 'select()' or with 'epoll'. 3121 * In the latter case, it will only add the single 'epoll' file 3122 * descriptor used by MHD to the sets. 3123 * It's necessary to use #MHD_get_timeout() to get maximum timeout 3124 * value for `select()`. Usage of `select()` with indefinite timeout 3125 * (or timeout larger than returned by #MHD_get_timeout()) will 3126 * violate MHD API and may results in pending unprocessed data. 3127 * 3128 * This function must be called only for daemon started 3129 * without #MHD_USE_INTERNAL_POLLING_THREAD flag. 3130 * 3131 * @param daemon daemon to get sets from 3132 * @param read_fd_set read set 3133 * @param write_fd_set write set 3134 * @param except_fd_set except set 3135 * @param max_fd increased to largest FD added (if larger 3136 * than existing value); can be NULL 3137 * @param fd_setsize value of FD_SETSIZE 3138 * @return #MHD_YES on success, #MHD_NO if this 3139 * daemon was not started with the right 3140 * options for this call or any FD didn't 3141 * fit fd_set. 3142 * @ingroup event 3143 */ 3144 _MHD_EXTERN enum MHD_Result 3145 MHD_get_fdset2 (struct MHD_Daemon *daemon, 3146 fd_set *read_fd_set, 3147 fd_set *write_fd_set, 3148 fd_set *except_fd_set, 3149 MHD_socket *max_fd, 3150 unsigned int fd_setsize); 3151 3152 3153 /** 3154 * Obtain the `select()` sets for this daemon. 3155 * Daemon's FDs will be added to fd_sets. To get only 3156 * daemon FDs in fd_sets, call FD_ZERO for each fd_set 3157 * before calling this function. Size of fd_set is 3158 * determined by current value of FD_SETSIZE. 3159 * 3160 * This function should be called only when MHD is configured to 3161 * use "external" sockets polling with 'select()' or with 'epoll'. 3162 * In the latter case, it will only add the single 'epoll' file 3163 * descriptor used by MHD to the sets. 3164 * It's necessary to use #MHD_get_timeout() to get maximum timeout 3165 * value for `select()`. Usage of `select()` with indefinite timeout 3166 * (or timeout larger than returned by #MHD_get_timeout()) will 3167 * violate MHD API and may results in pending unprocessed data. 3168 * 3169 * This function must be called only for daemon started 3170 * without #MHD_USE_INTERNAL_POLLING_THREAD flag. 3171 * 3172 * @param daemon daemon to get sets from 3173 * @param read_fd_set read set 3174 * @param write_fd_set write set 3175 * @param except_fd_set except set 3176 * @param max_fd increased to largest FD added (if larger 3177 * than existing value); can be NULL 3178 * @return #MHD_YES on success, #MHD_NO if this 3179 * daemon was not started with the right 3180 * options for this call or any FD didn't 3181 * fit fd_set. 3182 * @ingroup event 3183 */ 3184 #define MHD_get_fdset(daemon,read_fd_set,write_fd_set,except_fd_set,max_fd) \ 3185 MHD_get_fdset2 ((daemon),(read_fd_set),(write_fd_set),(except_fd_set), \ 3186 (max_fd),FD_SETSIZE) 3187 3188 3189 /** 3190 * Obtain timeout value for polling function for this daemon. 3191 * 3192 * This function set value to the amount of milliseconds for which polling 3193 * function (`select()`, `poll()` or epoll) should at most block, not the 3194 * timeout value set for connections. 3195 * 3196 * Any "external" sockets polling function must be called with the timeout 3197 * value provided by this function. Smaller timeout values can be used for 3198 * polling function if it is required for any reason, but using larger 3199 * timeout value or no timeout (indefinite timeout) when this function 3200 * return #MHD_YES will break MHD processing logic and result in "hung" 3201 * connections with data pending in network buffers and other problems. 3202 * 3203 * It is important to always use this function (or #MHD_get_timeout64(), 3204 * #MHD_get_timeout64s(), #MHD_get_timeout_i() functions) when "external" 3205 * polling is used. 3206 * If this function returns #MHD_YES then #MHD_run() (or #MHD_run_from_select()) 3207 * must be called right after return from polling function, regardless of 3208 * the states of MHD FDs. 3209 * 3210 * In practice, if #MHD_YES is returned then #MHD_run() (or 3211 * #MHD_run_from_select()) must be called not later than @a timeout 3212 * millisecond even if no activity is detected on sockets by sockets 3213 * polling function. 3214 * 3215 * @param daemon daemon to query for timeout 3216 * @param[out] timeout set to the timeout (in milliseconds) 3217 * @return #MHD_YES on success, #MHD_NO if timeouts are 3218 * not used and no data processing is pending. 3219 * @ingroup event 3220 */ 3221 _MHD_EXTERN enum MHD_Result 3222 MHD_get_timeout (struct MHD_Daemon *daemon, 3223 MHD_UNSIGNED_LONG_LONG *timeout); 3224 3225 3226 /** 3227 * Free the memory allocated by MHD. 3228 * 3229 * If any MHD function explicitly mentions that returned pointer must be 3230 * freed by this function, then no other method must be used to free 3231 * the memory. 3232 * 3233 * @param ptr the pointer to free. 3234 * @sa #MHD_digest_auth_get_username(), #MHD_basic_auth_get_username_password3() 3235 * @sa #MHD_basic_auth_get_username_password() 3236 * @note Available since #MHD_VERSION 0x00095600 3237 * @ingroup specialized 3238 */ 3239 _MHD_EXTERN void 3240 MHD_free (void *ptr); 3241 3242 /** 3243 * Obtain timeout value for external polling function for this daemon. 3244 * 3245 * This function set value to the amount of milliseconds for which polling 3246 * function (`select()`, `poll()` or epoll) should at most block, not the 3247 * timeout value set for connections. 3248 * 3249 * Any "external" sockets polling function must be called with the timeout 3250 * value provided by this function. Smaller timeout values can be used for 3251 * polling function if it is required for any reason, but using larger 3252 * timeout value or no timeout (indefinite timeout) when this function 3253 * return #MHD_YES will break MHD processing logic and result in "hung" 3254 * connections with data pending in network buffers and other problems. 3255 * 3256 * It is important to always use this function (or #MHD_get_timeout(), 3257 * #MHD_get_timeout64s(), #MHD_get_timeout_i() functions) when "external" 3258 * polling is used. 3259 * If this function returns #MHD_YES then #MHD_run() (or #MHD_run_from_select()) 3260 * must be called right after return from polling function, regardless of 3261 * the states of MHD FDs. 3262 * 3263 * In practice, if #MHD_YES is returned then #MHD_run() (or 3264 * #MHD_run_from_select()) must be called not later than @a timeout 3265 * millisecond even if no activity is detected on sockets by sockets 3266 * polling function. 3267 * 3268 * @param daemon daemon to query for timeout 3269 * @param[out] timeout64 the pointer to the variable to be set to the 3270 * timeout (in milliseconds) 3271 * @return #MHD_YES if timeout value has been set, 3272 * #MHD_NO if timeouts are not used and no data processing is pending. 3273 * @note Available since #MHD_VERSION 0x00097701 3274 * @ingroup event 3275 */ 3276 _MHD_EXTERN enum MHD_Result 3277 MHD_get_timeout64 (struct MHD_Daemon *daemon, 3278 uint64_t *timeout); 3279 3280 3281 /** 3282 * Obtain timeout value for external polling function for this daemon. 3283 * 3284 * This function set value to the amount of milliseconds for which polling 3285 * function (`select()`, `poll()` or epoll) should at most block, not the 3286 * timeout value set for connections. 3287 * 3288 * Any "external" sockets polling function must be called with the timeout 3289 * value provided by this function (if returned value is non-negative). 3290 * Smaller timeout values can be used for polling function if it is required 3291 * for any reason, but using larger timeout value or no timeout (indefinite 3292 * timeout) when this function returns non-negative value will break MHD 3293 * processing logic and result in "hung" connections with data pending in 3294 * network buffers and other problems. 3295 * 3296 * It is important to always use this function (or #MHD_get_timeout(), 3297 * #MHD_get_timeout64(), #MHD_get_timeout_i() functions) when "external" 3298 * polling is used. 3299 * If this function returns non-negative value then #MHD_run() (or 3300 * #MHD_run_from_select()) must be called right after return from polling 3301 * function, regardless of the states of MHD FDs. 3302 * 3303 * In practice, if zero or positive value is returned then #MHD_run() (or 3304 * #MHD_run_from_select()) must be called not later than returned amount of 3305 * millisecond even if no activity is detected on sockets by sockets 3306 * polling function. 3307 * 3308 * @param daemon the daemon to query for timeout 3309 * @return -1 if connections' timeouts are not set and no data processing 3310 * is pending, so external polling function may wait for sockets 3311 * activity for indefinite amount of time, 3312 * otherwise returned value is the the maximum amount of millisecond 3313 * that external polling function must wait for the activity of FDs. 3314 * @note Available since #MHD_VERSION 0x00097701 3315 * @ingroup event 3316 */ 3317 _MHD_EXTERN int64_t 3318 MHD_get_timeout64s (struct MHD_Daemon *daemon); 3319 3320 3321 /** 3322 * Obtain timeout value for external polling function for this daemon. 3323 * 3324 * This function set value to the amount of milliseconds for which polling 3325 * function (`select()`, `poll()` or epoll) should at most block, not the 3326 * timeout value set for connections. 3327 * 3328 * Any "external" sockets polling function must be called with the timeout 3329 * value provided by this function (if returned value is non-negative). 3330 * Smaller timeout values can be used for polling function if it is required 3331 * for any reason, but using larger timeout value or no timeout (indefinite 3332 * timeout) when this function returns non-negative value will break MHD 3333 * processing logic and result in "hung" connections with data pending in 3334 * network buffers and other problems. 3335 * 3336 * It is important to always use this function (or #MHD_get_timeout(), 3337 * #MHD_get_timeout64(), #MHD_get_timeout64s() functions) when "external" 3338 * polling is used. 3339 * If this function returns non-negative value then #MHD_run() (or 3340 * #MHD_run_from_select()) must be called right after return from polling 3341 * function, regardless of the states of MHD FDs. 3342 * 3343 * In practice, if zero or positive value is returned then #MHD_run() (or 3344 * #MHD_run_from_select()) must be called not later than returned amount of 3345 * millisecond even if no activity is detected on sockets by sockets 3346 * polling function. 3347 * 3348 * @param daemon the daemon to query for timeout 3349 * @return -1 if connections' timeouts are not set and no data processing 3350 * is pending, so external polling function may wait for sockets 3351 * activity for indefinite amount of time, 3352 * otherwise returned value is the the maximum amount of millisecond 3353 * (capped at INT_MAX) that external polling function must wait 3354 * for the activity of FDs. 3355 * @note Available since #MHD_VERSION 0x00097701 3356 * @ingroup event 3357 */ 3358 _MHD_EXTERN int 3359 MHD_get_timeout_i (struct MHD_Daemon *daemon); 3360 3361 3362 /** 3363 * Run webserver operations (without blocking unless in client callbacks). 3364 * 3365 * This method should be called by clients in combination with 3366 * #MHD_get_fdset() (or #MHD_get_daemon_info() with MHD_DAEMON_INFO_EPOLL_FD 3367 * if epoll is used) and #MHD_get_timeout() if the client-controlled 3368 * connection polling method is used (i.e. daemon was started without 3369 * #MHD_USE_INTERNAL_POLLING_THREAD flag). 3370 * 3371 * This function is a convenience method, which is useful if the 3372 * fd_sets from #MHD_get_fdset were not directly passed to `select()`; 3373 * with this function, MHD will internally do the appropriate `select()` 3374 * call itself again. While it is acceptable to call #MHD_run (if 3375 * #MHD_USE_INTERNAL_POLLING_THREAD is not set) at any moment, you should 3376 * call #MHD_run_from_select() if performance is important (as it saves an 3377 * expensive call to `select()`). 3378 * 3379 * If #MHD_get_timeout() returned #MHD_YES, than this function must be called 3380 * right after polling function returns regardless of detected activity on 3381 * the daemon's FDs. 3382 * 3383 * @param daemon daemon to run 3384 * @return #MHD_YES on success, #MHD_NO if this 3385 * daemon was not started with the right 3386 * options for this call. 3387 * @ingroup event 3388 */ 3389 _MHD_EXTERN enum MHD_Result 3390 MHD_run (struct MHD_Daemon *daemon); 3391 3392 3393 /** 3394 * Run websever operation with possible blocking. 3395 * 3396 * This function does the following: waits for any network event not more than 3397 * specified number of milliseconds, processes all incoming and outgoing data, 3398 * processes new connections, processes any timed-out connection, and does 3399 * other things required to run webserver. 3400 * Once all connections are processed, function returns. 3401 * 3402 * This function is useful for quick and simple (lazy) webserver implementation 3403 * if application needs to run a single thread only and does not have any other 3404 * network activity. 3405 * 3406 * This function calls MHD_get_timeout() internally and use returned value as 3407 * maximum wait time if it less than value of @a millisec parameter. 3408 * 3409 * It is expected that the "external" socket polling function is not used in 3410 * conjunction with this function unless the @a millisec is set to zero. 3411 * 3412 * @param daemon the daemon to run 3413 * @param millisec the maximum time in milliseconds to wait for network and 3414 * other events. Note: there is no guarantee that function 3415 * blocks for the specified amount of time. The real processing 3416 * time can be shorter (if some data or connection timeout 3417 * comes earlier) or longer (if data processing requires more 3418 * time, especially in user callbacks). 3419 * If set to '0' then function does not block and processes 3420 * only already available data (if any). 3421 * If set to '-1' then function waits for events 3422 * indefinitely (blocks until next network activity or 3423 * connection timeout). 3424 * @return #MHD_YES on success, #MHD_NO if this 3425 * daemon was not started with the right 3426 * options for this call or some serious 3427 * unrecoverable error occurs. 3428 * @note Available since #MHD_VERSION 0x00097206 3429 * @ingroup event 3430 */ 3431 _MHD_EXTERN enum MHD_Result 3432 MHD_run_wait (struct MHD_Daemon *daemon, 3433 int32_t millisec); 3434 3435 3436 /** 3437 * Run webserver operations. This method should be called by clients 3438 * in combination with #MHD_get_fdset and #MHD_get_timeout() if the 3439 * client-controlled select method is used. 3440 * 3441 * You can use this function instead of #MHD_run if you called 3442 * `select()` on the result from #MHD_get_fdset. File descriptors in 3443 * the sets that are not controlled by MHD will be ignored. Calling 3444 * this function instead of #MHD_run is more efficient as MHD will 3445 * not have to call `select()` again to determine which operations are 3446 * ready. 3447 * 3448 * If #MHD_get_timeout() returned #MHD_YES, than this function must be 3449 * called right after `select()` returns regardless of detected activity 3450 * on the daemon's FDs. 3451 * 3452 * This function cannot be used with daemon started with 3453 * #MHD_USE_INTERNAL_POLLING_THREAD flag. 3454 * 3455 * @param daemon daemon to run select loop for 3456 * @param read_fd_set read set 3457 * @param write_fd_set write set 3458 * @param except_fd_set except set 3459 * @return #MHD_NO on serious errors, #MHD_YES on success 3460 * @ingroup event 3461 */ 3462 _MHD_EXTERN enum MHD_Result 3463 MHD_run_from_select (struct MHD_Daemon *daemon, 3464 const fd_set *read_fd_set, 3465 const fd_set *write_fd_set, 3466 const fd_set *except_fd_set); 3467 3468 3469 /** 3470 * Run webserver operations. This method should be called by clients 3471 * in combination with #MHD_get_fdset and #MHD_get_timeout() if the 3472 * client-controlled select method is used. 3473 * This function specifies FD_SETSIZE used when provided fd_sets were 3474 * created. It is important on platforms where FD_SETSIZE can be 3475 * overridden. 3476 * 3477 * You can use this function instead of #MHD_run if you called 3478 * 'select()' on the result from #MHD_get_fdset2(). File descriptors in 3479 * the sets that are not controlled by MHD will be ignored. Calling 3480 * this function instead of #MHD_run() is more efficient as MHD will 3481 * not have to call 'select()' again to determine which operations are 3482 * ready. 3483 * 3484 * If #MHD_get_timeout() returned #MHD_YES, than this function must be 3485 * called right after 'select()' returns regardless of detected activity 3486 * on the daemon's FDs. 3487 * 3488 * This function cannot be used with daemon started with 3489 * #MHD_USE_INTERNAL_POLLING_THREAD flag. 3490 * 3491 * @param daemon the daemon to run select loop for 3492 * @param read_fd_set the read set 3493 * @param write_fd_set the write set 3494 * @param except_fd_set the except set 3495 * @param fd_setsize the value of FD_SETSIZE 3496 * @return #MHD_NO on serious errors, #MHD_YES on success 3497 * @sa #MHD_get_fdset2(), #MHD_OPTION_APP_FD_SETSIZE 3498 * @ingroup event 3499 */ 3500 _MHD_EXTERN enum MHD_Result 3501 MHD_run_from_select2 (struct MHD_Daemon *daemon, 3502 const fd_set *read_fd_set, 3503 const fd_set *write_fd_set, 3504 const fd_set *except_fd_set, 3505 unsigned int fd_setsize); 3506 3507 3508 /** 3509 * Run webserver operations. This method should be called by clients 3510 * in combination with #MHD_get_fdset and #MHD_get_timeout() if the 3511 * client-controlled select method is used. 3512 * This macro automatically substitutes current FD_SETSIZE value. 3513 * It is important on platforms where FD_SETSIZE can be overridden. 3514 * 3515 * You can use this function instead of #MHD_run if you called 3516 * 'select()' on the result from #MHD_get_fdset2(). File descriptors in 3517 * the sets that are not controlled by MHD will be ignored. Calling 3518 * this function instead of #MHD_run() is more efficient as MHD will 3519 * not have to call 'select()' again to determine which operations are 3520 * ready. 3521 * 3522 * If #MHD_get_timeout() returned #MHD_YES, than this function must be 3523 * called right after 'select()' returns regardless of detected activity 3524 * on the daemon's FDs. 3525 * 3526 * This function cannot be used with daemon started with 3527 * #MHD_USE_INTERNAL_POLLING_THREAD flag. 3528 * 3529 * @param daemon the daemon to run select loop for 3530 * @param read_fd_set the read set 3531 * @param write_fd_set the write set 3532 * @param except_fd_set the except set 3533 * @param fd_setsize the value of FD_SETSIZE 3534 * @return #MHD_NO on serious errors, #MHD_YES on success 3535 * @sa #MHD_get_fdset2(), #MHD_OPTION_APP_FD_SETSIZE 3536 * @ingroup event 3537 */ 3538 #define MHD_run_from_select(d,r,w,e) \ 3539 MHD_run_from_select2 ((d),(r),(w),(e),(unsigned int) (FD_SETSIZE)) 3540 3541 /* **************** Connection handling functions ***************** */ 3542 3543 3544 /** 3545 * Get request URI path (the request target without query part). 3546 * 3547 * The value obtained by this function is the same value as @a url provided 3548 * for #MHD_AccessHandlerCallback callback, but this function also provides 3549 * the size of the string. 3550 * 3551 * This function is critically important when binary zero is allowed by daemon 3552 * option #MHD_OPTION_ALLOW_BIN_ZERO_IN_URI_PATH as this is the only way to 3553 * get the non-truncated request URI. 3554 * 3555 * Returned @a uri pointer is valid until response is started or connection 3556 * is terminated. 3557 * 3558 * @param connection the connection to URI from 3559 * @param[out] uri set to the request URI without query part, may contain 3560 * binary zeros (NUL) characters, never set to NULL on 3561 * success; can be NULL 3562 * @param[out] uri_size set to the size of the @a uri in bytes, not including 3563 * final zero-termination; can be NULL 3564 * @return #MHD_NO if failed (request is not yet processed or response has 3565 * been queued already); 3566 * #MHD_YES on success (*uri set to valid pointer) 3567 * @note Available since #MHD_VERSION 0x01000201 3568 * @sa #MHD_OPTION_ALLOW_BIN_ZERO_IN_URI_PATH, #MHD_AccessHandlerCallback 3569 * @ingroup request 3570 */ 3571 _MHD_EXTERN enum MHD_Result 3572 MHD_get_connection_URI_path_n (struct MHD_Connection *connection, 3573 const char **uri, 3574 size_t *uri_size); 3575 3576 /** 3577 * Get all of the headers from the request. 3578 * 3579 * @param connection connection to get values from 3580 * @param kind types of values to iterate over, can be a bitmask 3581 * @param iterator callback to call on each header; 3582 * may be NULL (then just count headers) 3583 * @param iterator_cls extra argument to @a iterator 3584 * @return number of entries iterated over, 3585 * -1 if connection is NULL. 3586 * @ingroup request 3587 */ 3588 _MHD_EXTERN int 3589 MHD_get_connection_values (struct MHD_Connection *connection, 3590 enum MHD_ValueKind kind, 3591 MHD_KeyValueIterator iterator, 3592 void *iterator_cls); 3593 3594 3595 /** 3596 * Get all of the headers from the request. 3597 * 3598 * @param connection connection to get values from 3599 * @param kind types of values to iterate over, can be a bitmask 3600 * @param iterator callback to call on each header; 3601 * may be NULL (then just count headers) 3602 * @param iterator_cls extra argument to @a iterator 3603 * @return number of entries iterated over, 3604 * -1 if connection is NULL. 3605 * @note Available since #MHD_VERSION 0x00096400 3606 * @ingroup request 3607 */ 3608 _MHD_EXTERN int 3609 MHD_get_connection_values_n (struct MHD_Connection *connection, 3610 enum MHD_ValueKind kind, 3611 MHD_KeyValueIteratorN iterator, 3612 void *iterator_cls); 3613 3614 3615 /** 3616 * This function can be used to add an entry to the HTTP headers of a 3617 * connection (so that the #MHD_get_connection_values function will 3618 * return them -- and the `struct MHD_PostProcessor` will also see 3619 * them). This maybe required in certain situations (see Mantis 3620 * #1399) where (broken) HTTP implementations fail to supply values 3621 * needed by the post processor (or other parts of the application). 3622 * 3623 * This function MUST only be called from within the 3624 * #MHD_AccessHandlerCallback (otherwise, access maybe improperly 3625 * synchronized). Furthermore, the client must guarantee that the key 3626 * and value arguments are 0-terminated strings that are NOT freed 3627 * until the connection is closed. (The easiest way to do this is by 3628 * passing only arguments to permanently allocated strings.). 3629 * 3630 * @param connection the connection for which a 3631 * value should be set 3632 * @param kind kind of the value 3633 * @param key key for the value 3634 * @param value the value itself 3635 * @return #MHD_NO if the operation could not be 3636 * performed due to insufficient memory; 3637 * #MHD_YES on success 3638 * @ingroup request 3639 */ 3640 _MHD_EXTERN enum MHD_Result 3641 MHD_set_connection_value (struct MHD_Connection *connection, 3642 enum MHD_ValueKind kind, 3643 const char *key, 3644 const char *value); 3645 3646 3647 /** 3648 * This function can be used to add an arbitrary entry to connection. 3649 * This function could add entry with binary zero, which is allowed 3650 * for #MHD_GET_ARGUMENT_KIND. For other kind on entries it is 3651 * recommended to use #MHD_set_connection_value. 3652 * 3653 * This function MUST only be called from within the 3654 * #MHD_AccessHandlerCallback (otherwise, access maybe improperly 3655 * synchronized). Furthermore, the client must guarantee that the key 3656 * and value arguments are 0-terminated strings that are NOT freed 3657 * until the connection is closed. (The easiest way to do this is by 3658 * passing only arguments to permanently allocated strings.). 3659 * 3660 * @param connection the connection for which a 3661 * value should be set 3662 * @param kind kind of the value 3663 * @param key key for the value, must be zero-terminated 3664 * @param key_size number of bytes in @a key (excluding 0-terminator) 3665 * @param value the value itself, must be zero-terminated 3666 * @param value_size number of bytes in @a value (excluding 0-terminator) 3667 * @return #MHD_NO if the operation could not be 3668 * performed due to insufficient memory; 3669 * #MHD_YES on success 3670 * @note Available since #MHD_VERSION 0x00096400 3671 * @ingroup request 3672 */ 3673 _MHD_EXTERN enum MHD_Result 3674 MHD_set_connection_value_n (struct MHD_Connection *connection, 3675 enum MHD_ValueKind kind, 3676 const char *key, 3677 size_t key_size, 3678 const char *value, 3679 size_t value_size); 3680 3681 3682 /** 3683 * Sets the global error handler to a different implementation. 3684 * 3685 * @a cb will only be called in the case of typically fatal, serious internal 3686 * consistency issues or serious system failures like failed lock of mutex. 3687 * 3688 * These issues should only arise in the case of serious memory corruption or 3689 * similar problems with the architecture, there is no safe way to continue 3690 * even for closing of the application. 3691 * 3692 * The default implementation that is used if no panic function is set simply 3693 * prints an error message and calls `abort()`. 3694 * Alternative implementations might call `exit()` or other similar functions. 3695 * 3696 * @param cb new error handler or NULL to use default handler 3697 * @param cls passed to @a cb 3698 * @ingroup logging 3699 */ 3700 _MHD_EXTERN void 3701 MHD_set_panic_func (MHD_PanicCallback cb, void *cls); 3702 3703 3704 /** 3705 * Process escape sequences ('%HH') Updates val in place; the 3706 * result cannot be larger than the input. 3707 * The result is still be 0-terminated. 3708 * 3709 * @param val value to unescape (modified in the process) 3710 * @return length of the resulting val (`strlen(val)` may be 3711 * shorter afterwards due to elimination of escape sequences) 3712 */ 3713 _MHD_EXTERN size_t 3714 MHD_http_unescape (char *val); 3715 3716 3717 /** 3718 * Get a particular header value. If multiple 3719 * values match the kind, return any one of them. 3720 * 3721 * @param connection connection to get values from 3722 * @param kind what kind of value are we looking for 3723 * @param key the header to look for, NULL to lookup 'trailing' value without a key 3724 * @return NULL if no such item was found 3725 * @ingroup request 3726 */ 3727 _MHD_EXTERN const char * 3728 MHD_lookup_connection_value (struct MHD_Connection *connection, 3729 enum MHD_ValueKind kind, 3730 const char *key); 3731 3732 3733 /** 3734 * Get a particular header value. If multiple 3735 * values match the kind, return any one of them. 3736 * @note Since MHD_VERSION 0x00096304 3737 * 3738 * @param connection connection to get values from 3739 * @param kind what kind of value are we looking for 3740 * @param key the header to look for, NULL to lookup 'trailing' value without a key 3741 * @param key_size the length of @a key in bytes 3742 * @param[out] value_ptr the pointer to variable, which will be set to found value, 3743 * will not be updated if key not found, 3744 * could be NULL to just check for presence of @a key 3745 * @param[out] value_size_ptr the pointer variable, which will set to found value, 3746 * will not be updated if key not found, 3747 * could be NULL 3748 * @return #MHD_YES if key is found, 3749 * #MHD_NO otherwise. 3750 * @ingroup request 3751 */ 3752 _MHD_EXTERN enum MHD_Result 3753 MHD_lookup_connection_value_n (struct MHD_Connection *connection, 3754 enum MHD_ValueKind kind, 3755 const char *key, 3756 size_t key_size, 3757 const char **value_ptr, 3758 size_t *value_size_ptr); 3759 3760 3761 /** 3762 * Queue a response to be transmitted to the client (as soon as 3763 * possible but after #MHD_AccessHandlerCallback returns). 3764 * 3765 * For any active connection this function must be called 3766 * only by #MHD_AccessHandlerCallback callback. 3767 * 3768 * For suspended connection this function can be called at any moment (this 3769 * behaviour is deprecated and will be removed!). Response will be sent 3770 * as soon as connection is resumed. 3771 * 3772 * For single thread environment, when MHD is used in "external polling" mode 3773 * (without MHD_USE_SELECT_INTERNALLY) this function can be called any 3774 * time (this behaviour is deprecated and will be removed!). 3775 * 3776 * If HTTP specifications require use no body in reply, like @a status_code with 3777 * value 1xx, the response body is automatically not sent even if it is present 3778 * in the response. No "Content-Length" or "Transfer-Encoding" headers are 3779 * generated and added. 3780 * 3781 * When the response is used to respond HEAD request or used with @a status_code 3782 * #MHD_HTTP_NOT_MODIFIED, then response body is not sent, but "Content-Length" 3783 * header is added automatically based the size of the body in the response. 3784 * If body size it set to #MHD_SIZE_UNKNOWN or chunked encoding is enforced 3785 * then "Transfer-Encoding: chunked" header (for HTTP/1.1 only) is added instead 3786 * of "Content-Length" header. For example, if response with zero-size body is 3787 * used for HEAD request, then "Content-Length: 0" is added automatically to 3788 * reply headers. 3789 * @sa #MHD_RF_HEAD_ONLY_RESPONSE 3790 * 3791 * In situations, where reply body is required, like answer for the GET request 3792 * with @a status_code #MHD_HTTP_OK, headers "Content-Length" (for known body 3793 * size) or "Transfer-Encoding: chunked" (for #MHD_SIZE_UNKNOWN with HTTP/1.1) 3794 * are added automatically. 3795 * In practice, the same response object can be used to respond to both HEAD and 3796 * GET requests. 3797 * 3798 * @param connection the connection identifying the client 3799 * @param status_code HTTP status code (i.e. #MHD_HTTP_OK) 3800 * @param response response to transmit, the NULL is tolerated 3801 * @return #MHD_NO on error (reply already sent, response is NULL), 3802 * #MHD_YES on success or if message has been queued 3803 * @ingroup response 3804 * @sa #MHD_AccessHandlerCallback 3805 */ 3806 _MHD_EXTERN enum MHD_Result 3807 MHD_queue_response (struct MHD_Connection *connection, 3808 unsigned int status_code, 3809 struct MHD_Response *response); 3810 3811 3812 /** 3813 * Suspend handling of network data for a given connection. 3814 * This can be used to dequeue a connection from MHD's event loop 3815 * (not applicable to thread-per-connection!) for a while. 3816 * 3817 * If you use this API in conjunction with an "internal" socket polling, 3818 * you must set the option #MHD_USE_ITC to ensure that a resumed 3819 * connection is immediately processed by MHD. 3820 * 3821 * Suspended connections continue to count against the total number of 3822 * connections allowed (per daemon, as well as per IP, if such limits 3823 * are set). Suspended connections will NOT time out; timeouts will 3824 * restart when the connection handling is resumed. While a 3825 * connection is suspended, MHD will not detect disconnects by the 3826 * client. 3827 * 3828 * The only safe way to call this function is to call it from the 3829 * #MHD_AccessHandlerCallback or #MHD_ContentReaderCallback. 3830 * 3831 * Finally, it is an API violation to call #MHD_stop_daemon while 3832 * having suspended connections (this will at least create memory and 3833 * socket leaks or lead to undefined behavior). You must explicitly 3834 * resume all connections before stopping the daemon. 3835 * 3836 * @param connection the connection to suspend 3837 * 3838 * @sa #MHD_AccessHandlerCallback 3839 */ 3840 _MHD_EXTERN void 3841 MHD_suspend_connection (struct MHD_Connection *connection); 3842 3843 3844 /** 3845 * Resume handling of network data for suspended connection. It is 3846 * safe to resume a suspended connection at any time. Calling this 3847 * function on a connection that was not previously suspended will 3848 * result in undefined behavior. 3849 * 3850 * If you are using this function in "external" sockets polling mode, you must 3851 * make sure to run #MHD_run() and #MHD_get_timeout() afterwards (before 3852 * again calling #MHD_get_fdset()), as otherwise the change may not be 3853 * reflected in the set returned by #MHD_get_fdset() and you may end up 3854 * with a connection that is stuck until the next network activity. 3855 * 3856 * @param connection the connection to resume 3857 */ 3858 _MHD_EXTERN void 3859 MHD_resume_connection (struct MHD_Connection *connection); 3860 3861 3862 /* **************** Response manipulation functions ***************** */ 3863 3864 3865 /** 3866 * Flags for special handling of responses. 3867 */ 3868 enum MHD_ResponseFlags 3869 { 3870 /** 3871 * Default: no special flags. 3872 * @note Available since #MHD_VERSION 0x00093701 3873 */ 3874 MHD_RF_NONE = 0, 3875 3876 /** 3877 * Only respond in conservative (dumb) HTTP/1.0-compatible mode. 3878 * Response still use HTTP/1.1 version in header, but always close 3879 * the connection after sending the response and do not use chunked 3880 * encoding for the response. 3881 * You can also set the #MHD_RF_HTTP_1_0_SERVER flag to force 3882 * HTTP/1.0 version in the response. 3883 * Responses are still compatible with HTTP/1.1. 3884 * This option can be used to communicate with some broken client, which 3885 * does not implement HTTP/1.1 features, but advertises HTTP/1.1 support. 3886 * @note Available since #MHD_VERSION 0x00097308 3887 */ 3888 MHD_RF_HTTP_1_0_COMPATIBLE_STRICT = 1 << 0, 3889 /** 3890 * The same as #MHD_RF_HTTP_1_0_COMPATIBLE_STRICT 3891 * @note Available since #MHD_VERSION 0x00093701 3892 */ 3893 MHD_RF_HTTP_VERSION_1_0_ONLY = 1 << 0, 3894 3895 /** 3896 * Only respond in HTTP 1.0-mode. 3897 * Contrary to the #MHD_RF_HTTP_1_0_COMPATIBLE_STRICT flag, the response's 3898 * HTTP version will always be set to 1.0 and keep-alive connections 3899 * will be used if explicitly requested by the client. 3900 * The "Connection:" header will be added for both "close" and "keep-alive" 3901 * connections. 3902 * Chunked encoding will not be used for the response. 3903 * Due to backward compatibility, responses still can be used with 3904 * HTTP/1.1 clients. 3905 * This option can be used to emulate HTTP/1.0 server (for response part 3906 * only as chunked encoding in requests (if any) is processed by MHD). 3907 * @note Available since #MHD_VERSION 0x00097308 3908 */ 3909 MHD_RF_HTTP_1_0_SERVER = 1 << 1, 3910 /** 3911 * The same as #MHD_RF_HTTP_1_0_SERVER 3912 * @note Available since #MHD_VERSION 0x00096000 3913 */ 3914 MHD_RF_HTTP_VERSION_1_0_RESPONSE = 1 << 1, 3915 3916 /** 3917 * Disable sanity check preventing clients from manually 3918 * setting the HTTP content length option. 3919 * Allow to set several "Content-Length" headers. These headers will 3920 * be used even with replies without body. 3921 * @note Available since #MHD_VERSION 0x00096702 3922 */ 3923 MHD_RF_INSANITY_HEADER_CONTENT_LENGTH = 1 << 2, 3924 3925 /** 3926 * Enable sending of "Connection: keep-alive" header even for 3927 * HTTP/1.1 clients when "Keep-Alive" connection is used. 3928 * Disabled by default for HTTP/1.1 clients as per RFC. 3929 * @note Available since #MHD_VERSION 0x00097310 3930 */ 3931 MHD_RF_SEND_KEEP_ALIVE_HEADER = 1 << 3, 3932 3933 /** 3934 * Enable special processing of the response as body-less (with undefined 3935 * body size). No automatic "Content-Length" or "Transfer-Encoding: chunked" 3936 * headers are added when the response is used with #MHD_HTTP_NOT_MODIFIED 3937 * code or to respond to HEAD request. 3938 * The flag also allow to set arbitrary "Content-Length" by 3939 * MHD_add_response_header() function. 3940 * This flag value can be used only with responses created without body 3941 * (zero-size body). 3942 * Responses with this flag enabled cannot be used in situations where 3943 * reply body must be sent to the client. 3944 * This flag is primarily intended to be used when automatic "Content-Length" 3945 * header is undesirable in response to HEAD requests. 3946 * @note Available since #MHD_VERSION 0x00097701 3947 */ 3948 MHD_RF_HEAD_ONLY_RESPONSE = 1 << 4 3949 } _MHD_FIXED_FLAGS_ENUM; 3950 3951 3952 /** 3953 * MHD options (for future extensions). 3954 */ 3955 enum MHD_ResponseOptions 3956 { 3957 /** 3958 * End of the list of options. 3959 */ 3960 MHD_RO_END = 0 3961 } _MHD_FIXED_ENUM; 3962 3963 3964 /** 3965 * Set special flags and options for a response. 3966 * 3967 * @param response the response to modify 3968 * @param flags to set for the response 3969 * @param ... #MHD_RO_END terminated list of options 3970 * @return #MHD_YES on success, #MHD_NO on error 3971 */ 3972 _MHD_EXTERN enum MHD_Result 3973 MHD_set_response_options (struct MHD_Response *response, 3974 enum MHD_ResponseFlags flags, 3975 ...); 3976 3977 3978 /** 3979 * Create a response object. 3980 * The response object can be extended with header information and then be used 3981 * any number of times. 3982 * 3983 * If response object is used to answer HEAD request then the body of the 3984 * response is not used, while all headers (including automatic headers) are 3985 * used. 3986 * 3987 * @param size size of the data portion of the response, #MHD_SIZE_UNKNOWN for unknown 3988 * @param block_size preferred block size for querying crc (advisory only, 3989 * MHD may still call @a crc using smaller chunks); this 3990 * is essentially the buffer size used for IO, clients 3991 * should pick a value that is appropriate for IO and 3992 * memory performance requirements 3993 * @param crc callback to use to obtain response data 3994 * @param crc_cls extra argument to @a crc 3995 * @param crfc callback to call to free @a crc_cls resources 3996 * @return NULL on error (i.e. invalid arguments, out of memory) 3997 * @ingroup response 3998 */ 3999 _MHD_EXTERN struct MHD_Response * 4000 MHD_create_response_from_callback (uint64_t size, 4001 size_t block_size, 4002 MHD_ContentReaderCallback crc, void *crc_cls, 4003 MHD_ContentReaderFreeCallback crfc); 4004 4005 4006 /** 4007 * Create a response object. 4008 * The response object can be extended with header information and then be used 4009 * any number of times. 4010 * 4011 * If response object is used to answer HEAD request then the body of the 4012 * response is not used, while all headers (including automatic headers) are 4013 * used. 4014 * 4015 * @param size size of the @a data portion of the response 4016 * @param data the data itself 4017 * @param must_free libmicrohttpd should free data when done 4018 * @param must_copy libmicrohttpd must make a copy of @a data 4019 * right away, the data may be released anytime after 4020 * this call returns 4021 * @return NULL on error (i.e. invalid arguments, out of memory) 4022 * @deprecated use #MHD_create_response_from_buffer instead 4023 * @ingroup response 4024 */ 4025 _MHD_DEPR_FUNC ( \ 4026 "MHD_create_response_from_data() is deprecated, use MHD_create_response_from_buffer()" \ 4027 ) \ 4028 _MHD_EXTERN struct MHD_Response * 4029 MHD_create_response_from_data (size_t size, 4030 void *data, 4031 int must_free, 4032 int must_copy); 4033 4034 4035 /** 4036 * Specification for how MHD should treat the memory buffer 4037 * given for the response. 4038 * @ingroup response 4039 */ 4040 enum MHD_ResponseMemoryMode 4041 { 4042 4043 /** 4044 * Buffer is a persistent (static/global) buffer that won't change 4045 * for at least the lifetime of the response, MHD should just use 4046 * it, not free it, not copy it, just keep an alias to it. 4047 * @ingroup response 4048 */ 4049 MHD_RESPMEM_PERSISTENT, 4050 4051 /** 4052 * Buffer is heap-allocated with `malloc()` (or equivalent) and 4053 * should be freed by MHD after processing the response has 4054 * concluded (response reference counter reaches zero). 4055 * The more portable way to automatically free the buffer is function 4056 * MHD_create_response_from_buffer_with_free_callback() with '&free' as 4057 * crfc parameter as it does not require to use the same runtime library. 4058 * @warning It is critical to make sure that the same C-runtime library 4059 * is used by both application and MHD (especially 4060 * important for W32). 4061 * @ingroup response 4062 */ 4063 MHD_RESPMEM_MUST_FREE, 4064 4065 /** 4066 * Buffer is in transient memory, but not on the heap (for example, 4067 * on the stack or non-`malloc()` allocated) and only valid during the 4068 * call to #MHD_create_response_from_buffer. MHD must make its 4069 * own private copy of the data for processing. 4070 * @ingroup response 4071 */ 4072 MHD_RESPMEM_MUST_COPY 4073 4074 } _MHD_FIXED_ENUM; 4075 4076 4077 /** 4078 * Create a response object with the content of provided buffer used as 4079 * the response body. 4080 * 4081 * The response object can be extended with header information and then 4082 * be used any number of times. 4083 * 4084 * If response object is used to answer HEAD request then the body 4085 * of the response is not used, while all headers (including automatic 4086 * headers) are used. 4087 * 4088 * @param size size of the data portion of the response 4089 * @param buffer size bytes containing the response's data portion 4090 * @param mode flags for buffer management 4091 * @return NULL on error (i.e. invalid arguments, out of memory) 4092 * @ingroup response 4093 */ 4094 _MHD_EXTERN struct MHD_Response * 4095 MHD_create_response_from_buffer (size_t size, 4096 void *buffer, 4097 enum MHD_ResponseMemoryMode mode); 4098 4099 4100 /** 4101 * Create a response object with the content of provided statically allocated 4102 * buffer used as the response body. 4103 * 4104 * The buffer must be valid for the lifetime of the response. The easiest way 4105 * to achieve this is to use a statically allocated buffer. 4106 * 4107 * The response object can be extended with header information and then 4108 * be used any number of times. 4109 * 4110 * If response object is used to answer HEAD request then the body 4111 * of the response is not used, while all headers (including automatic 4112 * headers) are used. 4113 * 4114 * @param size the size of the data in @a buffer, can be zero 4115 * @param buffer the buffer with the data for the response body, can be NULL 4116 * if @a size is zero 4117 * @return NULL on error (i.e. invalid arguments, out of memory) 4118 * @note Available since #MHD_VERSION 0x00097701 4119 * @ingroup response 4120 */ 4121 _MHD_EXTERN struct MHD_Response * 4122 MHD_create_response_from_buffer_static (size_t size, 4123 const void *buffer); 4124 4125 4126 /** 4127 * Create a response object with the content of provided temporal buffer 4128 * used as the response body. 4129 * 4130 * An internal copy of the buffer will be made automatically, so buffer have 4131 * to be valid only during the call of this function (as a typical example: 4132 * buffer is a local (non-static) array). 4133 * 4134 * The response object can be extended with header information and then 4135 * be used any number of times. 4136 * 4137 * If response object is used to answer HEAD request then the body 4138 * of the response is not used, while all headers (including automatic 4139 * headers) are used. 4140 * 4141 * @param size the size of the data in @a buffer, can be zero 4142 * @param buffer the buffer with the data for the response body, can be NULL 4143 * if @a size is zero 4144 * @return NULL on error (i.e. invalid arguments, out of memory) 4145 * @note Available since #MHD_VERSION 0x00097701 4146 * @ingroup response 4147 */ 4148 _MHD_EXTERN struct MHD_Response * 4149 MHD_create_response_from_buffer_copy (size_t size, 4150 const void *buffer); 4151 4152 4153 /** 4154 * Create a response object with the content of provided buffer used as 4155 * the response body. 4156 * 4157 * The response object can be extended with header information and then 4158 * be used any number of times. 4159 * 4160 * If response object is used to answer HEAD request then the body 4161 * of the response is not used, while all headers (including automatic 4162 * headers) are used. 4163 * 4164 * @param size size of the data portion of the response 4165 * @param buffer size bytes containing the response's data portion 4166 * @param crfc function to call to free the @a buffer 4167 * @return NULL on error (i.e. invalid arguments, out of memory) 4168 * @note Available since #MHD_VERSION 0x00096000 4169 * @ingroup response 4170 */ 4171 _MHD_EXTERN struct MHD_Response * 4172 MHD_create_response_from_buffer_with_free_callback (size_t size, 4173 void *buffer, 4174 MHD_ContentReaderFreeCallback 4175 crfc); 4176 4177 4178 /** 4179 * Create a response object with the content of provided buffer used as 4180 * the response body. 4181 * 4182 * The response object can be extended with header information and then 4183 * be used any number of times. 4184 * 4185 * If response object is used to answer HEAD request then the body 4186 * of the response is not used, while all headers (including automatic 4187 * headers) are used. 4188 * 4189 * @param size size of the data portion of the response 4190 * @param buffer size bytes containing the response's data portion 4191 * @param crfc function to call to cleanup, if set to NULL then callback 4192 * is not called 4193 * @param crfc_cls an argument for @a crfc 4194 * @return NULL on error (i.e. invalid arguments, out of memory) 4195 * @note Available since #MHD_VERSION 0x00097302 4196 * @note 'const' qualifier is used for @a buffer since #MHD_VERSION 0x00097701 4197 * @ingroup response 4198 */ 4199 _MHD_EXTERN struct MHD_Response * 4200 MHD_create_response_from_buffer_with_free_callback_cls (size_t size, 4201 const void *buffer, 4202 MHD_ContentReaderFreeCallback 4203 crfc, 4204 void *crfc_cls); 4205 4206 4207 /** 4208 * Create a response object with the content of provided file used as 4209 * the response body. 4210 * 4211 * The response object can be extended with header information and then 4212 * be used any number of times. 4213 * 4214 * If response object is used to answer HEAD request then the body 4215 * of the response is not used, while all headers (including automatic 4216 * headers) are used. 4217 * 4218 * @param size size of the data portion of the response 4219 * @param fd file descriptor referring to a file on disk with the 4220 * data; will be closed when response is destroyed; 4221 * fd should be in 'blocking' mode 4222 * @return NULL on error (i.e. invalid arguments, out of memory) 4223 * @ingroup response 4224 */ 4225 _MHD_EXTERN struct MHD_Response * 4226 MHD_create_response_from_fd (size_t size, 4227 int fd); 4228 4229 4230 /** 4231 * Create a response object with the response body created by reading 4232 * the provided pipe. 4233 * 4234 * The response object can be extended with header information and 4235 * then be used ONLY ONCE. 4236 * 4237 * If response object is used to answer HEAD request then the body 4238 * of the response is not used, while all headers (including automatic 4239 * headers) are used. 4240 * 4241 * @param fd file descriptor referring to a read-end of a pipe with the 4242 * data; will be closed when response is destroyed; 4243 * fd should be in 'blocking' mode 4244 * @return NULL on error (i.e. invalid arguments, out of memory) 4245 * @note Available since #MHD_VERSION 0x00097102 4246 * @ingroup response 4247 */ 4248 _MHD_EXTERN struct MHD_Response * 4249 MHD_create_response_from_pipe (int fd); 4250 4251 4252 /** 4253 * Create a response object with the content of provided file used as 4254 * the response body. 4255 * 4256 * The response object can be extended with header information and then 4257 * be used any number of times. 4258 * 4259 * If response object is used to answer HEAD request then the body 4260 * of the response is not used, while all headers (including automatic 4261 * headers) are used. 4262 * 4263 * @param size size of the data portion of the response; 4264 * sizes larger than 2 GiB may be not supported by OS or 4265 * MHD build; see ::MHD_FEATURE_LARGE_FILE 4266 * @param fd file descriptor referring to a file on disk with the 4267 * data; will be closed when response is destroyed; 4268 * fd should be in 'blocking' mode 4269 * @return NULL on error (i.e. invalid arguments, out of memory) 4270 * @ingroup response 4271 */ 4272 _MHD_EXTERN struct MHD_Response * 4273 MHD_create_response_from_fd64 (uint64_t size, 4274 int fd); 4275 4276 4277 /** 4278 * Create a response object with the content of provided file with 4279 * specified offset used as the response body. 4280 * 4281 * The response object can be extended with header information and then 4282 * be used any number of times. 4283 * 4284 * If response object is used to answer HEAD request then the body 4285 * of the response is not used, while all headers (including automatic 4286 * headers) are used. 4287 * 4288 * @param size size of the data portion of the response 4289 * @param fd file descriptor referring to a file on disk with the 4290 * data; will be closed when response is destroyed; 4291 * fd should be in 'blocking' mode 4292 * @param offset offset to start reading from in the file; 4293 * Be careful! `off_t` may have been compiled to be a 4294 * 64-bit variable for MHD, in which case your application 4295 * also has to be compiled using the same options! Read 4296 * the MHD manual for more details. 4297 * @return NULL on error (i.e. invalid arguments, out of memory) 4298 * @ingroup response 4299 */ 4300 _MHD_DEPR_FUNC ( \ 4301 "Function MHD_create_response_from_fd_at_offset() is deprecated, use MHD_create_response_from_fd_at_offset64()" \ 4302 ) \ 4303 _MHD_EXTERN struct MHD_Response * 4304 MHD_create_response_from_fd_at_offset (size_t size, 4305 int fd, 4306 off_t offset); 4307 4308 #if ! defined(_MHD_NO_DEPR_IN_MACRO) || defined(_MHD_NO_DEPR_FUNC) 4309 /* Substitute MHD_create_response_from_fd_at_offset64() instead of MHD_create_response_from_fd_at_offset() 4310 to minimize potential problems with different off_t sizes */ 4311 #define MHD_create_response_from_fd_at_offset(size,fd,offset) \ 4312 _MHD_DEPR_IN_MACRO ( \ 4313 "Usage of MHD_create_response_from_fd_at_offset() is deprecated, use MHD_create_response_from_fd_at_offset64()") \ 4314 MHD_create_response_from_fd_at_offset64 ((size),(fd),(offset)) 4315 #endif /* !_MHD_NO_DEPR_IN_MACRO || _MHD_NO_DEPR_FUNC */ 4316 4317 4318 /** 4319 * Create a response object with the content of provided file with 4320 * specified offset used as the response body. 4321 * 4322 * The response object can be extended with header information and then 4323 * be used any number of times. 4324 * 4325 * If response object is used to answer HEAD request then the body 4326 * of the response is not used, while all headers (including automatic 4327 * headers) are used. 4328 * 4329 * @param size size of the data portion of the response; 4330 * sizes larger than 2 GiB may be not supported by OS or 4331 * MHD build; see ::MHD_FEATURE_LARGE_FILE 4332 * @param fd file descriptor referring to a file on disk with the 4333 * data; will be closed when response is destroyed; 4334 * fd should be in 'blocking' mode 4335 * @param offset offset to start reading from in the file; 4336 * reading file beyond 2 GiB may be not supported by OS or 4337 * MHD build; see ::MHD_FEATURE_LARGE_FILE 4338 * @return NULL on error (i.e. invalid arguments, out of memory) 4339 * @ingroup response 4340 */ 4341 _MHD_EXTERN struct MHD_Response * 4342 MHD_create_response_from_fd_at_offset64 (uint64_t size, 4343 int fd, 4344 uint64_t offset); 4345 4346 4347 /** 4348 * Create a response object with an array of memory buffers 4349 * used as the response body. 4350 * 4351 * The response object can be extended with header information and then 4352 * be used any number of times. 4353 * 4354 * If response object is used to answer HEAD request then the body 4355 * of the response is not used, while all headers (including automatic 4356 * headers) are used. 4357 * 4358 * @param iov the array for response data buffers, an internal copy of this 4359 * will be made 4360 * @param iovcnt the number of elements in @a iov 4361 * @param free_cb the callback to clean up any data associated with @a iov when 4362 * the response is destroyed. 4363 * @param cls the argument passed to @a free_cb 4364 * @return NULL on error (i.e. invalid arguments, out of memory) 4365 * @note Available since #MHD_VERSION 0x00097204 4366 * @ingroup response 4367 */ 4368 _MHD_EXTERN struct MHD_Response * 4369 MHD_create_response_from_iovec (const struct MHD_IoVec *iov, 4370 unsigned int iovcnt, 4371 MHD_ContentReaderFreeCallback free_cb, 4372 void *cls); 4373 4374 4375 /** 4376 * Create a response object with empty (zero size) body. 4377 * 4378 * The response object can be extended with header information and then be used 4379 * any number of times. 4380 * 4381 * This function is a faster equivalent of #MHD_create_response_from_buffer call 4382 * with zero size combined with call of #MHD_set_response_options. 4383 * 4384 * @param flags the flags for the new response object 4385 * @return NULL on error (i.e. invalid arguments, out of memory), 4386 * the pointer to the created response object otherwise 4387 * @note Available since #MHD_VERSION 0x00097701 4388 * @ingroup response 4389 */ 4390 _MHD_EXTERN struct MHD_Response * 4391 MHD_create_response_empty (enum MHD_ResponseFlags flags); 4392 4393 4394 /** 4395 * Enumeration for actions MHD should perform on the underlying socket 4396 * of the upgrade. This API is not finalized, and in particular 4397 * the final set of actions is yet to be decided. This is just an 4398 * idea for what we might want. 4399 */ 4400 enum MHD_UpgradeAction 4401 { 4402 4403 /** 4404 * Close the socket, the application is done with it. 4405 * 4406 * Takes no extra arguments. 4407 */ 4408 MHD_UPGRADE_ACTION_CLOSE = 0, 4409 4410 /** 4411 * Enable CORKing on the underlying socket. 4412 */ 4413 MHD_UPGRADE_ACTION_CORK_ON = 1, 4414 4415 /** 4416 * Disable CORKing on the underlying socket. 4417 */ 4418 MHD_UPGRADE_ACTION_CORK_OFF = 2 4419 4420 } _MHD_FIXED_ENUM; 4421 4422 4423 /** 4424 * Handle given to the application to manage special 4425 * actions relating to MHD responses that "upgrade" 4426 * the HTTP protocol (i.e. to WebSockets). 4427 */ 4428 struct MHD_UpgradeResponseHandle; 4429 4430 4431 /** 4432 * This connection-specific callback is provided by MHD to 4433 * applications (unusual) during the #MHD_UpgradeHandler. 4434 * It allows applications to perform 'special' actions on 4435 * the underlying socket from the upgrade. 4436 * 4437 * @param urh the handle identifying the connection to perform 4438 * the upgrade @a action on. 4439 * @param action which action should be performed 4440 * @param ... arguments to the action (depends on the action) 4441 * @return #MHD_NO on error, #MHD_YES on success 4442 */ 4443 _MHD_EXTERN enum MHD_Result 4444 MHD_upgrade_action (struct MHD_UpgradeResponseHandle *urh, 4445 enum MHD_UpgradeAction action, 4446 ...); 4447 4448 4449 /** 4450 * Function called after a protocol "upgrade" response was sent 4451 * successfully and the socket should now be controlled by some 4452 * protocol other than HTTP. 4453 * 4454 * Any data already received on the socket will be made available in 4455 * @e extra_in. This can happen if the application sent extra data 4456 * before MHD send the upgrade response. The application should 4457 * treat data from @a extra_in as if it had read it from the socket. 4458 * 4459 * Note that the application must not close() @a sock directly, 4460 * but instead use #MHD_upgrade_action() for special operations 4461 * on @a sock. 4462 * 4463 * Data forwarding to "upgraded" @a sock will be started as soon 4464 * as this function return. 4465 * 4466 * Except when in 'thread-per-connection' mode, implementations 4467 * of this function should never block (as it will still be called 4468 * from within the main event loop). 4469 * 4470 * @param cls closure, whatever was given to #MHD_create_response_for_upgrade(). 4471 * @param connection original HTTP connection handle, 4472 * giving the function a last chance 4473 * to inspect the original HTTP request 4474 * @param req_cls last value left in `req_cls` of the `MHD_AccessHandlerCallback` 4475 * @param extra_in if we happened to have read bytes after the 4476 * HTTP header already (because the client sent 4477 * more than the HTTP header of the request before 4478 * we sent the upgrade response), 4479 * these are the extra bytes already read from @a sock 4480 * by MHD. The application should treat these as if 4481 * it had read them from @a sock. 4482 * @param extra_in_size number of bytes in @a extra_in 4483 * @param sock socket to use for bi-directional communication 4484 * with the client. For HTTPS, this may not be a socket 4485 * that is directly connected to the client and thus certain 4486 * operations (TCP-specific setsockopt(), getsockopt(), etc.) 4487 * may not work as expected (as the socket could be from a 4488 * socketpair() or a TCP-loopback). The application is expected 4489 * to perform read()/recv() and write()/send() calls on the socket. 4490 * The application may also call shutdown(), but must not call 4491 * close() directly. 4492 * @param urh argument for #MHD_upgrade_action()s on this @a connection. 4493 * Applications must eventually use this callback to (indirectly) 4494 * perform the close() action on the @a sock. 4495 */ 4496 typedef void 4497 (*MHD_UpgradeHandler)(void *cls, 4498 struct MHD_Connection *connection, 4499 void *req_cls, 4500 const char *extra_in, 4501 size_t extra_in_size, 4502 MHD_socket sock, 4503 struct MHD_UpgradeResponseHandle *urh); 4504 4505 4506 /** 4507 * Create a response object that can be used for 101 UPGRADE 4508 * responses, for example to implement WebSockets. After sending the 4509 * response, control over the data stream is given to the callback (which 4510 * can then, for example, start some bi-directional communication). 4511 * If the response is queued for multiple connections, the callback 4512 * will be called for each connection. The callback 4513 * will ONLY be called after the response header was successfully passed 4514 * to the OS; if there are communication errors before, the usual MHD 4515 * connection error handling code will be performed. 4516 * 4517 * Setting the correct HTTP code (i.e. MHD_HTTP_SWITCHING_PROTOCOLS) 4518 * and setting correct HTTP headers for the upgrade must be done 4519 * manually (this way, it is possible to implement most existing 4520 * WebSocket versions using this API; in fact, this API might be useful 4521 * for any protocol switch, not just WebSockets). Note that 4522 * draft-ietf-hybi-thewebsocketprotocol-00 cannot be implemented this 4523 * way as the header "HTTP/1.1 101 WebSocket Protocol Handshake" 4524 * cannot be generated; instead, MHD will always produce "HTTP/1.1 101 4525 * Switching Protocols" (if the response code 101 is used). 4526 * 4527 * As usual, the response object can be extended with header 4528 * information and then be used any number of times (as long as the 4529 * header information is not connection-specific). 4530 * 4531 * @param upgrade_handler function to call with the "upgraded" socket 4532 * @param upgrade_handler_cls closure for @a upgrade_handler 4533 * @return NULL on error (i.e. invalid arguments, out of memory) 4534 */ 4535 _MHD_EXTERN struct MHD_Response * 4536 MHD_create_response_for_upgrade (MHD_UpgradeHandler upgrade_handler, 4537 void *upgrade_handler_cls); 4538 4539 4540 /** 4541 * Destroy a response object and associated resources. Note that 4542 * libmicrohttpd may keep some of the resources around if the response 4543 * is still in the queue for some clients, so the memory may not 4544 * necessarily be freed immediately. 4545 * 4546 * @param response response to destroy 4547 * @ingroup response 4548 */ 4549 _MHD_EXTERN void 4550 MHD_destroy_response (struct MHD_Response *response); 4551 4552 4553 /** 4554 * Add a header line to the response. 4555 * 4556 * When reply is generated with queued response, some headers are generated 4557 * automatically. Automatically generated headers are only sent to the client, 4558 * but not added back to the response object. 4559 * 4560 * The list of automatic headers: 4561 * + "Date" header is added automatically unless already set by 4562 * this function 4563 * @see #MHD_USE_SUPPRESS_DATE_NO_CLOCK 4564 * + "Content-Length" is added automatically when required, attempt to set 4565 * it manually by this function is ignored. 4566 * @see #MHD_RF_INSANITY_HEADER_CONTENT_LENGTH 4567 * + "Transfer-Encoding" with value "chunked" is added automatically, 4568 * when chunked transfer encoding is used automatically. Same header with 4569 * the same value can be set manually by this function to enforce chunked 4570 * encoding, however for HTTP/1.0 clients chunked encoding will not be used 4571 * and manually set "Transfer-Encoding" header is automatically removed 4572 * for HTTP/1.0 clients 4573 * + "Connection" may be added automatically with value "Keep-Alive" (only 4574 * for HTTP/1.0 clients) or "Close". The header "Connection" with value 4575 * "Close" could be set by this function to enforce closure of 4576 * the connection after sending this response. "Keep-Alive" cannot be 4577 * enforced and will be removed automatically. 4578 * @see #MHD_RF_SEND_KEEP_ALIVE_HEADER 4579 * 4580 * Some headers are pre-processed by this function: 4581 * * "Connection" headers are combined into single header entry, value is 4582 * normilised, "Keep-Alive" tokens are removed. 4583 * * "Transfer-Encoding" header: the only one header is allowed, the only 4584 * allowed value is "chunked". 4585 * * "Date" header: the only one header is allowed, the second added header 4586 * replaces the first one. 4587 * * "Content-Length" application-defined header is not allowed. 4588 * @see #MHD_RF_INSANITY_HEADER_CONTENT_LENGTH 4589 * 4590 * Headers are used in order as they were added. 4591 * 4592 * @param response the response to add a header to 4593 * @param header the header name to add, no need to be static, an internal copy 4594 * will be created automatically 4595 * @param content the header value to add, no need to be static, an internal 4596 * copy will be created automatically 4597 * @return #MHD_YES on success, 4598 * #MHD_NO on error (i.e. invalid header or content format), 4599 * or out of memory 4600 * @ingroup response 4601 */ 4602 _MHD_EXTERN enum MHD_Result 4603 MHD_add_response_header (struct MHD_Response *response, 4604 const char *header, 4605 const char *content); 4606 4607 4608 /** 4609 * Add a footer line to the response. 4610 * 4611 * @param response response to remove a header from 4612 * @param footer the footer to delete 4613 * @param content value to delete 4614 * @return #MHD_NO on error (i.e. invalid footer or content format). 4615 * @ingroup response 4616 */ 4617 _MHD_EXTERN enum MHD_Result 4618 MHD_add_response_footer (struct MHD_Response *response, 4619 const char *footer, 4620 const char *content); 4621 4622 4623 /** 4624 * Delete a header (or footer) line from the response. 4625 * 4626 * For "Connection" headers this function remove all tokens from existing 4627 * value. Successful result means that at least one token has been removed. 4628 * If all tokens are removed from "Connection" header, the empty "Connection" 4629 * header removed. 4630 * 4631 * @param response response to remove a header from 4632 * @param header the header to delete 4633 * @param content value to delete 4634 * @return #MHD_NO on error (no such header known) 4635 * @ingroup response 4636 */ 4637 _MHD_EXTERN enum MHD_Result 4638 MHD_del_response_header (struct MHD_Response *response, 4639 const char *header, 4640 const char *content); 4641 4642 4643 /** 4644 * Get all of the headers (and footers) added to a response. 4645 * 4646 * @param response response to query 4647 * @param iterator callback to call on each header; 4648 * may be NULL (then just count headers) 4649 * @param iterator_cls extra argument to @a iterator 4650 * @return number of entries iterated over 4651 * @ingroup response 4652 */ 4653 _MHD_EXTERN int 4654 MHD_get_response_headers (struct MHD_Response *response, 4655 MHD_KeyValueIterator iterator, 4656 void *iterator_cls); 4657 4658 4659 /** 4660 * Get a particular header (or footer) from the response. 4661 * 4662 * @param response response to query 4663 * @param key which header to get 4664 * @return NULL if header does not exist 4665 * @ingroup response 4666 */ 4667 _MHD_EXTERN const char * 4668 MHD_get_response_header (struct MHD_Response *response, 4669 const char *key); 4670 4671 4672 /* ********************** PostProcessor functions ********************** */ 4673 4674 /** 4675 * Create a `struct MHD_PostProcessor`. 4676 * 4677 * A `struct MHD_PostProcessor` can be used to (incrementally) parse 4678 * the data portion of a POST request. Note that some buggy browsers 4679 * fail to set the encoding type. If you want to support those, you 4680 * may have to call #MHD_set_connection_value with the proper encoding 4681 * type before creating a post processor (if no supported encoding 4682 * type is set, this function will fail). 4683 * 4684 * @param connection the connection on which the POST is 4685 * happening (used to determine the POST format) 4686 * @param buffer_size maximum number of bytes to use for 4687 * internal buffering (used only for the parsing, 4688 * specifically the parsing of the keys). A 4689 * tiny value (256-1024) should be sufficient. 4690 * Do NOT use a value smaller than 256. For good 4691 * performance, use 32 or 64k (i.e. 65536). 4692 * @param iter iterator to be called with the parsed data, 4693 * Must NOT be NULL. 4694 * @param iter_cls first argument to @a iter 4695 * @return NULL on error (out of memory, unsupported encoding), 4696 * otherwise a PP handle 4697 * @ingroup request 4698 */ 4699 _MHD_EXTERN struct MHD_PostProcessor * 4700 MHD_create_post_processor (struct MHD_Connection *connection, 4701 size_t buffer_size, 4702 MHD_PostDataIterator iter, void *iter_cls); 4703 4704 4705 /** 4706 * Parse and process POST data. Call this function when POST data is 4707 * available (usually during an #MHD_AccessHandlerCallback) with the 4708 * "upload_data" and "upload_data_size". Whenever possible, this will 4709 * then cause calls to the #MHD_PostDataIterator. 4710 * 4711 * @param pp the post processor 4712 * @param post_data @a post_data_len bytes of POST data 4713 * @param post_data_len length of @a post_data 4714 * @return #MHD_YES on success, #MHD_NO on error 4715 * (out-of-memory, iterator aborted, parse error) 4716 * @ingroup request 4717 */ 4718 _MHD_EXTERN enum MHD_Result 4719 MHD_post_process (struct MHD_PostProcessor *pp, 4720 const char *post_data, 4721 size_t post_data_len); 4722 4723 4724 /** 4725 * Release PostProcessor resources. 4726 * 4727 * @param pp the PostProcessor to destroy 4728 * @return #MHD_YES if processing completed nicely, 4729 * #MHD_NO if there were spurious characters / formatting 4730 * problems; it is common to ignore the return 4731 * value of this function 4732 * @ingroup request 4733 */ 4734 _MHD_EXTERN enum MHD_Result 4735 MHD_destroy_post_processor (struct MHD_PostProcessor *pp); 4736 4737 4738 /* ********************* Digest Authentication functions *************** */ 4739 4740 4741 /** 4742 * Length of the binary output of the MD5 hash function. 4743 * @sa #MHD_digest_get_hash_size() 4744 * @ingroup authentication 4745 */ 4746 #define MHD_MD5_DIGEST_SIZE 16 4747 4748 /** 4749 * Length of the binary output of the SHA-256 hash function. 4750 * @sa #MHD_digest_get_hash_size() 4751 * @ingroup authentication 4752 */ 4753 #define MHD_SHA256_DIGEST_SIZE 32 4754 4755 /** 4756 * Length of the binary output of the SHA-512/256 hash function. 4757 * @warning While this value is the same as the #MHD_SHA256_DIGEST_SIZE, 4758 * the calculated digests for SHA-256 and SHA-512/256 are different. 4759 * @sa #MHD_digest_get_hash_size() 4760 * @note Available since #MHD_VERSION 0x00097701 4761 * @ingroup authentication 4762 */ 4763 #define MHD_SHA512_256_DIGEST_SIZE 32 4764 4765 /** 4766 * Base type of hash calculation. 4767 * Used as part of #MHD_DigestAuthAlgo3 values. 4768 * 4769 * @warning Not used directly by MHD API. 4770 * @note Available since #MHD_VERSION 0x00097701 4771 */ 4772 enum MHD_DigestBaseAlgo 4773 { 4774 /** 4775 * Invalid hash algorithm value 4776 */ 4777 MHD_DIGEST_BASE_ALGO_INVALID = 0, 4778 4779 /** 4780 * MD5 hash algorithm. 4781 * As specified by RFC1321 4782 */ 4783 MHD_DIGEST_BASE_ALGO_MD5 = (1 << 0), 4784 4785 /** 4786 * SHA-256 hash algorithm. 4787 * As specified by FIPS PUB 180-4 4788 */ 4789 MHD_DIGEST_BASE_ALGO_SHA256 = (1 << 1), 4790 4791 /** 4792 * SHA-512/256 hash algorithm. 4793 * As specified by FIPS PUB 180-4 4794 */ 4795 MHD_DIGEST_BASE_ALGO_SHA512_256 = (1 << 2) 4796 } _MHD_FIXED_FLAGS_ENUM; 4797 4798 /** 4799 * The flag indicating non-session algorithm types, 4800 * like 'MD5', 'SHA-256' or 'SHA-512-256'. 4801 * @note Available since #MHD_VERSION 0x00097701 4802 */ 4803 #define MHD_DIGEST_AUTH_ALGO3_NON_SESSION (1 << 6) 4804 4805 /** 4806 * The flag indicating session algorithm types, 4807 * like 'MD5-sess', 'SHA-256-sess' or 'SHA-512-256-sess'. 4808 * @note Available since #MHD_VERSION 0x00097701 4809 */ 4810 #define MHD_DIGEST_AUTH_ALGO3_SESSION (1 << 7) 4811 4812 /** 4813 * Digest algorithm identification 4814 * @warning Do not be confused with #MHD_DigestAuthAlgorithm, 4815 * which uses other values! 4816 * @note Available since #MHD_VERSION 0x00097701 4817 */ 4818 enum MHD_DigestAuthAlgo3 4819 { 4820 /** 4821 * Unknown or wrong algorithm type. 4822 * Used in struct MHD_DigestAuthInfo to indicate client value that 4823 * cannot by identified. 4824 */ 4825 MHD_DIGEST_AUTH_ALGO3_INVALID = 0, 4826 4827 /** 4828 * The 'MD5' algorithm, non-session version. 4829 */ 4830 MHD_DIGEST_AUTH_ALGO3_MD5 = 4831 MHD_DIGEST_BASE_ALGO_MD5 | MHD_DIGEST_AUTH_ALGO3_NON_SESSION, 4832 4833 /** 4834 * The 'MD5-sess' algorithm. 4835 * Not supported by MHD for authentication. 4836 */ 4837 MHD_DIGEST_AUTH_ALGO3_MD5_SESSION = 4838 MHD_DIGEST_BASE_ALGO_MD5 | MHD_DIGEST_AUTH_ALGO3_SESSION, 4839 4840 /** 4841 * The 'SHA-256' algorithm, non-session version. 4842 */ 4843 MHD_DIGEST_AUTH_ALGO3_SHA256 = 4844 MHD_DIGEST_BASE_ALGO_SHA256 | MHD_DIGEST_AUTH_ALGO3_NON_SESSION, 4845 4846 /** 4847 * The 'SHA-256-sess' algorithm. 4848 * Not supported by MHD for authentication. 4849 */ 4850 MHD_DIGEST_AUTH_ALGO3_SHA256_SESSION = 4851 MHD_DIGEST_BASE_ALGO_SHA256 | MHD_DIGEST_AUTH_ALGO3_SESSION, 4852 4853 /** 4854 * The 'SHA-512-256' (SHA-512/256) algorithm. 4855 */ 4856 MHD_DIGEST_AUTH_ALGO3_SHA512_256 = 4857 MHD_DIGEST_BASE_ALGO_SHA512_256 | MHD_DIGEST_AUTH_ALGO3_NON_SESSION, 4858 4859 /** 4860 * The 'SHA-512-256-sess' (SHA-512/256 session) algorithm. 4861 * Not supported by MHD for authentication. 4862 */ 4863 MHD_DIGEST_AUTH_ALGO3_SHA512_256_SESSION = 4864 MHD_DIGEST_BASE_ALGO_SHA512_256 | MHD_DIGEST_AUTH_ALGO3_SESSION 4865 }; 4866 4867 4868 /** 4869 * Get digest size for specified algorithm. 4870 * 4871 * The size of the digest specifies the size of the userhash, userdigest 4872 * and other parameters which size depends on used hash algorithm. 4873 * @param algo3 the algorithm to check 4874 * @return the size of the digest (either #MHD_MD5_DIGEST_SIZE or 4875 * #MHD_SHA256_DIGEST_SIZE/MHD_SHA512_256_DIGEST_SIZE) 4876 * or zero if the input value is not supported or not valid 4877 * @sa #MHD_digest_auth_calc_userdigest() 4878 * @sa #MHD_digest_auth_calc_userhash(), #MHD_digest_auth_calc_userhash_hex() 4879 * @note Available since #MHD_VERSION 0x00097701 4880 * @ingroup authentication 4881 */ 4882 _MHD_EXTERN size_t 4883 MHD_digest_get_hash_size (enum MHD_DigestAuthAlgo3 algo3); 4884 4885 /** 4886 * Digest algorithm identification, allow multiple selection. 4887 * 4888 * #MHD_DigestAuthAlgo3 always can be casted to #MHD_DigestAuthMultiAlgo3, but 4889 * not vice versa. 4890 * 4891 * @note Available since #MHD_VERSION 0x00097701 4892 */ 4893 enum MHD_DigestAuthMultiAlgo3 4894 { 4895 /** 4896 * Unknown or wrong algorithm type. 4897 */ 4898 MHD_DIGEST_AUTH_MULT_ALGO3_INVALID = MHD_DIGEST_AUTH_ALGO3_INVALID, 4899 4900 /** 4901 * The 'MD5' algorithm, non-session version. 4902 */ 4903 MHD_DIGEST_AUTH_MULT_ALGO3_MD5 = MHD_DIGEST_AUTH_ALGO3_MD5, 4904 4905 /** 4906 * The 'MD5-sess' algorithm. 4907 * Not supported by MHD for authentication. 4908 * Reserved value. 4909 */ 4910 MHD_DIGEST_AUTH_MULT_ALGO3_MD5_SESSION = MHD_DIGEST_AUTH_ALGO3_MD5_SESSION, 4911 4912 /** 4913 * The 'SHA-256' algorithm, non-session version. 4914 */ 4915 MHD_DIGEST_AUTH_MULT_ALGO3_SHA256 = MHD_DIGEST_AUTH_ALGO3_SHA256, 4916 4917 /** 4918 * The 'SHA-256-sess' algorithm. 4919 * Not supported by MHD for authentication. 4920 * Reserved value. 4921 */ 4922 MHD_DIGEST_AUTH_MULT_ALGO3_SHA256_SESSION = 4923 MHD_DIGEST_AUTH_ALGO3_SHA256_SESSION, 4924 4925 /** 4926 * The 'SHA-512-256' (SHA-512/256) algorithm, non-session version. 4927 */ 4928 MHD_DIGEST_AUTH_MULT_ALGO3_SHA512_256 = MHD_DIGEST_AUTH_ALGO3_SHA512_256, 4929 4930 /** 4931 * The 'SHA-512-256-sess' (SHA-512/256 session) algorithm. 4932 * Not supported by MHD for authentication. 4933 * Reserved value. 4934 */ 4935 MHD_DIGEST_AUTH_MULT_ALGO3_SHA512_256_SESSION = 4936 MHD_DIGEST_AUTH_ALGO3_SHA512_256_SESSION, 4937 4938 /** 4939 * SHA-256 or SHA-512/256 non-session algorithm, MHD will choose 4940 * the preferred or the matching one. 4941 */ 4942 MHD_DIGEST_AUTH_MULT_ALGO3_SHA_ANY_NON_SESSION = 4943 MHD_DIGEST_AUTH_ALGO3_SHA256 | MHD_DIGEST_AUTH_ALGO3_SHA512_256, 4944 4945 /** 4946 * Any non-session algorithm, MHD will choose the preferred or 4947 * the matching one. 4948 */ 4949 MHD_DIGEST_AUTH_MULT_ALGO3_ANY_NON_SESSION = 4950 (0x3F) | MHD_DIGEST_AUTH_ALGO3_NON_SESSION, 4951 4952 /** 4953 * The SHA-256 or SHA-512/256 session algorithm. 4954 * Not supported by MHD. 4955 * Reserved value. 4956 */ 4957 MHD_DIGEST_AUTH_MULT_ALGO3_SHA_ANY_SESSION = 4958 MHD_DIGEST_AUTH_ALGO3_SHA256_SESSION 4959 | MHD_DIGEST_AUTH_ALGO3_SHA512_256_SESSION, 4960 4961 /** 4962 * Any session algorithm. 4963 * Not supported by MHD. 4964 * Reserved value. 4965 */ 4966 MHD_DIGEST_AUTH_MULT_ALGO3_ANY_SESSION = 4967 (0x3F) | MHD_DIGEST_AUTH_ALGO3_SESSION, 4968 4969 /** 4970 * The MD5 algorithm, session or non-session. 4971 * Currently supported as non-session only. 4972 */ 4973 MHD_DIGEST_AUTH_MULT_ALGO3_MD5_ANY = 4974 MHD_DIGEST_AUTH_MULT_ALGO3_MD5 | MHD_DIGEST_AUTH_MULT_ALGO3_MD5_SESSION, 4975 4976 /** 4977 * The SHA-256 algorithm, session or non-session. 4978 * Currently supported as non-session only. 4979 */ 4980 MHD_DIGEST_AUTH_MULT_ALGO3_SHA256_ANY = 4981 MHD_DIGEST_AUTH_MULT_ALGO3_SHA256 4982 | MHD_DIGEST_AUTH_MULT_ALGO3_SHA256_SESSION, 4983 4984 /** 4985 * The SHA-512/256 algorithm, session or non-session. 4986 * Currently supported as non-session only. 4987 */ 4988 MHD_DIGEST_AUTH_MULT_ALGO3_SHA512_256_ANY = 4989 MHD_DIGEST_AUTH_MULT_ALGO3_SHA512_256 4990 | MHD_DIGEST_AUTH_MULT_ALGO3_SHA512_256_SESSION, 4991 4992 /** 4993 * The SHA-256 or SHA-512/256 algorithm, session or non-session. 4994 * Currently supported as non-session only. 4995 */ 4996 MHD_DIGEST_AUTH_MULT_ALGO3_SHA_ANY_ANY = 4997 MHD_DIGEST_AUTH_MULT_ALGO3_SHA_ANY_NON_SESSION 4998 | MHD_DIGEST_AUTH_MULT_ALGO3_SHA_ANY_SESSION, 4999 5000 /** 5001 * Any algorithm, MHD will choose the preferred or the matching one. 5002 */ 5003 MHD_DIGEST_AUTH_MULT_ALGO3_ANY = 5004 (0x3F) | MHD_DIGEST_AUTH_ALGO3_NON_SESSION | MHD_DIGEST_AUTH_ALGO3_SESSION 5005 }; 5006 5007 5008 /** 5009 * Calculate "userhash", return it as binary data. 5010 * 5011 * The "userhash" is the hash of the string "username:realm". 5012 * 5013 * The "userhash" could be used to avoid sending username in cleartext in Digest 5014 * Authorization client's header. 5015 * 5016 * Userhash is not designed to hide the username in local database or files, 5017 * as username in cleartext is required for #MHD_digest_auth_check3() function 5018 * to check the response, but it can be used to hide username in HTTP headers. 5019 * 5020 * This function could be used when the new username is added to the username 5021 * database to save the "userhash" alongside with the username (preferably) or 5022 * when loading list of the usernames to generate the userhash for every loaded 5023 * username (this will cause delays at the start with the long lists). 5024 * 5025 * Once "userhash" is generated it could be used to identify users by clients 5026 * with "userhash" support. 5027 * Avoid repetitive usage of this function for the same username/realm 5028 * combination as it will cause excessive CPU load; save and re-use the result 5029 * instead. 5030 * 5031 * @param algo3 the algorithm for userhash calculations 5032 * @param username the username 5033 * @param realm the realm 5034 * @param[out] userhash_bin the output buffer for userhash as binary data; 5035 * if this function succeeds, then this buffer has 5036 * #MHD_digest_get_hash_size(algo3) bytes of userhash 5037 * upon return 5038 * @param bin_buf_size the size of the @a userhash_bin buffer, must be 5039 * at least #MHD_digest_get_hash_size(algo3) bytes long 5040 * @return MHD_YES on success, 5041 * MHD_NO if @a bin_buf_size is too small or if @a algo3 algorithm is 5042 * not supported (or external error has occurred, 5043 * see #MHD_FEATURE_EXTERN_HASH) 5044 * @sa #MHD_digest_auth_calc_userhash_hex() 5045 * @note Available since #MHD_VERSION 0x00097701 5046 * @ingroup authentication 5047 */ 5048 _MHD_EXTERN enum MHD_Result 5049 MHD_digest_auth_calc_userhash (enum MHD_DigestAuthAlgo3 algo3, 5050 const char *username, 5051 const char *realm, 5052 void *userhash_bin, 5053 size_t bin_buf_size); 5054 5055 5056 /** 5057 * Calculate "userhash", return it as hexadecimal string. 5058 * 5059 * The "userhash" is the hash of the string "username:realm". 5060 * 5061 * The "userhash" could be used to avoid sending username in cleartext in Digest 5062 * Authorization client's header. 5063 * 5064 * Userhash is not designed to hide the username in local database or files, 5065 * as username in cleartext is required for #MHD_digest_auth_check3() function 5066 * to check the response, but it can be used to hide username in HTTP headers. 5067 * 5068 * This function could be used when the new username is added to the username 5069 * database to save the "userhash" alongside with the username (preferably) or 5070 * when loading list of the usernames to generate the userhash for every loaded 5071 * username (this will cause delays at the start with the long lists). 5072 * 5073 * Once "userhash" is generated it could be used to identify users by clients 5074 * with "userhash" support. 5075 * Avoid repetitive usage of this function for the same username/realm 5076 * combination as it will cause excessive CPU load; save and re-use the result 5077 * instead. 5078 * 5079 * @param algo3 the algorithm for userhash calculations 5080 * @param username the username 5081 * @param realm the realm 5082 * @param[out] userhash_hex the output buffer for userhash as hex string; 5083 * if this function succeeds, then this buffer has 5084 * #MHD_digest_get_hash_size(algo3)*2 chars long 5085 * userhash zero-terminated string 5086 * @param bin_buf_size the size of the @a userhash_bin buffer, must be 5087 * at least #MHD_digest_get_hash_size(algo3)*2+1 chars long 5088 * @return MHD_YES on success, 5089 * MHD_NO if @a bin_buf_size is too small or if @a algo3 algorithm is 5090 * not supported (or external error has occurred, 5091 * see #MHD_FEATURE_EXTERN_HASH). 5092 * @sa #MHD_digest_auth_calc_userhash() 5093 * @note Available since #MHD_VERSION 0x00097701 5094 * @ingroup authentication 5095 */ 5096 _MHD_EXTERN enum MHD_Result 5097 MHD_digest_auth_calc_userhash_hex (enum MHD_DigestAuthAlgo3 algo3, 5098 const char *username, 5099 const char *realm, 5100 char *userhash_hex, 5101 size_t hex_buf_size); 5102 5103 5104 /** 5105 * The type of username used by client in Digest Authorization header 5106 * 5107 * Values are sorted so simplified checks could be used. 5108 * For example: 5109 * * (value <= MHD_DIGEST_AUTH_UNAME_TYPE_INVALID) is true if no valid username 5110 * is provided by the client 5111 * * (value >= MHD_DIGEST_AUTH_UNAME_TYPE_USERHASH) is true if username is 5112 * provided in any form 5113 * * (value >= MHD_DIGEST_AUTH_UNAME_TYPE_STANDARD) is true if username is 5114 * provided in clear text (no userhash matching is needed) 5115 * 5116 * @note Available since #MHD_VERSION 0x00097701 5117 */ 5118 enum MHD_DigestAuthUsernameType 5119 { 5120 /** 5121 * No username parameter in in Digest Authorization header. 5122 * This should be treated as an error. 5123 */ 5124 MHD_DIGEST_AUTH_UNAME_TYPE_MISSING = 0, 5125 5126 /** 5127 * The 'username' parameter is used to specify the username. 5128 */ 5129 MHD_DIGEST_AUTH_UNAME_TYPE_STANDARD = (1 << 2), 5130 5131 /** 5132 * The username is specified by 'username*' parameter with 5133 * the extended notation (see RFC 5987 #section-3.2.1). 5134 * The only difference between standard and extended types is 5135 * the way how username value is encoded in the header. 5136 */ 5137 MHD_DIGEST_AUTH_UNAME_TYPE_EXTENDED = (1 << 3), 5138 5139 /** 5140 * The username provided in form of 'userhash' as 5141 * specified by RFC 7616 #section-3.4.4. 5142 * @sa #MHD_digest_auth_calc_userhash_hex(), #MHD_digest_auth_calc_userhash() 5143 */ 5144 MHD_DIGEST_AUTH_UNAME_TYPE_USERHASH = (1 << 1), 5145 5146 /** 5147 * The invalid combination of username parameters are used by client. 5148 * Either: 5149 * * both 'username' and 'username*' are used 5150 * * 'username*' is used with 'userhash=true' 5151 * * 'username*' used with invalid extended notation 5152 * * 'username' is not hexadecimal string, while 'userhash' set to 'true' 5153 */ 5154 MHD_DIGEST_AUTH_UNAME_TYPE_INVALID = (1 << 0) 5155 } _MHD_FIXED_ENUM; 5156 5157 /** 5158 * The QOP ('quality of protection') types. 5159 * @note Available since #MHD_VERSION 0x00097701 5160 */ 5161 enum MHD_DigestAuthQOP 5162 { 5163 /** 5164 * Invalid/unknown QOP. 5165 * Used in struct MHD_DigestAuthInfo to indicate client value that 5166 * cannot by identified. 5167 */ 5168 MHD_DIGEST_AUTH_QOP_INVALID = 0, 5169 5170 /** 5171 * No QOP parameter. 5172 * As described in old RFC 2069 original specification. 5173 * This mode is not allowed by latest RFCs and should be used only to 5174 * communicate with clients that do not support more modern modes (with QOP 5175 * parameter). 5176 * This mode is less secure than other modes and inefficient. 5177 */ 5178 MHD_DIGEST_AUTH_QOP_NONE = 1 << 0, 5179 5180 /** 5181 * The 'auth' QOP type. 5182 */ 5183 MHD_DIGEST_AUTH_QOP_AUTH = 1 << 1, 5184 5185 /** 5186 * The 'auth-int' QOP type. 5187 * Not supported by MHD for authentication. 5188 */ 5189 MHD_DIGEST_AUTH_QOP_AUTH_INT = 1 << 2 5190 } _MHD_FIXED_FLAGS_ENUM; 5191 5192 /** 5193 * The QOP ('quality of protection') types, multiple selection. 5194 * 5195 * #MHD_DigestAuthQOP always can be casted to #MHD_DigestAuthMultiQOP, but 5196 * not vice versa. 5197 * 5198 * @note Available since #MHD_VERSION 0x00097701 5199 */ 5200 enum MHD_DigestAuthMultiQOP 5201 { 5202 /** 5203 * Invalid/unknown QOP. 5204 */ 5205 MHD_DIGEST_AUTH_MULT_QOP_INVALID = MHD_DIGEST_AUTH_QOP_INVALID, 5206 5207 /** 5208 * No QOP parameter. 5209 * As described in old RFC 2069 original specification. 5210 * This mode is not allowed by latest RFCs and should be used only to 5211 * communicate with clients that do not support more modern modes (with QOP 5212 * parameter). 5213 * This mode is less secure than other modes and inefficient. 5214 */ 5215 MHD_DIGEST_AUTH_MULT_QOP_NONE = MHD_DIGEST_AUTH_QOP_NONE, 5216 5217 /** 5218 * The 'auth' QOP type. 5219 */ 5220 MHD_DIGEST_AUTH_MULT_QOP_AUTH = MHD_DIGEST_AUTH_QOP_AUTH, 5221 5222 /** 5223 * The 'auth-int' QOP type. 5224 * Not supported by MHD. 5225 * Reserved value. 5226 */ 5227 MHD_DIGEST_AUTH_MULT_QOP_AUTH_INT = MHD_DIGEST_AUTH_QOP_AUTH_INT, 5228 5229 /** 5230 * The 'auth' QOP type OR the old RFC2069 (no QOP) type. 5231 * In other words: any types except 'auth-int'. 5232 * RFC2069-compatible mode is allowed, thus this value should be used only 5233 * when it is really necessary. 5234 */ 5235 MHD_DIGEST_AUTH_MULT_QOP_ANY_NON_INT = 5236 MHD_DIGEST_AUTH_QOP_NONE | MHD_DIGEST_AUTH_QOP_AUTH, 5237 5238 /** 5239 * Any 'auth' QOP type ('auth' or 'auth-int'). 5240 * Currently supported as 'auth' QOP type only. 5241 */ 5242 MHD_DIGEST_AUTH_MULT_QOP_AUTH_ANY = 5243 MHD_DIGEST_AUTH_QOP_AUTH | MHD_DIGEST_AUTH_QOP_AUTH_INT 5244 } _MHD_FIXED_ENUM; 5245 5246 /** 5247 * The invalid value of 'nc' parameter in client Digest Authorization header. 5248 * @note Available since #MHD_VERSION 0x00097701 5249 */ 5250 #define MHD_DIGEST_AUTH_INVALID_NC_VALUE (0) 5251 5252 /** 5253 * Information from Digest Authorization client's header. 5254 * 5255 * All buffers pointed by any struct members are freed when #MHD_free() is 5256 * called for pointer to this structure. 5257 * 5258 * Application may modify buffers as needed until #MHD_free() is called for 5259 * pointer to this structure 5260 * @note Available since #MHD_VERSION 0x00097701 5261 */ 5262 struct MHD_DigestAuthInfo 5263 { 5264 /** 5265 * The algorithm as defined by client. 5266 * Set automatically to MD5 if not specified by client. 5267 * @warning Do not be confused with #MHD_DigestAuthAlgorithm, 5268 * which uses other values! 5269 */ 5270 enum MHD_DigestAuthAlgo3 algo3; 5271 5272 /** 5273 * The type of username used by client. 5274 */ 5275 enum MHD_DigestAuthUsernameType uname_type; 5276 5277 /** 5278 * The username string. 5279 * Used only if username type is standard or extended, always NULL otherwise. 5280 * If extended notation is used, this string is pct-decoded string 5281 * with charset and language tag removed (i.e. it is original username 5282 * extracted from the extended notation). 5283 * When userhash is used by the client, this member is NULL and 5284 * @a userhash_hex and @a userhash_bin are set. 5285 * The buffer pointed by the @a username becomes invalid when the pointer 5286 * to the structure is freed by #MHD_free(). 5287 */ 5288 char *username; 5289 5290 /** 5291 * The length of the @a username. 5292 * When the @a username is NULL, this member is always zero. 5293 */ 5294 size_t username_len; 5295 5296 /** 5297 * The userhash string. 5298 * Valid only if username type is userhash. 5299 * This is unqoted string without decoding of the hexadecimal 5300 * digits (as provided by the client). 5301 * The buffer pointed by the @a userhash_hex becomes invalid when the pointer 5302 * to the structure is freed by #MHD_free(). 5303 * @sa #MHD_digest_auth_calc_userhash_hex() 5304 */ 5305 char *userhash_hex; 5306 5307 /** 5308 * The length of the @a userhash_hex in characters. 5309 * The valid size should be #MHD_digest_get_hash_size(algo3) * 2 characters. 5310 * When the @a userhash_hex is NULL, this member is always zero. 5311 */ 5312 size_t userhash_hex_len; 5313 5314 /** 5315 * The userhash decoded to binary form. 5316 * Used only if username type is userhash, always NULL otherwise. 5317 * When not NULL, this points to binary sequence @a userhash_hex_len /2 bytes 5318 * long. 5319 * The valid size should be #MHD_digest_get_hash_size(algo3) bytes. 5320 * The buffer pointed by the @a userhash_bin becomes invalid when the pointer 5321 * to the structure is freed by #MHD_free(). 5322 * @warning This is a binary data, no zero termination. 5323 * @warning To avoid buffer overruns, always check the size of the data before 5324 * use, because @a userhash_bin can point even to zero-sized 5325 * data. 5326 * @sa #MHD_digest_auth_calc_userhash() 5327 */ 5328 uint8_t *userhash_bin; 5329 5330 /** 5331 * The 'opaque' parameter value, as specified by client. 5332 * NULL if not specified by client. 5333 * The buffer pointed by the @a opaque becomes invalid when the pointer 5334 * to the structure is freed by #MHD_free(). 5335 */ 5336 char *opaque; 5337 5338 /** 5339 * The length of the @a opaque. 5340 * When the @a opaque is NULL, this member is always zero. 5341 */ 5342 size_t opaque_len; 5343 5344 /** 5345 * The 'realm' parameter value, as specified by client. 5346 * NULL if not specified by client. 5347 * The buffer pointed by the @a realm becomes invalid when the pointer 5348 * to the structure is freed by #MHD_free(). 5349 */ 5350 char *realm; 5351 5352 /** 5353 * The length of the @a realm. 5354 * When the @a realm is NULL, this member is always zero. 5355 */ 5356 size_t realm_len; 5357 5358 /** 5359 * The 'qop' parameter value. 5360 */ 5361 enum MHD_DigestAuthQOP qop; 5362 5363 /** 5364 * The length of the 'cnonce' parameter value, including possible 5365 * backslash-escape characters. 5366 * 'cnonce' is used in hash calculation, which is CPU-intensive procedure. 5367 * An application may want to reject too large cnonces to limit the CPU load. 5368 * A few kilobytes is a reasonable limit, typically cnonce is just 32-160 5369 * characters long. 5370 */ 5371 size_t cnonce_len; 5372 5373 /** 5374 * The nc parameter value. 5375 * Can be used by application to limit the number of nonce re-uses. If @a nc 5376 * is higher than application wants to allow, then "auth required" response 5377 * with 'stale=true' could be used to force client to retry with the fresh 5378 * 'nonce'. 5379 * If not specified by client or does not have hexadecimal digits only, the 5380 * value is #MHD_DIGEST_AUTH_INVALID_NC_VALUE. 5381 */ 5382 uint32_t nc; 5383 }; 5384 5385 5386 /** 5387 * Get information about Digest Authorization client's header. 5388 * 5389 * @param connection The MHD connection structure 5390 * @return NULL if no valid Digest Authorization header is used in the request; 5391 * a pointer to the structure with information if the valid request 5392 * header found, free using #MHD_free(). 5393 * @sa #MHD_digest_auth_get_username3() 5394 * @note Available since #MHD_VERSION 0x00097701 5395 * @ingroup authentication 5396 */ 5397 _MHD_EXTERN struct MHD_DigestAuthInfo * 5398 MHD_digest_auth_get_request_info3 (struct MHD_Connection *connection); 5399 5400 5401 /** 5402 * Information from Digest Authorization client's header. 5403 * 5404 * All buffers pointed by any struct members are freed when #MHD_free() is 5405 * called for pointer to this structure. 5406 * 5407 * Application may modify buffers as needed until #MHD_free() is called for 5408 * pointer to this structure 5409 * @note Available since #MHD_VERSION 0x00097701 5410 */ 5411 struct MHD_DigestAuthUsernameInfo 5412 { 5413 /** 5414 * The algorithm as defined by client. 5415 * Set automatically to MD5 if not specified by client. 5416 * @warning Do not be confused with #MHD_DigestAuthAlgorithm, 5417 * which uses other values! 5418 */ 5419 enum MHD_DigestAuthAlgo3 algo3; 5420 5421 /** 5422 * The type of username used by client. 5423 * The 'invalid' and 'missing' types are not used in this structure, 5424 * instead NULL is returned by #MHD_digest_auth_get_username3(). 5425 */ 5426 enum MHD_DigestAuthUsernameType uname_type; 5427 5428 /** 5429 * The username string. 5430 * Used only if username type is standard or extended, always NULL otherwise. 5431 * If extended notation is used, this string is pct-decoded string 5432 * with charset and language tag removed (i.e. it is original username 5433 * extracted from the extended notation). 5434 * When userhash is used by the client, this member is NULL and 5435 * @a userhash_hex and @a userhash_bin are set. 5436 * The buffer pointed by the @a username becomes invalid when the pointer 5437 * to the structure is freed by #MHD_free(). 5438 */ 5439 char *username; 5440 5441 /** 5442 * The length of the @a username. 5443 * When the @a username is NULL, this member is always zero. 5444 */ 5445 size_t username_len; 5446 5447 /** 5448 * The userhash string. 5449 * Valid only if username type is userhash. 5450 * This is unqoted string without decoding of the hexadecimal 5451 * digits (as provided by the client). 5452 * The buffer pointed by the @a userhash_hex becomes invalid when the pointer 5453 * to the structure is freed by #MHD_free(). 5454 * @sa #MHD_digest_auth_calc_userhash_hex() 5455 */ 5456 char *userhash_hex; 5457 5458 /** 5459 * The length of the @a userhash_hex in characters. 5460 * The valid size should be #MHD_digest_get_hash_size(algo3) * 2 characters. 5461 * When the @a userhash_hex is NULL, this member is always zero. 5462 */ 5463 size_t userhash_hex_len; 5464 5465 /** 5466 * The userhash decoded to binary form. 5467 * Used only if username type is userhash, always NULL otherwise. 5468 * When not NULL, this points to binary sequence @a userhash_hex_len /2 bytes 5469 * long. 5470 * The valid size should be #MHD_digest_get_hash_size(algo3) bytes. 5471 * The buffer pointed by the @a userhash_bin becomes invalid when the pointer 5472 * to the structure is freed by #MHD_free(). 5473 * @warning This is a binary data, no zero termination. 5474 * @warning To avoid buffer overruns, always check the size of the data before 5475 * use, because @a userhash_bin can point even to zero-sized 5476 * data. 5477 * @sa #MHD_digest_auth_calc_userhash() 5478 */ 5479 uint8_t *userhash_bin; 5480 }; 5481 5482 5483 /** 5484 * Get the username from Digest Authorization client's header. 5485 * 5486 * @param connection The MHD connection structure 5487 * @return NULL if no valid Digest Authorization header is used in the request, 5488 * or no username parameter is present in the header, or username is 5489 * provided incorrectly by client (see description for 5490 * #MHD_DIGEST_AUTH_UNAME_TYPE_INVALID); 5491 * a pointer structure with information if the valid request header 5492 * found, free using #MHD_free(). 5493 * @sa #MHD_digest_auth_get_request_info3() provides more complete information 5494 * @note Available since #MHD_VERSION 0x00097701 5495 * @ingroup authentication 5496 */ 5497 _MHD_EXTERN struct MHD_DigestAuthUsernameInfo * 5498 MHD_digest_auth_get_username3 (struct MHD_Connection *connection); 5499 5500 5501 /** 5502 * The result of digest authentication of the client. 5503 * 5504 * All error values are zero or negative. 5505 * 5506 * @note Available since #MHD_VERSION 0x00097701 5507 */ 5508 enum MHD_DigestAuthResult 5509 { 5510 /** 5511 * Authentication OK. 5512 */ 5513 MHD_DAUTH_OK = 1, 5514 5515 /** 5516 * General error, like "out of memory". 5517 */ 5518 MHD_DAUTH_ERROR = 0, 5519 5520 /** 5521 * No "Authorization" header or wrong format of the header. 5522 * Also may be returned if required parameters in client Authorisation header 5523 * are missing or broken (in invalid format). 5524 */ 5525 MHD_DAUTH_WRONG_HEADER = -1, 5526 5527 /** 5528 * Wrong 'username'. 5529 */ 5530 MHD_DAUTH_WRONG_USERNAME = -2, 5531 5532 /** 5533 * Wrong 'realm'. 5534 */ 5535 MHD_DAUTH_WRONG_REALM = -3, 5536 5537 /** 5538 * Wrong 'URI' (or URI parameters). 5539 */ 5540 MHD_DAUTH_WRONG_URI = -4, 5541 5542 /** 5543 * Wrong 'qop'. 5544 */ 5545 MHD_DAUTH_WRONG_QOP = -5, 5546 5547 /** 5548 * Wrong 'algorithm'. 5549 */ 5550 MHD_DAUTH_WRONG_ALGO = -6, 5551 5552 /** 5553 * Too large (>64 KiB) Authorization parameter value. 5554 */ 5555 MHD_DAUTH_TOO_LARGE = -15, 5556 5557 /* The different form of naming is intentionally used for the results below, 5558 * as they are more important */ 5559 5560 /** 5561 * The 'nonce' is too old. Suggest the client to retry with the same 5562 * username and password to get the fresh 'nonce'. 5563 * The validity of the 'nonce' may be not checked. 5564 */ 5565 MHD_DAUTH_NONCE_STALE = -17, 5566 5567 /** 5568 * The 'nonce' was generated by MHD for other conditions. 5569 * This value is only returned if #MHD_OPTION_DIGEST_AUTH_NONCE_BIND_TYPE 5570 * is set to anything other than #MHD_DAUTH_BIND_NONCE_NONE. 5571 * The interpretation of this code could be different. For example, if 5572 * #MHD_DAUTH_BIND_NONCE_URI is set and client just used the same 'nonce' for 5573 * another URI, the code could be handled as #MHD_DAUTH_NONCE_STALE as 5574 * RFCs allow nonces re-using for other URIs in the same "protection 5575 * space". However, if only #MHD_DAUTH_BIND_NONCE_CLIENT_IP bit is set and 5576 * it is know that clients have fixed IP addresses, this return code could 5577 * be handled like #MHD_DAUTH_NONCE_WRONG. 5578 */ 5579 MHD_DAUTH_NONCE_OTHER_COND = -18, 5580 5581 /** 5582 * The 'nonce' is wrong. May indicate an attack attempt. 5583 */ 5584 MHD_DAUTH_NONCE_WRONG = -33, 5585 5586 /** 5587 * The 'response' is wrong. Typically it means that wrong password used. 5588 * May indicate an attack attempt. 5589 */ 5590 MHD_DAUTH_RESPONSE_WRONG = -34 5591 }; 5592 5593 5594 /** 5595 * Authenticates the authorization header sent by the client. 5596 * 5597 * If RFC2069 mode is allowed by setting bit #MHD_DIGEST_AUTH_QOP_NONE in 5598 * @a mqop and the client uses this mode, then server generated nonces are 5599 * used as one-time nonces because nonce-count is not supported in this old RFC. 5600 * Communication in this mode is very inefficient, especially if the client 5601 * requests several resources one-by-one as for every request a new nonce must 5602 * be generated and client repeats all requests twice (first time to get a new 5603 * nonce and second time to perform an authorised request). 5604 * 5605 * @param connection the MHD connection structure 5606 * @param realm the realm for authorization of the client 5607 * @param username the username to be authenticated, must be in clear text 5608 * even if userhash is used by the client 5609 * @param password the password matching the @a username (and the @a realm) 5610 * @param nonce_timeout the period of seconds since nonce generation, when 5611 * the nonce is recognised as valid and not stale; 5612 * if zero is specified then daemon default value is used. 5613 * @param max_nc the maximum allowed nc (Nonce Count) value, if client's nc 5614 * exceeds the specified value then MHD_DAUTH_NONCE_STALE is 5615 * returned; 5616 * if zero is specified then daemon default value is used. 5617 * @param mqop the QOP to use 5618 * @param malgo3 digest algorithms allowed to use, fail if algorithm used 5619 * by the client is not allowed by this parameter 5620 * @return #MHD_DAUTH_OK if authenticated, 5621 * the error code otherwise 5622 * @note Available since #MHD_VERSION 0x00097708 5623 * @ingroup authentication 5624 */ 5625 _MHD_EXTERN enum MHD_DigestAuthResult 5626 MHD_digest_auth_check3 (struct MHD_Connection *connection, 5627 const char *realm, 5628 const char *username, 5629 const char *password, 5630 unsigned int nonce_timeout, 5631 uint32_t max_nc, 5632 enum MHD_DigestAuthMultiQOP mqop, 5633 enum MHD_DigestAuthMultiAlgo3 malgo3); 5634 5635 5636 /** 5637 * Calculate userdigest, return it as a binary data. 5638 * 5639 * The "userdigest" is the hash of the "username:realm:password" string. 5640 * 5641 * The "userdigest" can be used to avoid storing the password in clear text 5642 * in database/files 5643 * 5644 * This function is designed to improve security of stored credentials, 5645 * the "userdigest" does not improve security of the authentication process. 5646 * 5647 * The results can be used to store username & userdigest pairs instead of 5648 * username & password pairs. To further improve security, application may 5649 * store username & userhash & userdigest triplets. 5650 * 5651 * @param algo3 the digest algorithm 5652 * @param username the username 5653 * @param realm the realm 5654 * @param password the password 5655 * @param[out] userdigest_bin the output buffer for userdigest; 5656 * if this function succeeds, then this buffer has 5657 * #MHD_digest_get_hash_size(algo3) bytes of 5658 * userdigest upon return 5659 * @param bin_buf_size the size of the @a userdigest_bin buffer, must be 5660 * at least #MHD_digest_get_hash_size(algo3) bytes long 5661 * @return MHD_YES on success, 5662 * MHD_NO if @a userdigest_bin is too small or if @a algo3 algorithm is 5663 * not supported (or external error has occurred, 5664 * see #MHD_FEATURE_EXTERN_HASH). 5665 * @sa #MHD_digest_auth_check_digest3() 5666 * @note Available since #MHD_VERSION 0x00097701 5667 * @ingroup authentication 5668 */ 5669 _MHD_EXTERN enum MHD_Result 5670 MHD_digest_auth_calc_userdigest (enum MHD_DigestAuthAlgo3 algo3, 5671 const char *username, 5672 const char *realm, 5673 const char *password, 5674 void *userdigest_bin, 5675 size_t bin_buf_size); 5676 5677 5678 /** 5679 * Authenticates the authorization header sent by the client by using 5680 * hash of "username:realm:password". 5681 * 5682 * If RFC2069 mode is allowed by setting bit #MHD_DIGEST_AUTH_QOP_NONE in 5683 * @a mqop and the client uses this mode, then server generated nonces are 5684 * used as one-time nonces because nonce-count is not supported in this old RFC. 5685 * Communication in this mode is very inefficient, especially if the client 5686 * requests several resources one-by-one as for every request a new nonce must 5687 * be generated and client repeats all requests twice (first time to get a new 5688 * nonce and second time to perform an authorised request). 5689 * 5690 * @param connection the MHD connection structure 5691 * @param realm the realm for authorization of the client 5692 * @param username the username to be authenticated, must be in clear text 5693 * even if userhash is used by the client 5694 * @param userdigest the precalculated binary hash of the string 5695 * "username:realm:password", 5696 * see #MHD_digest_auth_calc_userdigest() 5697 * @param userdigest_size the size of the @a userdigest in bytes, must match the 5698 * hashing algorithm (see #MHD_MD5_DIGEST_SIZE, 5699 * #MHD_SHA256_DIGEST_SIZE, #MHD_SHA512_256_DIGEST_SIZE, 5700 * #MHD_digest_get_hash_size()) 5701 * @param nonce_timeout the period of seconds since nonce generation, when 5702 * the nonce is recognised as valid and not stale; 5703 * if zero is specified then daemon default value is used. 5704 * @param max_nc the maximum allowed nc (Nonce Count) value, if client's nc 5705 * exceeds the specified value then MHD_DAUTH_NONCE_STALE is 5706 * returned; 5707 * if zero is specified then daemon default value is used. 5708 * @param mqop the QOP to use 5709 * @param malgo3 digest algorithms allowed to use, fail if algorithm used 5710 * by the client is not allowed by this parameter; 5711 * more than one base algorithms (MD5, SHA-256, SHA-512/256) 5712 * cannot be used at the same time for this function 5713 * as @a userdigest must match specified algorithm 5714 * @return #MHD_DAUTH_OK if authenticated, 5715 * the error code otherwise 5716 * @sa #MHD_digest_auth_calc_userdigest() 5717 * @note Available since #MHD_VERSION 0x00097701 5718 * @ingroup authentication 5719 */ 5720 _MHD_EXTERN enum MHD_DigestAuthResult 5721 MHD_digest_auth_check_digest3 (struct MHD_Connection *connection, 5722 const char *realm, 5723 const char *username, 5724 const void *userdigest, 5725 size_t userdigest_size, 5726 unsigned int nonce_timeout, 5727 uint32_t max_nc, 5728 enum MHD_DigestAuthMultiQOP mqop, 5729 enum MHD_DigestAuthMultiAlgo3 malgo3); 5730 5731 5732 /** 5733 * Queues a response to request authentication from the client 5734 * 5735 * This function modifies provided @a response. The @a response must not be 5736 * reused and should be destroyed (by #MHD_destroy_response()) after call of 5737 * this function. 5738 * 5739 * If @a mqop allows both RFC 2069 (MHD_DIGEST_AUTH_QOP_NONE) and QOP with 5740 * value, then response is formed like if MHD_DIGEST_AUTH_QOP_NONE bit was 5741 * not set, because such response should be backward-compatible with RFC 2069. 5742 * 5743 * If @a mqop allows only MHD_DIGEST_AUTH_MULT_QOP_NONE, then the response is 5744 * formed in strict accordance with RFC 2069 (no 'qop', no 'userhash', no 5745 * 'charset'). For better compatibility with clients, it is recommended (but 5746 * not required) to set @a domain to NULL in this mode. 5747 * 5748 * @param connection the MHD connection structure 5749 * @param realm the realm presented to the client 5750 * @param opaque the string for opaque value, can be NULL, but NULL is 5751 * not recommended for better compatibility with clients; 5752 * the recommended format is hex or Base64 encoded string 5753 * @param domain the optional space-separated list of URIs for which the 5754 * same authorisation could be used, URIs can be in form 5755 * "path-absolute" (the path for the same host with initial slash) 5756 * or in form "absolute-URI" (the full path with protocol), in 5757 * any case client may assume that URI is in the same "protection 5758 * space" if it starts with any of values specified here; 5759 * could be NULL (clients typically assume that the same 5760 * credentials could be used for any URI on the same host); 5761 * this list provides information for the client only and does 5762 * not actually restrict anything on the server side 5763 * @param response the reply to send; should contain the "access denied" 5764 * body; 5765 * note: this function sets the "WWW Authenticate" header and 5766 * the caller should not set this header; 5767 * the NULL is tolerated 5768 * @param signal_stale if set to #MHD_YES then indication of stale nonce used in 5769 * the client's request is signalled by adding 'stale=true' 5770 * to the authentication header, this instructs the client 5771 * to retry immediately with the new nonce and the same 5772 * credentials, without asking user for the new password 5773 * @param mqop the QOP to use 5774 * @param malgo3 digest algorithm to use; if several algorithms are allowed 5775 * then MD5 is preferred (currently, may be changed in next 5776 * versions) 5777 * @param userhash_support if set to non-zero value (#MHD_YES) then support of 5778 * userhash is indicated, allowing client to provide 5779 * hash("username:realm") instead of the username in 5780 * clear text; 5781 * note that clients are allowed to provide the username 5782 * in cleartext even if this parameter set to non-zero; 5783 * when userhash is used, application must be ready to 5784 * identify users by provided userhash value instead of 5785 * username; see #MHD_digest_auth_calc_userhash() and 5786 * #MHD_digest_auth_calc_userhash_hex() 5787 * @param prefer_utf8 if not set to #MHD_NO, parameter 'charset=UTF-8' is 5788 * added, indicating for the client that UTF-8 encoding for 5789 * the username is preferred 5790 * @return #MHD_YES on success, #MHD_NO otherwise 5791 * @note Available since #MHD_VERSION 0x00097701 5792 * @ingroup authentication 5793 */ 5794 _MHD_EXTERN enum MHD_Result 5795 MHD_queue_auth_required_response3 (struct MHD_Connection *connection, 5796 const char *realm, 5797 const char *opaque, 5798 const char *domain, 5799 struct MHD_Response *response, 5800 int signal_stale, 5801 enum MHD_DigestAuthMultiQOP mqop, 5802 enum MHD_DigestAuthMultiAlgo3 algo, 5803 int userhash_support, 5804 int prefer_utf8); 5805 5806 5807 /** 5808 * Constant to indicate that the nonce of the provided 5809 * authentication code was wrong. 5810 * Used as return code by #MHD_digest_auth_check(), #MHD_digest_auth_check2(), 5811 * #MHD_digest_auth_check_digest(), #MHD_digest_auth_check_digest2(). 5812 * @ingroup authentication 5813 */ 5814 #define MHD_INVALID_NONCE -1 5815 5816 5817 /** 5818 * Get the username from the authorization header sent by the client 5819 * 5820 * This function supports username in standard and extended notations. 5821 * "userhash" is not supported by this function. 5822 * 5823 * @param connection The MHD connection structure 5824 * @return NULL if no username could be found, username provided as 5825 * "userhash", extended notation broken or memory allocation error 5826 * occurs; 5827 * a pointer to the username if found, free using #MHD_free(). 5828 * @warning Returned value must be freed by #MHD_free(). 5829 * @sa #MHD_digest_auth_get_username3() 5830 * @ingroup authentication 5831 */ 5832 _MHD_EXTERN char * 5833 MHD_digest_auth_get_username (struct MHD_Connection *connection); 5834 5835 5836 /** 5837 * Which digest algorithm should MHD use for HTTP digest authentication? 5838 * Used as parameter for #MHD_digest_auth_check2(), 5839 * #MHD_digest_auth_check_digest2(), #MHD_queue_auth_fail_response2(). 5840 */ 5841 enum MHD_DigestAuthAlgorithm 5842 { 5843 5844 /** 5845 * MHD should pick (currently defaults to MD5). 5846 */ 5847 MHD_DIGEST_ALG_AUTO = 0, 5848 5849 /** 5850 * Force use of MD5. 5851 */ 5852 MHD_DIGEST_ALG_MD5, 5853 5854 /** 5855 * Force use of SHA-256. 5856 */ 5857 MHD_DIGEST_ALG_SHA256 5858 5859 } _MHD_FIXED_ENUM; 5860 5861 5862 /** 5863 * Authenticates the authorization header sent by the client. 5864 * 5865 * @param connection The MHD connection structure 5866 * @param realm The realm presented to the client 5867 * @param username The username needs to be authenticated 5868 * @param password The password used in the authentication 5869 * @param nonce_timeout The amount of time for a nonce to be 5870 * invalid in seconds 5871 * @param algo digest algorithms allowed for verification 5872 * @return #MHD_YES if authenticated, #MHD_NO if not, 5873 * #MHD_INVALID_NONCE if nonce is invalid or stale 5874 * @note Available since #MHD_VERSION 0x00096200 5875 * @deprecated use MHD_digest_auth_check3() 5876 * @ingroup authentication 5877 */ 5878 _MHD_EXTERN int 5879 MHD_digest_auth_check2 (struct MHD_Connection *connection, 5880 const char *realm, 5881 const char *username, 5882 const char *password, 5883 unsigned int nonce_timeout, 5884 enum MHD_DigestAuthAlgorithm algo); 5885 5886 5887 /** 5888 * Authenticates the authorization header sent by the client. 5889 * Uses #MHD_DIGEST_ALG_MD5 (for now, for backwards-compatibility). 5890 * Note that this MAY change to #MHD_DIGEST_ALG_AUTO in the future. 5891 * If you want to be sure you get MD5, use #MHD_digest_auth_check2() 5892 * and specify MD5 explicitly. 5893 * 5894 * @param connection The MHD connection structure 5895 * @param realm The realm presented to the client 5896 * @param username The username needs to be authenticated 5897 * @param password The password used in the authentication 5898 * @param nonce_timeout The amount of time for a nonce to be 5899 * invalid in seconds 5900 * @return #MHD_YES if authenticated, #MHD_NO if not, 5901 * #MHD_INVALID_NONCE if nonce is invalid or stale 5902 * @deprecated use MHD_digest_auth_check3() 5903 * @ingroup authentication 5904 */ 5905 _MHD_EXTERN int 5906 MHD_digest_auth_check (struct MHD_Connection *connection, 5907 const char *realm, 5908 const char *username, 5909 const char *password, 5910 unsigned int nonce_timeout); 5911 5912 5913 /** 5914 * Authenticates the authorization header sent by the client. 5915 * 5916 * @param connection The MHD connection structure 5917 * @param realm The realm presented to the client 5918 * @param username The username needs to be authenticated 5919 * @param digest An `unsigned char *' pointer to the binary MD5 sum 5920 * for the precalculated hash value "username:realm:password" 5921 * of @a digest_size bytes 5922 * @param digest_size number of bytes in @a digest (size must match @a algo!) 5923 * @param nonce_timeout The amount of time for a nonce to be 5924 * invalid in seconds 5925 * @param algo digest algorithms allowed for verification 5926 * @return #MHD_YES if authenticated, #MHD_NO if not, 5927 * #MHD_INVALID_NONCE if nonce is invalid or stale 5928 * @note Available since #MHD_VERSION 0x00096200 5929 * @deprecated use MHD_digest_auth_check_digest3() 5930 * @ingroup authentication 5931 */ 5932 _MHD_EXTERN int 5933 MHD_digest_auth_check_digest2 (struct MHD_Connection *connection, 5934 const char *realm, 5935 const char *username, 5936 const uint8_t *digest, 5937 size_t digest_size, 5938 unsigned int nonce_timeout, 5939 enum MHD_DigestAuthAlgorithm algo); 5940 5941 5942 /** 5943 * Authenticates the authorization header sent by the client 5944 * Uses #MHD_DIGEST_ALG_MD5 (required, as @a digest is of fixed 5945 * size). 5946 * 5947 * @param connection The MHD connection structure 5948 * @param realm The realm presented to the client 5949 * @param username The username needs to be authenticated 5950 * @param digest An `unsigned char *' pointer to the binary hash 5951 * for the precalculated hash value "username:realm:password"; 5952 * length must be #MHD_MD5_DIGEST_SIZE bytes 5953 * @param nonce_timeout The amount of time for a nonce to be 5954 * invalid in seconds 5955 * @return #MHD_YES if authenticated, #MHD_NO if not, 5956 * #MHD_INVALID_NONCE if nonce is invalid or stale 5957 * @note Available since #MHD_VERSION 0x00096000 5958 * @deprecated use #MHD_digest_auth_check_digest3() 5959 * @ingroup authentication 5960 */ 5961 _MHD_EXTERN int 5962 MHD_digest_auth_check_digest (struct MHD_Connection *connection, 5963 const char *realm, 5964 const char *username, 5965 const uint8_t digest[MHD_MD5_DIGEST_SIZE], 5966 unsigned int nonce_timeout); 5967 5968 5969 /** 5970 * Queues a response to request authentication from the client 5971 * 5972 * This function modifies provided @a response. The @a response must not be 5973 * reused and should be destroyed after call of this function. 5974 * 5975 * @param connection The MHD connection structure 5976 * @param realm the realm presented to the client 5977 * @param opaque string to user for opaque value 5978 * @param response reply to send; should contain the "access denied" 5979 * body; note that this function will set the "WWW Authenticate" 5980 * header and that the caller should not do this; the NULL is tolerated 5981 * @param signal_stale #MHD_YES if the nonce is stale to add 5982 * 'stale=true' to the authentication header 5983 * @param algo digest algorithm to use 5984 * @return #MHD_YES on success, #MHD_NO otherwise 5985 * @note Available since #MHD_VERSION 0x00096200 5986 * @deprecated use MHD_queue_auth_required_response3() 5987 * @ingroup authentication 5988 */ 5989 _MHD_EXTERN enum MHD_Result 5990 MHD_queue_auth_fail_response2 (struct MHD_Connection *connection, 5991 const char *realm, 5992 const char *opaque, 5993 struct MHD_Response *response, 5994 int signal_stale, 5995 enum MHD_DigestAuthAlgorithm algo); 5996 5997 5998 /** 5999 * Queues a response to request authentication from the client. 6000 * For now uses MD5 (for backwards-compatibility). Still, if you 6001 * need to be sure, use #MHD_queue_auth_fail_response2(). 6002 * 6003 * This function modifies provided @a response. The @a response must not be 6004 * reused and should be destroyed after call of this function. 6005 * 6006 * @param connection The MHD connection structure 6007 * @param realm the realm presented to the client 6008 * @param opaque string to user for opaque value 6009 * @param response reply to send; should contain the "access denied" 6010 * body; note that this function will set the "WWW Authenticate" 6011 * header and that the caller should not do this; the NULL is tolerated 6012 * @param signal_stale #MHD_YES if the nonce is stale to add 6013 * 'stale=true' to the authentication header 6014 * @return #MHD_YES on success, #MHD_NO otherwise 6015 * @deprecated use MHD_queue_auth_required_response3() 6016 * @ingroup authentication 6017 */ 6018 _MHD_EXTERN enum MHD_Result 6019 MHD_queue_auth_fail_response (struct MHD_Connection *connection, 6020 const char *realm, 6021 const char *opaque, 6022 struct MHD_Response *response, 6023 int signal_stale); 6024 6025 6026 /* ********************* Basic Authentication functions *************** */ 6027 6028 6029 /** 6030 * Information decoded from Basic Authentication client's header. 6031 * 6032 * The username and the password are technically allowed to have binary zeros, 6033 * username_len and password_len could be used to detect such situations. 6034 * 6035 * The buffers pointed by username and password members are freed 6036 * when #MHD_free() is called for pointer to this structure. 6037 * 6038 * Application may modify buffers as needed until #MHD_free() is called for 6039 * pointer to this structure 6040 */ 6041 struct MHD_BasicAuthInfo 6042 { 6043 /** 6044 * The username, cannot be NULL. 6045 * The buffer pointed by the @a username becomes invalid when the pointer 6046 * to the structure is freed by #MHD_free(). 6047 */ 6048 char *username; 6049 6050 /** 6051 * The length of the @a username, not including zero-termination 6052 */ 6053 size_t username_len; 6054 6055 /** 6056 * The password, may be NULL if password is not encoded by the client. 6057 * The buffer pointed by the @a password becomes invalid when the pointer 6058 * to the structure is freed by #MHD_free(). 6059 */ 6060 char *password; 6061 6062 /** 6063 * The length of the @a password, not including zero-termination; 6064 * when the @a password is NULL, the length is always zero. 6065 */ 6066 size_t password_len; 6067 }; 6068 6069 /** 6070 * Get the username and password from the Basic Authorisation header 6071 * sent by the client 6072 * 6073 * @param connection the MHD connection structure 6074 * @return NULL if no valid Basic Authentication header is present in 6075 * current request, or 6076 * pointer to structure with username and password, which must be 6077 * freed by #MHD_free(). 6078 * @note Available since #MHD_VERSION 0x00097701 6079 * @ingroup authentication 6080 */ 6081 _MHD_EXTERN struct MHD_BasicAuthInfo * 6082 MHD_basic_auth_get_username_password3 (struct MHD_Connection *connection); 6083 6084 /** 6085 * Queues a response to request basic authentication from the client. 6086 * 6087 * The given response object is expected to include the payload for 6088 * the response; the "WWW-Authenticate" header will be added and the 6089 * response queued with the 'UNAUTHORIZED' status code. 6090 * 6091 * See RFC 7617#section-2 for details. 6092 * 6093 * The @a response is modified by this function. The modified response object 6094 * can be used to respond subsequent requests by #MHD_queue_response() 6095 * function with status code #MHD_HTTP_UNAUTHORIZED and must not be used again 6096 * with MHD_queue_basic_auth_required_response3() function. The response could 6097 * be destroyed right after call of this function. 6098 * 6099 * @param connection the MHD connection structure 6100 * @param realm the realm presented to the client 6101 * @param prefer_utf8 if not set to #MHD_NO, parameter'charset="UTF-8"' will 6102 * be added, indicating for client that UTF-8 encoding 6103 * is preferred 6104 * @param response the response object to modify and queue; the NULL 6105 * is tolerated 6106 * @return #MHD_YES on success, #MHD_NO otherwise 6107 * @note Available since #MHD_VERSION 0x00097704 6108 * @ingroup authentication 6109 */ 6110 _MHD_EXTERN enum MHD_Result 6111 MHD_queue_basic_auth_required_response3 (struct MHD_Connection *connection, 6112 const char *realm, 6113 int prefer_utf8, 6114 struct MHD_Response *response); 6115 6116 /** 6117 * Get the username and password from the basic authorization header sent by the client 6118 * 6119 * @param connection The MHD connection structure 6120 * @param[out] password a pointer for the password, free using #MHD_free(). 6121 * @return NULL if no username could be found, a pointer 6122 * to the username if found, free using #MHD_free(). 6123 * @deprecated use #MHD_basic_auth_get_username_password3() 6124 * @ingroup authentication 6125 */ 6126 _MHD_EXTERN char * 6127 MHD_basic_auth_get_username_password (struct MHD_Connection *connection, 6128 char **password); 6129 6130 6131 /** 6132 * Queues a response to request basic authentication from the client 6133 * The given response object is expected to include the payload for 6134 * the response; the "WWW-Authenticate" header will be added and the 6135 * response queued with the 'UNAUTHORIZED' status code. 6136 * 6137 * @param connection The MHD connection structure 6138 * @param realm the realm presented to the client 6139 * @param response response object to modify and queue; the NULL is tolerated 6140 * @return #MHD_YES on success, #MHD_NO otherwise 6141 * @deprecated use MHD_queue_basic_auth_required_response3() 6142 * @ingroup authentication 6143 */ 6144 _MHD_EXTERN enum MHD_Result 6145 MHD_queue_basic_auth_fail_response (struct MHD_Connection *connection, 6146 const char *realm, 6147 struct MHD_Response *response); 6148 6149 /* ********************** generic query functions ********************** */ 6150 6151 6152 /** 6153 * Obtain information about the given connection. 6154 * The returned pointer is invalidated with the next call of this function or 6155 * when the connection is closed. 6156 * 6157 * @param connection what connection to get information about 6158 * @param info_type what information is desired? 6159 * @param ... depends on @a info_type 6160 * @return NULL if this information is not available 6161 * (or if the @a info_type is unknown) 6162 * @ingroup specialized 6163 */ 6164 _MHD_EXTERN const union MHD_ConnectionInfo * 6165 MHD_get_connection_info (struct MHD_Connection *connection, 6166 enum MHD_ConnectionInfoType info_type, 6167 ...); 6168 6169 6170 /** 6171 * MHD connection options. Given to #MHD_set_connection_option to 6172 * set custom options for a particular connection. 6173 */ 6174 enum MHD_CONNECTION_OPTION 6175 { 6176 6177 /** 6178 * Set a custom timeout for the given connection. Specified 6179 * as the number of seconds, given as an `unsigned int`. Use 6180 * zero for no timeout. 6181 * If timeout was set to zero (or unset) before, setup of new value by 6182 * MHD_set_connection_option() will reset timeout timer. 6183 * Values larger than (UINT64_MAX / 2000 - 1) will 6184 * be clipped to this number. 6185 */ 6186 MHD_CONNECTION_OPTION_TIMEOUT 6187 6188 } _MHD_FIXED_ENUM; 6189 6190 6191 /** 6192 * Set a custom option for the given connection, overriding defaults. 6193 * 6194 * @param connection connection to modify 6195 * @param option option to set 6196 * @param ... arguments to the option, depending on the option type 6197 * @return #MHD_YES on success, #MHD_NO if setting the option failed 6198 * @ingroup specialized 6199 */ 6200 _MHD_EXTERN enum MHD_Result 6201 MHD_set_connection_option (struct MHD_Connection *connection, 6202 enum MHD_CONNECTION_OPTION option, 6203 ...); 6204 6205 6206 /** 6207 * Information about an MHD daemon. 6208 */ 6209 union MHD_DaemonInfo 6210 { 6211 /** 6212 * Size of the key, no longer supported. 6213 * @deprecated 6214 */ 6215 size_t key_size; 6216 6217 /** 6218 * Size of the mac key, no longer supported. 6219 * @deprecated 6220 */ 6221 size_t mac_key_size; 6222 6223 /** 6224 * Socket, returned for #MHD_DAEMON_INFO_LISTEN_FD. 6225 */ 6226 MHD_socket listen_fd; 6227 6228 /** 6229 * Bind port number, returned for #MHD_DAEMON_INFO_BIND_PORT. 6230 */ 6231 uint16_t port; 6232 6233 /** 6234 * epoll FD, returned for #MHD_DAEMON_INFO_EPOLL_FD. 6235 */ 6236 int epoll_fd; 6237 6238 /** 6239 * Number of active connections, for #MHD_DAEMON_INFO_CURRENT_CONNECTIONS. 6240 */ 6241 unsigned int num_connections; 6242 6243 /** 6244 * Combination of #MHD_FLAG values, for #MHD_DAEMON_INFO_FLAGS. 6245 * This value is actually a bitfield. 6246 * Note: flags may differ from original 'flags' specified for 6247 * daemon, especially if #MHD_USE_AUTO was set. 6248 */ 6249 enum MHD_FLAG flags; 6250 }; 6251 6252 6253 /** 6254 * Obtain information about the given daemon. 6255 * The returned pointer is invalidated with the next call of this function or 6256 * when the daemon is stopped. 6257 * 6258 * @param daemon what daemon to get information about 6259 * @param info_type what information is desired? 6260 * @param ... depends on @a info_type 6261 * @return NULL if this information is not available 6262 * (or if the @a info_type is unknown) 6263 * @ingroup specialized 6264 */ 6265 _MHD_EXTERN const union MHD_DaemonInfo * 6266 MHD_get_daemon_info (struct MHD_Daemon *daemon, 6267 enum MHD_DaemonInfoType info_type, 6268 ...); 6269 6270 6271 /** 6272 * Obtain the version of this library 6273 * 6274 * @return static version string, e.g. "0.9.9" 6275 * @ingroup specialized 6276 */ 6277 _MHD_EXTERN const char * 6278 MHD_get_version (void); 6279 6280 6281 /** 6282 * Obtain the version of this library as a binary value. 6283 * 6284 * @return version binary value, e.g. "0x00090900" (#MHD_VERSION of 6285 * compiled MHD binary) 6286 * @note Available since #MHD_VERSION 0x00097601 6287 * @ingroup specialized 6288 */ 6289 _MHD_EXTERN uint32_t 6290 MHD_get_version_bin (void); 6291 6292 6293 /** 6294 * Types of information about MHD features, 6295 * used by #MHD_is_feature_supported(). 6296 */ 6297 enum MHD_FEATURE 6298 { 6299 /** 6300 * Get whether messages are supported. If supported then in debug 6301 * mode messages can be printed to stderr or to external logger. 6302 */ 6303 MHD_FEATURE_MESSAGES = 1, 6304 6305 /** 6306 * Get whether HTTPS is supported. If supported then flag 6307 * #MHD_USE_TLS and options #MHD_OPTION_HTTPS_MEM_KEY, 6308 * #MHD_OPTION_HTTPS_MEM_CERT, #MHD_OPTION_HTTPS_MEM_TRUST, 6309 * #MHD_OPTION_HTTPS_MEM_DHPARAMS, #MHD_OPTION_HTTPS_CRED_TYPE, 6310 * #MHD_OPTION_HTTPS_PRIORITIES can be used. 6311 */ 6312 MHD_FEATURE_TLS = 2, 6313 MHD_FEATURE_SSL = 2, 6314 6315 /** 6316 * Get whether option #MHD_OPTION_HTTPS_CERT_CALLBACK is 6317 * supported. 6318 */ 6319 MHD_FEATURE_HTTPS_CERT_CALLBACK = 3, 6320 6321 /** 6322 * Get whether IPv6 is supported. If supported then flag 6323 * #MHD_USE_IPv6 can be used. 6324 */ 6325 MHD_FEATURE_IPv6 = 4, 6326 6327 /** 6328 * Get whether IPv6 without IPv4 is supported. If not supported 6329 * then IPv4 is always enabled in IPv6 sockets and 6330 * flag #MHD_USE_DUAL_STACK is always used when #MHD_USE_IPv6 is 6331 * specified. 6332 */ 6333 MHD_FEATURE_IPv6_ONLY = 5, 6334 6335 /** 6336 * Get whether `poll()` is supported. If supported then flag 6337 * #MHD_USE_POLL can be used. 6338 */ 6339 MHD_FEATURE_POLL = 6, 6340 6341 /** 6342 * Get whether `epoll()` is supported. If supported then Flags 6343 * #MHD_USE_EPOLL and 6344 * #MHD_USE_EPOLL_INTERNAL_THREAD can be used. 6345 */ 6346 MHD_FEATURE_EPOLL = 7, 6347 6348 /** 6349 * Get whether shutdown on listen socket to signal other 6350 * threads is supported. If not supported flag 6351 * #MHD_USE_ITC is automatically forced. 6352 */ 6353 MHD_FEATURE_SHUTDOWN_LISTEN_SOCKET = 8, 6354 6355 /** 6356 * Get whether socketpair is used internally instead of pipe to 6357 * signal other threads. 6358 */ 6359 MHD_FEATURE_SOCKETPAIR = 9, 6360 6361 /** 6362 * Get whether TCP Fast Open is supported. If supported then 6363 * flag #MHD_USE_TCP_FASTOPEN and option 6364 * #MHD_OPTION_TCP_FASTOPEN_QUEUE_SIZE can be used. 6365 */ 6366 MHD_FEATURE_TCP_FASTOPEN = 10, 6367 6368 /** 6369 * Get whether HTTP Basic authorization is supported. If supported 6370 * then functions #MHD_basic_auth_get_username_password and 6371 * #MHD_queue_basic_auth_fail_response can be used. 6372 */ 6373 MHD_FEATURE_BASIC_AUTH = 11, 6374 6375 /** 6376 * Get whether HTTP Digest authorization is supported. If 6377 * supported then options #MHD_OPTION_DIGEST_AUTH_RANDOM, 6378 * #MHD_OPTION_NONCE_NC_SIZE and 6379 * #MHD_digest_auth_check() can be used. 6380 */ 6381 MHD_FEATURE_DIGEST_AUTH = 12, 6382 6383 /** 6384 * Get whether postprocessor is supported. If supported then 6385 * functions #MHD_create_post_processor(), #MHD_post_process() and 6386 * #MHD_destroy_post_processor() can 6387 * be used. 6388 */ 6389 MHD_FEATURE_POSTPROCESSOR = 13, 6390 6391 /** 6392 * Get whether password encrypted private key for HTTPS daemon is 6393 * supported. If supported then option 6394 * ::MHD_OPTION_HTTPS_KEY_PASSWORD can be used. 6395 */ 6396 MHD_FEATURE_HTTPS_KEY_PASSWORD = 14, 6397 6398 /** 6399 * Get whether reading files beyond 2 GiB boundary is supported. 6400 * If supported then #MHD_create_response_from_fd(), 6401 * #MHD_create_response_from_fd64 #MHD_create_response_from_fd_at_offset() 6402 * and #MHD_create_response_from_fd_at_offset64() can be used with sizes and 6403 * offsets larger than 2 GiB. If not supported value of size+offset is 6404 * limited to 2 GiB. 6405 */ 6406 MHD_FEATURE_LARGE_FILE = 15, 6407 6408 /** 6409 * Get whether MHD set names on generated threads. 6410 */ 6411 MHD_FEATURE_THREAD_NAMES = 16, 6412 MHD_THREAD_NAMES = 16, 6413 6414 /** 6415 * Get whether HTTP "Upgrade" is supported. 6416 * If supported then #MHD_ALLOW_UPGRADE, #MHD_upgrade_action() and 6417 * #MHD_create_response_for_upgrade() can be used. 6418 */ 6419 MHD_FEATURE_UPGRADE = 17, 6420 6421 /** 6422 * Get whether it's safe to use same FD for multiple calls of 6423 * #MHD_create_response_from_fd() and whether it's safe to use single 6424 * response generated by #MHD_create_response_from_fd() with multiple 6425 * connections at same time. 6426 * If #MHD_is_feature_supported() return #MHD_NO for this feature then 6427 * usage of responses with same file FD in multiple parallel threads may 6428 * results in incorrect data sent to remote client. 6429 * It's always safe to use same file FD in multiple responses if MHD 6430 * is run in any single thread mode. 6431 */ 6432 MHD_FEATURE_RESPONSES_SHARED_FD = 18, 6433 6434 /** 6435 * Get whether MHD support automatic detection of bind port number. 6436 * @sa #MHD_DAEMON_INFO_BIND_PORT 6437 */ 6438 MHD_FEATURE_AUTODETECT_BIND_PORT = 19, 6439 6440 /** 6441 * Get whether MHD supports automatic SIGPIPE suppression. 6442 * If SIGPIPE suppression is not supported, application must handle 6443 * SIGPIPE signal by itself. 6444 */ 6445 MHD_FEATURE_AUTOSUPPRESS_SIGPIPE = 20, 6446 6447 /** 6448 * Get whether MHD use system's sendfile() function to send 6449 * file-FD based responses over non-TLS connections. 6450 * @note Since v0.9.56 6451 */ 6452 MHD_FEATURE_SENDFILE = 21, 6453 6454 /** 6455 * Get whether MHD supports threads. 6456 */ 6457 MHD_FEATURE_THREADS = 22, 6458 6459 /** 6460 * Get whether option #MHD_OPTION_HTTPS_CERT_CALLBACK2 is 6461 * supported. 6462 */ 6463 MHD_FEATURE_HTTPS_CERT_CALLBACK2 = 23, 6464 6465 /** 6466 * Get whether automatic parsing of HTTP Cookie header is supported. 6467 * If disabled, no MHD_COOKIE_KIND will be generated by MHD. 6468 * MHD versions before 0x00097701 always support cookie parsing. 6469 * @note Available since #MHD_VERSION 0x01000200 6470 */ 6471 MHD_FEATURE_COOKIE_PARSING = 24, 6472 6473 /** 6474 * Get whether the early version the Digest Authorization (RFC 2069) is 6475 * supported (digest authorisation without QOP parameter). 6476 * Since #MHD_VERSION 0x00097701 it is always supported if Digest Auth 6477 * module is built. 6478 * @note Available since #MHD_VERSION 0x00097701 6479 */ 6480 MHD_FEATURE_DIGEST_AUTH_RFC2069 = 25, 6481 6482 /** 6483 * Get whether the MD5-based hashing algorithms are supported for Digest 6484 * Authorization. 6485 * Currently it is always supported if Digest Auth module is built 6486 * unless manually disabled in a custom build. 6487 * @note Available since #MHD_VERSION 0x00097701 6488 */ 6489 MHD_FEATURE_DIGEST_AUTH_MD5 = 26, 6490 6491 /** 6492 * Get whether the SHA-256-based hashing algorithms are supported for Digest 6493 * Authorization. 6494 * It is always supported since #MHD_VERSION 0x00096200 if Digest Auth 6495 * module is built unless manually disabled in a custom build. 6496 * @note Available since #MHD_VERSION 0x00097701 6497 */ 6498 MHD_FEATURE_DIGEST_AUTH_SHA256 = 27, 6499 6500 /** 6501 * Get whether the SHA-512/256-based hashing algorithms are supported 6502 * for Digest Authorization. 6503 * It it always supported since #MHD_VERSION 0x00097701 if Digest Auth 6504 * module is built unless manually disabled in a custom build. 6505 * @note Available since #MHD_VERSION 0x00097701 6506 */ 6507 MHD_FEATURE_DIGEST_AUTH_SHA512_256 = 28, 6508 6509 /** 6510 * Get whether QOP with value 'auth-int' (authentication with integrity 6511 * protection) is supported for Digest Authorization. 6512 * Currently it is always not supported. 6513 * @note Available since #MHD_VERSION 0x00097701 6514 */ 6515 MHD_FEATURE_DIGEST_AUTH_AUTH_INT = 29, 6516 6517 /** 6518 * Get whether 'session' algorithms (like 'MD5-sess') are supported for Digest 6519 * Authorization. 6520 * Currently it is always not supported. 6521 * @note Available since #MHD_VERSION 0x00097701 6522 */ 6523 MHD_FEATURE_DIGEST_AUTH_ALGO_SESSION = 30, 6524 6525 /** 6526 * Get whether 'userhash' is supported for Digest Authorization. 6527 * It is always supported since #MHD_VERSION 0x00097701 if Digest Auth 6528 * module is built. 6529 * @note Available since #MHD_VERSION 0x00097701 6530 */ 6531 MHD_FEATURE_DIGEST_AUTH_USERHASH = 31, 6532 6533 /** 6534 * Get whether any of hashing algorithms is implemented by external 6535 * function (like TLS library) and may fail due to external conditions, 6536 * like "out-of-memory". 6537 * 6538 * If result is #MHD_YES then functions which use hash calculations 6539 * like #MHD_digest_auth_calc_userhash(), #MHD_digest_auth_check3() and others 6540 * potentially may fail even with valid input because of out-of-memory error 6541 * or crypto accelerator device failure, however in practice such fails are 6542 * unlikely. 6543 * @note Available since #MHD_VERSION 0x00097701 6544 */ 6545 MHD_FEATURE_EXTERN_HASH = 32, 6546 6547 /** 6548 * Get whether MHD was built with asserts enabled. 6549 * For debug builds the error log is always enabled even if #MHD_USE_ERROR_LOG 6550 * is not specified for daemon. 6551 * @note Available since #MHD_VERSION 0x00097701 6552 */ 6553 MHD_FEATURE_DEBUG_BUILD = 33, 6554 6555 /** 6556 * Get whether MHD was build with support for overridable FD_SETSIZE. 6557 * This feature should be always available when the relevant platform ability 6558 * is detected. 6559 * @sa #MHD_OPTION_APP_FD_SETSIZE 6560 * @note Available since #MHD_VERSION 0x00097705 6561 */ 6562 MHD_FEATURE_FLEXIBLE_FD_SETSIZE = 34 6563 }; 6564 6565 #define MHD_FEATURE_HTTPS_COOKIE_PARSING _MHD_DEPR_IN_MACRO ( \ 6566 "Value MHD_FEATURE_HTTPS_COOKIE_PARSING is deprecated, use MHD_FEATURE_COOKIE_PARSING" \ 6567 ) MHD_FEATURE_COOKIE_PARSING 6568 6569 /** 6570 * Get information about supported MHD features. 6571 * Indicate that MHD was compiled with or without support for 6572 * particular feature. Some features require additional support 6573 * by kernel. Kernel support is not checked by this function. 6574 * 6575 * @param feature type of requested information 6576 * @return #MHD_YES if feature is supported by MHD, #MHD_NO if 6577 * feature is not supported or feature is unknown. 6578 * @ingroup specialized 6579 */ 6580 _MHD_EXTERN enum MHD_Result 6581 MHD_is_feature_supported (enum MHD_FEATURE feature); 6582 6583 6584 MHD_C_DECLRATIONS_FINISH_HERE_ 6585 6586 #endif