microhttpd.h (257385B)
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 manage 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 0x01000800 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 * Note that while this flag has no effect of its own with "external" 1444 * sockets polling, the channel implied by #MHD_ALLOW_SUSPEND_RESUME 1445 * is created and used in that mode as well: #MHD_get_fdset() adds it 1446 * to the read set, so that #MHD_resume_connection() called from 1447 * another thread interrupts a blocking select()/poll() of the 1448 * application. See #MHD_resume_connection(). 1449 * #MHD_USE_ITC is always used automatically on platforms 1450 * where select()/poll()/other ignore shutdown of listen 1451 * socket. 1452 */ 1453 MHD_USE_ITC = 1024, 1454 1455 /** @deprecated */ 1456 MHD_USE_PIPE_FOR_SHUTDOWN = 1024, 1457 #if 0 /* Will be marked for real deprecation later. */ 1458 #define MHD_USE_PIPE_FOR_SHUTDOWN \ 1459 _MHD_DEPR_IN_MACRO ( \ 1460 "Value MHD_USE_PIPE_FOR_SHUTDOWN is deprecated, use MHD_USE_ITC") \ 1461 MHD_USE_ITC 1462 #endif /* 0 */ 1463 1464 /** 1465 * Use a single socket for IPv4 and IPv6. 1466 */ 1467 MHD_USE_DUAL_STACK = MHD_USE_IPv6 | 2048, 1468 1469 /** 1470 * Enable `turbo`. Disables certain calls to `shutdown()`, 1471 * enables aggressive non-blocking optimistic reads and 1472 * other potentially unsafe optimizations. 1473 * Most effects only happen with #MHD_USE_EPOLL. 1474 */ 1475 MHD_USE_TURBO = 4096, 1476 1477 /** @deprecated */ 1478 MHD_USE_EPOLL_TURBO = 4096, 1479 #if 0 /* Will be marked for real deprecation later. */ 1480 #define MHD_USE_EPOLL_TURBO \ 1481 _MHD_DEPR_IN_MACRO ( \ 1482 "Value MHD_USE_EPOLL_TURBO is deprecated, use MHD_USE_TURBO") \ 1483 MHD_USE_TURBO 1484 #endif /* 0 */ 1485 1486 /** 1487 * Enable suspend/resume functions, which also implies setting up 1488 * ITC to signal resume. 1489 */ 1490 MHD_ALLOW_SUSPEND_RESUME = 8192 | MHD_USE_ITC, 1491 1492 /** @deprecated */ 1493 MHD_USE_SUSPEND_RESUME = 8192 | MHD_USE_ITC, 1494 #if 0 /* Will be marked for real deprecation later. */ 1495 #define MHD_USE_SUSPEND_RESUME \ 1496 _MHD_DEPR_IN_MACRO ( \ 1497 "Value MHD_USE_SUSPEND_RESUME is deprecated, use MHD_ALLOW_SUSPEND_RESUME instead") \ 1498 MHD_ALLOW_SUSPEND_RESUME 1499 #endif /* 0 */ 1500 1501 /** 1502 * Enable TCP_FASTOPEN option. This option is only available on Linux with a 1503 * kernel >= 3.6. On other systems, using this option cases #MHD_start_daemon 1504 * to fail. 1505 */ 1506 MHD_USE_TCP_FASTOPEN = 16384, 1507 1508 /** 1509 * You need to set this option if you want to use HTTP "Upgrade". 1510 * "Upgrade" may require usage of additional internal resources, 1511 * which we do not want to use unless necessary. 1512 */ 1513 MHD_ALLOW_UPGRADE = 32768, 1514 1515 /** 1516 * Automatically use best available polling function. 1517 * Choice of polling function is also depend on other daemon options. 1518 * If #MHD_USE_INTERNAL_POLLING_THREAD is specified then epoll, poll() or 1519 * select() will be used (listed in decreasing preference order, first 1520 * function available on system will be used). 1521 * If #MHD_USE_THREAD_PER_CONNECTION is specified then poll() or select() 1522 * will be used. 1523 * If those flags are not specified then epoll or select() will be 1524 * used (as the only suitable for MHD_get_fdset()) 1525 */ 1526 MHD_USE_AUTO = 65536, 1527 1528 /** 1529 * Run using an internal thread (or thread pool) with best available on 1530 * system polling function. 1531 * This is combination of #MHD_USE_AUTO and #MHD_USE_INTERNAL_POLLING_THREAD 1532 * flags. 1533 */ 1534 MHD_USE_AUTO_INTERNAL_THREAD = MHD_USE_AUTO | MHD_USE_INTERNAL_POLLING_THREAD, 1535 1536 /** 1537 * Flag set to enable post-handshake client authentication 1538 * (only useful in combination with #MHD_USE_TLS). 1539 */ 1540 MHD_USE_POST_HANDSHAKE_AUTH_SUPPORT = 1U << 17, 1541 1542 /** 1543 * Flag set to enable TLS 1.3 early data. This has 1544 * security implications, be VERY careful when using this. 1545 */ 1546 MHD_USE_INSECURE_TLS_EARLY_DATA = 1U << 18, 1547 1548 /** 1549 * Indicates that MHD daemon will be used by application in single-threaded 1550 * mode only. When this flag is set then application must call any MHD 1551 * function only within a single thread. 1552 * This flag turns off some internal thread-safety and allows MHD making 1553 * some of the internal optimisations suitable only for single-threaded 1554 * environment. 1555 * Not compatible with #MHD_USE_INTERNAL_POLLING_THREAD. 1556 * @note Available since #MHD_VERSION 0x00097707 1557 */ 1558 MHD_USE_NO_THREAD_SAFETY = 1U << 19 1559 1560 }; 1561 1562 1563 /** 1564 * Type of a callback function used for logging by MHD. 1565 * 1566 * @param cls closure 1567 * @param fm format string (`printf()`-style) 1568 * @param ap arguments to @a fm 1569 * @ingroup logging 1570 */ 1571 typedef void 1572 (*MHD_LogCallback)(void *cls, 1573 const char *fm, 1574 va_list ap); 1575 1576 1577 /** 1578 * Function called to lookup the pre shared key (@a psk) for a given 1579 * HTTP connection based on the @a username. 1580 * 1581 * @param cls closure 1582 * @param connection the HTTPS connection 1583 * @param username the user name claimed by the other side 1584 * @param[out] psk to be set to the pre-shared-key; should be allocated with malloc(), 1585 * will be freed by MHD 1586 * @param[out] psk_size to be set to the number of bytes in @a psk 1587 * @return 0 on success, -1 on errors 1588 */ 1589 typedef int 1590 (*MHD_PskServerCredentialsCallback)(void *cls, 1591 const struct MHD_Connection *connection, 1592 const char *username, 1593 void **psk, 1594 size_t *psk_size); 1595 1596 /** 1597 * Values for #MHD_OPTION_DIGEST_AUTH_NONCE_BIND_TYPE. 1598 * 1599 * These values can limit the scope of validity of MHD-generated nonces. 1600 * Values can be combined with bitwise OR. 1601 * Any value, except #MHD_DAUTH_BIND_NONCE_NONE, enforce function 1602 * #MHD_digest_auth_check3() (and similar functions) to check nonce by 1603 * re-generating it again with the same parameters, which is CPU-intensive 1604 * operation. 1605 * @note Available since #MHD_VERSION 0x00097701 1606 */ 1607 enum MHD_DAuthBindNonce 1608 { 1609 /** 1610 * Generated nonces are valid for any request from any client until expired. 1611 * This is default and recommended value. 1612 * #MHD_digest_auth_check3() (and similar functions) would check only whether 1613 * the nonce value that is used by client has been generated by MHD and not 1614 * expired yet. 1615 * It is recommended because RFC 7616 allows clients to use the same nonce 1616 * for any request in the same "protection space". 1617 * When checking client's authorisation requests CPU is loaded less if this 1618 * value is used. 1619 * This mode gives MHD maximum flexibility for nonces generation and can 1620 * prevent possible nonce collisions (and corresponding log warning messages) 1621 * when clients' requests are intensive. 1622 * This value cannot be biwise-OR combined with other values. 1623 */ 1624 MHD_DAUTH_BIND_NONCE_NONE = 0, 1625 1626 /** 1627 * Generated nonces are valid only for the same realm. 1628 */ 1629 MHD_DAUTH_BIND_NONCE_REALM = 1 << 0, 1630 1631 /** 1632 * Generated nonces are valid only for the same URI (excluding parameters 1633 * after '?' in URI) and request method (GET, POST etc). 1634 * Not recommended unless "protection space" is limited to a single URI as 1635 * RFC 7616 allows clients to re-use server-generated nonces for any URI 1636 * in the same "protection space" which by default consists of all server 1637 * URIs. 1638 * Before #MHD_VERSION 0x00097701 this was default (and only supported) 1639 * nonce bind type. 1640 */ 1641 MHD_DAUTH_BIND_NONCE_URI = 1 << 1, 1642 1643 /** 1644 * Generated nonces are valid only for the same URI including URI parameters 1645 * and request method (GET, POST etc). 1646 * This value implies #MHD_DAUTH_BIND_NONCE_URI. 1647 * Not recommended for that same reasons as #MHD_DAUTH_BIND_NONCE_URI. 1648 */ 1649 MHD_DAUTH_BIND_NONCE_URI_PARAMS = 1 << 2, 1650 1651 /** 1652 * Generated nonces are valid only for the single client's IP. 1653 * While it looks like security improvement, in practice the same client may 1654 * jump from one IP to another (mobile or Wi-Fi handover, DHCP re-assignment, 1655 * Multi-NAT, different proxy chain and other reasons), while IP address 1656 * spoofing could be used relatively easily. 1657 */ 1658 MHD_DAUTH_BIND_NONCE_CLIENT_IP = 1 << 3 1659 } _MHD_FLAGS_ENUM; 1660 1661 /** 1662 * @brief MHD options. 1663 * 1664 * Passed in the varargs portion of #MHD_start_daemon. 1665 */ 1666 enum MHD_OPTION 1667 { 1668 1669 /** 1670 * No more options / last option. This is used 1671 * to terminate the VARARGs list. 1672 */ 1673 MHD_OPTION_END = 0, 1674 1675 /** 1676 * Maximum memory size per connection (followed by a `size_t`). 1677 * Default is 32 kb (#MHD_POOL_SIZE_DEFAULT). 1678 * Values above 128k are unlikely to result in much benefit, as half 1679 * of the memory will be typically used for IO, and TCP buffers are 1680 * unlikely to support window sizes above 64k on most systems. 1681 * Values below 64 bytes are completely unusable. 1682 * Since #MHD_VERSION 0x00097710 silently ignored if followed by zero value. 1683 */ 1684 MHD_OPTION_CONNECTION_MEMORY_LIMIT = 1, 1685 1686 /** 1687 * Maximum number of concurrent connections to 1688 * accept (followed by an `unsigned int`). 1689 */ 1690 MHD_OPTION_CONNECTION_LIMIT = 2, 1691 1692 /** 1693 * After how many seconds of inactivity should a 1694 * connection automatically be timed out? (followed 1695 * by an `unsigned int`; use zero for no timeout). 1696 * Values larger than (UINT64_MAX / 2000 - 1) will 1697 * be clipped to this number. 1698 */ 1699 MHD_OPTION_CONNECTION_TIMEOUT = 3, 1700 1701 /** 1702 * Register a function that should be called whenever a request has 1703 * been completed (this can be used for application-specific clean 1704 * up). Requests that have never been presented to the application 1705 * (via #MHD_AccessHandlerCallback) will not result in 1706 * notifications. 1707 * 1708 * This option should be followed by TWO pointers. First a pointer 1709 * to a function of type #MHD_RequestCompletedCallback and second a 1710 * pointer to a closure to pass to the request completed callback. 1711 * The second pointer may be NULL. 1712 */ 1713 MHD_OPTION_NOTIFY_COMPLETED = 4, 1714 1715 /** 1716 * Limit on the number of (concurrent) connections made to the 1717 * server from the same IP address. Can be used to prevent one 1718 * IP from taking over all of the allowed connections. If the 1719 * same IP tries to establish more than the specified number of 1720 * connections, they will be immediately rejected. The option 1721 * should be followed by an `unsigned int`. The default is 1722 * zero, which means no limit on the number of connections 1723 * from the same IP address. 1724 */ 1725 MHD_OPTION_PER_IP_CONNECTION_LIMIT = 5, 1726 1727 /** 1728 * Bind daemon to the supplied `struct sockaddr`. This option should 1729 * be followed by a `struct sockaddr *`. If #MHD_USE_IPv6 is 1730 * specified, the `struct sockaddr*` should point to a `struct 1731 * sockaddr_in6`, otherwise to a `struct sockaddr_in`. 1732 * Silently ignored if followed by NULL pointer. 1733 * @deprecated Use #MHD_OPTION_SOCK_ADDR_LEN 1734 */ 1735 MHD_OPTION_SOCK_ADDR = 6, 1736 1737 /** 1738 * Specify a function that should be called before parsing the URI from 1739 * the client. The specified callback function can be used for processing 1740 * the URI (including the options) before it is parsed. The URI after 1741 * parsing will no longer contain the options, which maybe inconvenient for 1742 * logging. This option should be followed by two arguments, the first 1743 * one must be of the form 1744 * 1745 * void * my_logger(void *cls, const char *uri, struct MHD_Connection *con) 1746 * 1747 * where the return value will be passed as 1748 * (`* req_cls`) in calls to the #MHD_AccessHandlerCallback 1749 * when this request is processed later; returning a 1750 * value of NULL has no special significance (however, 1751 * note that if you return non-NULL, you can no longer 1752 * rely on the first call to the access handler having 1753 * `NULL == *req_cls` on entry;) 1754 * "cls" will be set to the second argument following 1755 * #MHD_OPTION_URI_LOG_CALLBACK. Finally, uri will 1756 * be the 0-terminated URI of the request. 1757 * 1758 * Note that during the time of this call, most of the connection's 1759 * state is not initialized (as we have not yet parsed the headers). 1760 * However, information about the connecting client (IP, socket) 1761 * is available. 1762 * 1763 * The specified function is called only once per request, therefore some 1764 * programmers may use it to instantiate their own request objects, freeing 1765 * them in the notifier #MHD_OPTION_NOTIFY_COMPLETED. 1766 */ 1767 MHD_OPTION_URI_LOG_CALLBACK = 7, 1768 1769 /** 1770 * Memory pointer for the private key (key.pem) to be used by the 1771 * HTTPS daemon. This option should be followed by a 1772 * `const char *` argument. 1773 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_CERT. 1774 */ 1775 MHD_OPTION_HTTPS_MEM_KEY = 8, 1776 1777 /** 1778 * Memory pointer for the certificate (cert.pem) to be used by the 1779 * HTTPS daemon. This option should be followed by a 1780 * `const char *` argument. 1781 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY. 1782 */ 1783 MHD_OPTION_HTTPS_MEM_CERT = 9, 1784 1785 /** 1786 * Daemon credentials type. 1787 * Followed by an argument of type 1788 * `gnutls_credentials_type_t`. 1789 */ 1790 MHD_OPTION_HTTPS_CRED_TYPE = 10, 1791 1792 /** 1793 * Memory pointer to a `const char *` specifying the GnuTLS priorities string. 1794 * If this options is not specified, then MHD will try the following strings: 1795 * * "@LIBMICROHTTPD" (application-specific system-wide configuration) 1796 * * "@SYSTEM" (system-wide configuration) 1797 * * default GnuTLS priorities string 1798 * * "NORMAL" 1799 * The first configuration accepted by GnuTLS will be used. 1800 * For more details see GnuTLS documentation for "Application-specific 1801 * priority strings". 1802 */ 1803 MHD_OPTION_HTTPS_PRIORITIES = 11, 1804 1805 /** 1806 * Pass a listen socket for MHD to use (systemd-style). If this 1807 * option is used, MHD will not open its own listen socket(s). The 1808 * argument passed must be of type `MHD_socket` and refer to an 1809 * existing socket that has been bound to a port and is listening. 1810 * If followed by MHD_INVALID_SOCKET value, MHD ignores this option 1811 * and creates socket by itself. 1812 */ 1813 MHD_OPTION_LISTEN_SOCKET = 12, 1814 1815 /** 1816 * Use the given function for logging error messages. This option 1817 * must be followed by two arguments; the first must be a pointer to 1818 * a function of type #MHD_LogCallback and the second a pointer 1819 * `void *` which will be passed as the first argument to the log 1820 * callback. 1821 * Should be specified as the first option, otherwise some messages 1822 * may be printed by standard MHD logger during daemon startup. 1823 * 1824 * Note that MHD will not generate any log messages 1825 * if it was compiled without the "--enable-messages" 1826 * flag being set. 1827 */ 1828 MHD_OPTION_EXTERNAL_LOGGER = 13, 1829 1830 /** 1831 * Number (`unsigned int`) of threads in thread pool. Enable 1832 * thread pooling by setting this value to to something 1833 * greater than 1. 1834 * Can be used only for daemons started with #MHD_USE_INTERNAL_POLLING_THREAD. 1835 * Ignored if followed by zero value. 1836 */ 1837 MHD_OPTION_THREAD_POOL_SIZE = 14, 1838 1839 /** 1840 * Additional options given in an array of `struct MHD_OptionItem`. 1841 * The array must be terminated with an entry `{MHD_OPTION_END, 0, NULL}`. 1842 * An example for code using #MHD_OPTION_ARRAY is: 1843 * 1844 * struct MHD_OptionItem ops[] = { 1845 * { MHD_OPTION_CONNECTION_LIMIT, 100, NULL }, 1846 * { MHD_OPTION_CONNECTION_TIMEOUT, 10, NULL }, 1847 * { MHD_OPTION_END, 0, NULL } 1848 * }; 1849 * d = MHD_start_daemon (0, 8080, NULL, NULL, dh, NULL, 1850 * MHD_OPTION_ARRAY, ops, 1851 * MHD_OPTION_END); 1852 * 1853 * For options that expect a single pointer argument, the 1854 * 'value' member of the `struct MHD_OptionItem` is ignored. 1855 * For options that expect two pointer arguments, the first 1856 * argument must be cast to `intptr_t`. 1857 */ 1858 MHD_OPTION_ARRAY = 15, 1859 1860 /** 1861 * Specify a function that should be called for unescaping escape 1862 * sequences in URIs and URI arguments. Note that this function 1863 * will NOT be used by the `struct MHD_PostProcessor`. If this 1864 * option is not specified, the default method will be used which 1865 * decodes escape sequences of the form "%HH". This option should 1866 * be followed by two arguments, the first one must be of the form 1867 * 1868 * size_t my_unescaper(void *cls, 1869 * struct MHD_Connection *c, 1870 * char *s) 1871 * 1872 * where the return value must be the length of the value left in 1873 * "s" (without the 0-terminator) and "s" should be updated. Note 1874 * that the unescape function must not lengthen "s" (the result must 1875 * be shorter than the input and must still be 0-terminated). 1876 * However, it may also include binary zeros before the 1877 * 0-termination. "cls" will be set to the second argument 1878 * following #MHD_OPTION_UNESCAPE_CALLBACK. 1879 */ 1880 MHD_OPTION_UNESCAPE_CALLBACK = 16, 1881 1882 /** 1883 * Memory pointer for the random values to be used by the Digest 1884 * Auth module. This option should be followed by two arguments. 1885 * First an integer of type `size_t` which specifies the size 1886 * of the buffer pointed to by the second argument in bytes. 1887 * The recommended size is between 8 and 32. If size is four or less 1888 * then security could be lowered. Sizes more then 32 (or, probably 1889 * more than 16 - debatable) will not increase security. 1890 * Note that the application must ensure that the buffer of the 1891 * second argument remains allocated and unmodified while the 1892 * daemon is running. 1893 * @sa #MHD_OPTION_DIGEST_AUTH_RANDOM_COPY 1894 */ 1895 MHD_OPTION_DIGEST_AUTH_RANDOM = 17, 1896 1897 /** 1898 * Size of the internal array holding the map of the nonce and 1899 * the nonce counter. This option should be followed by an `unsigned int` 1900 * argument. 1901 * The map size is 4 by default, which is enough to communicate with 1902 * a single client at any given moment of time, but not enough to 1903 * handle several clients simultaneously. 1904 * If Digest Auth is not used, this option can be set to zero to minimise 1905 * memory allocation. 1906 */ 1907 MHD_OPTION_NONCE_NC_SIZE = 18, 1908 1909 /** 1910 * Desired size of the stack for threads created by MHD. Followed 1911 * by an argument of type `size_t`. Use 0 for system default. 1912 */ 1913 MHD_OPTION_THREAD_STACK_SIZE = 19, 1914 1915 /** 1916 * Memory pointer for the certificate (ca.pem) to be used by the 1917 * HTTPS daemon for client authentication. 1918 * This option should be followed by a `const char *` argument. 1919 */ 1920 MHD_OPTION_HTTPS_MEM_TRUST = 20, 1921 1922 /** 1923 * Increment to use for growing the read buffer (followed by a 1924 * `size_t`). 1925 * Must not be higher than 1/4 of #MHD_OPTION_CONNECTION_MEMORY_LIMIT. 1926 * Since #MHD_VERSION 0x00097710 silently ignored if followed by zero value. 1927 */ 1928 MHD_OPTION_CONNECTION_MEMORY_INCREMENT = 21, 1929 1930 /** 1931 * Use a callback to determine which X.509 certificate should be 1932 * used for a given HTTPS connection. This option should be 1933 * followed by a argument of type `gnutls_certificate_retrieve_function2 *`. 1934 * This option provides an 1935 * alternative to #MHD_OPTION_HTTPS_MEM_KEY, 1936 * #MHD_OPTION_HTTPS_MEM_CERT. You must use this version if 1937 * multiple domains are to be hosted at the same IP address using 1938 * TLS's Server Name Indication (SNI) extension. In this case, 1939 * the callback is expected to select the correct certificate 1940 * based on the SNI information provided. The callback is expected 1941 * to access the SNI data using `gnutls_server_name_get()`. 1942 * Using this option requires GnuTLS 3.0 or higher. 1943 */ 1944 MHD_OPTION_HTTPS_CERT_CALLBACK = 22, 1945 1946 /** 1947 * When using #MHD_USE_TCP_FASTOPEN, this option changes the default TCP 1948 * fastopen queue length of 50. Note that having a larger queue size can 1949 * cause resource exhaustion attack as the TCP stack has to now allocate 1950 * resources for the SYN packet along with its DATA. This option should be 1951 * followed by an `unsigned int` argument. 1952 */ 1953 MHD_OPTION_TCP_FASTOPEN_QUEUE_SIZE = 23, 1954 1955 /** 1956 * Memory pointer for the Diffie-Hellman parameters (dh.pem) to be used by the 1957 * HTTPS daemon for key exchange. 1958 * This option must be followed by a `const char *` argument. 1959 */ 1960 MHD_OPTION_HTTPS_MEM_DHPARAMS = 24, 1961 1962 /** 1963 * If present and set to true, allow reusing address:port socket 1964 * (by using SO_REUSEPORT on most platform, or platform-specific ways). 1965 * If present and set to false, disallow reusing address:port socket 1966 * (does nothing on most platform, but uses SO_EXCLUSIVEADDRUSE on Windows). 1967 * This option must be followed by a `unsigned int` argument. 1968 */ 1969 MHD_OPTION_LISTENING_ADDRESS_REUSE = 25, 1970 1971 /** 1972 * Memory pointer for a password that decrypts the private key (key.pem) 1973 * to be used by the HTTPS daemon. This option should be followed by a 1974 * `const char *` argument. 1975 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY. 1976 * @sa ::MHD_FEATURE_HTTPS_KEY_PASSWORD 1977 */ 1978 MHD_OPTION_HTTPS_KEY_PASSWORD = 26, 1979 1980 /** 1981 * Register a function that should be called whenever a connection is 1982 * started or closed. 1983 * 1984 * This option should be followed by TWO pointers. First a pointer 1985 * to a function of type #MHD_NotifyConnectionCallback and second a 1986 * pointer to a closure to pass to the request completed callback. 1987 * The second pointer may be NULL. 1988 */ 1989 MHD_OPTION_NOTIFY_CONNECTION = 27, 1990 1991 /** 1992 * Allow to change maximum length of the queue of pending connections on 1993 * listen socket. If not present than default platform-specific SOMAXCONN 1994 * value is used. This option should be followed by an `unsigned int` 1995 * argument. 1996 */ 1997 MHD_OPTION_LISTEN_BACKLOG_SIZE = 28, 1998 1999 /** 2000 * If set to 1 - be strict about the protocol. Use -1 to be 2001 * as tolerant as possible. 2002 * 2003 * The more flexible option #MHD_OPTION_CLIENT_DISCIPLINE_LVL is recommended 2004 * instead of this option. 2005 * 2006 * The values mapping table: 2007 * #MHD_OPTION_STRICT_FOR_CLIENT | #MHD_OPTION_CLIENT_DISCIPLINE_LVL 2008 * -----------------------------:|:--------------------------------- 2009 * 1 | 1 2010 * 0 | 0 2011 * -1 | -3 2012 * 2013 * This option should be followed by an `int` argument. 2014 * @sa #MHD_OPTION_CLIENT_DISCIPLINE_LVL 2015 */ 2016 MHD_OPTION_STRICT_FOR_CLIENT = 29, 2017 2018 /** 2019 * This should be a pointer to callback of type 2020 * gnutls_psk_server_credentials_function that will be given to 2021 * gnutls_psk_set_server_credentials_function. It is used to 2022 * retrieve the shared key for a given username. 2023 */ 2024 MHD_OPTION_GNUTLS_PSK_CRED_HANDLER = 30, 2025 2026 /** 2027 * Use a callback to determine which X.509 certificate should be 2028 * used for a given HTTPS connection. This option should be 2029 * followed by a argument of type `gnutls_certificate_retrieve_function3 *`. 2030 * This option provides an 2031 * alternative/extension to #MHD_OPTION_HTTPS_CERT_CALLBACK. 2032 * You must use this version if you want to use OCSP stapling. 2033 * Using this option requires GnuTLS 3.6.3 or higher. 2034 */ 2035 MHD_OPTION_HTTPS_CERT_CALLBACK2 = 31, 2036 2037 /** 2038 * Allows the application to disable certain sanity precautions 2039 * in MHD. With these, the client can break the HTTP protocol, 2040 * so this should never be used in production. The options are, 2041 * however, useful for testing HTTP clients against "broken" 2042 * server implementations. 2043 * This argument must be followed by an "unsigned int", corresponding 2044 * to an `enum MHD_DisableSanityCheck`. 2045 */ 2046 MHD_OPTION_SERVER_INSANITY = 32, 2047 2048 /** 2049 * If followed by value '1' informs MHD that SIGPIPE is suppressed or 2050 * handled by application. Allows MHD to use network functions that could 2051 * generate SIGPIPE, like `sendfile()`. 2052 * Valid only for daemons without #MHD_USE_INTERNAL_POLLING_THREAD as 2053 * MHD automatically suppresses SIGPIPE for threads started by MHD. 2054 * This option should be followed by an `int` argument. 2055 * @note Available since #MHD_VERSION 0x00097205 2056 */ 2057 MHD_OPTION_SIGPIPE_HANDLED_BY_APP = 33, 2058 2059 /** 2060 * If followed by 'int' with value '1' disables usage of ALPN for TLS 2061 * connections even if supported by TLS library. 2062 * Valid only for daemons with #MHD_USE_TLS. 2063 * This option should be followed by an `int` argument. 2064 * @note Available since #MHD_VERSION 0x00097207 2065 */ 2066 MHD_OPTION_TLS_NO_ALPN = 34, 2067 2068 /** 2069 * Memory pointer for the random values to be used by the Digest 2070 * Auth module. This option should be followed by two arguments. 2071 * First an integer of type `size_t` which specifies the size 2072 * of the buffer pointed to by the second argument in bytes. 2073 * The recommended size is between 8 and 32. If size is four or less 2074 * then security could be lowered. Sizes more then 32 (or, probably 2075 * more than 16 - debatable) will not increase security. 2076 * An internal copy of the buffer will be made, the data do not 2077 * need to be static. 2078 * @sa #MHD_OPTION_DIGEST_AUTH_RANDOM 2079 * @note Available since #MHD_VERSION 0x00097701 2080 */ 2081 MHD_OPTION_DIGEST_AUTH_RANDOM_COPY = 35, 2082 2083 /** 2084 * Allow to controls the scope of validity of MHD-generated nonces. 2085 * This regulates how "nonces" are generated and how "nonces" are checked by 2086 * #MHD_digest_auth_check3() and similar functions. 2087 * This option should be followed by an 'unsigned int` argument with value 2088 * formed as bitwise OR combination of #MHD_DAuthBindNonce values. 2089 * When not specified, default value #MHD_DAUTH_BIND_NONCE_NONE is used. 2090 * @note Available since #MHD_VERSION 0x00097701 2091 */ 2092 MHD_OPTION_DIGEST_AUTH_NONCE_BIND_TYPE = 36, 2093 2094 /** 2095 * Memory pointer to a `const char *` specifying the GnuTLS priorities to be 2096 * appended to default priorities. 2097 * This allow some specific options to be enabled/disabled, while leaving 2098 * the rest of the settings to their defaults. 2099 * The string does not have to start with a colon ':' character. 2100 * See #MHD_OPTION_HTTPS_PRIORITIES description for details of automatic 2101 * default priorities. 2102 * @note Available since #MHD_VERSION 0x00097701 2103 */ 2104 MHD_OPTION_HTTPS_PRIORITIES_APPEND = 37, 2105 2106 /** 2107 * Sets specified client discipline level (i.e. HTTP protocol parsing 2108 * strictness level). 2109 * 2110 * The following basic values are supported: 2111 * 0 - default MHD level, a balance between extra security and broader 2112 * compatibility, as allowed by RFCs for HTTP servers; 2113 * 1 - more strict protocol interpretation, within the limits set by 2114 * RFCs for HTTP servers; 2115 * -1 - more lenient protocol interpretation, within the limits set by 2116 * RFCs for HTTP servers. 2117 * The following extended values could be used as well: 2118 * 2 - stricter protocol interpretation, even stricter then allowed 2119 * by RFCs for HTTP servers, however it should be absolutely compatible 2120 * with clients following at least RFCs' "MUST" type of requirements 2121 * for HTTP clients; 2122 * 3 - strictest protocol interpretation, even stricter then allowed 2123 * by RFCs for HTTP servers, however it should be absolutely compatible 2124 * with clients following RFCs' "SHOULD" and "MUST" types of requirements 2125 * for HTTP clients; 2126 * -2 - more relaxed protocol interpretation, violating RFCs' "SHOULD" type 2127 * of requirements for HTTP servers; 2128 * -3 - the most flexible protocol interpretation, beyond RFCs' "MUST" type of 2129 * requirements for HTTP server. 2130 * Values higher than "3" or lower than "-3" are interpreted as "3" or "-3" 2131 * respectively. 2132 * 2133 * Higher values are more secure, lower values are more compatible with 2134 * various HTTP clients. 2135 * 2136 * The default value ("0") could be used in most cases. 2137 * Value "1" is suitable for highly loaded public servers. 2138 * Values "2" and "3" are generally recommended only for testing of HTTP 2139 * clients against MHD. 2140 * Value "2" may be used for security-centric application, however it is 2141 * slight violation of RFCs' requirements. 2142 * Negative values are not recommended for public servers. 2143 * Values "-1" and "-2" could be used for servers in isolated environment. 2144 * Value "-3" is not recommended unless it is absolutely necessary to 2145 * communicate with some client(s) with badly broken HTTP implementation. 2146 * 2147 * This option should be followed by an `int` argument. 2148 * @note Available since #MHD_VERSION 0x00097701 2149 */ 2150 MHD_OPTION_CLIENT_DISCIPLINE_LVL = 38, 2151 2152 /** 2153 * Specifies value of FD_SETSIZE used by application. Only For external 2154 * polling modes (without MHD internal threads). 2155 * Some platforms (FreeBSD, Solaris, W32 etc.) allow overriding of FD_SETSIZE 2156 * value. When polling by select() is used, MHD rejects sockets with numbers 2157 * equal or higher than FD_SETSIZE. If this option is used, MHD treats this 2158 * value as a limitation for socket number instead of FD_SETSIZE value which 2159 * was used for building MHD. 2160 * When external polling is used with #MHD_get_fdset2() (or #MHD_get_fdset() 2161 * macro) and #MHD_run_from_select() interfaces, it is recommended to always 2162 * use this option. 2163 * It is safe to use this option on platforms with fixed FD_SETSIZE (like 2164 * GNU/Linux) if system value of FD_SETSIZE is used as the argument. 2165 * Can be used only for daemons without #MHD_USE_INTERNAL_POLLING_THREAD, i.e. 2166 * only when external sockets polling is used. 2167 * On W32 it is silently ignored, as W32 does not limit the socket number in 2168 * fd_sets. 2169 * This option should be followed by a positive 'int' argument. 2170 * @note Available since #MHD_VERSION 0x00097705 2171 */ 2172 MHD_OPTION_APP_FD_SETSIZE = 39, 2173 2174 /** 2175 * Bind daemon to the supplied 'struct sockaddr'. This option should 2176 * be followed by two parameters: 'socklen_t' the size of memory at the next 2177 * pointer and the pointer 'const struct sockaddr *'. 2178 * Note: the order of the arguments is not the same as for system bind() and 2179 * other network functions. 2180 * If #MHD_USE_IPv6 is specified, the 'struct sockaddr*' should 2181 * point to a 'struct sockaddr_in6'. 2182 * The socket domain (protocol family) is detected from provided 2183 * 'struct sockaddr'. IP, IPv6 and UNIX sockets are supported (if supported 2184 * by the platform). Other types may work occasionally. 2185 * Silently ignored if followed by zero size and NULL pointer. 2186 * @note Available since #MHD_VERSION 0x00097706 2187 */ 2188 MHD_OPTION_SOCK_ADDR_LEN = 40 2189 , 2190 /** 2191 * Default nonce timeout value used for Digest Auth. 2192 * This option should be followed by an 'unsigned int' argument. 2193 * Silently ignored if followed by zero value. 2194 * @see #MHD_digest_auth_check3(), MHD_digest_auth_check_digest3() 2195 * @note Available since #MHD_VERSION 0x00097709 2196 */ 2197 MHD_OPTION_DIGEST_AUTH_DEFAULT_NONCE_TIMEOUT = 41 2198 , 2199 /** 2200 * Default maximum nc (nonce count) value used for Digest Auth. 2201 * This option should be followed by an 'uint32_t' argument. 2202 * Silently ignored if followed by zero value. 2203 * @see #MHD_digest_auth_check3(), MHD_digest_auth_check_digest3() 2204 * @note Available since #MHD_VERSION 0x00097709 2205 */ 2206 MHD_OPTION_DIGEST_AUTH_DEFAULT_MAX_NC = 42 2207 , 2208 /** 2209 * Default maximum nc (nonce count) value used for Digest Auth. 2210 * This option must be followed by an 'int' argument. 2211 * If followed by '0' (default) then: 2212 * + requests are rejected if request URI has binary zero (the result 2213 * of %00 decoding) in the path part of the URI. 2214 * If followed by '1' then: 2215 * + binary zero is allowed in request URI path; 2216 * + #MHD_AccessHandlerCallback called with NULL in @a url parameter when 2217 * request URI path has binary zero, the full @a url is available only 2218 * via #MHD_get_connection_URI_path_n() 2219 * If followed by '2' (unsafe!) then: 2220 * + binary zero is allowed in request URI path; 2221 * + #MHD_AccessHandlerCallback called with truncated (unsafe!) @a url 2222 * parameter when request URI path has binary zero. 2223 * @see #MHD_get_connection_URI_path_n() 2224 * @note Available since #MHD_VERSION 0x01000201 2225 */ 2226 MHD_OPTION_ALLOW_BIN_ZERO_IN_URI_PATH = 43 2227 2228 } _MHD_FIXED_ENUM; 2229 2230 2231 /** 2232 * Bitfield for the #MHD_OPTION_SERVER_INSANITY specifying 2233 * which santiy checks should be disabled. 2234 */ 2235 enum MHD_DisableSanityCheck 2236 { 2237 /** 2238 * All sanity checks are enabled. 2239 */ 2240 MHD_DSC_SANE = 0 2241 2242 } _MHD_FIXED_FLAGS_ENUM; 2243 2244 2245 /** 2246 * Entry in an #MHD_OPTION_ARRAY. 2247 */ 2248 struct MHD_OptionItem 2249 { 2250 /** 2251 * Which option is being given. Use #MHD_OPTION_END 2252 * to terminate the array. 2253 */ 2254 enum MHD_OPTION option; 2255 2256 /** 2257 * Option value (for integer arguments, and for options requiring 2258 * two pointer arguments); should be 0 for options that take no 2259 * arguments or only a single pointer argument. 2260 */ 2261 intptr_t value; 2262 2263 /** 2264 * Pointer option value (use NULL for options taking no arguments 2265 * or only an integer option). 2266 */ 2267 void *ptr_value; 2268 2269 }; 2270 2271 2272 /** 2273 * The `enum MHD_ValueKind` specifies the source of 2274 * the key-value pairs in the HTTP protocol. 2275 */ 2276 enum MHD_ValueKind 2277 { 2278 2279 /** 2280 * Response header 2281 * @deprecated 2282 */ 2283 MHD_RESPONSE_HEADER_KIND = 0, 2284 #define MHD_RESPONSE_HEADER_KIND \ 2285 _MHD_DEPR_IN_MACRO ( \ 2286 "Value MHD_RESPONSE_HEADER_KIND is deprecated and not used") \ 2287 MHD_RESPONSE_HEADER_KIND 2288 2289 /** 2290 * HTTP header (request/response). 2291 */ 2292 MHD_HEADER_KIND = 1, 2293 2294 /** 2295 * Cookies. Note that the original HTTP header containing 2296 * the cookie(s) will still be available and intact. 2297 */ 2298 MHD_COOKIE_KIND = 2, 2299 2300 /** 2301 * POST data. This is available only if a content encoding 2302 * supported by MHD is used (currently only URL encoding), 2303 * and only if the posted content fits within the available 2304 * memory pool. Note that in that case, the upload data 2305 * given to the #MHD_AccessHandlerCallback will be 2306 * empty (since it has already been processed). 2307 */ 2308 MHD_POSTDATA_KIND = 4, 2309 2310 /** 2311 * GET (URI) arguments. 2312 */ 2313 MHD_GET_ARGUMENT_KIND = 8, 2314 2315 /** 2316 * HTTP footer (only for HTTP 1.1 chunked encodings). 2317 */ 2318 MHD_FOOTER_KIND = 16 2319 } _MHD_FIXED_ENUM; 2320 2321 2322 /** 2323 * The `enum MHD_RequestTerminationCode` specifies reasons 2324 * why a request has been terminated (or completed). 2325 * @ingroup request 2326 */ 2327 enum MHD_RequestTerminationCode 2328 { 2329 2330 /** 2331 * We finished sending the response. 2332 * @ingroup request 2333 */ 2334 MHD_REQUEST_TERMINATED_COMPLETED_OK = 0, 2335 2336 /** 2337 * Error handling the connection (resources 2338 * exhausted, application error accepting request, 2339 * decrypt error (for HTTPS), connection died when 2340 * sending the response etc.) 2341 * @ingroup request 2342 */ 2343 MHD_REQUEST_TERMINATED_WITH_ERROR = 1, 2344 2345 /** 2346 * No activity on the connection for the number 2347 * of seconds specified using 2348 * #MHD_OPTION_CONNECTION_TIMEOUT. 2349 * @ingroup request 2350 */ 2351 MHD_REQUEST_TERMINATED_TIMEOUT_REACHED = 2, 2352 2353 /** 2354 * We had to close the session since MHD was being 2355 * shut down. 2356 * @ingroup request 2357 */ 2358 MHD_REQUEST_TERMINATED_DAEMON_SHUTDOWN = 3, 2359 2360 /** 2361 * We tried to read additional data, but the connection became broken or 2362 * the other side hard closed the connection. 2363 * This error is similar to #MHD_REQUEST_TERMINATED_WITH_ERROR, but 2364 * specific to the case where the connection died before request completely 2365 * received. 2366 * @ingroup request 2367 */ 2368 MHD_REQUEST_TERMINATED_READ_ERROR = 4, 2369 2370 /** 2371 * The client terminated the connection by closing the socket 2372 * for writing (TCP half-closed) while still sending request. 2373 * @ingroup request 2374 */ 2375 MHD_REQUEST_TERMINATED_CLIENT_ABORT = 5 2376 2377 } _MHD_FIXED_ENUM; 2378 2379 2380 /** 2381 * The `enum MHD_ConnectionNotificationCode` specifies types 2382 * of connection notifications. 2383 * @ingroup request 2384 */ 2385 enum MHD_ConnectionNotificationCode 2386 { 2387 2388 /** 2389 * A new connection has been started. 2390 * @ingroup request 2391 */ 2392 MHD_CONNECTION_NOTIFY_STARTED = 0, 2393 2394 /** 2395 * A connection is closed. 2396 * @ingroup request 2397 */ 2398 MHD_CONNECTION_NOTIFY_CLOSED = 1 2399 2400 } _MHD_FIXED_ENUM; 2401 2402 2403 /** 2404 * Information about a connection. 2405 */ 2406 union MHD_ConnectionInfo 2407 { 2408 2409 /** 2410 * Cipher algorithm used, of type "enum gnutls_cipher_algorithm". 2411 */ 2412 int /* enum gnutls_cipher_algorithm */ cipher_algorithm; 2413 2414 /** 2415 * Protocol used, of type "enum gnutls_protocol". 2416 */ 2417 int /* enum gnutls_protocol */ protocol; 2418 2419 /** 2420 * The suspended status of a connection. 2421 */ 2422 int /* MHD_YES or MHD_NO */ suspended; 2423 2424 /** 2425 * Amount of second that connection could spend in idle state 2426 * before automatically disconnected. 2427 * Zero for no timeout (unlimited idle time). 2428 */ 2429 unsigned int connection_timeout; 2430 2431 /** 2432 * HTTP status queued with the response, for #MHD_CONNECTION_INFO_HTTP_STATUS. 2433 */ 2434 unsigned int http_status; 2435 2436 /** 2437 * Connect socket 2438 */ 2439 MHD_socket connect_fd; 2440 2441 /** 2442 * Size of the client's HTTP header. 2443 * It includes the request line, all request headers, the header section 2444 * terminating empty line, with all CRLF (or LF) characters. 2445 */ 2446 size_t header_size; 2447 2448 /** 2449 * GNUtls session handle, of type "gnutls_session_t". 2450 */ 2451 void * /* gnutls_session_t */ tls_session; 2452 2453 /** 2454 * GNUtls client certificate handle, of type "gnutls_x509_crt_t". 2455 */ 2456 void * /* gnutls_x509_crt_t */ client_cert; 2457 2458 /** 2459 * Address information for the client. 2460 */ 2461 struct sockaddr *client_addr; 2462 2463 /** 2464 * Which daemon manages this connection (useful in case there are many 2465 * daemons running). 2466 */ 2467 struct MHD_Daemon *daemon; 2468 2469 /** 2470 * Socket-specific client context. Points to the same address as 2471 * the "socket_context" of the #MHD_NotifyConnectionCallback. 2472 */ 2473 void *socket_context; 2474 }; 2475 2476 2477 /** 2478 * I/O vector type. Provided for use with #MHD_create_response_from_iovec(). 2479 * @note Available since #MHD_VERSION 0x00097204 2480 */ 2481 struct MHD_IoVec 2482 { 2483 /** 2484 * The pointer to the memory region for I/O. 2485 */ 2486 const void *iov_base; 2487 2488 /** 2489 * The size in bytes of the memory region for I/O. 2490 */ 2491 size_t iov_len; 2492 }; 2493 2494 2495 /** 2496 * Values of this enum are used to specify what 2497 * information about a connection is desired. 2498 * @ingroup request 2499 */ 2500 enum MHD_ConnectionInfoType 2501 { 2502 /** 2503 * What cipher algorithm is being used. 2504 * Takes no extra arguments. 2505 * @ingroup request 2506 */ 2507 MHD_CONNECTION_INFO_CIPHER_ALGO, 2508 2509 /** 2510 * 2511 * Takes no extra arguments. 2512 * @ingroup request 2513 */ 2514 MHD_CONNECTION_INFO_PROTOCOL, 2515 2516 /** 2517 * Obtain IP address of the client. Takes no extra arguments. 2518 * Returns essentially a `struct sockaddr **` (since the API returns 2519 * a `union MHD_ConnectionInfo *` and that union contains a `struct 2520 * sockaddr *`). 2521 * @ingroup request 2522 */ 2523 MHD_CONNECTION_INFO_CLIENT_ADDRESS, 2524 2525 /** 2526 * Get the gnuTLS session handle. 2527 * @ingroup request 2528 */ 2529 MHD_CONNECTION_INFO_GNUTLS_SESSION, 2530 2531 /** 2532 * Get the gnuTLS client certificate handle. Dysfunctional (never 2533 * implemented, deprecated). Use #MHD_CONNECTION_INFO_GNUTLS_SESSION 2534 * to get the `gnutls_session_t` and then call 2535 * gnutls_certificate_get_peers(). 2536 */ 2537 MHD_CONNECTION_INFO_GNUTLS_CLIENT_CERT, 2538 2539 /** 2540 * Get the `struct MHD_Daemon *` responsible for managing this connection. 2541 * @ingroup request 2542 */ 2543 MHD_CONNECTION_INFO_DAEMON, 2544 2545 /** 2546 * Request the file descriptor for the connection socket. 2547 * MHD sockets are always in non-blocking mode. 2548 * No extra arguments should be passed. 2549 * @ingroup request 2550 */ 2551 MHD_CONNECTION_INFO_CONNECTION_FD, 2552 2553 /** 2554 * Returns the client-specific pointer to a `void *` that was (possibly) 2555 * set during a #MHD_NotifyConnectionCallback when the socket was 2556 * first accepted. 2557 * Note that this is NOT the same as the "req_cls" argument of 2558 * the #MHD_AccessHandlerCallback. The "req_cls" is fresh for each 2559 * HTTP request, while the "socket_context" is fresh for each socket. 2560 */ 2561 MHD_CONNECTION_INFO_SOCKET_CONTEXT, 2562 2563 /** 2564 * Check whether the connection is suspended. 2565 * @ingroup request 2566 */ 2567 MHD_CONNECTION_INFO_CONNECTION_SUSPENDED, 2568 2569 /** 2570 * Get connection timeout 2571 * @ingroup request 2572 */ 2573 MHD_CONNECTION_INFO_CONNECTION_TIMEOUT, 2574 2575 /** 2576 * Return length of the client's HTTP request header. 2577 * @ingroup request 2578 */ 2579 MHD_CONNECTION_INFO_REQUEST_HEADER_SIZE, 2580 2581 /** 2582 * Return HTTP status queued with the response. NULL 2583 * if no HTTP response has been queued yet. 2584 */ 2585 MHD_CONNECTION_INFO_HTTP_STATUS 2586 2587 } _MHD_FIXED_ENUM; 2588 2589 2590 /** 2591 * Values of this enum are used to specify what 2592 * information about a daemon is desired. 2593 */ 2594 enum MHD_DaemonInfoType 2595 { 2596 /** 2597 * No longer supported (will return NULL). 2598 */ 2599 MHD_DAEMON_INFO_KEY_SIZE, 2600 2601 /** 2602 * No longer supported (will return NULL). 2603 */ 2604 MHD_DAEMON_INFO_MAC_KEY_SIZE, 2605 2606 /** 2607 * Request the file descriptor for the listening socket. 2608 * No extra arguments should be passed. 2609 */ 2610 MHD_DAEMON_INFO_LISTEN_FD, 2611 2612 /** 2613 * Request the file descriptor for the "external" sockets polling 2614 * when 'epoll' mode is used. 2615 * No extra arguments should be passed. 2616 * 2617 * Waiting on epoll FD must not block longer than value 2618 * returned by #MHD_get_timeout() otherwise connections 2619 * will "hung" with unprocessed data in network buffers 2620 * and timed-out connections will not be closed. 2621 * 2622 * @sa #MHD_get_timeout(), #MHD_run() 2623 */ 2624 MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY, 2625 MHD_DAEMON_INFO_EPOLL_FD = MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY, 2626 2627 /** 2628 * Request the number of current connections handled by the daemon. 2629 * No extra arguments should be passed. 2630 * Note: when using MHD in "external" polling mode, this type of request 2631 * could be used only when #MHD_run()/#MHD_run_from_select is not 2632 * working in other thread at the same time. 2633 */ 2634 MHD_DAEMON_INFO_CURRENT_CONNECTIONS, 2635 2636 /** 2637 * Request the daemon flags. 2638 * No extra arguments should be passed. 2639 * Note: flags may differ from original 'flags' specified for 2640 * daemon, especially if #MHD_USE_AUTO was set. 2641 */ 2642 MHD_DAEMON_INFO_FLAGS, 2643 2644 /** 2645 * Request the port number of daemon's listen socket. 2646 * No extra arguments should be passed. 2647 * Note: if port '0' was specified for #MHD_start_daemon(), returned 2648 * value will be real port number. 2649 */ 2650 MHD_DAEMON_INFO_BIND_PORT 2651 } _MHD_FIXED_ENUM; 2652 2653 2654 /** 2655 * Callback for serious error condition. The default action is to print 2656 * an error message and `abort()`. 2657 * 2658 * @param cls user specified value 2659 * @param file where the error occurred, may be NULL if MHD was built without 2660 * messages support 2661 * @param line where the error occurred 2662 * @param reason error detail, may be NULL 2663 * @ingroup logging 2664 */ 2665 typedef void 2666 (*MHD_PanicCallback) (void *cls, 2667 const char *file, 2668 unsigned int line, 2669 const char *reason); 2670 2671 /** 2672 * Allow or deny a client to connect. 2673 * 2674 * @param cls closure 2675 * @param addr address information from the client 2676 * @param addrlen length of @a addr 2677 * @return #MHD_YES if connection is allowed, #MHD_NO if not 2678 */ 2679 typedef enum MHD_Result 2680 (*MHD_AcceptPolicyCallback)(void *cls, 2681 const struct sockaddr *addr, 2682 socklen_t addrlen); 2683 2684 2685 /** 2686 * A client has requested the given @a url using the given @a method 2687 * (#MHD_HTTP_METHOD_GET, #MHD_HTTP_METHOD_PUT, #MHD_HTTP_METHOD_DELETE, 2688 * #MHD_HTTP_METHOD_POST, etc). 2689 * 2690 * The callback must call MHD function MHD_queue_response() to provide content 2691 * to give back to the client and return an HTTP status code (i.e. 2692 * #MHD_HTTP_OK, #MHD_HTTP_NOT_FOUND, etc.). The response can be created 2693 * in this callback or prepared in advance. 2694 * Alternatively, callback may call MHD_suspend_connection() to temporarily 2695 * suspend data processing for this connection. 2696 * 2697 * As soon as response is provided this callback will not be called anymore 2698 * for the current request. 2699 * 2700 * For each HTTP request this callback is called several times: 2701 * * after request headers are fully received and decoded, 2702 * * for each received part of request body (optional, if request has body), 2703 * * when request is fully received. 2704 * 2705 * If response is provided before request is fully received, the rest 2706 * of the request is discarded and connection is automatically closed 2707 * after sending response. 2708 * 2709 * If the request is fully received, but response hasn't been provided and 2710 * connection is not suspended, the callback can be called again immediately. 2711 * 2712 * The response cannot be queued when this callback is called to process 2713 * the client upload data (when @a upload_data is not NULL). 2714 * 2715 * @param cls argument given together with the function 2716 * pointer when the handler was registered with MHD 2717 * @param connection the connection handle 2718 * @param url the requested url, can be truncated or can be NULL, depending 2719 * on #MHD_OPTION_ALLOW_BIN_ZERO_IN_URI_PATH option, 2720 * see #MHD_get_connection_URI_path_n() 2721 * @param method the HTTP method used (#MHD_HTTP_METHOD_GET, 2722 * #MHD_HTTP_METHOD_PUT, etc.) 2723 * @param version the HTTP version string (i.e. 2724 * #MHD_HTTP_VERSION_1_1) 2725 * @param upload_data the data being uploaded (excluding HEADERS, 2726 * for a POST that fits into memory and that is encoded 2727 * with a supported encoding, the POST data will NOT be 2728 * given in upload_data and is instead available as 2729 * part of #MHD_get_connection_values; very large POST 2730 * data *will* be made available incrementally in 2731 * @a upload_data) 2732 * @param[in,out] upload_data_size set initially to the size of the 2733 * @a upload_data provided; the method must update this 2734 * value to the number of bytes NOT processed; 2735 * @param[in,out] req_cls pointer that the callback can set to some 2736 * address and that will be preserved by MHD for future 2737 * calls for this request; since the access handler may 2738 * be called many times (i.e., for a PUT/POST operation 2739 * with plenty of upload data) this allows the application 2740 * to easily associate some request-specific state. 2741 * If necessary, this state can be cleaned up in the 2742 * global #MHD_RequestCompletedCallback (which 2743 * can be set with the #MHD_OPTION_NOTIFY_COMPLETED). 2744 * Initially, `*req_cls` will be NULL. 2745 * @return #MHD_YES if the connection was handled successfully, 2746 * #MHD_NO if the socket must be closed due to a serious 2747 * error while handling the request 2748 * 2749 * @sa #MHD_queue_response(), #MHD_get_connection_URI_path_n() 2750 */ 2751 typedef enum MHD_Result 2752 (*MHD_AccessHandlerCallback)(void *cls, 2753 struct MHD_Connection *connection, 2754 const char *url, 2755 const char *method, 2756 const char *version, 2757 const char *upload_data, 2758 size_t *upload_data_size, 2759 void **req_cls); 2760 2761 2762 /** 2763 * Signature of the callback used by MHD to notify the 2764 * application about completed requests. 2765 * 2766 * @param cls client-defined closure 2767 * @param connection connection handle 2768 * @param req_cls value as set by the last call to 2769 * the #MHD_AccessHandlerCallback 2770 * @param toe reason for request termination 2771 * @see #MHD_OPTION_NOTIFY_COMPLETED 2772 * @ingroup request 2773 */ 2774 typedef void 2775 (*MHD_RequestCompletedCallback) (void *cls, 2776 struct MHD_Connection *connection, 2777 void **req_cls, 2778 enum MHD_RequestTerminationCode toe); 2779 2780 2781 /** 2782 * Signature of the callback used by MHD to notify the 2783 * application about started/stopped connections 2784 * 2785 * @param cls client-defined closure 2786 * @param connection connection handle 2787 * @param socket_context socket-specific pointer where the 2788 * client can associate some state specific 2789 * to the TCP connection; note that this is 2790 * different from the "req_cls" which is per 2791 * HTTP request. The client can initialize 2792 * during #MHD_CONNECTION_NOTIFY_STARTED and 2793 * cleanup during #MHD_CONNECTION_NOTIFY_CLOSED 2794 * and access in the meantime using 2795 * #MHD_CONNECTION_INFO_SOCKET_CONTEXT. 2796 * @param toe reason for connection notification 2797 * @see #MHD_OPTION_NOTIFY_CONNECTION 2798 * @ingroup request 2799 */ 2800 typedef void 2801 (*MHD_NotifyConnectionCallback) (void *cls, 2802 struct MHD_Connection *connection, 2803 void **socket_context, 2804 enum MHD_ConnectionNotificationCode toe); 2805 2806 2807 /** 2808 * Iterator over key-value pairs. This iterator 2809 * can be used to iterate over all of the cookies, 2810 * headers, or POST-data fields of a request, and 2811 * also to iterate over the headers that have been 2812 * added to a response. 2813 * 2814 * @param cls closure 2815 * @param kind kind of the header we are looking at 2816 * @param key key for the value, can be an empty string 2817 * @param value corresponding value, can be NULL 2818 * @return #MHD_YES to continue iterating, 2819 * #MHD_NO to abort the iteration 2820 * @ingroup request 2821 */ 2822 typedef enum MHD_Result 2823 (*MHD_KeyValueIterator)(void *cls, 2824 enum MHD_ValueKind kind, 2825 const char *key, 2826 const char *value); 2827 2828 2829 /** 2830 * Iterator over key-value pairs with size parameters. 2831 * This iterator can be used to iterate over all of 2832 * the cookies, headers, or POST-data fields of a 2833 * request, and also to iterate over the headers that 2834 * have been added to a response. 2835 * @note Available since #MHD_VERSION 0x00096303 2836 * 2837 * @param cls closure 2838 * @param kind kind of the header we are looking at 2839 * @param key key for the value, can be an empty string 2840 * @param value corresponding value, can be NULL 2841 * @param value_size number of bytes in @a value; 2842 * for C-strings, the length excludes the 0-terminator 2843 * @return #MHD_YES to continue iterating, 2844 * #MHD_NO to abort the iteration 2845 * @ingroup request 2846 */ 2847 typedef enum MHD_Result 2848 (*MHD_KeyValueIteratorN)(void *cls, 2849 enum MHD_ValueKind kind, 2850 const char *key, 2851 size_t key_size, 2852 const char *value, 2853 size_t value_size); 2854 2855 2856 /** 2857 * Callback used by libmicrohttpd in order to obtain content. 2858 * 2859 * The callback is to copy at most @a max bytes of content into @a buf. 2860 * The total number of bytes that has been placed into @a buf should be 2861 * returned. 2862 * 2863 * Note that returning zero will cause libmicrohttpd to try again. 2864 * Thus, returning zero should only be used in conjunction 2865 * with MHD_suspend_connection() to avoid busy waiting. 2866 * 2867 * @param cls extra argument to the callback 2868 * @param pos position in the datastream to access; 2869 * note that if a `struct MHD_Response` object is re-used, 2870 * it is possible for the same content reader to 2871 * be queried multiple times for the same data; 2872 * however, if a `struct MHD_Response` is not re-used, 2873 * libmicrohttpd guarantees that "pos" will be 2874 * the sum of all non-negative return values 2875 * obtained from the content reader so far. 2876 * @param buf where to copy the data 2877 * @param max maximum number of bytes to copy to @a buf (size of @a buf) 2878 * @return number of bytes written to @a buf; 2879 * 0 is legal unless MHD is started in "internal" sockets polling mode 2880 * (since this would cause busy-waiting); 0 in "external" sockets 2881 * polling mode will cause this function to be called again once 2882 * any MHD_run*() function is called; 2883 * #MHD_CONTENT_READER_END_OF_STREAM (-1) for the regular 2884 * end of transmission (with chunked encoding, MHD will then 2885 * terminate the chunk and send any HTTP footers that might be 2886 * present; without chunked encoding and given an unknown 2887 * response size, MHD will simply close the connection; note 2888 * that while returning #MHD_CONTENT_READER_END_OF_STREAM is not technically 2889 * legal if a response size was specified, MHD accepts this 2890 * and treats it just as #MHD_CONTENT_READER_END_WITH_ERROR; 2891 * #MHD_CONTENT_READER_END_WITH_ERROR (-2) to indicate a server 2892 * error generating the response; this will cause MHD to simply 2893 * close the connection immediately. If a response size was 2894 * given or if chunked encoding is in use, this will indicate 2895 * an error to the client. Note, however, that if the client 2896 * does not know a response size and chunked encoding is not in 2897 * use, then clients will not be able to tell the difference between 2898 * #MHD_CONTENT_READER_END_WITH_ERROR and #MHD_CONTENT_READER_END_OF_STREAM. 2899 * This is not a limitation of MHD but rather of the HTTP protocol. 2900 */ 2901 typedef ssize_t 2902 (*MHD_ContentReaderCallback) (void *cls, 2903 uint64_t pos, 2904 char *buf, 2905 size_t max); 2906 2907 2908 /** 2909 * This method is called by libmicrohttpd if we 2910 * are done with a content reader. It should 2911 * be used to free resources associated with the 2912 * content reader. 2913 * 2914 * @param cls closure 2915 * @ingroup response 2916 */ 2917 typedef void 2918 (*MHD_ContentReaderFreeCallback) (void *cls); 2919 2920 2921 /** 2922 * Iterator over key-value pairs where the value 2923 * may be made available in increments and/or may 2924 * not be zero-terminated. Used for processing 2925 * POST data. 2926 * 2927 * @param cls user-specified closure 2928 * @param kind type of the value, always #MHD_POSTDATA_KIND when called from MHD 2929 * @param key 0-terminated key for the value, NULL if not known. This value 2930 * is never NULL for url-encoded POST data. 2931 * @param filename name of the uploaded file, NULL if not known 2932 * @param content_type mime-type of the data, NULL if not known 2933 * @param transfer_encoding encoding of the data, NULL if not known 2934 * @param data pointer to @a size bytes of data at the 2935 * specified offset 2936 * @param off offset of data in the overall value 2937 * @param size number of bytes in @a data available 2938 * @return #MHD_YES to continue iterating, 2939 * #MHD_NO to abort the iteration 2940 */ 2941 typedef enum MHD_Result 2942 (*MHD_PostDataIterator)(void *cls, 2943 enum MHD_ValueKind kind, 2944 const char *key, 2945 const char *filename, 2946 const char *content_type, 2947 const char *transfer_encoding, 2948 const char *data, 2949 uint64_t off, 2950 size_t size); 2951 2952 /* **************** Daemon handling functions ***************** */ 2953 2954 /** 2955 * Start a webserver on the given port. 2956 * 2957 * @param flags combination of `enum MHD_FLAG` values 2958 * @param port port to bind to (in host byte order), 2959 * use '0' to bind to random free port, 2960 * ignored if MHD_OPTION_SOCK_ADDR or 2961 * MHD_OPTION_LISTEN_SOCKET is provided 2962 * or MHD_USE_NO_LISTEN_SOCKET is specified 2963 * @param apc callback to call to check which clients 2964 * will be allowed to connect; you can pass NULL 2965 * in which case connections from any IP will be 2966 * accepted 2967 * @param apc_cls extra argument to apc 2968 * @param dh handler called for all requests (repeatedly) 2969 * @param dh_cls extra argument to @a dh 2970 * @param ap list of options (type-value pairs, 2971 * terminated with #MHD_OPTION_END). 2972 * @return NULL on error, handle to daemon on success 2973 * @ingroup event 2974 */ 2975 _MHD_EXTERN struct MHD_Daemon * 2976 MHD_start_daemon_va (unsigned int flags, 2977 uint16_t port, 2978 MHD_AcceptPolicyCallback apc, void *apc_cls, 2979 MHD_AccessHandlerCallback dh, void *dh_cls, 2980 va_list ap); 2981 2982 2983 /** 2984 * Start a webserver on the given port. Variadic version of 2985 * #MHD_start_daemon_va. 2986 * 2987 * @param flags combination of `enum MHD_FLAG` values 2988 * @param port port to bind to (in host byte order), 2989 * use '0' to bind to random free port, 2990 * ignored if MHD_OPTION_SOCK_ADDR or 2991 * MHD_OPTION_LISTEN_SOCKET is provided 2992 * or MHD_USE_NO_LISTEN_SOCKET is specified 2993 * @param apc callback to call to check which clients 2994 * will be allowed to connect; you can pass NULL 2995 * in which case connections from any IP will be 2996 * accepted 2997 * @param apc_cls extra argument to apc 2998 * @param dh handler called for all requests (repeatedly) 2999 * @param dh_cls extra argument to @a dh 3000 * @return NULL on error, handle to daemon on success 3001 * @ingroup event 3002 */ 3003 _MHD_EXTERN struct MHD_Daemon * 3004 MHD_start_daemon (unsigned int flags, 3005 uint16_t port, 3006 MHD_AcceptPolicyCallback apc, void *apc_cls, 3007 MHD_AccessHandlerCallback dh, void *dh_cls, 3008 ...); 3009 3010 3011 /** 3012 * Stop accepting connections from the listening socket. Allows 3013 * clients to continue processing, but stops accepting new 3014 * connections. Note that the caller is responsible for closing the 3015 * returned socket; however, if MHD is run using threads (anything but 3016 * "external" sockets polling mode), it must not be closed until AFTER 3017 * #MHD_stop_daemon has been called (as it is theoretically possible 3018 * that an existing thread is still using it). 3019 * 3020 * Note that some thread modes require the caller to have passed 3021 * #MHD_USE_ITC when using this API. If this daemon is 3022 * in one of those modes and this option was not given to 3023 * #MHD_start_daemon, this function will return #MHD_INVALID_SOCKET. 3024 * 3025 * @param daemon daemon to stop accepting new connections for 3026 * @return old listen socket on success, #MHD_INVALID_SOCKET if 3027 * the daemon was already not listening anymore 3028 * @ingroup specialized 3029 */ 3030 _MHD_EXTERN MHD_socket 3031 MHD_quiesce_daemon (struct MHD_Daemon *daemon); 3032 3033 3034 /** 3035 * Shutdown an HTTP daemon. 3036 * 3037 * @param daemon daemon to stop 3038 * @ingroup event 3039 */ 3040 _MHD_EXTERN void 3041 MHD_stop_daemon (struct MHD_Daemon *daemon); 3042 3043 3044 /** 3045 * Add another client connection to the set of connections managed by 3046 * MHD. This API is usually not needed (since MHD will accept inbound 3047 * connections on the server socket). Use this API in special cases, 3048 * for example if your HTTP server is behind NAT and needs to connect 3049 * out to the HTTP client, or if you are building a proxy. 3050 * 3051 * If you use this API in conjunction with an "internal" socket polling, 3052 * you must set the option #MHD_USE_ITC to ensure that the freshly added 3053 * connection is immediately processed by MHD. 3054 * 3055 * The given client socket will be managed (and closed!) by MHD after 3056 * this call and must no longer be used directly by the application 3057 * afterwards. 3058 * 3059 * @param daemon daemon that manages the connection 3060 * @param client_socket socket to manage (MHD will expect 3061 * to receive an HTTP request from this socket next). 3062 * @param addr IP address of the client 3063 * @param addrlen number of bytes in @a addr 3064 * @return #MHD_YES on success, #MHD_NO if this daemon could 3065 * not handle the connection (i.e. `malloc()` failed, etc). 3066 * The socket will be closed in any case; `errno` is 3067 * set to indicate further details about the error. 3068 * @ingroup specialized 3069 */ 3070 _MHD_EXTERN enum MHD_Result 3071 MHD_add_connection (struct MHD_Daemon *daemon, 3072 MHD_socket client_socket, 3073 const struct sockaddr *addr, 3074 socklen_t addrlen); 3075 3076 3077 /** 3078 * Obtain the `select()` sets for this daemon. 3079 * Daemon's FDs will be added to fd_sets. To get only 3080 * daemon FDs in fd_sets, call FD_ZERO for each fd_set 3081 * before calling this function. FD_SETSIZE is assumed 3082 * to be platform's default. 3083 * 3084 * This function should be called only when MHD is configured to 3085 * use "external" sockets polling with 'select()' or with 'epoll'. 3086 * In the latter case, it will only add the single 'epoll' file 3087 * descriptor used by MHD to the sets. 3088 * It's necessary to use #MHD_get_timeout() to get maximum timeout 3089 * value for `select()`. Usage of `select()` with indefinite timeout 3090 * (or timeout larger than returned by #MHD_get_timeout()) will 3091 * violate MHD API and may results in pending unprocessed data. 3092 * 3093 * This function must be called only for daemon started 3094 * without #MHD_USE_INTERNAL_POLLING_THREAD flag. 3095 * 3096 * @param daemon daemon to get sets from 3097 * @param read_fd_set read set 3098 * @param write_fd_set write set 3099 * @param except_fd_set except set 3100 * @param max_fd increased to largest FD added (if larger 3101 * than existing value); can be NULL 3102 * @return #MHD_YES on success, #MHD_NO if this 3103 * daemon was not started with the right 3104 * options for this call or any FD didn't 3105 * fit fd_set. 3106 * @ingroup event 3107 */ 3108 _MHD_EXTERN enum MHD_Result 3109 MHD_get_fdset (struct MHD_Daemon *daemon, 3110 fd_set *read_fd_set, 3111 fd_set *write_fd_set, 3112 fd_set *except_fd_set, 3113 MHD_socket *max_fd); 3114 3115 3116 /** 3117 * Obtain the `select()` sets for this daemon. 3118 * Daemon's FDs will be added to fd_sets. To get only 3119 * daemon FDs in fd_sets, call FD_ZERO for each fd_set 3120 * before calling this function. 3121 * 3122 * Passing custom FD_SETSIZE as @a fd_setsize allow usage of 3123 * larger/smaller than platform's default fd_sets. 3124 * 3125 * This function should be called only when MHD is configured to 3126 * use "external" sockets polling with 'select()' or with 'epoll'. 3127 * In the latter case, it will only add the single 'epoll' file 3128 * descriptor used by MHD to the sets. 3129 * It's necessary to use #MHD_get_timeout() to get maximum timeout 3130 * value for `select()`. Usage of `select()` with indefinite timeout 3131 * (or timeout larger than returned by #MHD_get_timeout()) will 3132 * violate MHD API and may results in pending unprocessed data. 3133 * 3134 * This function must be called only for daemon started 3135 * without #MHD_USE_INTERNAL_POLLING_THREAD flag. 3136 * 3137 * @param daemon daemon to get sets from 3138 * @param read_fd_set read set 3139 * @param write_fd_set write set 3140 * @param except_fd_set except set 3141 * @param max_fd increased to largest FD added (if larger 3142 * than existing value); can be NULL 3143 * @param fd_setsize value of FD_SETSIZE 3144 * @return #MHD_YES on success, #MHD_NO if this 3145 * daemon was not started with the right 3146 * options for this call or any FD didn't 3147 * fit fd_set. 3148 * @ingroup event 3149 */ 3150 _MHD_EXTERN enum MHD_Result 3151 MHD_get_fdset2 (struct MHD_Daemon *daemon, 3152 fd_set *read_fd_set, 3153 fd_set *write_fd_set, 3154 fd_set *except_fd_set, 3155 MHD_socket *max_fd, 3156 unsigned int fd_setsize); 3157 3158 3159 /** 3160 * Obtain the `select()` sets for this daemon. 3161 * Daemon's FDs will be added to fd_sets. To get only 3162 * daemon FDs in fd_sets, call FD_ZERO for each fd_set 3163 * before calling this function. Size of fd_set is 3164 * determined by current value of FD_SETSIZE. 3165 * 3166 * This function should be called only when MHD is configured to 3167 * use "external" sockets polling with 'select()' or with 'epoll'. 3168 * In the latter case, it will only add the single 'epoll' file 3169 * descriptor used by MHD to the sets. 3170 * It's necessary to use #MHD_get_timeout() to get maximum timeout 3171 * value for `select()`. Usage of `select()` with indefinite timeout 3172 * (or timeout larger than returned by #MHD_get_timeout()) will 3173 * violate MHD API and may results in pending unprocessed data. 3174 * 3175 * This function must be called only for daemon started 3176 * without #MHD_USE_INTERNAL_POLLING_THREAD flag. 3177 * 3178 * @param daemon daemon to get sets from 3179 * @param read_fd_set read set 3180 * @param write_fd_set write set 3181 * @param except_fd_set except set 3182 * @param max_fd increased to largest FD added (if larger 3183 * than existing value); can be NULL 3184 * @return #MHD_YES on success, #MHD_NO if this 3185 * daemon was not started with the right 3186 * options for this call or any FD didn't 3187 * fit fd_set. 3188 * @ingroup event 3189 */ 3190 #define MHD_get_fdset(daemon,read_fd_set,write_fd_set,except_fd_set,max_fd) \ 3191 MHD_get_fdset2 ((daemon),(read_fd_set),(write_fd_set),(except_fd_set), \ 3192 (max_fd),FD_SETSIZE) 3193 3194 3195 /** 3196 * Obtain timeout value for polling function for this daemon. 3197 * 3198 * This function set value to the amount of milliseconds for which polling 3199 * function (`select()`, `poll()` or epoll) should at most block, not the 3200 * timeout value set for connections. 3201 * 3202 * Any "external" sockets polling function must be called with the timeout 3203 * value provided by this function. Smaller timeout values can be used for 3204 * polling function if it is required for any reason, but using larger 3205 * timeout value or no timeout (indefinite timeout) when this function 3206 * return #MHD_YES will break MHD processing logic and result in "hung" 3207 * connections with data pending in network buffers and other problems. 3208 * 3209 * It is important to always use this function (or #MHD_get_timeout64(), 3210 * #MHD_get_timeout64s(), #MHD_get_timeout_i() functions) when "external" 3211 * polling is used. 3212 * If this function returns #MHD_YES then #MHD_run() (or #MHD_run_from_select()) 3213 * must be called right after return from polling function, regardless of 3214 * the states of MHD FDs. 3215 * 3216 * In practice, if #MHD_YES is returned then #MHD_run() (or 3217 * #MHD_run_from_select()) must be called not later than @a timeout 3218 * millisecond even if no activity is detected on sockets by sockets 3219 * polling function. 3220 * 3221 * @param daemon daemon to query for timeout 3222 * @param[out] timeout set to the timeout (in milliseconds) 3223 * @return #MHD_YES on success, #MHD_NO if timeouts are 3224 * not used and no data processing is pending. 3225 * @ingroup event 3226 */ 3227 _MHD_EXTERN enum MHD_Result 3228 MHD_get_timeout (struct MHD_Daemon *daemon, 3229 MHD_UNSIGNED_LONG_LONG *timeout); 3230 3231 3232 /** 3233 * Free the memory allocated by MHD. 3234 * 3235 * If any MHD function explicitly mentions that returned pointer must be 3236 * freed by this function, then no other method must be used to free 3237 * the memory. 3238 * 3239 * @param ptr the pointer to free. 3240 * @sa #MHD_digest_auth_get_username(), #MHD_basic_auth_get_username_password3() 3241 * @sa #MHD_basic_auth_get_username_password() 3242 * @note Available since #MHD_VERSION 0x00095600 3243 * @ingroup specialized 3244 */ 3245 _MHD_EXTERN void 3246 MHD_free (void *ptr); 3247 3248 /** 3249 * Obtain timeout value for external polling function for this daemon. 3250 * 3251 * This function set value to the amount of milliseconds for which polling 3252 * function (`select()`, `poll()` or epoll) should at most block, not the 3253 * timeout value set for connections. 3254 * 3255 * Any "external" sockets polling function must be called with the timeout 3256 * value provided by this function. Smaller timeout values can be used for 3257 * polling function if it is required for any reason, but using larger 3258 * timeout value or no timeout (indefinite timeout) when this function 3259 * return #MHD_YES will break MHD processing logic and result in "hung" 3260 * connections with data pending in network buffers and other problems. 3261 * 3262 * It is important to always use this function (or #MHD_get_timeout(), 3263 * #MHD_get_timeout64s(), #MHD_get_timeout_i() functions) when "external" 3264 * polling is used. 3265 * If this function returns #MHD_YES then #MHD_run() (or #MHD_run_from_select()) 3266 * must be called right after return from polling function, regardless of 3267 * the states of MHD FDs. 3268 * 3269 * In practice, if #MHD_YES is returned then #MHD_run() (or 3270 * #MHD_run_from_select()) must be called not later than @a timeout 3271 * millisecond even if no activity is detected on sockets by sockets 3272 * polling function. 3273 * 3274 * @param daemon daemon to query for timeout 3275 * @param[out] timeout64 the pointer to the variable to be set to the 3276 * timeout (in milliseconds) 3277 * @return #MHD_YES if timeout value has been set, 3278 * #MHD_NO if timeouts are not used and no data processing is pending. 3279 * @note Available since #MHD_VERSION 0x00097701 3280 * @ingroup event 3281 */ 3282 _MHD_EXTERN enum MHD_Result 3283 MHD_get_timeout64 (struct MHD_Daemon *daemon, 3284 uint64_t *timeout); 3285 3286 3287 /** 3288 * Obtain timeout value for external polling function for this daemon. 3289 * 3290 * This function set value to the amount of milliseconds for which polling 3291 * function (`select()`, `poll()` or epoll) should at most block, not the 3292 * timeout value set for connections. 3293 * 3294 * Any "external" sockets polling function must be called with the timeout 3295 * value provided by this function (if returned value is non-negative). 3296 * Smaller timeout values can be used for polling function if it is required 3297 * for any reason, but using larger timeout value or no timeout (indefinite 3298 * timeout) when this function returns non-negative value will break MHD 3299 * processing logic and result in "hung" connections with data pending in 3300 * network buffers and other problems. 3301 * 3302 * It is important to always use this function (or #MHD_get_timeout(), 3303 * #MHD_get_timeout64(), #MHD_get_timeout_i() functions) when "external" 3304 * polling is used. 3305 * If this function returns non-negative value then #MHD_run() (or 3306 * #MHD_run_from_select()) must be called right after return from polling 3307 * function, regardless of the states of MHD FDs. 3308 * 3309 * In practice, if zero or positive value is returned then #MHD_run() (or 3310 * #MHD_run_from_select()) must be called not later than returned amount of 3311 * millisecond even if no activity is detected on sockets by sockets 3312 * polling function. 3313 * 3314 * @param daemon the daemon to query for timeout 3315 * @return -1 if connections' timeouts are not set and no data processing 3316 * is pending, so external polling function may wait for sockets 3317 * activity for indefinite amount of time, 3318 * otherwise returned value is the the maximum amount of millisecond 3319 * that external polling function must wait for the activity of FDs. 3320 * @note Available since #MHD_VERSION 0x00097701 3321 * @ingroup event 3322 */ 3323 _MHD_EXTERN int64_t 3324 MHD_get_timeout64s (struct MHD_Daemon *daemon); 3325 3326 3327 /** 3328 * Obtain timeout value for external polling function for this daemon. 3329 * 3330 * This function set value to the amount of milliseconds for which polling 3331 * function (`select()`, `poll()` or epoll) should at most block, not the 3332 * timeout value set for connections. 3333 * 3334 * Any "external" sockets polling function must be called with the timeout 3335 * value provided by this function (if returned value is non-negative). 3336 * Smaller timeout values can be used for polling function if it is required 3337 * for any reason, but using larger timeout value or no timeout (indefinite 3338 * timeout) when this function returns non-negative value will break MHD 3339 * processing logic and result in "hung" connections with data pending in 3340 * network buffers and other problems. 3341 * 3342 * It is important to always use this function (or #MHD_get_timeout(), 3343 * #MHD_get_timeout64(), #MHD_get_timeout64s() functions) when "external" 3344 * polling is used. 3345 * If this function returns non-negative value then #MHD_run() (or 3346 * #MHD_run_from_select()) must be called right after return from polling 3347 * function, regardless of the states of MHD FDs. 3348 * 3349 * In practice, if zero or positive value is returned then #MHD_run() (or 3350 * #MHD_run_from_select()) must be called not later than returned amount of 3351 * millisecond even if no activity is detected on sockets by sockets 3352 * polling function. 3353 * 3354 * @param daemon the daemon to query for timeout 3355 * @return -1 if connections' timeouts are not set and no data processing 3356 * is pending, so external polling function may wait for sockets 3357 * activity for indefinite amount of time, 3358 * otherwise returned value is the the maximum amount of millisecond 3359 * (capped at INT_MAX) that external polling function must wait 3360 * for the activity of FDs. 3361 * @note Available since #MHD_VERSION 0x00097701 3362 * @ingroup event 3363 */ 3364 _MHD_EXTERN int 3365 MHD_get_timeout_i (struct MHD_Daemon *daemon); 3366 3367 3368 /** 3369 * Run webserver operations (without blocking unless in client callbacks). 3370 * 3371 * This method should be called by clients in combination with 3372 * #MHD_get_fdset() (or #MHD_get_daemon_info() with MHD_DAEMON_INFO_EPOLL_FD 3373 * if epoll is used) and #MHD_get_timeout() if the client-controlled 3374 * connection polling method is used (i.e. daemon was started without 3375 * #MHD_USE_INTERNAL_POLLING_THREAD flag). 3376 * 3377 * This function is a convenience method, which is useful if the 3378 * fd_sets from #MHD_get_fdset were not directly passed to `select()`; 3379 * with this function, MHD will internally do the appropriate `select()` 3380 * call itself again. While it is acceptable to call #MHD_run (if 3381 * #MHD_USE_INTERNAL_POLLING_THREAD is not set) at any moment, you should 3382 * call #MHD_run_from_select() if performance is important (as it saves an 3383 * expensive call to `select()`). 3384 * 3385 * If #MHD_get_timeout() returned #MHD_YES, than this function must be called 3386 * right after polling function returns regardless of detected activity on 3387 * the daemon's FDs. 3388 * 3389 * @param daemon daemon to run 3390 * @return #MHD_YES on success, #MHD_NO if this 3391 * daemon was not started with the right 3392 * options for this call. 3393 * @ingroup event 3394 */ 3395 _MHD_EXTERN enum MHD_Result 3396 MHD_run (struct MHD_Daemon *daemon); 3397 3398 3399 /** 3400 * Run websever operation with possible blocking. 3401 * 3402 * This function does the following: waits for any network event not more than 3403 * specified number of milliseconds, processes all incoming and outgoing data, 3404 * processes new connections, processes any timed-out connection, and does 3405 * other things required to run webserver. 3406 * Once all connections are processed, function returns. 3407 * 3408 * This function is useful for quick and simple (lazy) webserver implementation 3409 * if application needs to run a single thread only and does not have any other 3410 * network activity. 3411 * 3412 * This function calls MHD_get_timeout() internally and use returned value as 3413 * maximum wait time if it less than value of @a millisec parameter. 3414 * 3415 * It is expected that the "external" socket polling function is not used in 3416 * conjunction with this function unless the @a millisec is set to zero. 3417 * 3418 * @param daemon the daemon to run 3419 * @param millisec the maximum time in milliseconds to wait for network and 3420 * other events. Note: there is no guarantee that function 3421 * blocks for the specified amount of time. The real processing 3422 * time can be shorter (if some data or connection timeout 3423 * comes earlier) or longer (if data processing requires more 3424 * time, especially in user callbacks). 3425 * If set to '0' then function does not block and processes 3426 * only already available data (if any). 3427 * If set to '-1' then function waits for events 3428 * indefinitely (blocks until next network activity or 3429 * connection timeout). 3430 * @return #MHD_YES on success, #MHD_NO if this 3431 * daemon was not started with the right 3432 * options for this call or some serious 3433 * unrecoverable error occurs. 3434 * @note Available since #MHD_VERSION 0x00097206 3435 * @ingroup event 3436 */ 3437 _MHD_EXTERN enum MHD_Result 3438 MHD_run_wait (struct MHD_Daemon *daemon, 3439 int32_t millisec); 3440 3441 3442 /** 3443 * Run webserver operations. This method should be called by clients 3444 * in combination with #MHD_get_fdset and #MHD_get_timeout() if the 3445 * client-controlled select method is used. 3446 * 3447 * You can use this function instead of #MHD_run if you called 3448 * `select()` on the result from #MHD_get_fdset. File descriptors in 3449 * the sets that are not controlled by MHD will be ignored. Calling 3450 * this function instead of #MHD_run is more efficient as MHD will 3451 * not have to call `select()` again to determine which operations are 3452 * ready. 3453 * 3454 * If #MHD_get_timeout() returned #MHD_YES, than this function must be 3455 * called right after `select()` returns regardless of detected activity 3456 * on the daemon's FDs. 3457 * 3458 * This function cannot be used with daemon started with 3459 * #MHD_USE_INTERNAL_POLLING_THREAD flag. 3460 * 3461 * @param daemon daemon to run select loop for 3462 * @param read_fd_set read set 3463 * @param write_fd_set write set 3464 * @param except_fd_set except set 3465 * @return #MHD_NO on serious errors, #MHD_YES on success 3466 * @ingroup event 3467 */ 3468 _MHD_EXTERN enum MHD_Result 3469 MHD_run_from_select (struct MHD_Daemon *daemon, 3470 const fd_set *read_fd_set, 3471 const fd_set *write_fd_set, 3472 const fd_set *except_fd_set); 3473 3474 3475 /** 3476 * Run webserver operations. This method should be called by clients 3477 * in combination with #MHD_get_fdset and #MHD_get_timeout() if the 3478 * client-controlled select method is used. 3479 * This function specifies FD_SETSIZE used when provided fd_sets were 3480 * created. It is important on platforms where FD_SETSIZE can be 3481 * overridden. 3482 * 3483 * You can use this function instead of #MHD_run if you called 3484 * 'select()' on the result from #MHD_get_fdset2(). File descriptors in 3485 * the sets that are not controlled by MHD will be ignored. Calling 3486 * this function instead of #MHD_run() is more efficient as MHD will 3487 * not have to call 'select()' again to determine which operations are 3488 * ready. 3489 * 3490 * If #MHD_get_timeout() returned #MHD_YES, than this function must be 3491 * called right after 'select()' returns regardless of detected activity 3492 * on the daemon's FDs. 3493 * 3494 * This function cannot be used with daemon started with 3495 * #MHD_USE_INTERNAL_POLLING_THREAD flag. 3496 * 3497 * @param daemon the daemon to run select loop for 3498 * @param read_fd_set the read set 3499 * @param write_fd_set the write set 3500 * @param except_fd_set the except set 3501 * @param fd_setsize the value of FD_SETSIZE 3502 * @return #MHD_NO on serious errors, #MHD_YES on success 3503 * @sa #MHD_get_fdset2(), #MHD_OPTION_APP_FD_SETSIZE 3504 * @ingroup event 3505 */ 3506 _MHD_EXTERN enum MHD_Result 3507 MHD_run_from_select2 (struct MHD_Daemon *daemon, 3508 const fd_set *read_fd_set, 3509 const fd_set *write_fd_set, 3510 const fd_set *except_fd_set, 3511 unsigned int fd_setsize); 3512 3513 3514 /** 3515 * Run webserver operations. This method should be called by clients 3516 * in combination with #MHD_get_fdset and #MHD_get_timeout() if the 3517 * client-controlled select method is used. 3518 * This macro automatically substitutes current FD_SETSIZE value. 3519 * It is important on platforms where FD_SETSIZE can be overridden. 3520 * 3521 * You can use this function instead of #MHD_run if you called 3522 * 'select()' on the result from #MHD_get_fdset2(). File descriptors in 3523 * the sets that are not controlled by MHD will be ignored. Calling 3524 * this function instead of #MHD_run() is more efficient as MHD will 3525 * not have to call 'select()' again to determine which operations are 3526 * ready. 3527 * 3528 * If #MHD_get_timeout() returned #MHD_YES, than this function must be 3529 * called right after 'select()' returns regardless of detected activity 3530 * on the daemon's FDs. 3531 * 3532 * This function cannot be used with daemon started with 3533 * #MHD_USE_INTERNAL_POLLING_THREAD flag. 3534 * 3535 * @param daemon the daemon to run select loop for 3536 * @param read_fd_set the read set 3537 * @param write_fd_set the write set 3538 * @param except_fd_set the except set 3539 * @param fd_setsize the value of FD_SETSIZE 3540 * @return #MHD_NO on serious errors, #MHD_YES on success 3541 * @sa #MHD_get_fdset2(), #MHD_OPTION_APP_FD_SETSIZE 3542 * @ingroup event 3543 */ 3544 #define MHD_run_from_select(d,r,w,e) \ 3545 MHD_run_from_select2 ((d),(r),(w),(e),(unsigned int) (FD_SETSIZE)) 3546 3547 /* **************** Connection handling functions ***************** */ 3548 3549 3550 /** 3551 * Get request URI path (the request target without query part). 3552 * 3553 * The value obtained by this function is the same value as @a url provided 3554 * for #MHD_AccessHandlerCallback callback, but this function also provides 3555 * the size of the string. 3556 * 3557 * This function is critically important when binary zero is allowed by daemon 3558 * option #MHD_OPTION_ALLOW_BIN_ZERO_IN_URI_PATH as this is the only way to 3559 * get the non-truncated request URI. 3560 * 3561 * Returned @a uri pointer is valid until response is started or connection 3562 * is terminated. 3563 * 3564 * @param connection the connection to URI from 3565 * @param[out] uri set to the request URI without query part, may contain 3566 * binary zeros (NUL) characters, never set to NULL on 3567 * success; can be NULL 3568 * @param[out] uri_size set to the size of the @a uri in bytes, not including 3569 * final zero-termination; can be NULL 3570 * @return #MHD_NO if failed (request is not yet processed or response has 3571 * been queued already); 3572 * #MHD_YES on success (*uri set to valid pointer) 3573 * @note Available since #MHD_VERSION 0x01000201 3574 * @sa #MHD_OPTION_ALLOW_BIN_ZERO_IN_URI_PATH, #MHD_AccessHandlerCallback 3575 * @ingroup request 3576 */ 3577 _MHD_EXTERN enum MHD_Result 3578 MHD_get_connection_URI_path_n (struct MHD_Connection *connection, 3579 const char **uri, 3580 size_t *uri_size); 3581 3582 /** 3583 * Get all of the headers from the request. 3584 * 3585 * @param connection connection to get values from 3586 * @param kind types of values to iterate over, can be a bitmask 3587 * @param iterator callback to call on each header; 3588 * may be NULL (then just count headers) 3589 * @param iterator_cls extra argument to @a iterator 3590 * @return number of entries iterated over, 3591 * -1 if connection is NULL. 3592 * @ingroup request 3593 */ 3594 _MHD_EXTERN int 3595 MHD_get_connection_values (struct MHD_Connection *connection, 3596 enum MHD_ValueKind kind, 3597 MHD_KeyValueIterator iterator, 3598 void *iterator_cls); 3599 3600 3601 /** 3602 * Get all of the headers from the request. 3603 * 3604 * @param connection connection to get values from 3605 * @param kind types of values to iterate over, can be a bitmask 3606 * @param iterator callback to call on each header; 3607 * may be NULL (then just count headers) 3608 * @param iterator_cls extra argument to @a iterator 3609 * @return number of entries iterated over, 3610 * -1 if connection is NULL. 3611 * @note Available since #MHD_VERSION 0x00096400 3612 * @ingroup request 3613 */ 3614 _MHD_EXTERN int 3615 MHD_get_connection_values_n (struct MHD_Connection *connection, 3616 enum MHD_ValueKind kind, 3617 MHD_KeyValueIteratorN iterator, 3618 void *iterator_cls); 3619 3620 3621 /** 3622 * This function can be used to add an entry to the HTTP headers of a 3623 * connection (so that the #MHD_get_connection_values function will 3624 * return them -- and the `struct MHD_PostProcessor` will also see 3625 * them). This maybe required in certain situations (see Mantis 3626 * #1399) where (broken) HTTP implementations fail to supply values 3627 * needed by the post processor (or other parts of the application). 3628 * 3629 * This function MUST only be called from within the 3630 * #MHD_AccessHandlerCallback (otherwise, access maybe improperly 3631 * synchronized). Furthermore, the client must guarantee that the key 3632 * and value arguments are 0-terminated strings that are NOT freed 3633 * until the connection is closed. (The easiest way to do this is by 3634 * passing only arguments to permanently allocated strings.). 3635 * 3636 * @param connection the connection for which a 3637 * value should be set 3638 * @param kind kind of the value 3639 * @param key key for the value 3640 * @param value the value itself 3641 * @return #MHD_NO if the operation could not be 3642 * performed due to insufficient memory; 3643 * #MHD_YES on success 3644 * @ingroup request 3645 */ 3646 _MHD_EXTERN enum MHD_Result 3647 MHD_set_connection_value (struct MHD_Connection *connection, 3648 enum MHD_ValueKind kind, 3649 const char *key, 3650 const char *value); 3651 3652 3653 /** 3654 * This function can be used to add an arbitrary entry to connection. 3655 * This function could add entry with binary zero, which is allowed 3656 * for #MHD_GET_ARGUMENT_KIND. For other kind on entries it is 3657 * recommended to use #MHD_set_connection_value. 3658 * 3659 * This function MUST only be called from within the 3660 * #MHD_AccessHandlerCallback (otherwise, access maybe improperly 3661 * synchronized). Furthermore, the client must guarantee that the key 3662 * and value arguments are 0-terminated strings that are NOT freed 3663 * until the connection is closed. (The easiest way to do this is by 3664 * passing only arguments to permanently allocated strings.). 3665 * 3666 * @param connection the connection for which a 3667 * value should be set 3668 * @param kind kind of the value 3669 * @param key key for the value, must be zero-terminated 3670 * @param key_size number of bytes in @a key (excluding 0-terminator) 3671 * @param value the value itself, must be zero-terminated 3672 * @param value_size number of bytes in @a value (excluding 0-terminator) 3673 * @return #MHD_NO if the operation could not be 3674 * performed due to insufficient memory; 3675 * #MHD_YES on success 3676 * @note Available since #MHD_VERSION 0x00096400 3677 * @ingroup request 3678 */ 3679 _MHD_EXTERN enum MHD_Result 3680 MHD_set_connection_value_n (struct MHD_Connection *connection, 3681 enum MHD_ValueKind kind, 3682 const char *key, 3683 size_t key_size, 3684 const char *value, 3685 size_t value_size); 3686 3687 3688 /** 3689 * Sets the global error handler to a different implementation. 3690 * 3691 * @a cb will only be called in the case of typically fatal, serious internal 3692 * consistency issues or serious system failures like failed lock of mutex. 3693 * 3694 * These issues should only arise in the case of serious memory corruption or 3695 * similar problems with the architecture, there is no safe way to continue 3696 * even for closing of the application. 3697 * 3698 * The default implementation that is used if no panic function is set simply 3699 * prints an error message and calls `abort()`. 3700 * Alternative implementations might call `exit()` or other similar functions. 3701 * 3702 * @param cb new error handler or NULL to use default handler 3703 * @param cls passed to @a cb 3704 * @ingroup logging 3705 */ 3706 _MHD_EXTERN void 3707 MHD_set_panic_func (MHD_PanicCallback cb, void *cls); 3708 3709 3710 /** 3711 * Process escape sequences ('%HH') Updates val in place; the 3712 * result cannot be larger than the input. 3713 * The result is still be 0-terminated. 3714 * 3715 * @param val value to unescape (modified in the process) 3716 * @return length of the resulting val (`strlen(val)` may be 3717 * shorter afterwards due to elimination of escape sequences) 3718 */ 3719 _MHD_EXTERN size_t 3720 MHD_http_unescape (char *val); 3721 3722 3723 /** 3724 * Get a particular header value. If multiple 3725 * values match the kind, return any one of them. 3726 * 3727 * @param connection connection to get values from 3728 * @param kind what kind of value are we looking for 3729 * @param key the header to look for, NULL to lookup 'trailing' value without a key 3730 * @return NULL if no such item was found 3731 * @ingroup request 3732 */ 3733 _MHD_EXTERN const char * 3734 MHD_lookup_connection_value (struct MHD_Connection *connection, 3735 enum MHD_ValueKind kind, 3736 const char *key); 3737 3738 3739 /** 3740 * Get a particular header value. If multiple 3741 * values match the kind, return any one of them. 3742 * @note Since MHD_VERSION 0x00096304 3743 * 3744 * @param connection connection to get values from 3745 * @param kind what kind of value are we looking for 3746 * @param key the header to look for, NULL to lookup 'trailing' value without a key 3747 * @param key_size the length of @a key in bytes 3748 * @param[out] value_ptr the pointer to variable, which will be set to found value, 3749 * will not be updated if key not found, 3750 * could be NULL to just check for presence of @a key 3751 * @param[out] value_size_ptr the pointer variable, which will set to found value, 3752 * will not be updated if key not found, 3753 * could be NULL 3754 * @return #MHD_YES if key is found, 3755 * #MHD_NO otherwise. 3756 * @ingroup request 3757 */ 3758 _MHD_EXTERN enum MHD_Result 3759 MHD_lookup_connection_value_n (struct MHD_Connection *connection, 3760 enum MHD_ValueKind kind, 3761 const char *key, 3762 size_t key_size, 3763 const char **value_ptr, 3764 size_t *value_size_ptr); 3765 3766 3767 /** 3768 * Queue a response to be transmitted to the client (as soon as 3769 * possible but after #MHD_AccessHandlerCallback returns). 3770 * 3771 * For any active connection this function must be called 3772 * only by #MHD_AccessHandlerCallback callback. 3773 * 3774 * For suspended connection this function can be called at any moment (this 3775 * behaviour is deprecated and will be removed!). Response will be sent 3776 * as soon as connection is resumed. 3777 * 3778 * For single thread environment, when MHD is used in "external polling" mode 3779 * (without MHD_USE_SELECT_INTERNALLY) this function can be called any 3780 * time (this behaviour is deprecated and will be removed!). 3781 * 3782 * If HTTP specifications require use no body in reply, like @a status_code with 3783 * value 1xx, the response body is automatically not sent even if it is present 3784 * in the response. No "Content-Length" or "Transfer-Encoding" headers are 3785 * generated and added. 3786 * 3787 * When the response is used to respond HEAD request or used with @a status_code 3788 * #MHD_HTTP_NOT_MODIFIED, then response body is not sent, but "Content-Length" 3789 * header is added automatically based the size of the body in the response. 3790 * If body size it set to #MHD_SIZE_UNKNOWN or chunked encoding is enforced 3791 * then "Transfer-Encoding: chunked" header (for HTTP/1.1 only) is added instead 3792 * of "Content-Length" header. For example, if response with zero-size body is 3793 * used for HEAD request, then "Content-Length: 0" is added automatically to 3794 * reply headers. 3795 * @sa #MHD_RF_HEAD_ONLY_RESPONSE 3796 * 3797 * In situations, where reply body is required, like answer for the GET request 3798 * with @a status_code #MHD_HTTP_OK, headers "Content-Length" (for known body 3799 * size) or "Transfer-Encoding: chunked" (for #MHD_SIZE_UNKNOWN with HTTP/1.1) 3800 * are added automatically. 3801 * In practice, the same response object can be used to respond to both HEAD and 3802 * GET requests. 3803 * 3804 * @param connection the connection identifying the client 3805 * @param status_code HTTP status code (i.e. #MHD_HTTP_OK) 3806 * @param response response to transmit, the NULL is tolerated 3807 * @return #MHD_NO on error (reply already sent, response is NULL), 3808 * #MHD_YES on success or if message has been queued 3809 * @ingroup response 3810 * @sa #MHD_AccessHandlerCallback 3811 */ 3812 _MHD_EXTERN enum MHD_Result 3813 MHD_queue_response (struct MHD_Connection *connection, 3814 unsigned int status_code, 3815 struct MHD_Response *response); 3816 3817 3818 /** 3819 * Suspend handling of network data for a given connection. 3820 * This can be used to dequeue a connection from MHD's event loop 3821 * (not applicable to thread-per-connection!) for a while. 3822 * 3823 * If you use this API in conjunction with an "internal" socket polling, 3824 * you must set the option #MHD_USE_ITC to ensure that a resumed 3825 * connection is immediately processed by MHD. 3826 * 3827 * Suspended connections continue to count against the total number of 3828 * connections allowed (per daemon, as well as per IP, if such limits 3829 * are set). Suspended connections will NOT time out; timeouts will 3830 * restart when the connection handling is resumed. While a 3831 * connection is suspended, MHD will not detect disconnects by the 3832 * client. 3833 * 3834 * The only safe way to call this function is to call it from the 3835 * #MHD_AccessHandlerCallback or #MHD_ContentReaderCallback. 3836 * 3837 * Finally, it is an API violation to call #MHD_stop_daemon while 3838 * having suspended connections (this will at least create memory and 3839 * socket leaks or lead to undefined behavior). You must explicitly 3840 * resume all connections before stopping the daemon. 3841 * 3842 * @param connection the connection to suspend 3843 * 3844 * @sa #MHD_AccessHandlerCallback 3845 */ 3846 _MHD_EXTERN void 3847 MHD_suspend_connection (struct MHD_Connection *connection); 3848 3849 3850 /** 3851 * Resume handling of network data for suspended connection. It is 3852 * safe to resume a suspended connection at any time. Calling this 3853 * function on a connection that was not previously suspended will 3854 * result in undefined behavior. 3855 * 3856 * If you are using this function in "external" sockets polling mode, you must 3857 * make sure to run #MHD_run() and #MHD_get_timeout() afterwards (before 3858 * again calling #MHD_get_fdset()), as otherwise the change may not be 3859 * reflected in the set returned by #MHD_get_fdset() and you may end up 3860 * with a connection that is stuck until the next network activity. 3861 * 3862 * This function may be called from any thread. In "external" sockets 3863 * polling mode it writes to the inter-thread communication channel that 3864 * #MHD_ALLOW_SUSPEND_RESUME sets up, and as #MHD_get_fdset() puts the 3865 * reading end of that channel into the read set, a call from another 3866 * thread interrupts a select()/poll() that the application is blocked 3867 * in. This matters because #MHD_get_timeout() reports no timeout at 3868 * all while every connection is suspended, so the application would 3869 * otherwise block indefinitely. The channel is level triggered, hence 3870 * a resume issued between #MHD_get_fdset() and select() cannot be lost. 3871 * 3872 * @param connection the connection to resume 3873 */ 3874 _MHD_EXTERN void 3875 MHD_resume_connection (struct MHD_Connection *connection); 3876 3877 3878 /* **************** Response manipulation functions ***************** */ 3879 3880 3881 /** 3882 * Flags for special handling of responses. 3883 */ 3884 enum MHD_ResponseFlags 3885 { 3886 /** 3887 * Default: no special flags. 3888 * @note Available since #MHD_VERSION 0x00093701 3889 */ 3890 MHD_RF_NONE = 0, 3891 3892 /** 3893 * Only respond in conservative (dumb) HTTP/1.0-compatible mode. 3894 * Response still use HTTP/1.1 version in header, but always close 3895 * the connection after sending the response and do not use chunked 3896 * encoding for the response. 3897 * You can also set the #MHD_RF_HTTP_1_0_SERVER flag to force 3898 * HTTP/1.0 version in the response. 3899 * Responses are still compatible with HTTP/1.1. 3900 * This option can be used to communicate with some broken client, which 3901 * does not implement HTTP/1.1 features, but advertises HTTP/1.1 support. 3902 * @note Available since #MHD_VERSION 0x00097308 3903 */ 3904 MHD_RF_HTTP_1_0_COMPATIBLE_STRICT = 1 << 0, 3905 /** 3906 * The same as #MHD_RF_HTTP_1_0_COMPATIBLE_STRICT 3907 * @note Available since #MHD_VERSION 0x00093701 3908 */ 3909 MHD_RF_HTTP_VERSION_1_0_ONLY = 1 << 0, 3910 3911 /** 3912 * Only respond in HTTP 1.0-mode. 3913 * Contrary to the #MHD_RF_HTTP_1_0_COMPATIBLE_STRICT flag, the response's 3914 * HTTP version will always be set to 1.0 and keep-alive connections 3915 * will be used if explicitly requested by the client. 3916 * The "Connection:" header will be added for both "close" and "keep-alive" 3917 * connections. 3918 * Chunked encoding will not be used for the response. 3919 * Due to backward compatibility, responses still can be used with 3920 * HTTP/1.1 clients. 3921 * This option can be used to emulate HTTP/1.0 server (for response part 3922 * only as chunked encoding in requests (if any) is processed by MHD). 3923 * @note Available since #MHD_VERSION 0x00097308 3924 */ 3925 MHD_RF_HTTP_1_0_SERVER = 1 << 1, 3926 /** 3927 * The same as #MHD_RF_HTTP_1_0_SERVER 3928 * @note Available since #MHD_VERSION 0x00096000 3929 */ 3930 MHD_RF_HTTP_VERSION_1_0_RESPONSE = 1 << 1, 3931 3932 /** 3933 * Disable sanity check preventing clients from manually 3934 * setting the HTTP content length option. 3935 * Allow to set several "Content-Length" headers. These headers will 3936 * be used even with replies without body. 3937 * @note Available since #MHD_VERSION 0x00096702 3938 */ 3939 MHD_RF_INSANITY_HEADER_CONTENT_LENGTH = 1 << 2, 3940 3941 /** 3942 * Enable sending of "Connection: keep-alive" header even for 3943 * HTTP/1.1 clients when "Keep-Alive" connection is used. 3944 * Disabled by default for HTTP/1.1 clients as per RFC. 3945 * @note Available since #MHD_VERSION 0x00097310 3946 */ 3947 MHD_RF_SEND_KEEP_ALIVE_HEADER = 1 << 3, 3948 3949 /** 3950 * Enable special processing of the response as body-less (with undefined 3951 * body size). No automatic "Content-Length" or "Transfer-Encoding: chunked" 3952 * headers are added when the response is used with #MHD_HTTP_NOT_MODIFIED 3953 * code or to respond to HEAD request. 3954 * The flag also allow to set arbitrary "Content-Length" by 3955 * MHD_add_response_header() function. 3956 * This flag value can be used only with responses created without body 3957 * (zero-size body). 3958 * Responses with this flag enabled cannot be used in situations where 3959 * reply body must be sent to the client. 3960 * This flag is primarily intended to be used when automatic "Content-Length" 3961 * header is undesirable in response to HEAD requests. 3962 * @note Available since #MHD_VERSION 0x00097701 3963 */ 3964 MHD_RF_HEAD_ONLY_RESPONSE = 1 << 4 3965 } _MHD_FIXED_FLAGS_ENUM; 3966 3967 3968 /** 3969 * MHD options (for future extensions). 3970 */ 3971 enum MHD_ResponseOptions 3972 { 3973 /** 3974 * End of the list of options. 3975 */ 3976 MHD_RO_END = 0 3977 } _MHD_FIXED_ENUM; 3978 3979 3980 /** 3981 * Set special flags and options for a response. 3982 * 3983 * @param response the response to modify 3984 * @param flags to set for the response 3985 * @param ... #MHD_RO_END terminated list of options 3986 * @return #MHD_YES on success, #MHD_NO on error 3987 */ 3988 _MHD_EXTERN enum MHD_Result 3989 MHD_set_response_options (struct MHD_Response *response, 3990 enum MHD_ResponseFlags flags, 3991 ...); 3992 3993 3994 /** 3995 * Create a response object. 3996 * The response object can be extended with header information and then be used 3997 * any number of times. 3998 * 3999 * If response object is used to answer HEAD request then the body of the 4000 * response is not used, while all headers (including automatic headers) are 4001 * used. 4002 * 4003 * @param size size of the data portion of the response, #MHD_SIZE_UNKNOWN for unknown 4004 * @param block_size preferred block size for querying crc (advisory only, 4005 * MHD may still call @a crc using smaller chunks); this 4006 * is essentially the buffer size used for IO, clients 4007 * should pick a value that is appropriate for IO and 4008 * memory performance requirements 4009 * @param crc callback to use to obtain response data 4010 * @param crc_cls extra argument to @a crc 4011 * @param crfc callback to call to free @a crc_cls resources 4012 * @return NULL on error (i.e. invalid arguments, out of memory) 4013 * @ingroup response 4014 */ 4015 _MHD_EXTERN struct MHD_Response * 4016 MHD_create_response_from_callback (uint64_t size, 4017 size_t block_size, 4018 MHD_ContentReaderCallback crc, void *crc_cls, 4019 MHD_ContentReaderFreeCallback crfc); 4020 4021 4022 /** 4023 * Create a response object. 4024 * The response object can be extended with header information and then be used 4025 * any number of times. 4026 * 4027 * If response object is used to answer HEAD request then the body of the 4028 * response is not used, while all headers (including automatic headers) are 4029 * used. 4030 * 4031 * @param size size of the @a data portion of the response 4032 * @param data the data itself 4033 * @param must_free libmicrohttpd should free data when done 4034 * @param must_copy libmicrohttpd must make a copy of @a data 4035 * right away, the data may be released anytime after 4036 * this call returns 4037 * @return NULL on error (i.e. invalid arguments, out of memory) 4038 * @deprecated use #MHD_create_response_from_buffer instead 4039 * @ingroup response 4040 */ 4041 _MHD_DEPR_FUNC ( \ 4042 "MHD_create_response_from_data() is deprecated, use MHD_create_response_from_buffer()" \ 4043 ) \ 4044 _MHD_EXTERN struct MHD_Response * 4045 MHD_create_response_from_data (size_t size, 4046 void *data, 4047 int must_free, 4048 int must_copy); 4049 4050 4051 /** 4052 * Specification for how MHD should treat the memory buffer 4053 * given for the response. 4054 * @ingroup response 4055 */ 4056 enum MHD_ResponseMemoryMode 4057 { 4058 4059 /** 4060 * Buffer is a persistent (static/global) buffer that won't change 4061 * for at least the lifetime of the response, MHD should just use 4062 * it, not free it, not copy it, just keep an alias to it. 4063 * @ingroup response 4064 */ 4065 MHD_RESPMEM_PERSISTENT, 4066 4067 /** 4068 * Buffer is heap-allocated with `malloc()` (or equivalent) and 4069 * should be freed by MHD after processing the response has 4070 * concluded (response reference counter reaches zero). 4071 * The more portable way to automatically free the buffer is function 4072 * MHD_create_response_from_buffer_with_free_callback() with '&free' as 4073 * crfc parameter as it does not require to use the same runtime library. 4074 * @warning It is critical to make sure that the same C-runtime library 4075 * is used by both application and MHD (especially 4076 * important for W32). 4077 * @ingroup response 4078 */ 4079 MHD_RESPMEM_MUST_FREE, 4080 4081 /** 4082 * Buffer is in transient memory, but not on the heap (for example, 4083 * on the stack or non-`malloc()` allocated) and only valid during the 4084 * call to #MHD_create_response_from_buffer. MHD must make its 4085 * own private copy of the data for processing. 4086 * @ingroup response 4087 */ 4088 MHD_RESPMEM_MUST_COPY 4089 4090 } _MHD_FIXED_ENUM; 4091 4092 4093 /** 4094 * Create a response object with the content of provided buffer used as 4095 * the response body. 4096 * 4097 * The response object can be extended with header information and then 4098 * be used any number of times. 4099 * 4100 * If response object is used to answer HEAD request then the body 4101 * of the response is not used, while all headers (including automatic 4102 * headers) are used. 4103 * 4104 * @param size size of the data portion of the response 4105 * @param buffer size bytes containing the response's data portion 4106 * @param mode flags for buffer management 4107 * @return NULL on error (i.e. invalid arguments, out of memory) 4108 * @ingroup response 4109 */ 4110 _MHD_EXTERN struct MHD_Response * 4111 MHD_create_response_from_buffer (size_t size, 4112 void *buffer, 4113 enum MHD_ResponseMemoryMode mode); 4114 4115 4116 /** 4117 * Create a response object with the content of provided statically allocated 4118 * buffer used as the response body. 4119 * 4120 * The buffer must be valid for the lifetime of the response. The easiest way 4121 * to achieve this is to use a statically allocated buffer. 4122 * 4123 * The response object can be extended with header information and then 4124 * be used any number of times. 4125 * 4126 * If response object is used to answer HEAD request then the body 4127 * of the response is not used, while all headers (including automatic 4128 * headers) are used. 4129 * 4130 * @param size the size of the data in @a buffer, can be zero 4131 * @param buffer the buffer with the data for the response body, can be NULL 4132 * if @a size is zero 4133 * @return NULL on error (i.e. invalid arguments, out of memory) 4134 * @note Available since #MHD_VERSION 0x00097701 4135 * @ingroup response 4136 */ 4137 _MHD_EXTERN struct MHD_Response * 4138 MHD_create_response_from_buffer_static (size_t size, 4139 const void *buffer); 4140 4141 4142 /** 4143 * Create a response object with the content of provided temporal buffer 4144 * used as the response body. 4145 * 4146 * An internal copy of the buffer will be made automatically, so buffer have 4147 * to be valid only during the call of this function (as a typical example: 4148 * buffer is a local (non-static) array). 4149 * 4150 * The response object can be extended with header information and then 4151 * be used any number of times. 4152 * 4153 * If response object is used to answer HEAD request then the body 4154 * of the response is not used, while all headers (including automatic 4155 * headers) are used. 4156 * 4157 * @param size the size of the data in @a buffer, can be zero 4158 * @param buffer the buffer with the data for the response body, can be NULL 4159 * if @a size is zero 4160 * @return NULL on error (i.e. invalid arguments, out of memory) 4161 * @note Available since #MHD_VERSION 0x00097701 4162 * @ingroup response 4163 */ 4164 _MHD_EXTERN struct MHD_Response * 4165 MHD_create_response_from_buffer_copy (size_t size, 4166 const void *buffer); 4167 4168 4169 /** 4170 * Create a response object with the content of provided buffer used as 4171 * the response body. 4172 * 4173 * The response object can be extended with header information and then 4174 * be used any number of times. 4175 * 4176 * If response object is used to answer HEAD request then the body 4177 * of the response is not used, while all headers (including automatic 4178 * headers) are used. 4179 * 4180 * @param size size of the data portion of the response 4181 * @param buffer size bytes containing the response's data portion 4182 * @param crfc function to call to free the @a buffer 4183 * @return NULL on error (i.e. invalid arguments, out of memory) 4184 * @note Available since #MHD_VERSION 0x00096000 4185 * @ingroup response 4186 */ 4187 _MHD_EXTERN struct MHD_Response * 4188 MHD_create_response_from_buffer_with_free_callback (size_t size, 4189 void *buffer, 4190 MHD_ContentReaderFreeCallback 4191 crfc); 4192 4193 4194 /** 4195 * Create a response object with the content of provided buffer used as 4196 * the response body. 4197 * 4198 * The response object can be extended with header information and then 4199 * be used any number of times. 4200 * 4201 * If response object is used to answer HEAD request then the body 4202 * of the response is not used, while all headers (including automatic 4203 * headers) are used. 4204 * 4205 * @param size size of the data portion of the response 4206 * @param buffer size bytes containing the response's data portion 4207 * @param crfc function to call to cleanup, if set to NULL then callback 4208 * is not called 4209 * @param crfc_cls an argument for @a crfc 4210 * @return NULL on error (i.e. invalid arguments, out of memory) 4211 * @note Available since #MHD_VERSION 0x00097302 4212 * @note 'const' qualifier is used for @a buffer since #MHD_VERSION 0x00097701 4213 * @ingroup response 4214 */ 4215 _MHD_EXTERN struct MHD_Response * 4216 MHD_create_response_from_buffer_with_free_callback_cls (size_t size, 4217 const void *buffer, 4218 MHD_ContentReaderFreeCallback 4219 crfc, 4220 void *crfc_cls); 4221 4222 4223 /** 4224 * Create a response object with the content of provided file used as 4225 * the response body. 4226 * 4227 * The response object can be extended with header information and then 4228 * be used any number of times. 4229 * 4230 * If response object is used to answer HEAD request then the body 4231 * of the response is not used, while all headers (including automatic 4232 * headers) are used. 4233 * 4234 * @param size size of the data portion of the response 4235 * @param fd file descriptor referring to a file on disk with the 4236 * data; will be closed when response is destroyed; 4237 * fd should be in 'blocking' mode 4238 * @return NULL on error (i.e. invalid arguments, out of memory) 4239 * @ingroup response 4240 */ 4241 _MHD_EXTERN struct MHD_Response * 4242 MHD_create_response_from_fd (size_t size, 4243 int fd); 4244 4245 4246 /** 4247 * Create a response object with the response body created by reading 4248 * the provided pipe. 4249 * 4250 * The response object can be extended with header information and 4251 * then be used ONLY ONCE. 4252 * 4253 * If response object is used to answer HEAD request then the body 4254 * of the response is not used, while all headers (including automatic 4255 * headers) are used. 4256 * 4257 * @param fd file descriptor referring to a read-end of a pipe with the 4258 * data; will be closed when response is destroyed; 4259 * fd should be in 'blocking' mode 4260 * @return NULL on error (i.e. invalid arguments, out of memory) 4261 * @note Available since #MHD_VERSION 0x00097102 4262 * @ingroup response 4263 */ 4264 _MHD_EXTERN struct MHD_Response * 4265 MHD_create_response_from_pipe (int fd); 4266 4267 4268 /** 4269 * Create a response object with the content of provided file used as 4270 * the response body. 4271 * 4272 * The response object can be extended with header information and then 4273 * be used any number of times. 4274 * 4275 * If response object is used to answer HEAD request then the body 4276 * of the response is not used, while all headers (including automatic 4277 * headers) are used. 4278 * 4279 * @param size size of the data portion of the response; 4280 * sizes larger than 2 GiB may be not supported by OS or 4281 * MHD build; see ::MHD_FEATURE_LARGE_FILE 4282 * @param fd file descriptor referring to a file on disk with the 4283 * data; will be closed when response is destroyed; 4284 * fd should be in 'blocking' mode 4285 * @return NULL on error (i.e. invalid arguments, out of memory) 4286 * @ingroup response 4287 */ 4288 _MHD_EXTERN struct MHD_Response * 4289 MHD_create_response_from_fd64 (uint64_t size, 4290 int fd); 4291 4292 4293 /** 4294 * Create a response object with the content of provided file with 4295 * specified offset used as the response body. 4296 * 4297 * The response object can be extended with header information and then 4298 * be used any number of times. 4299 * 4300 * If response object is used to answer HEAD request then the body 4301 * of the response is not used, while all headers (including automatic 4302 * headers) are used. 4303 * 4304 * @param size size of the data portion of the response 4305 * @param fd file descriptor referring to a file on disk with the 4306 * data; will be closed when response is destroyed; 4307 * fd should be in 'blocking' mode 4308 * @param offset offset to start reading from in the file; 4309 * Be careful! `off_t` may have been compiled to be a 4310 * 64-bit variable for MHD, in which case your application 4311 * also has to be compiled using the same options! Read 4312 * the MHD manual for more details. 4313 * @return NULL on error (i.e. invalid arguments, out of memory) 4314 * @ingroup response 4315 */ 4316 _MHD_DEPR_FUNC ( \ 4317 "Function MHD_create_response_from_fd_at_offset() is deprecated, use MHD_create_response_from_fd_at_offset64()" \ 4318 ) \ 4319 _MHD_EXTERN struct MHD_Response * 4320 MHD_create_response_from_fd_at_offset (size_t size, 4321 int fd, 4322 off_t offset); 4323 4324 #if ! defined(_MHD_NO_DEPR_IN_MACRO) || defined(_MHD_NO_DEPR_FUNC) 4325 /* Substitute MHD_create_response_from_fd_at_offset64() instead of MHD_create_response_from_fd_at_offset() 4326 to minimize potential problems with different off_t sizes */ 4327 #define MHD_create_response_from_fd_at_offset(size,fd,offset) \ 4328 _MHD_DEPR_IN_MACRO ( \ 4329 "Usage of MHD_create_response_from_fd_at_offset() is deprecated, use MHD_create_response_from_fd_at_offset64()") \ 4330 MHD_create_response_from_fd_at_offset64 ((size),(fd),(offset)) 4331 #endif /* !_MHD_NO_DEPR_IN_MACRO || _MHD_NO_DEPR_FUNC */ 4332 4333 4334 /** 4335 * Create a response object with the content of provided file with 4336 * specified offset used as the response body. 4337 * 4338 * The response object can be extended with header information and then 4339 * be used any number of times. 4340 * 4341 * If response object is used to answer HEAD request then the body 4342 * of the response is not used, while all headers (including automatic 4343 * headers) are used. 4344 * 4345 * @param size size of the data portion of the response; 4346 * sizes larger than 2 GiB may be not supported by OS or 4347 * MHD build; see ::MHD_FEATURE_LARGE_FILE 4348 * @param fd file descriptor referring to a file on disk with the 4349 * data; will be closed when response is destroyed; 4350 * fd should be in 'blocking' mode 4351 * @param offset offset to start reading from in the file; 4352 * reading file beyond 2 GiB may be not supported by OS or 4353 * MHD build; see ::MHD_FEATURE_LARGE_FILE 4354 * @return NULL on error (i.e. invalid arguments, out of memory) 4355 * @ingroup response 4356 */ 4357 _MHD_EXTERN struct MHD_Response * 4358 MHD_create_response_from_fd_at_offset64 (uint64_t size, 4359 int fd, 4360 uint64_t offset); 4361 4362 4363 /** 4364 * Create a response object with an array of memory buffers 4365 * used as the response body. 4366 * 4367 * The response object can be extended with header information and then 4368 * be used any number of times. 4369 * 4370 * If response object is used to answer HEAD request then the body 4371 * of the response is not used, while all headers (including automatic 4372 * headers) are used. 4373 * 4374 * @param iov the array for response data buffers, an internal copy of this 4375 * will be made 4376 * @param iovcnt the number of elements in @a iov 4377 * @param free_cb the callback to clean up any data associated with @a iov when 4378 * the response is destroyed. 4379 * @param cls the argument passed to @a free_cb 4380 * @return NULL on error (i.e. invalid arguments, out of memory) 4381 * @note Available since #MHD_VERSION 0x00097204 4382 * @ingroup response 4383 */ 4384 _MHD_EXTERN struct MHD_Response * 4385 MHD_create_response_from_iovec (const struct MHD_IoVec *iov, 4386 unsigned int iovcnt, 4387 MHD_ContentReaderFreeCallback free_cb, 4388 void *cls); 4389 4390 4391 /** 4392 * Create a response object with empty (zero size) body. 4393 * 4394 * The response object can be extended with header information and then be used 4395 * any number of times. 4396 * 4397 * This function is a faster equivalent of #MHD_create_response_from_buffer call 4398 * with zero size combined with call of #MHD_set_response_options. 4399 * 4400 * @param flags the flags for the new response object 4401 * @return NULL on error (i.e. invalid arguments, out of memory), 4402 * the pointer to the created response object otherwise 4403 * @note Available since #MHD_VERSION 0x00097701 4404 * @ingroup response 4405 */ 4406 _MHD_EXTERN struct MHD_Response * 4407 MHD_create_response_empty (enum MHD_ResponseFlags flags); 4408 4409 4410 /** 4411 * Enumeration for actions MHD should perform on the underlying socket 4412 * of the upgrade. This API is not finalized, and in particular 4413 * the final set of actions is yet to be decided. This is just an 4414 * idea for what we might want. 4415 */ 4416 enum MHD_UpgradeAction 4417 { 4418 4419 /** 4420 * Close the socket, the application is done with it. 4421 * 4422 * Takes no extra arguments. 4423 */ 4424 MHD_UPGRADE_ACTION_CLOSE = 0, 4425 4426 /** 4427 * Enable CORKing on the underlying socket. 4428 */ 4429 MHD_UPGRADE_ACTION_CORK_ON = 1, 4430 4431 /** 4432 * Disable CORKing on the underlying socket. 4433 */ 4434 MHD_UPGRADE_ACTION_CORK_OFF = 2 4435 4436 } _MHD_FIXED_ENUM; 4437 4438 4439 /** 4440 * Handle given to the application to manage special 4441 * actions relating to MHD responses that "upgrade" 4442 * the HTTP protocol (i.e. to WebSockets). 4443 */ 4444 struct MHD_UpgradeResponseHandle; 4445 4446 4447 /** 4448 * This connection-specific callback is provided by MHD to 4449 * applications (unusual) during the #MHD_UpgradeHandler. 4450 * It allows applications to perform 'special' actions on 4451 * the underlying socket from the upgrade. 4452 * 4453 * @param urh the handle identifying the connection to perform 4454 * the upgrade @a action on. 4455 * @param action which action should be performed 4456 * @param ... arguments to the action (depends on the action) 4457 * @return #MHD_NO on error, #MHD_YES on success 4458 */ 4459 _MHD_EXTERN enum MHD_Result 4460 MHD_upgrade_action (struct MHD_UpgradeResponseHandle *urh, 4461 enum MHD_UpgradeAction action, 4462 ...); 4463 4464 4465 /** 4466 * Function called after a protocol "upgrade" response was sent 4467 * successfully and the socket should now be controlled by some 4468 * protocol other than HTTP. 4469 * 4470 * Any data already received on the socket will be made available in 4471 * @e extra_in. This can happen if the application sent extra data 4472 * before MHD send the upgrade response. The application should 4473 * treat data from @a extra_in as if it had read it from the socket. 4474 * 4475 * Note that the application must not close() @a sock directly, 4476 * but instead use #MHD_upgrade_action() for special operations 4477 * on @a sock. 4478 * 4479 * Data forwarding to "upgraded" @a sock will be started as soon 4480 * as this function return. 4481 * 4482 * Except when in 'thread-per-connection' mode, implementations 4483 * of this function should never block (as it will still be called 4484 * from within the main event loop). 4485 * 4486 * @param cls closure, whatever was given to #MHD_create_response_for_upgrade(). 4487 * @param connection original HTTP connection handle, 4488 * giving the function a last chance 4489 * to inspect the original HTTP request 4490 * @param req_cls last value left in `req_cls` of the `MHD_AccessHandlerCallback` 4491 * @param extra_in if we happened to have read bytes after the 4492 * HTTP header already (because the client sent 4493 * more than the HTTP header of the request before 4494 * we sent the upgrade response), 4495 * these are the extra bytes already read from @a sock 4496 * by MHD. The application should treat these as if 4497 * it had read them from @a sock. 4498 * @param extra_in_size number of bytes in @a extra_in 4499 * @param sock socket to use for bi-directional communication 4500 * with the client. For HTTPS, this may not be a socket 4501 * that is directly connected to the client and thus certain 4502 * operations (TCP-specific setsockopt(), getsockopt(), etc.) 4503 * may not work as expected (as the socket could be from a 4504 * socketpair() or a TCP-loopback). The application is expected 4505 * to perform read()/recv() and write()/send() calls on the socket. 4506 * The application may also call shutdown(), but must not call 4507 * close() directly. 4508 * @param urh argument for #MHD_upgrade_action()s on this @a connection. 4509 * Applications must eventually use this callback to (indirectly) 4510 * perform the close() action on the @a sock. 4511 */ 4512 typedef void 4513 (*MHD_UpgradeHandler)(void *cls, 4514 struct MHD_Connection *connection, 4515 void *req_cls, 4516 const char *extra_in, 4517 size_t extra_in_size, 4518 MHD_socket sock, 4519 struct MHD_UpgradeResponseHandle *urh); 4520 4521 4522 /** 4523 * Create a response object that can be used for 101 UPGRADE 4524 * responses, for example to implement WebSockets. After sending the 4525 * response, control over the data stream is given to the callback (which 4526 * can then, for example, start some bi-directional communication). 4527 * If the response is queued for multiple connections, the callback 4528 * will be called for each connection. The callback 4529 * will ONLY be called after the response header was successfully passed 4530 * to the OS; if there are communication errors before, the usual MHD 4531 * connection error handling code will be performed. 4532 * 4533 * Setting the correct HTTP code (i.e. MHD_HTTP_SWITCHING_PROTOCOLS) 4534 * and setting correct HTTP headers for the upgrade must be done 4535 * manually (this way, it is possible to implement most existing 4536 * WebSocket versions using this API; in fact, this API might be useful 4537 * for any protocol switch, not just WebSockets). Note that 4538 * draft-ietf-hybi-thewebsocketprotocol-00 cannot be implemented this 4539 * way as the header "HTTP/1.1 101 WebSocket Protocol Handshake" 4540 * cannot be generated; instead, MHD will always produce "HTTP/1.1 101 4541 * Switching Protocols" (if the response code 101 is used). 4542 * 4543 * As usual, the response object can be extended with header 4544 * information and then be used any number of times (as long as the 4545 * header information is not connection-specific). 4546 * 4547 * @param upgrade_handler function to call with the "upgraded" socket 4548 * @param upgrade_handler_cls closure for @a upgrade_handler 4549 * @return NULL on error (i.e. invalid arguments, out of memory) 4550 */ 4551 _MHD_EXTERN struct MHD_Response * 4552 MHD_create_response_for_upgrade (MHD_UpgradeHandler upgrade_handler, 4553 void *upgrade_handler_cls); 4554 4555 4556 /** 4557 * Destroy a response object and associated resources. Note that 4558 * libmicrohttpd may keep some of the resources around if the response 4559 * is still in the queue for some clients, so the memory may not 4560 * necessarily be freed immediately. 4561 * 4562 * @param response response to destroy 4563 * @ingroup response 4564 */ 4565 _MHD_EXTERN void 4566 MHD_destroy_response (struct MHD_Response *response); 4567 4568 4569 /** 4570 * Add a header line to the response. 4571 * 4572 * When reply is generated with queued response, some headers are generated 4573 * automatically. Automatically generated headers are only sent to the client, 4574 * but not added back to the response object. 4575 * 4576 * The list of automatic headers: 4577 * + "Date" header is added automatically unless already set by 4578 * this function 4579 * @see #MHD_USE_SUPPRESS_DATE_NO_CLOCK 4580 * + "Content-Length" is added automatically when required, attempt to set 4581 * it manually by this function is ignored. 4582 * @see #MHD_RF_INSANITY_HEADER_CONTENT_LENGTH 4583 * + "Transfer-Encoding" with value "chunked" is added automatically, 4584 * when chunked transfer encoding is used automatically. Same header with 4585 * the same value can be set manually by this function to enforce chunked 4586 * encoding, however for HTTP/1.0 clients chunked encoding will not be used 4587 * and manually set "Transfer-Encoding" header is automatically removed 4588 * for HTTP/1.0 clients 4589 * + "Connection" may be added automatically with value "Keep-Alive" (only 4590 * for HTTP/1.0 clients) or "Close". The header "Connection" with value 4591 * "Close" could be set by this function to enforce closure of 4592 * the connection after sending this response. "Keep-Alive" cannot be 4593 * enforced and will be removed automatically. 4594 * @see #MHD_RF_SEND_KEEP_ALIVE_HEADER 4595 * 4596 * Some headers are pre-processed by this function: 4597 * * "Connection" headers are combined into single header entry, value is 4598 * normilised, "Keep-Alive" tokens are removed. 4599 * * "Transfer-Encoding" header: the only one header is allowed, the only 4600 * allowed value is "chunked". 4601 * * "Date" header: the only one header is allowed, the second added header 4602 * replaces the first one. 4603 * * "Content-Length" application-defined header is not allowed. 4604 * @see #MHD_RF_INSANITY_HEADER_CONTENT_LENGTH 4605 * 4606 * Headers are used in order as they were added. 4607 * 4608 * @param response the response to add a header to 4609 * @param header the header name to add, no need to be static, an internal copy 4610 * will be created automatically 4611 * @param content the header value to add, no need to be static, an internal 4612 * copy will be created automatically 4613 * @return #MHD_YES on success, 4614 * #MHD_NO on error (i.e. invalid header or content format), 4615 * or out of memory 4616 * @ingroup response 4617 */ 4618 _MHD_EXTERN enum MHD_Result 4619 MHD_add_response_header (struct MHD_Response *response, 4620 const char *header, 4621 const char *content); 4622 4623 4624 /** 4625 * Add a footer line to the response. 4626 * 4627 * @param response response to remove a header from 4628 * @param footer the footer to delete 4629 * @param content value to delete 4630 * @return #MHD_NO on error (i.e. invalid footer or content format). 4631 * @ingroup response 4632 */ 4633 _MHD_EXTERN enum MHD_Result 4634 MHD_add_response_footer (struct MHD_Response *response, 4635 const char *footer, 4636 const char *content); 4637 4638 4639 /** 4640 * Delete a header (or footer) line from the response. 4641 * 4642 * For "Connection" headers this function remove all tokens from existing 4643 * value. Successful result means that at least one token has been removed. 4644 * If all tokens are removed from "Connection" header, the empty "Connection" 4645 * header removed. 4646 * 4647 * @param response response to remove a header from 4648 * @param header the header to delete 4649 * @param content value to delete 4650 * @return #MHD_NO on error (no such header known) 4651 * @ingroup response 4652 */ 4653 _MHD_EXTERN enum MHD_Result 4654 MHD_del_response_header (struct MHD_Response *response, 4655 const char *header, 4656 const char *content); 4657 4658 4659 /** 4660 * Get all of the headers (and footers) added to a response. 4661 * 4662 * @param response response to query 4663 * @param iterator callback to call on each header; 4664 * may be NULL (then just count headers) 4665 * @param iterator_cls extra argument to @a iterator 4666 * @return number of entries iterated over 4667 * @ingroup response 4668 */ 4669 _MHD_EXTERN int 4670 MHD_get_response_headers (struct MHD_Response *response, 4671 MHD_KeyValueIterator iterator, 4672 void *iterator_cls); 4673 4674 4675 /** 4676 * Get a particular header (or footer) from the response. 4677 * 4678 * @param response response to query 4679 * @param key which header to get 4680 * @return NULL if header does not exist 4681 * @ingroup response 4682 */ 4683 _MHD_EXTERN const char * 4684 MHD_get_response_header (struct MHD_Response *response, 4685 const char *key); 4686 4687 4688 /* ********************** PostProcessor functions ********************** */ 4689 4690 /** 4691 * Create a `struct MHD_PostProcessor`. 4692 * 4693 * A `struct MHD_PostProcessor` can be used to (incrementally) parse 4694 * the data portion of a POST request. Note that some buggy browsers 4695 * fail to set the encoding type. If you want to support those, you 4696 * may have to call #MHD_set_connection_value with the proper encoding 4697 * type before creating a post processor (if no supported encoding 4698 * type is set, this function will fail). 4699 * 4700 * @param connection the connection on which the POST is 4701 * happening (used to determine the POST format) 4702 * @param buffer_size maximum number of bytes to use for 4703 * internal buffering (used only for the parsing, 4704 * specifically the parsing of the keys). A 4705 * tiny value (256-1024) should be sufficient. 4706 * Do NOT use a value smaller than 256. For good 4707 * performance, use 32 or 64k (i.e. 65536). 4708 * @param iter iterator to be called with the parsed data, 4709 * Must NOT be NULL. 4710 * @param iter_cls first argument to @a iter 4711 * @return NULL on error (out of memory, unsupported encoding), 4712 * otherwise a PP handle 4713 * @ingroup request 4714 */ 4715 _MHD_EXTERN struct MHD_PostProcessor * 4716 MHD_create_post_processor (struct MHD_Connection *connection, 4717 size_t buffer_size, 4718 MHD_PostDataIterator iter, void *iter_cls); 4719 4720 4721 /** 4722 * Parse and process POST data. Call this function when POST data is 4723 * available (usually during an #MHD_AccessHandlerCallback) with the 4724 * "upload_data" and "upload_data_size". Whenever possible, this will 4725 * then cause calls to the #MHD_PostDataIterator. 4726 * 4727 * @param pp the post processor 4728 * @param post_data @a post_data_len bytes of POST data 4729 * @param post_data_len length of @a post_data 4730 * @return #MHD_YES on success, #MHD_NO on error 4731 * (out-of-memory, iterator aborted, parse error) 4732 * @ingroup request 4733 */ 4734 _MHD_EXTERN enum MHD_Result 4735 MHD_post_process (struct MHD_PostProcessor *pp, 4736 const char *post_data, 4737 size_t post_data_len); 4738 4739 4740 /** 4741 * Release PostProcessor resources. 4742 * 4743 * @param pp the PostProcessor to destroy 4744 * @return #MHD_YES if processing completed nicely, 4745 * #MHD_NO if there were spurious characters / formatting 4746 * problems; it is common to ignore the return 4747 * value of this function 4748 * @ingroup request 4749 */ 4750 _MHD_EXTERN enum MHD_Result 4751 MHD_destroy_post_processor (struct MHD_PostProcessor *pp); 4752 4753 4754 /* ********************* Digest Authentication functions *************** */ 4755 4756 4757 /** 4758 * Length of the binary output of the MD5 hash function. 4759 * @sa #MHD_digest_get_hash_size() 4760 * @ingroup authentication 4761 */ 4762 #define MHD_MD5_DIGEST_SIZE 16 4763 4764 /** 4765 * Length of the binary output of the SHA-256 hash function. 4766 * @sa #MHD_digest_get_hash_size() 4767 * @ingroup authentication 4768 */ 4769 #define MHD_SHA256_DIGEST_SIZE 32 4770 4771 /** 4772 * Length of the binary output of the SHA-512/256 hash function. 4773 * @warning While this value is the same as the #MHD_SHA256_DIGEST_SIZE, 4774 * the calculated digests for SHA-256 and SHA-512/256 are different. 4775 * @sa #MHD_digest_get_hash_size() 4776 * @note Available since #MHD_VERSION 0x00097701 4777 * @ingroup authentication 4778 */ 4779 #define MHD_SHA512_256_DIGEST_SIZE 32 4780 4781 /** 4782 * Base type of hash calculation. 4783 * Used as part of #MHD_DigestAuthAlgo3 values. 4784 * 4785 * @warning Not used directly by MHD API. 4786 * @note Available since #MHD_VERSION 0x00097701 4787 */ 4788 enum MHD_DigestBaseAlgo 4789 { 4790 /** 4791 * Invalid hash algorithm value 4792 */ 4793 MHD_DIGEST_BASE_ALGO_INVALID = 0, 4794 4795 /** 4796 * MD5 hash algorithm. 4797 * As specified by RFC1321 4798 */ 4799 MHD_DIGEST_BASE_ALGO_MD5 = (1 << 0), 4800 4801 /** 4802 * SHA-256 hash algorithm. 4803 * As specified by FIPS PUB 180-4 4804 */ 4805 MHD_DIGEST_BASE_ALGO_SHA256 = (1 << 1), 4806 4807 /** 4808 * SHA-512/256 hash algorithm. 4809 * As specified by FIPS PUB 180-4 4810 */ 4811 MHD_DIGEST_BASE_ALGO_SHA512_256 = (1 << 2) 4812 } _MHD_FIXED_FLAGS_ENUM; 4813 4814 /** 4815 * The flag indicating non-session algorithm types, 4816 * like 'MD5', 'SHA-256' or 'SHA-512-256'. 4817 * @note Available since #MHD_VERSION 0x00097701 4818 */ 4819 #define MHD_DIGEST_AUTH_ALGO3_NON_SESSION (1 << 6) 4820 4821 /** 4822 * The flag indicating session algorithm types, 4823 * like 'MD5-sess', 'SHA-256-sess' or 'SHA-512-256-sess'. 4824 * @note Available since #MHD_VERSION 0x00097701 4825 */ 4826 #define MHD_DIGEST_AUTH_ALGO3_SESSION (1 << 7) 4827 4828 /** 4829 * Digest algorithm identification 4830 * @warning Do not be confused with #MHD_DigestAuthAlgorithm, 4831 * which uses other values! 4832 * @note Available since #MHD_VERSION 0x00097701 4833 */ 4834 enum MHD_DigestAuthAlgo3 4835 { 4836 /** 4837 * Unknown or wrong algorithm type. 4838 * Used in struct MHD_DigestAuthInfo to indicate client value that 4839 * cannot by identified. 4840 */ 4841 MHD_DIGEST_AUTH_ALGO3_INVALID = 0, 4842 4843 /** 4844 * The 'MD5' algorithm, non-session version. 4845 */ 4846 MHD_DIGEST_AUTH_ALGO3_MD5 = 4847 MHD_DIGEST_BASE_ALGO_MD5 | MHD_DIGEST_AUTH_ALGO3_NON_SESSION, 4848 4849 /** 4850 * The 'MD5-sess' algorithm. 4851 * Not supported by MHD for authentication. 4852 */ 4853 MHD_DIGEST_AUTH_ALGO3_MD5_SESSION = 4854 MHD_DIGEST_BASE_ALGO_MD5 | MHD_DIGEST_AUTH_ALGO3_SESSION, 4855 4856 /** 4857 * The 'SHA-256' algorithm, non-session version. 4858 */ 4859 MHD_DIGEST_AUTH_ALGO3_SHA256 = 4860 MHD_DIGEST_BASE_ALGO_SHA256 | MHD_DIGEST_AUTH_ALGO3_NON_SESSION, 4861 4862 /** 4863 * The 'SHA-256-sess' algorithm. 4864 * Not supported by MHD for authentication. 4865 */ 4866 MHD_DIGEST_AUTH_ALGO3_SHA256_SESSION = 4867 MHD_DIGEST_BASE_ALGO_SHA256 | MHD_DIGEST_AUTH_ALGO3_SESSION, 4868 4869 /** 4870 * The 'SHA-512-256' (SHA-512/256) algorithm. 4871 */ 4872 MHD_DIGEST_AUTH_ALGO3_SHA512_256 = 4873 MHD_DIGEST_BASE_ALGO_SHA512_256 | MHD_DIGEST_AUTH_ALGO3_NON_SESSION, 4874 4875 /** 4876 * The 'SHA-512-256-sess' (SHA-512/256 session) algorithm. 4877 * Not supported by MHD for authentication. 4878 */ 4879 MHD_DIGEST_AUTH_ALGO3_SHA512_256_SESSION = 4880 MHD_DIGEST_BASE_ALGO_SHA512_256 | MHD_DIGEST_AUTH_ALGO3_SESSION 4881 }; 4882 4883 4884 /** 4885 * Get digest size for specified algorithm. 4886 * 4887 * The size of the digest specifies the size of the userhash, userdigest 4888 * and other parameters which size depends on used hash algorithm. 4889 * @param algo3 the algorithm to check 4890 * @return the size of the digest (either #MHD_MD5_DIGEST_SIZE or 4891 * #MHD_SHA256_DIGEST_SIZE/MHD_SHA512_256_DIGEST_SIZE) 4892 * or zero if the input value is not supported or not valid 4893 * @sa #MHD_digest_auth_calc_userdigest() 4894 * @sa #MHD_digest_auth_calc_userhash(), #MHD_digest_auth_calc_userhash_hex() 4895 * @note Available since #MHD_VERSION 0x00097701 4896 * @ingroup authentication 4897 */ 4898 _MHD_EXTERN size_t 4899 MHD_digest_get_hash_size (enum MHD_DigestAuthAlgo3 algo3); 4900 4901 /** 4902 * Digest algorithm identification, allow multiple selection. 4903 * 4904 * #MHD_DigestAuthAlgo3 always can be casted to #MHD_DigestAuthMultiAlgo3, but 4905 * not vice versa. 4906 * 4907 * @note Available since #MHD_VERSION 0x00097701 4908 */ 4909 enum MHD_DigestAuthMultiAlgo3 4910 { 4911 /** 4912 * Unknown or wrong algorithm type. 4913 */ 4914 MHD_DIGEST_AUTH_MULT_ALGO3_INVALID = MHD_DIGEST_AUTH_ALGO3_INVALID, 4915 4916 /** 4917 * The 'MD5' algorithm, non-session version. 4918 */ 4919 MHD_DIGEST_AUTH_MULT_ALGO3_MD5 = MHD_DIGEST_AUTH_ALGO3_MD5, 4920 4921 /** 4922 * The 'MD5-sess' algorithm. 4923 * Not supported by MHD for authentication. 4924 * Reserved value. 4925 */ 4926 MHD_DIGEST_AUTH_MULT_ALGO3_MD5_SESSION = MHD_DIGEST_AUTH_ALGO3_MD5_SESSION, 4927 4928 /** 4929 * The 'SHA-256' algorithm, non-session version. 4930 */ 4931 MHD_DIGEST_AUTH_MULT_ALGO3_SHA256 = MHD_DIGEST_AUTH_ALGO3_SHA256, 4932 4933 /** 4934 * The 'SHA-256-sess' algorithm. 4935 * Not supported by MHD for authentication. 4936 * Reserved value. 4937 */ 4938 MHD_DIGEST_AUTH_MULT_ALGO3_SHA256_SESSION = 4939 MHD_DIGEST_AUTH_ALGO3_SHA256_SESSION, 4940 4941 /** 4942 * The 'SHA-512-256' (SHA-512/256) algorithm, non-session version. 4943 */ 4944 MHD_DIGEST_AUTH_MULT_ALGO3_SHA512_256 = MHD_DIGEST_AUTH_ALGO3_SHA512_256, 4945 4946 /** 4947 * The 'SHA-512-256-sess' (SHA-512/256 session) algorithm. 4948 * Not supported by MHD for authentication. 4949 * Reserved value. 4950 */ 4951 MHD_DIGEST_AUTH_MULT_ALGO3_SHA512_256_SESSION = 4952 MHD_DIGEST_AUTH_ALGO3_SHA512_256_SESSION, 4953 4954 /** 4955 * SHA-256 or SHA-512/256 non-session algorithm, MHD will choose 4956 * the preferred or the matching one. 4957 */ 4958 MHD_DIGEST_AUTH_MULT_ALGO3_SHA_ANY_NON_SESSION = 4959 MHD_DIGEST_AUTH_ALGO3_SHA256 | MHD_DIGEST_AUTH_ALGO3_SHA512_256, 4960 4961 /** 4962 * Any non-session algorithm, MHD will choose the preferred or 4963 * the matching one. 4964 */ 4965 MHD_DIGEST_AUTH_MULT_ALGO3_ANY_NON_SESSION = 4966 (0x3F) | MHD_DIGEST_AUTH_ALGO3_NON_SESSION, 4967 4968 /** 4969 * The SHA-256 or SHA-512/256 session algorithm. 4970 * Not supported by MHD. 4971 * Reserved value. 4972 */ 4973 MHD_DIGEST_AUTH_MULT_ALGO3_SHA_ANY_SESSION = 4974 MHD_DIGEST_AUTH_ALGO3_SHA256_SESSION 4975 | MHD_DIGEST_AUTH_ALGO3_SHA512_256_SESSION, 4976 4977 /** 4978 * Any session algorithm. 4979 * Not supported by MHD. 4980 * Reserved value. 4981 */ 4982 MHD_DIGEST_AUTH_MULT_ALGO3_ANY_SESSION = 4983 (0x3F) | MHD_DIGEST_AUTH_ALGO3_SESSION, 4984 4985 /** 4986 * The MD5 algorithm, session or non-session. 4987 * Currently supported as non-session only. 4988 */ 4989 MHD_DIGEST_AUTH_MULT_ALGO3_MD5_ANY = 4990 MHD_DIGEST_AUTH_MULT_ALGO3_MD5 | MHD_DIGEST_AUTH_MULT_ALGO3_MD5_SESSION, 4991 4992 /** 4993 * The SHA-256 algorithm, session or non-session. 4994 * Currently supported as non-session only. 4995 */ 4996 MHD_DIGEST_AUTH_MULT_ALGO3_SHA256_ANY = 4997 MHD_DIGEST_AUTH_MULT_ALGO3_SHA256 4998 | MHD_DIGEST_AUTH_MULT_ALGO3_SHA256_SESSION, 4999 5000 /** 5001 * The SHA-512/256 algorithm, session or non-session. 5002 * Currently supported as non-session only. 5003 */ 5004 MHD_DIGEST_AUTH_MULT_ALGO3_SHA512_256_ANY = 5005 MHD_DIGEST_AUTH_MULT_ALGO3_SHA512_256 5006 | MHD_DIGEST_AUTH_MULT_ALGO3_SHA512_256_SESSION, 5007 5008 /** 5009 * The SHA-256 or SHA-512/256 algorithm, session or non-session. 5010 * Currently supported as non-session only. 5011 */ 5012 MHD_DIGEST_AUTH_MULT_ALGO3_SHA_ANY_ANY = 5013 MHD_DIGEST_AUTH_MULT_ALGO3_SHA_ANY_NON_SESSION 5014 | MHD_DIGEST_AUTH_MULT_ALGO3_SHA_ANY_SESSION, 5015 5016 /** 5017 * Any algorithm, MHD will choose the preferred or the matching one. 5018 */ 5019 MHD_DIGEST_AUTH_MULT_ALGO3_ANY = 5020 (0x3F) | MHD_DIGEST_AUTH_ALGO3_NON_SESSION | MHD_DIGEST_AUTH_ALGO3_SESSION 5021 }; 5022 5023 5024 /** 5025 * Calculate "userhash", return it as binary data. 5026 * 5027 * The "userhash" is the hash of the string "username:realm". 5028 * 5029 * The "userhash" could be used to avoid sending username in cleartext in Digest 5030 * Authorization client's header. 5031 * 5032 * Userhash is not designed to hide the username in local database or files, 5033 * as username in cleartext is required for #MHD_digest_auth_check3() function 5034 * to check the response, but it can be used to hide username in HTTP headers. 5035 * 5036 * This function could be used when the new username is added to the username 5037 * database to save the "userhash" alongside with the username (preferably) or 5038 * when loading list of the usernames to generate the userhash for every loaded 5039 * username (this will cause delays at the start with the long lists). 5040 * 5041 * Once "userhash" is generated it could be used to identify users by clients 5042 * with "userhash" support. 5043 * Avoid repetitive usage of this function for the same username/realm 5044 * combination as it will cause excessive CPU load; save and re-use the result 5045 * instead. 5046 * 5047 * @param algo3 the algorithm for userhash calculations 5048 * @param username the username 5049 * @param realm the realm 5050 * @param[out] userhash_bin the output buffer for userhash as binary data; 5051 * if this function succeeds, then this buffer has 5052 * #MHD_digest_get_hash_size(algo3) bytes of userhash 5053 * upon return 5054 * @param bin_buf_size the size of the @a userhash_bin buffer, must be 5055 * at least #MHD_digest_get_hash_size(algo3) bytes long 5056 * @return MHD_YES on success, 5057 * MHD_NO if @a bin_buf_size is too small or if @a algo3 algorithm is 5058 * not supported (or external error has occurred, 5059 * see #MHD_FEATURE_EXTERN_HASH) 5060 * @sa #MHD_digest_auth_calc_userhash_hex() 5061 * @note Available since #MHD_VERSION 0x00097701 5062 * @ingroup authentication 5063 */ 5064 _MHD_EXTERN enum MHD_Result 5065 MHD_digest_auth_calc_userhash (enum MHD_DigestAuthAlgo3 algo3, 5066 const char *username, 5067 const char *realm, 5068 void *userhash_bin, 5069 size_t bin_buf_size); 5070 5071 5072 /** 5073 * Calculate "userhash", return it as hexadecimal string. 5074 * 5075 * The "userhash" is the hash of the string "username:realm". 5076 * 5077 * The "userhash" could be used to avoid sending username in cleartext in Digest 5078 * Authorization client's header. 5079 * 5080 * Userhash is not designed to hide the username in local database or files, 5081 * as username in cleartext is required for #MHD_digest_auth_check3() function 5082 * to check the response, but it can be used to hide username in HTTP headers. 5083 * 5084 * This function could be used when the new username is added to the username 5085 * database to save the "userhash" alongside with the username (preferably) or 5086 * when loading list of the usernames to generate the userhash for every loaded 5087 * username (this will cause delays at the start with the long lists). 5088 * 5089 * Once "userhash" is generated it could be used to identify users by clients 5090 * with "userhash" support. 5091 * Avoid repetitive usage of this function for the same username/realm 5092 * combination as it will cause excessive CPU load; save and re-use the result 5093 * instead. 5094 * 5095 * @param algo3 the algorithm for userhash calculations 5096 * @param username the username 5097 * @param realm the realm 5098 * @param[out] userhash_hex the output buffer for userhash as hex string; 5099 * if this function succeeds, then this buffer has 5100 * #MHD_digest_get_hash_size(algo3)*2 chars long 5101 * userhash zero-terminated string 5102 * @param bin_buf_size the size of the @a userhash_bin buffer, must be 5103 * at least #MHD_digest_get_hash_size(algo3)*2+1 chars long 5104 * @return MHD_YES on success, 5105 * MHD_NO if @a bin_buf_size is too small or if @a algo3 algorithm is 5106 * not supported (or external error has occurred, 5107 * see #MHD_FEATURE_EXTERN_HASH). 5108 * @sa #MHD_digest_auth_calc_userhash() 5109 * @note Available since #MHD_VERSION 0x00097701 5110 * @ingroup authentication 5111 */ 5112 _MHD_EXTERN enum MHD_Result 5113 MHD_digest_auth_calc_userhash_hex (enum MHD_DigestAuthAlgo3 algo3, 5114 const char *username, 5115 const char *realm, 5116 char *userhash_hex, 5117 size_t hex_buf_size); 5118 5119 5120 /** 5121 * The type of username used by client in Digest Authorization header 5122 * 5123 * Values are sorted so simplified checks could be used. 5124 * For example: 5125 * * (value <= MHD_DIGEST_AUTH_UNAME_TYPE_INVALID) is true if no valid username 5126 * is provided by the client 5127 * * (value >= MHD_DIGEST_AUTH_UNAME_TYPE_USERHASH) is true if username is 5128 * provided in any form 5129 * * (value >= MHD_DIGEST_AUTH_UNAME_TYPE_STANDARD) is true if username is 5130 * provided in clear text (no userhash matching is needed) 5131 * 5132 * @note Available since #MHD_VERSION 0x00097701 5133 */ 5134 enum MHD_DigestAuthUsernameType 5135 { 5136 /** 5137 * No username parameter in in Digest Authorization header. 5138 * This should be treated as an error. 5139 */ 5140 MHD_DIGEST_AUTH_UNAME_TYPE_MISSING = 0, 5141 5142 /** 5143 * The 'username' parameter is used to specify the username. 5144 */ 5145 MHD_DIGEST_AUTH_UNAME_TYPE_STANDARD = (1 << 2), 5146 5147 /** 5148 * The username is specified by 'username*' parameter with 5149 * the extended notation (see RFC 5987 #section-3.2.1). 5150 * The only difference between standard and extended types is 5151 * the way how username value is encoded in the header. 5152 */ 5153 MHD_DIGEST_AUTH_UNAME_TYPE_EXTENDED = (1 << 3), 5154 5155 /** 5156 * The username provided in form of 'userhash' as 5157 * specified by RFC 7616 #section-3.4.4. 5158 * @sa #MHD_digest_auth_calc_userhash_hex(), #MHD_digest_auth_calc_userhash() 5159 */ 5160 MHD_DIGEST_AUTH_UNAME_TYPE_USERHASH = (1 << 1), 5161 5162 /** 5163 * The invalid combination of username parameters are used by client. 5164 * Either: 5165 * * both 'username' and 'username*' are used 5166 * * 'username*' is used with 'userhash=true' 5167 * * 'username*' used with invalid extended notation 5168 * * 'username' is not hexadecimal string, while 'userhash' set to 'true' 5169 */ 5170 MHD_DIGEST_AUTH_UNAME_TYPE_INVALID = (1 << 0) 5171 } _MHD_FIXED_ENUM; 5172 5173 /** 5174 * The QOP ('quality of protection') types. 5175 * @note Available since #MHD_VERSION 0x00097701 5176 */ 5177 enum MHD_DigestAuthQOP 5178 { 5179 /** 5180 * Invalid/unknown QOP. 5181 * Used in struct MHD_DigestAuthInfo to indicate client value that 5182 * cannot by identified. 5183 */ 5184 MHD_DIGEST_AUTH_QOP_INVALID = 0, 5185 5186 /** 5187 * No QOP parameter. 5188 * As described in old RFC 2069 original specification. 5189 * This mode is not allowed by latest RFCs and should be used only to 5190 * communicate with clients that do not support more modern modes (with QOP 5191 * parameter). 5192 * This mode is less secure than other modes and inefficient. 5193 */ 5194 MHD_DIGEST_AUTH_QOP_NONE = 1 << 0, 5195 5196 /** 5197 * The 'auth' QOP type. 5198 */ 5199 MHD_DIGEST_AUTH_QOP_AUTH = 1 << 1, 5200 5201 /** 5202 * The 'auth-int' QOP type. 5203 * Not supported by MHD for authentication. 5204 */ 5205 MHD_DIGEST_AUTH_QOP_AUTH_INT = 1 << 2 5206 } _MHD_FIXED_FLAGS_ENUM; 5207 5208 /** 5209 * The QOP ('quality of protection') types, multiple selection. 5210 * 5211 * #MHD_DigestAuthQOP always can be casted to #MHD_DigestAuthMultiQOP, but 5212 * not vice versa. 5213 * 5214 * @note Available since #MHD_VERSION 0x00097701 5215 */ 5216 enum MHD_DigestAuthMultiQOP 5217 { 5218 /** 5219 * Invalid/unknown QOP. 5220 */ 5221 MHD_DIGEST_AUTH_MULT_QOP_INVALID = MHD_DIGEST_AUTH_QOP_INVALID, 5222 5223 /** 5224 * No QOP parameter. 5225 * As described in old RFC 2069 original specification. 5226 * This mode is not allowed by latest RFCs and should be used only to 5227 * communicate with clients that do not support more modern modes (with QOP 5228 * parameter). 5229 * This mode is less secure than other modes and inefficient. 5230 */ 5231 MHD_DIGEST_AUTH_MULT_QOP_NONE = MHD_DIGEST_AUTH_QOP_NONE, 5232 5233 /** 5234 * The 'auth' QOP type. 5235 */ 5236 MHD_DIGEST_AUTH_MULT_QOP_AUTH = MHD_DIGEST_AUTH_QOP_AUTH, 5237 5238 /** 5239 * The 'auth-int' QOP type. 5240 * Not supported by MHD. 5241 * Reserved value. 5242 */ 5243 MHD_DIGEST_AUTH_MULT_QOP_AUTH_INT = MHD_DIGEST_AUTH_QOP_AUTH_INT, 5244 5245 /** 5246 * The 'auth' QOP type OR the old RFC2069 (no QOP) type. 5247 * In other words: any types except 'auth-int'. 5248 * RFC2069-compatible mode is allowed, thus this value should be used only 5249 * when it is really necessary. 5250 */ 5251 MHD_DIGEST_AUTH_MULT_QOP_ANY_NON_INT = 5252 MHD_DIGEST_AUTH_QOP_NONE | MHD_DIGEST_AUTH_QOP_AUTH, 5253 5254 /** 5255 * Any 'auth' QOP type ('auth' or 'auth-int'). 5256 * Currently supported as 'auth' QOP type only. 5257 */ 5258 MHD_DIGEST_AUTH_MULT_QOP_AUTH_ANY = 5259 MHD_DIGEST_AUTH_QOP_AUTH | MHD_DIGEST_AUTH_QOP_AUTH_INT 5260 } _MHD_FIXED_ENUM; 5261 5262 /** 5263 * The invalid value of 'nc' parameter in client Digest Authorization header. 5264 * @note Available since #MHD_VERSION 0x00097701 5265 */ 5266 #define MHD_DIGEST_AUTH_INVALID_NC_VALUE (0) 5267 5268 /** 5269 * Information from Digest Authorization client's header. 5270 * 5271 * All buffers pointed by any struct members are freed when #MHD_free() is 5272 * called for pointer to this structure. 5273 * 5274 * Application may modify buffers as needed until #MHD_free() is called for 5275 * pointer to this structure 5276 * @note Available since #MHD_VERSION 0x00097701 5277 */ 5278 struct MHD_DigestAuthInfo 5279 { 5280 /** 5281 * The algorithm as defined by client. 5282 * Set automatically to MD5 if not specified by client. 5283 * @warning Do not be confused with #MHD_DigestAuthAlgorithm, 5284 * which uses other values! 5285 */ 5286 enum MHD_DigestAuthAlgo3 algo3; 5287 5288 /** 5289 * The type of username used by client. 5290 */ 5291 enum MHD_DigestAuthUsernameType uname_type; 5292 5293 /** 5294 * The username string. 5295 * Used only if username type is standard or extended, always NULL otherwise. 5296 * If extended notation is used, this string is pct-decoded string 5297 * with charset and language tag removed (i.e. it is original username 5298 * extracted from the extended notation). 5299 * When userhash is used by the client, this member is NULL and 5300 * @a userhash_hex and @a userhash_bin are set. 5301 * The buffer pointed by the @a username becomes invalid when the pointer 5302 * to the structure is freed by #MHD_free(). 5303 */ 5304 char *username; 5305 5306 /** 5307 * The length of the @a username. 5308 * When the @a username is NULL, this member is always zero. 5309 */ 5310 size_t username_len; 5311 5312 /** 5313 * The userhash string. 5314 * Valid only if username type is userhash. 5315 * This is unqoted string without decoding of the hexadecimal 5316 * digits (as provided by the client). 5317 * The buffer pointed by the @a userhash_hex becomes invalid when the pointer 5318 * to the structure is freed by #MHD_free(). 5319 * @sa #MHD_digest_auth_calc_userhash_hex() 5320 */ 5321 char *userhash_hex; 5322 5323 /** 5324 * The length of the @a userhash_hex in characters. 5325 * The valid size should be #MHD_digest_get_hash_size(algo3) * 2 characters. 5326 * When the @a userhash_hex is NULL, this member is always zero. 5327 */ 5328 size_t userhash_hex_len; 5329 5330 /** 5331 * The userhash decoded to binary form. 5332 * Used only if username type is userhash, always NULL otherwise. 5333 * When not NULL, this points to binary sequence @a userhash_hex_len /2 bytes 5334 * long. 5335 * The valid size should be #MHD_digest_get_hash_size(algo3) bytes. 5336 * The buffer pointed by the @a userhash_bin becomes invalid when the pointer 5337 * to the structure is freed by #MHD_free(). 5338 * @warning This is a binary data, no zero termination. 5339 * @warning To avoid buffer overruns, always check the size of the data before 5340 * use, because @a userhash_bin can point even to zero-sized 5341 * data. 5342 * @sa #MHD_digest_auth_calc_userhash() 5343 */ 5344 uint8_t *userhash_bin; 5345 5346 /** 5347 * The 'opaque' parameter value, as specified by client. 5348 * NULL if not specified by client. 5349 * The buffer pointed by the @a opaque becomes invalid when the pointer 5350 * to the structure is freed by #MHD_free(). 5351 */ 5352 char *opaque; 5353 5354 /** 5355 * The length of the @a opaque. 5356 * When the @a opaque is NULL, this member is always zero. 5357 */ 5358 size_t opaque_len; 5359 5360 /** 5361 * The 'realm' parameter value, as specified by client. 5362 * NULL if not specified by client. 5363 * The buffer pointed by the @a realm becomes invalid when the pointer 5364 * to the structure is freed by #MHD_free(). 5365 */ 5366 char *realm; 5367 5368 /** 5369 * The length of the @a realm. 5370 * When the @a realm is NULL, this member is always zero. 5371 */ 5372 size_t realm_len; 5373 5374 /** 5375 * The 'qop' parameter value. 5376 */ 5377 enum MHD_DigestAuthQOP qop; 5378 5379 /** 5380 * The length of the 'cnonce' parameter value, including possible 5381 * backslash-escape characters. 5382 * 'cnonce' is used in hash calculation, which is CPU-intensive procedure. 5383 * An application may want to reject too large cnonces to limit the CPU load. 5384 * A few kilobytes is a reasonable limit, typically cnonce is just 32-160 5385 * characters long. 5386 */ 5387 size_t cnonce_len; 5388 5389 /** 5390 * The nc parameter value. 5391 * Can be used by application to limit the number of nonce re-uses. If @a nc 5392 * is higher than application wants to allow, then "auth required" response 5393 * with 'stale=true' could be used to force client to retry with the fresh 5394 * 'nonce'. 5395 * If not specified by client or does not have hexadecimal digits only, the 5396 * value is #MHD_DIGEST_AUTH_INVALID_NC_VALUE. 5397 */ 5398 uint32_t nc; 5399 }; 5400 5401 5402 /** 5403 * Get information about Digest Authorization client's header. 5404 * 5405 * @param connection The MHD connection structure 5406 * @return NULL if no valid Digest Authorization header is used in the request; 5407 * a pointer to the structure with information if the valid request 5408 * header found, free using #MHD_free(). 5409 * @sa #MHD_digest_auth_get_username3() 5410 * @note Available since #MHD_VERSION 0x00097701 5411 * @ingroup authentication 5412 */ 5413 _MHD_EXTERN struct MHD_DigestAuthInfo * 5414 MHD_digest_auth_get_request_info3 (struct MHD_Connection *connection); 5415 5416 5417 /** 5418 * Information from Digest Authorization client's header. 5419 * 5420 * All buffers pointed by any struct members are freed when #MHD_free() is 5421 * called for pointer to this structure. 5422 * 5423 * Application may modify buffers as needed until #MHD_free() is called for 5424 * pointer to this structure 5425 * @note Available since #MHD_VERSION 0x00097701 5426 */ 5427 struct MHD_DigestAuthUsernameInfo 5428 { 5429 /** 5430 * The algorithm as defined by client. 5431 * Set automatically to MD5 if not specified by client. 5432 * @warning Do not be confused with #MHD_DigestAuthAlgorithm, 5433 * which uses other values! 5434 */ 5435 enum MHD_DigestAuthAlgo3 algo3; 5436 5437 /** 5438 * The type of username used by client. 5439 * The 'invalid' and 'missing' types are not used in this structure, 5440 * instead NULL is returned by #MHD_digest_auth_get_username3(). 5441 */ 5442 enum MHD_DigestAuthUsernameType uname_type; 5443 5444 /** 5445 * The username string. 5446 * Used only if username type is standard or extended, always NULL otherwise. 5447 * If extended notation is used, this string is pct-decoded string 5448 * with charset and language tag removed (i.e. it is original username 5449 * extracted from the extended notation). 5450 * When userhash is used by the client, this member is NULL and 5451 * @a userhash_hex and @a userhash_bin are set. 5452 * The buffer pointed by the @a username becomes invalid when the pointer 5453 * to the structure is freed by #MHD_free(). 5454 */ 5455 char *username; 5456 5457 /** 5458 * The length of the @a username. 5459 * When the @a username is NULL, this member is always zero. 5460 */ 5461 size_t username_len; 5462 5463 /** 5464 * The userhash string. 5465 * Valid only if username type is userhash. 5466 * This is unqoted string without decoding of the hexadecimal 5467 * digits (as provided by the client). 5468 * The buffer pointed by the @a userhash_hex becomes invalid when the pointer 5469 * to the structure is freed by #MHD_free(). 5470 * @sa #MHD_digest_auth_calc_userhash_hex() 5471 */ 5472 char *userhash_hex; 5473 5474 /** 5475 * The length of the @a userhash_hex in characters. 5476 * The valid size should be #MHD_digest_get_hash_size(algo3) * 2 characters. 5477 * When the @a userhash_hex is NULL, this member is always zero. 5478 */ 5479 size_t userhash_hex_len; 5480 5481 /** 5482 * The userhash decoded to binary form. 5483 * Used only if username type is userhash, always NULL otherwise. 5484 * When not NULL, this points to binary sequence @a userhash_hex_len /2 bytes 5485 * long. 5486 * The valid size should be #MHD_digest_get_hash_size(algo3) bytes. 5487 * The buffer pointed by the @a userhash_bin becomes invalid when the pointer 5488 * to the structure is freed by #MHD_free(). 5489 * @warning This is a binary data, no zero termination. 5490 * @warning To avoid buffer overruns, always check the size of the data before 5491 * use, because @a userhash_bin can point even to zero-sized 5492 * data. 5493 * @sa #MHD_digest_auth_calc_userhash() 5494 */ 5495 uint8_t *userhash_bin; 5496 }; 5497 5498 5499 /** 5500 * Get the username from Digest Authorization client's header. 5501 * 5502 * @param connection The MHD connection structure 5503 * @return NULL if no valid Digest Authorization header is used in the request, 5504 * or no username parameter is present in the header, or username is 5505 * provided incorrectly by client (see description for 5506 * #MHD_DIGEST_AUTH_UNAME_TYPE_INVALID); 5507 * a pointer structure with information if the valid request header 5508 * found, free using #MHD_free(). 5509 * @sa #MHD_digest_auth_get_request_info3() provides more complete information 5510 * @note Available since #MHD_VERSION 0x00097701 5511 * @ingroup authentication 5512 */ 5513 _MHD_EXTERN struct MHD_DigestAuthUsernameInfo * 5514 MHD_digest_auth_get_username3 (struct MHD_Connection *connection); 5515 5516 5517 /** 5518 * The result of digest authentication of the client. 5519 * 5520 * All error values are zero or negative. 5521 * 5522 * @note Available since #MHD_VERSION 0x00097701 5523 */ 5524 enum MHD_DigestAuthResult 5525 { 5526 /** 5527 * Authentication OK. 5528 */ 5529 MHD_DAUTH_OK = 1, 5530 5531 /** 5532 * General error, like "out of memory". 5533 */ 5534 MHD_DAUTH_ERROR = 0, 5535 5536 /** 5537 * No "Authorization" header or wrong format of the header. 5538 * Also may be returned if required parameters in client Authorisation header 5539 * are missing or broken (in invalid format). 5540 */ 5541 MHD_DAUTH_WRONG_HEADER = -1, 5542 5543 /** 5544 * Wrong 'username'. 5545 */ 5546 MHD_DAUTH_WRONG_USERNAME = -2, 5547 5548 /** 5549 * Wrong 'realm'. 5550 */ 5551 MHD_DAUTH_WRONG_REALM = -3, 5552 5553 /** 5554 * Wrong 'URI' (or URI parameters). 5555 */ 5556 MHD_DAUTH_WRONG_URI = -4, 5557 5558 /** 5559 * Wrong 'qop'. 5560 */ 5561 MHD_DAUTH_WRONG_QOP = -5, 5562 5563 /** 5564 * Wrong 'algorithm'. 5565 */ 5566 MHD_DAUTH_WRONG_ALGO = -6, 5567 5568 /** 5569 * Too large (>64 KiB) Authorization parameter value. 5570 */ 5571 MHD_DAUTH_TOO_LARGE = -15, 5572 5573 /* The different form of naming is intentionally used for the results below, 5574 * as they are more important */ 5575 5576 /** 5577 * The 'nonce' is too old. Suggest the client to retry with the same 5578 * username and password to get the fresh 'nonce'. 5579 * The validity of the 'nonce' may be not checked. 5580 */ 5581 MHD_DAUTH_NONCE_STALE = -17, 5582 5583 /** 5584 * The 'nonce' was generated by MHD for other conditions. 5585 * This value is only returned if #MHD_OPTION_DIGEST_AUTH_NONCE_BIND_TYPE 5586 * is set to anything other than #MHD_DAUTH_BIND_NONCE_NONE. 5587 * The interpretation of this code could be different. For example, if 5588 * #MHD_DAUTH_BIND_NONCE_URI is set and client just used the same 'nonce' for 5589 * another URI, the code could be handled as #MHD_DAUTH_NONCE_STALE as 5590 * RFCs allow nonces re-using for other URIs in the same "protection 5591 * space". However, if only #MHD_DAUTH_BIND_NONCE_CLIENT_IP bit is set and 5592 * it is know that clients have fixed IP addresses, this return code could 5593 * be handled like #MHD_DAUTH_NONCE_WRONG. 5594 */ 5595 MHD_DAUTH_NONCE_OTHER_COND = -18, 5596 5597 /** 5598 * The 'nonce' is wrong. May indicate an attack attempt. 5599 */ 5600 MHD_DAUTH_NONCE_WRONG = -33, 5601 5602 /** 5603 * The 'response' is wrong. Typically it means that wrong password used. 5604 * May indicate an attack attempt. 5605 */ 5606 MHD_DAUTH_RESPONSE_WRONG = -34 5607 }; 5608 5609 5610 /** 5611 * Authenticates the authorization header sent by the client. 5612 * 5613 * If RFC2069 mode is allowed by setting bit #MHD_DIGEST_AUTH_QOP_NONE in 5614 * @a mqop and the client uses this mode, then server generated nonces are 5615 * used as one-time nonces because nonce-count is not supported in this old RFC. 5616 * Communication in this mode is very inefficient, especially if the client 5617 * requests several resources one-by-one as for every request a new nonce must 5618 * be generated and client repeats all requests twice (first time to get a new 5619 * nonce and second time to perform an authorised request). 5620 * 5621 * @param connection the MHD connection structure 5622 * @param realm the realm for authorization of the client 5623 * @param username the username to be authenticated, must be in clear text 5624 * even if userhash is used by the client 5625 * @param password the password matching the @a username (and the @a realm) 5626 * @param nonce_timeout the period of seconds since nonce generation, when 5627 * the nonce is recognised as valid and not stale; 5628 * if zero is specified then daemon default value is used. 5629 * @param max_nc the maximum allowed nc (Nonce Count) value, if client's nc 5630 * exceeds the specified value then MHD_DAUTH_NONCE_STALE is 5631 * returned; 5632 * if zero is specified then daemon default value is used. 5633 * @param mqop the QOP to use 5634 * @param malgo3 digest algorithms allowed to use, fail if algorithm used 5635 * by the client is not allowed by this parameter 5636 * @return #MHD_DAUTH_OK if authenticated, 5637 * the error code otherwise 5638 * @note Available since #MHD_VERSION 0x00097708 5639 * @ingroup authentication 5640 */ 5641 _MHD_EXTERN enum MHD_DigestAuthResult 5642 MHD_digest_auth_check3 (struct MHD_Connection *connection, 5643 const char *realm, 5644 const char *username, 5645 const char *password, 5646 unsigned int nonce_timeout, 5647 uint32_t max_nc, 5648 enum MHD_DigestAuthMultiQOP mqop, 5649 enum MHD_DigestAuthMultiAlgo3 malgo3); 5650 5651 5652 /** 5653 * Calculate userdigest, return it as a binary data. 5654 * 5655 * The "userdigest" is the hash of the "username:realm:password" string. 5656 * 5657 * The "userdigest" can be used to avoid storing the password in clear text 5658 * in database/files 5659 * 5660 * This function is designed to improve security of stored credentials, 5661 * the "userdigest" does not improve security of the authentication process. 5662 * 5663 * The results can be used to store username & userdigest pairs instead of 5664 * username & password pairs. To further improve security, application may 5665 * store username & userhash & userdigest triplets. 5666 * 5667 * @param algo3 the digest algorithm 5668 * @param username the username 5669 * @param realm the realm 5670 * @param password the password 5671 * @param[out] userdigest_bin the output buffer for userdigest; 5672 * if this function succeeds, then this buffer has 5673 * #MHD_digest_get_hash_size(algo3) bytes of 5674 * userdigest upon return 5675 * @param bin_buf_size the size of the @a userdigest_bin buffer, must be 5676 * at least #MHD_digest_get_hash_size(algo3) bytes long 5677 * @return MHD_YES on success, 5678 * MHD_NO if @a userdigest_bin is too small or if @a algo3 algorithm is 5679 * not supported (or external error has occurred, 5680 * see #MHD_FEATURE_EXTERN_HASH). 5681 * @sa #MHD_digest_auth_check_digest3() 5682 * @note Available since #MHD_VERSION 0x00097701 5683 * @ingroup authentication 5684 */ 5685 _MHD_EXTERN enum MHD_Result 5686 MHD_digest_auth_calc_userdigest (enum MHD_DigestAuthAlgo3 algo3, 5687 const char *username, 5688 const char *realm, 5689 const char *password, 5690 void *userdigest_bin, 5691 size_t bin_buf_size); 5692 5693 5694 /** 5695 * Authenticates the authorization header sent by the client by using 5696 * hash of "username:realm:password". 5697 * 5698 * If RFC2069 mode is allowed by setting bit #MHD_DIGEST_AUTH_QOP_NONE in 5699 * @a mqop and the client uses this mode, then server generated nonces are 5700 * used as one-time nonces because nonce-count is not supported in this old RFC. 5701 * Communication in this mode is very inefficient, especially if the client 5702 * requests several resources one-by-one as for every request a new nonce must 5703 * be generated and client repeats all requests twice (first time to get a new 5704 * nonce and second time to perform an authorised request). 5705 * 5706 * @param connection the MHD connection structure 5707 * @param realm the realm for authorization of the client 5708 * @param username the username to be authenticated, must be in clear text 5709 * even if userhash is used by the client 5710 * @param userdigest the precalculated binary hash of the string 5711 * "username:realm:password", 5712 * see #MHD_digest_auth_calc_userdigest() 5713 * @param userdigest_size the size of the @a userdigest in bytes, must match the 5714 * hashing algorithm (see #MHD_MD5_DIGEST_SIZE, 5715 * #MHD_SHA256_DIGEST_SIZE, #MHD_SHA512_256_DIGEST_SIZE, 5716 * #MHD_digest_get_hash_size()) 5717 * @param nonce_timeout the period of seconds since nonce generation, when 5718 * the nonce is recognised as valid and not stale; 5719 * if zero is specified then daemon default value is used. 5720 * @param max_nc the maximum allowed nc (Nonce Count) value, if client's nc 5721 * exceeds the specified value then MHD_DAUTH_NONCE_STALE is 5722 * returned; 5723 * if zero is specified then daemon default value is used. 5724 * @param mqop the QOP to use 5725 * @param malgo3 digest algorithms allowed to use, fail if algorithm used 5726 * by the client is not allowed by this parameter; 5727 * more than one base algorithms (MD5, SHA-256, SHA-512/256) 5728 * cannot be used at the same time for this function 5729 * as @a userdigest must match specified algorithm 5730 * @return #MHD_DAUTH_OK if authenticated, 5731 * the error code otherwise 5732 * @sa #MHD_digest_auth_calc_userdigest() 5733 * @note Available since #MHD_VERSION 0x00097701 5734 * @ingroup authentication 5735 */ 5736 _MHD_EXTERN enum MHD_DigestAuthResult 5737 MHD_digest_auth_check_digest3 (struct MHD_Connection *connection, 5738 const char *realm, 5739 const char *username, 5740 const void *userdigest, 5741 size_t userdigest_size, 5742 unsigned int nonce_timeout, 5743 uint32_t max_nc, 5744 enum MHD_DigestAuthMultiQOP mqop, 5745 enum MHD_DigestAuthMultiAlgo3 malgo3); 5746 5747 5748 /** 5749 * Queues a response to request authentication from the client 5750 * 5751 * This function modifies provided @a response. The @a response must not be 5752 * reused and should be destroyed (by #MHD_destroy_response()) after call of 5753 * this function. 5754 * 5755 * If @a mqop allows both RFC 2069 (MHD_DIGEST_AUTH_QOP_NONE) and QOP with 5756 * value, then response is formed like if MHD_DIGEST_AUTH_QOP_NONE bit was 5757 * not set, because such response should be backward-compatible with RFC 2069. 5758 * 5759 * If @a mqop allows only MHD_DIGEST_AUTH_MULT_QOP_NONE, then the response is 5760 * formed in strict accordance with RFC 2069 (no 'qop', no 'userhash', no 5761 * 'charset'). For better compatibility with clients, it is recommended (but 5762 * not required) to set @a domain to NULL in this mode. 5763 * 5764 * @param connection the MHD connection structure 5765 * @param realm the realm presented to the client 5766 * @param opaque the string for opaque value, can be NULL, but NULL is 5767 * not recommended for better compatibility with clients; 5768 * the recommended format is hex or Base64 encoded string 5769 * @param domain the optional space-separated list of URIs for which the 5770 * same authorisation could be used, URIs can be in form 5771 * "path-absolute" (the path for the same host with initial slash) 5772 * or in form "absolute-URI" (the full path with protocol), in 5773 * any case client may assume that URI is in the same "protection 5774 * space" if it starts with any of values specified here; 5775 * could be NULL (clients typically assume that the same 5776 * credentials could be used for any URI on the same host); 5777 * this list provides information for the client only and does 5778 * not actually restrict anything on the server side 5779 * @param response the reply to send; should contain the "access denied" 5780 * body; 5781 * note: this function sets the "WWW Authenticate" header and 5782 * the caller should not set this header; 5783 * the NULL is tolerated 5784 * @param signal_stale if set to #MHD_YES then indication of stale nonce used in 5785 * the client's request is signalled by adding 'stale=true' 5786 * to the authentication header, this instructs the client 5787 * to retry immediately with the new nonce and the same 5788 * credentials, without asking user for the new password 5789 * @param mqop the QOP to use 5790 * @param malgo3 digest algorithm to use; if several algorithms are allowed 5791 * then MD5 is preferred (currently, may be changed in next 5792 * versions) 5793 * @param userhash_support if set to non-zero value (#MHD_YES) then support of 5794 * userhash is indicated, allowing client to provide 5795 * hash("username:realm") instead of the username in 5796 * clear text; 5797 * note that clients are allowed to provide the username 5798 * in cleartext even if this parameter set to non-zero; 5799 * when userhash is used, application must be ready to 5800 * identify users by provided userhash value instead of 5801 * username; see #MHD_digest_auth_calc_userhash() and 5802 * #MHD_digest_auth_calc_userhash_hex() 5803 * @param prefer_utf8 if not set to #MHD_NO, parameter 'charset=UTF-8' is 5804 * added, indicating for the client that UTF-8 encoding for 5805 * the username is preferred 5806 * @return #MHD_YES on success, #MHD_NO otherwise 5807 * @note Available since #MHD_VERSION 0x00097701 5808 * @ingroup authentication 5809 */ 5810 _MHD_EXTERN enum MHD_Result 5811 MHD_queue_auth_required_response3 (struct MHD_Connection *connection, 5812 const char *realm, 5813 const char *opaque, 5814 const char *domain, 5815 struct MHD_Response *response, 5816 int signal_stale, 5817 enum MHD_DigestAuthMultiQOP mqop, 5818 enum MHD_DigestAuthMultiAlgo3 algo, 5819 int userhash_support, 5820 int prefer_utf8); 5821 5822 5823 /** 5824 * Constant to indicate that the nonce of the provided 5825 * authentication code was wrong. 5826 * Used as return code by #MHD_digest_auth_check(), #MHD_digest_auth_check2(), 5827 * #MHD_digest_auth_check_digest(), #MHD_digest_auth_check_digest2(). 5828 * @ingroup authentication 5829 */ 5830 #define MHD_INVALID_NONCE -1 5831 5832 5833 /** 5834 * Get the username from the authorization header sent by the client 5835 * 5836 * This function supports username in standard and extended notations. 5837 * "userhash" is not supported by this function. 5838 * 5839 * @param connection The MHD connection structure 5840 * @return NULL if no username could be found, username provided as 5841 * "userhash", extended notation broken or memory allocation error 5842 * occurs; 5843 * a pointer to the username if found, free using #MHD_free(). 5844 * @warning Returned value must be freed by #MHD_free(). 5845 * @sa #MHD_digest_auth_get_username3() 5846 * @ingroup authentication 5847 */ 5848 _MHD_EXTERN char * 5849 MHD_digest_auth_get_username (struct MHD_Connection *connection); 5850 5851 5852 /** 5853 * Which digest algorithm should MHD use for HTTP digest authentication? 5854 * Used as parameter for #MHD_digest_auth_check2(), 5855 * #MHD_digest_auth_check_digest2(), #MHD_queue_auth_fail_response2(). 5856 */ 5857 enum MHD_DigestAuthAlgorithm 5858 { 5859 5860 /** 5861 * MHD should pick (currently defaults to MD5). 5862 */ 5863 MHD_DIGEST_ALG_AUTO = 0, 5864 5865 /** 5866 * Force use of MD5. 5867 */ 5868 MHD_DIGEST_ALG_MD5, 5869 5870 /** 5871 * Force use of SHA-256. 5872 */ 5873 MHD_DIGEST_ALG_SHA256 5874 5875 } _MHD_FIXED_ENUM; 5876 5877 5878 /** 5879 * Authenticates the authorization header sent by the client. 5880 * 5881 * @param connection The MHD connection structure 5882 * @param realm The realm presented to the client 5883 * @param username The username needs to be authenticated 5884 * @param password The password used in the authentication 5885 * @param nonce_timeout The amount of time for a nonce to be 5886 * invalid in seconds 5887 * @param algo digest algorithms allowed for verification 5888 * @return #MHD_YES if authenticated, #MHD_NO if not, 5889 * #MHD_INVALID_NONCE if nonce is invalid or stale 5890 * @note Available since #MHD_VERSION 0x00096200 5891 * @deprecated use MHD_digest_auth_check3() 5892 * @ingroup authentication 5893 */ 5894 _MHD_EXTERN int 5895 MHD_digest_auth_check2 (struct MHD_Connection *connection, 5896 const char *realm, 5897 const char *username, 5898 const char *password, 5899 unsigned int nonce_timeout, 5900 enum MHD_DigestAuthAlgorithm algo); 5901 5902 5903 /** 5904 * Authenticates the authorization header sent by the client. 5905 * Uses #MHD_DIGEST_ALG_MD5 (for now, for backwards-compatibility). 5906 * Note that this MAY change to #MHD_DIGEST_ALG_AUTO in the future. 5907 * If you want to be sure you get MD5, use #MHD_digest_auth_check2() 5908 * and specify MD5 explicitly. 5909 * 5910 * @param connection The MHD connection structure 5911 * @param realm The realm presented to the client 5912 * @param username The username needs to be authenticated 5913 * @param password The password used in the authentication 5914 * @param nonce_timeout The amount of time for a nonce to be 5915 * invalid in seconds 5916 * @return #MHD_YES if authenticated, #MHD_NO if not, 5917 * #MHD_INVALID_NONCE if nonce is invalid or stale 5918 * @deprecated use MHD_digest_auth_check3() 5919 * @ingroup authentication 5920 */ 5921 _MHD_EXTERN int 5922 MHD_digest_auth_check (struct MHD_Connection *connection, 5923 const char *realm, 5924 const char *username, 5925 const char *password, 5926 unsigned int nonce_timeout); 5927 5928 5929 /** 5930 * Authenticates the authorization header sent by the client. 5931 * 5932 * @param connection The MHD connection structure 5933 * @param realm The realm presented to the client 5934 * @param username The username needs to be authenticated 5935 * @param digest An `unsigned char *' pointer to the binary MD5 sum 5936 * for the precalculated hash value "username:realm:password" 5937 * of @a digest_size bytes 5938 * @param digest_size number of bytes in @a digest (size must match @a algo!) 5939 * @param nonce_timeout The amount of time for a nonce to be 5940 * invalid in seconds 5941 * @param algo digest algorithm allowed for verification; exactly one 5942 * algorithm must be named, as @a digest is a hash produced by one 5943 * specific algorithm. #MHD_DIGEST_ALG_AUTO cannot be used here 5944 * and makes this function return #MHD_NO 5945 * @return #MHD_YES if authenticated, #MHD_NO if not, 5946 * #MHD_INVALID_NONCE if nonce is invalid or stale 5947 * @note Available since #MHD_VERSION 0x00096200 5948 * @deprecated use MHD_digest_auth_check_digest3() 5949 * @ingroup authentication 5950 */ 5951 _MHD_EXTERN int 5952 MHD_digest_auth_check_digest2 (struct MHD_Connection *connection, 5953 const char *realm, 5954 const char *username, 5955 const uint8_t *digest, 5956 size_t digest_size, 5957 unsigned int nonce_timeout, 5958 enum MHD_DigestAuthAlgorithm algo); 5959 5960 5961 /** 5962 * Authenticates the authorization header sent by the client 5963 * Uses #MHD_DIGEST_ALG_MD5 (required, as @a digest is of fixed 5964 * size). 5965 * 5966 * @param connection The MHD connection structure 5967 * @param realm The realm presented to the client 5968 * @param username The username needs to be authenticated 5969 * @param digest An `unsigned char *' pointer to the binary hash 5970 * for the precalculated hash value "username:realm:password"; 5971 * length must be #MHD_MD5_DIGEST_SIZE bytes 5972 * @param nonce_timeout The amount of time for a nonce to be 5973 * invalid in seconds 5974 * @return #MHD_YES if authenticated, #MHD_NO if not, 5975 * #MHD_INVALID_NONCE if nonce is invalid or stale 5976 * @note Available since #MHD_VERSION 0x00096000 5977 * @deprecated use #MHD_digest_auth_check_digest3() 5978 * @ingroup authentication 5979 */ 5980 _MHD_EXTERN int 5981 MHD_digest_auth_check_digest (struct MHD_Connection *connection, 5982 const char *realm, 5983 const char *username, 5984 const uint8_t digest[MHD_MD5_DIGEST_SIZE], 5985 unsigned int nonce_timeout); 5986 5987 5988 /** 5989 * Queues a response to request authentication from the client 5990 * 5991 * This function modifies provided @a response. The @a response must not be 5992 * reused and should be destroyed after call of this function. 5993 * 5994 * @param connection The MHD connection structure 5995 * @param realm the realm presented to the client 5996 * @param opaque string to user for opaque value 5997 * @param response reply to send; should contain the "access denied" 5998 * body; note that this function will set the "WWW Authenticate" 5999 * header and that the caller should not do this; the NULL is tolerated 6000 * @param signal_stale #MHD_YES if the nonce is stale to add 6001 * 'stale=true' to the authentication header 6002 * @param algo digest algorithm to use 6003 * @return #MHD_YES on success, #MHD_NO otherwise 6004 * @note Available since #MHD_VERSION 0x00096200 6005 * @deprecated use MHD_queue_auth_required_response3() 6006 * @ingroup authentication 6007 */ 6008 _MHD_EXTERN enum MHD_Result 6009 MHD_queue_auth_fail_response2 (struct MHD_Connection *connection, 6010 const char *realm, 6011 const char *opaque, 6012 struct MHD_Response *response, 6013 int signal_stale, 6014 enum MHD_DigestAuthAlgorithm algo); 6015 6016 6017 /** 6018 * Queues a response to request authentication from the client. 6019 * For now uses MD5 (for backwards-compatibility). Still, if you 6020 * need to be sure, use #MHD_queue_auth_fail_response2(). 6021 * 6022 * This function modifies provided @a response. The @a response must not be 6023 * reused and should be destroyed after call of this function. 6024 * 6025 * @param connection The MHD connection structure 6026 * @param realm the realm presented to the client 6027 * @param opaque string to user for opaque value 6028 * @param response reply to send; should contain the "access denied" 6029 * body; note that this function will set the "WWW Authenticate" 6030 * header and that the caller should not do this; the NULL is tolerated 6031 * @param signal_stale #MHD_YES if the nonce is stale to add 6032 * 'stale=true' to the authentication header 6033 * @return #MHD_YES on success, #MHD_NO otherwise 6034 * @deprecated use MHD_queue_auth_required_response3() 6035 * @ingroup authentication 6036 */ 6037 _MHD_EXTERN enum MHD_Result 6038 MHD_queue_auth_fail_response (struct MHD_Connection *connection, 6039 const char *realm, 6040 const char *opaque, 6041 struct MHD_Response *response, 6042 int signal_stale); 6043 6044 6045 /* ********************* Basic Authentication functions *************** */ 6046 6047 6048 /** 6049 * Information decoded from Basic Authentication client's header. 6050 * 6051 * The username and the password are technically allowed to have binary zeros, 6052 * username_len and password_len could be used to detect such situations. 6053 * 6054 * The buffers pointed by username and password members are freed 6055 * when #MHD_free() is called for pointer to this structure. 6056 * 6057 * Application may modify buffers as needed until #MHD_free() is called for 6058 * pointer to this structure 6059 */ 6060 struct MHD_BasicAuthInfo 6061 { 6062 /** 6063 * The username, cannot be NULL. 6064 * The buffer pointed by the @a username becomes invalid when the pointer 6065 * to the structure is freed by #MHD_free(). 6066 */ 6067 char *username; 6068 6069 /** 6070 * The length of the @a username, not including zero-termination 6071 */ 6072 size_t username_len; 6073 6074 /** 6075 * The password, may be NULL if password is not encoded by the client. 6076 * The buffer pointed by the @a password becomes invalid when the pointer 6077 * to the structure is freed by #MHD_free(). 6078 */ 6079 char *password; 6080 6081 /** 6082 * The length of the @a password, not including zero-termination; 6083 * when the @a password is NULL, the length is always zero. 6084 */ 6085 size_t password_len; 6086 }; 6087 6088 /** 6089 * Get the username and password from the Basic Authorisation header 6090 * sent by the client 6091 * 6092 * @param connection the MHD connection structure 6093 * @return NULL if no valid Basic Authentication header is present in 6094 * current request, or 6095 * pointer to structure with username and password, which must be 6096 * freed by #MHD_free(). 6097 * @note Available since #MHD_VERSION 0x00097701 6098 * @ingroup authentication 6099 */ 6100 _MHD_EXTERN struct MHD_BasicAuthInfo * 6101 MHD_basic_auth_get_username_password3 (struct MHD_Connection *connection); 6102 6103 /** 6104 * Queues a response to request basic authentication from the client. 6105 * 6106 * The given response object is expected to include the payload for 6107 * the response; the "WWW-Authenticate" header will be added and the 6108 * response queued with the 'UNAUTHORIZED' status code. 6109 * 6110 * See RFC 7617#section-2 for details. 6111 * 6112 * The @a response is modified by this function. The modified response object 6113 * can be used to respond subsequent requests by #MHD_queue_response() 6114 * function with status code #MHD_HTTP_UNAUTHORIZED and must not be used again 6115 * with MHD_queue_basic_auth_required_response3() function. The response could 6116 * be destroyed right after call of this function. 6117 * 6118 * @param connection the MHD connection structure 6119 * @param realm the realm presented to the client 6120 * @param prefer_utf8 if not set to #MHD_NO, parameter'charset="UTF-8"' will 6121 * be added, indicating for client that UTF-8 encoding 6122 * is preferred 6123 * @param response the response object to modify and queue; the NULL 6124 * is tolerated 6125 * @return #MHD_YES on success, #MHD_NO otherwise 6126 * @note Available since #MHD_VERSION 0x00097704 6127 * @ingroup authentication 6128 */ 6129 _MHD_EXTERN enum MHD_Result 6130 MHD_queue_basic_auth_required_response3 (struct MHD_Connection *connection, 6131 const char *realm, 6132 int prefer_utf8, 6133 struct MHD_Response *response); 6134 6135 /** 6136 * Get the username and password from the basic authorization header sent by the client 6137 * 6138 * @param connection The MHD connection structure 6139 * @param[out] password a pointer for the password, free using #MHD_free(). 6140 * @return NULL if no username could be found, a pointer 6141 * to the username if found, free using #MHD_free(). 6142 * @deprecated use #MHD_basic_auth_get_username_password3() 6143 * @ingroup authentication 6144 */ 6145 _MHD_EXTERN char * 6146 MHD_basic_auth_get_username_password (struct MHD_Connection *connection, 6147 char **password); 6148 6149 6150 /** 6151 * Queues a response to request basic authentication from the client 6152 * The given response object is expected to include the payload for 6153 * the response; the "WWW-Authenticate" header will be added and the 6154 * response queued with the 'UNAUTHORIZED' status code. 6155 * 6156 * @param connection The MHD connection structure 6157 * @param realm the realm presented to the client 6158 * @param response response object to modify and queue; the NULL is tolerated 6159 * @return #MHD_YES on success, #MHD_NO otherwise 6160 * @deprecated use MHD_queue_basic_auth_required_response3() 6161 * @ingroup authentication 6162 */ 6163 _MHD_EXTERN enum MHD_Result 6164 MHD_queue_basic_auth_fail_response (struct MHD_Connection *connection, 6165 const char *realm, 6166 struct MHD_Response *response); 6167 6168 /* ********************** generic query functions ********************** */ 6169 6170 6171 /** 6172 * Obtain information about the given connection. 6173 * The returned pointer is invalidated with the next call of this function or 6174 * when the connection is closed. 6175 * 6176 * @param connection what connection to get information about 6177 * @param info_type what information is desired? 6178 * @param ... depends on @a info_type 6179 * @return NULL if this information is not available 6180 * (or if the @a info_type is unknown) 6181 * @ingroup specialized 6182 */ 6183 _MHD_EXTERN const union MHD_ConnectionInfo * 6184 MHD_get_connection_info (struct MHD_Connection *connection, 6185 enum MHD_ConnectionInfoType info_type, 6186 ...); 6187 6188 6189 /** 6190 * MHD connection options. Given to #MHD_set_connection_option to 6191 * set custom options for a particular connection. 6192 */ 6193 enum MHD_CONNECTION_OPTION 6194 { 6195 6196 /** 6197 * Set a custom timeout for the given connection. Specified 6198 * as the number of seconds, given as an `unsigned int`. Use 6199 * zero for no timeout. 6200 * If timeout was set to zero (or unset) before, setup of new value by 6201 * MHD_set_connection_option() will reset timeout timer. 6202 * Values larger than (UINT64_MAX / 2000 - 1) will 6203 * be clipped to this number. 6204 */ 6205 MHD_CONNECTION_OPTION_TIMEOUT 6206 6207 } _MHD_FIXED_ENUM; 6208 6209 6210 /** 6211 * Set a custom option for the given connection, overriding defaults. 6212 * 6213 * @param connection connection to modify 6214 * @param option option to set 6215 * @param ... arguments to the option, depending on the option type 6216 * @return #MHD_YES on success, #MHD_NO if setting the option failed 6217 * @ingroup specialized 6218 */ 6219 _MHD_EXTERN enum MHD_Result 6220 MHD_set_connection_option (struct MHD_Connection *connection, 6221 enum MHD_CONNECTION_OPTION option, 6222 ...); 6223 6224 6225 /** 6226 * Information about an MHD daemon. 6227 */ 6228 union MHD_DaemonInfo 6229 { 6230 /** 6231 * Size of the key, no longer supported. 6232 * @deprecated 6233 */ 6234 size_t key_size; 6235 6236 /** 6237 * Size of the mac key, no longer supported. 6238 * @deprecated 6239 */ 6240 size_t mac_key_size; 6241 6242 /** 6243 * Socket, returned for #MHD_DAEMON_INFO_LISTEN_FD. 6244 */ 6245 MHD_socket listen_fd; 6246 6247 /** 6248 * Bind port number, returned for #MHD_DAEMON_INFO_BIND_PORT. 6249 */ 6250 uint16_t port; 6251 6252 /** 6253 * epoll FD, returned for #MHD_DAEMON_INFO_EPOLL_FD. 6254 */ 6255 int epoll_fd; 6256 6257 /** 6258 * Number of active connections, for #MHD_DAEMON_INFO_CURRENT_CONNECTIONS. 6259 */ 6260 unsigned int num_connections; 6261 6262 /** 6263 * Combination of #MHD_FLAG values, for #MHD_DAEMON_INFO_FLAGS. 6264 * This value is actually a bitfield. 6265 * Note: flags may differ from original 'flags' specified for 6266 * daemon, especially if #MHD_USE_AUTO was set. 6267 */ 6268 enum MHD_FLAG flags; 6269 }; 6270 6271 6272 /** 6273 * Obtain information about the given daemon. 6274 * The returned pointer is invalidated with the next call of this function or 6275 * when the daemon is stopped. 6276 * 6277 * @param daemon what daemon to get information about 6278 * @param info_type what information is desired? 6279 * @param ... depends on @a info_type 6280 * @return NULL if this information is not available 6281 * (or if the @a info_type is unknown) 6282 * @ingroup specialized 6283 */ 6284 _MHD_EXTERN const union MHD_DaemonInfo * 6285 MHD_get_daemon_info (struct MHD_Daemon *daemon, 6286 enum MHD_DaemonInfoType info_type, 6287 ...); 6288 6289 6290 /** 6291 * Obtain the version of this library 6292 * 6293 * @return static version string, e.g. "0.9.9" 6294 * @ingroup specialized 6295 */ 6296 _MHD_EXTERN const char * 6297 MHD_get_version (void); 6298 6299 6300 /** 6301 * Obtain the version of this library as a binary value. 6302 * 6303 * @return version binary value, e.g. "0x00090900" (#MHD_VERSION of 6304 * compiled MHD binary) 6305 * @note Available since #MHD_VERSION 0x00097601 6306 * @ingroup specialized 6307 */ 6308 _MHD_EXTERN uint32_t 6309 MHD_get_version_bin (void); 6310 6311 6312 /** 6313 * Types of information about MHD features, 6314 * used by #MHD_is_feature_supported(). 6315 */ 6316 enum MHD_FEATURE 6317 { 6318 /** 6319 * Get whether messages are supported. If supported then in debug 6320 * mode messages can be printed to stderr or to external logger. 6321 */ 6322 MHD_FEATURE_MESSAGES = 1, 6323 6324 /** 6325 * Get whether HTTPS is supported. If supported then flag 6326 * #MHD_USE_TLS and options #MHD_OPTION_HTTPS_MEM_KEY, 6327 * #MHD_OPTION_HTTPS_MEM_CERT, #MHD_OPTION_HTTPS_MEM_TRUST, 6328 * #MHD_OPTION_HTTPS_MEM_DHPARAMS, #MHD_OPTION_HTTPS_CRED_TYPE, 6329 * #MHD_OPTION_HTTPS_PRIORITIES can be used. 6330 */ 6331 MHD_FEATURE_TLS = 2, 6332 MHD_FEATURE_SSL = 2, 6333 6334 /** 6335 * Get whether option #MHD_OPTION_HTTPS_CERT_CALLBACK is 6336 * supported. 6337 */ 6338 MHD_FEATURE_HTTPS_CERT_CALLBACK = 3, 6339 6340 /** 6341 * Get whether IPv6 is supported. If supported then flag 6342 * #MHD_USE_IPv6 can be used. 6343 */ 6344 MHD_FEATURE_IPv6 = 4, 6345 6346 /** 6347 * Get whether IPv6 without IPv4 is supported. If not supported 6348 * then IPv4 is always enabled in IPv6 sockets and 6349 * flag #MHD_USE_DUAL_STACK is always used when #MHD_USE_IPv6 is 6350 * specified. 6351 */ 6352 MHD_FEATURE_IPv6_ONLY = 5, 6353 6354 /** 6355 * Get whether `poll()` is supported. If supported then flag 6356 * #MHD_USE_POLL can be used. 6357 */ 6358 MHD_FEATURE_POLL = 6, 6359 6360 /** 6361 * Get whether `epoll()` is supported. If supported then Flags 6362 * #MHD_USE_EPOLL and 6363 * #MHD_USE_EPOLL_INTERNAL_THREAD can be used. 6364 */ 6365 MHD_FEATURE_EPOLL = 7, 6366 6367 /** 6368 * Get whether shutdown on listen socket to signal other 6369 * threads is supported. If not supported flag 6370 * #MHD_USE_ITC is automatically forced. 6371 */ 6372 MHD_FEATURE_SHUTDOWN_LISTEN_SOCKET = 8, 6373 6374 /** 6375 * Get whether socketpair is used internally instead of pipe to 6376 * signal other threads. 6377 */ 6378 MHD_FEATURE_SOCKETPAIR = 9, 6379 6380 /** 6381 * Get whether TCP Fast Open is supported. If supported then 6382 * flag #MHD_USE_TCP_FASTOPEN and option 6383 * #MHD_OPTION_TCP_FASTOPEN_QUEUE_SIZE can be used. 6384 */ 6385 MHD_FEATURE_TCP_FASTOPEN = 10, 6386 6387 /** 6388 * Get whether HTTP Basic authorization is supported. If supported 6389 * then functions #MHD_basic_auth_get_username_password and 6390 * #MHD_queue_basic_auth_fail_response can be used. 6391 */ 6392 MHD_FEATURE_BASIC_AUTH = 11, 6393 6394 /** 6395 * Get whether HTTP Digest authorization is supported. If 6396 * supported then options #MHD_OPTION_DIGEST_AUTH_RANDOM, 6397 * #MHD_OPTION_NONCE_NC_SIZE and 6398 * #MHD_digest_auth_check() can be used. 6399 */ 6400 MHD_FEATURE_DIGEST_AUTH = 12, 6401 6402 /** 6403 * Get whether postprocessor is supported. If supported then 6404 * functions #MHD_create_post_processor(), #MHD_post_process() and 6405 * #MHD_destroy_post_processor() can 6406 * be used. 6407 */ 6408 MHD_FEATURE_POSTPROCESSOR = 13, 6409 6410 /** 6411 * Get whether password encrypted private key for HTTPS daemon is 6412 * supported. If supported then option 6413 * ::MHD_OPTION_HTTPS_KEY_PASSWORD can be used. 6414 */ 6415 MHD_FEATURE_HTTPS_KEY_PASSWORD = 14, 6416 6417 /** 6418 * Get whether reading files beyond 2 GiB boundary is supported. 6419 * If supported then #MHD_create_response_from_fd(), 6420 * #MHD_create_response_from_fd64 #MHD_create_response_from_fd_at_offset() 6421 * and #MHD_create_response_from_fd_at_offset64() can be used with sizes and 6422 * offsets larger than 2 GiB. If not supported value of size+offset is 6423 * limited to 2 GiB. 6424 */ 6425 MHD_FEATURE_LARGE_FILE = 15, 6426 6427 /** 6428 * Get whether MHD set names on generated threads. 6429 */ 6430 MHD_FEATURE_THREAD_NAMES = 16, 6431 MHD_THREAD_NAMES = 16, 6432 6433 /** 6434 * Get whether HTTP "Upgrade" is supported. 6435 * If supported then #MHD_ALLOW_UPGRADE, #MHD_upgrade_action() and 6436 * #MHD_create_response_for_upgrade() can be used. 6437 */ 6438 MHD_FEATURE_UPGRADE = 17, 6439 6440 /** 6441 * Get whether it's safe to use same FD for multiple calls of 6442 * #MHD_create_response_from_fd() and whether it's safe to use single 6443 * response generated by #MHD_create_response_from_fd() with multiple 6444 * connections at same time. 6445 * If #MHD_is_feature_supported() return #MHD_NO for this feature then 6446 * usage of responses with same file FD in multiple parallel threads may 6447 * results in incorrect data sent to remote client. 6448 * It's always safe to use same file FD in multiple responses if MHD 6449 * is run in any single thread mode. 6450 */ 6451 MHD_FEATURE_RESPONSES_SHARED_FD = 18, 6452 6453 /** 6454 * Get whether MHD support automatic detection of bind port number. 6455 * @sa #MHD_DAEMON_INFO_BIND_PORT 6456 */ 6457 MHD_FEATURE_AUTODETECT_BIND_PORT = 19, 6458 6459 /** 6460 * Get whether MHD supports automatic SIGPIPE suppression. 6461 * If SIGPIPE suppression is not supported, application must handle 6462 * SIGPIPE signal by itself. 6463 */ 6464 MHD_FEATURE_AUTOSUPPRESS_SIGPIPE = 20, 6465 6466 /** 6467 * Get whether MHD use system's sendfile() function to send 6468 * file-FD based responses over non-TLS connections. 6469 * @note Since v0.9.56 6470 */ 6471 MHD_FEATURE_SENDFILE = 21, 6472 6473 /** 6474 * Get whether MHD supports threads. 6475 */ 6476 MHD_FEATURE_THREADS = 22, 6477 6478 /** 6479 * Get whether option #MHD_OPTION_HTTPS_CERT_CALLBACK2 is 6480 * supported. 6481 */ 6482 MHD_FEATURE_HTTPS_CERT_CALLBACK2 = 23, 6483 6484 /** 6485 * Get whether automatic parsing of HTTP Cookie header is supported. 6486 * If disabled, no MHD_COOKIE_KIND will be generated by MHD. 6487 * MHD versions before 0x00097701 always support cookie parsing. 6488 * @note Available since #MHD_VERSION 0x01000200 6489 */ 6490 MHD_FEATURE_COOKIE_PARSING = 24, 6491 6492 /** 6493 * Get whether the early version the Digest Authorization (RFC 2069) is 6494 * supported (digest authorisation without QOP parameter). 6495 * Since #MHD_VERSION 0x00097701 it is always supported if Digest Auth 6496 * module is built. 6497 * @note Available since #MHD_VERSION 0x00097701 6498 */ 6499 MHD_FEATURE_DIGEST_AUTH_RFC2069 = 25, 6500 6501 /** 6502 * Get whether the MD5-based hashing algorithms are supported for Digest 6503 * Authorization. 6504 * Currently it is always supported if Digest Auth module is built 6505 * unless manually disabled in a custom build. 6506 * @note Available since #MHD_VERSION 0x00097701 6507 */ 6508 MHD_FEATURE_DIGEST_AUTH_MD5 = 26, 6509 6510 /** 6511 * Get whether the SHA-256-based hashing algorithms are supported for Digest 6512 * Authorization. 6513 * It is always supported since #MHD_VERSION 0x00096200 if Digest Auth 6514 * module is built unless manually disabled in a custom build. 6515 * @note Available since #MHD_VERSION 0x00097701 6516 */ 6517 MHD_FEATURE_DIGEST_AUTH_SHA256 = 27, 6518 6519 /** 6520 * Get whether the SHA-512/256-based hashing algorithms are supported 6521 * for Digest Authorization. 6522 * It it always supported since #MHD_VERSION 0x00097701 if Digest Auth 6523 * module is built unless manually disabled in a custom build. 6524 * @note Available since #MHD_VERSION 0x00097701 6525 */ 6526 MHD_FEATURE_DIGEST_AUTH_SHA512_256 = 28, 6527 6528 /** 6529 * Get whether QOP with value 'auth-int' (authentication with integrity 6530 * protection) is supported for Digest Authorization. 6531 * Currently it is always not supported. 6532 * @note Available since #MHD_VERSION 0x00097701 6533 */ 6534 MHD_FEATURE_DIGEST_AUTH_AUTH_INT = 29, 6535 6536 /** 6537 * Get whether 'session' algorithms (like 'MD5-sess') are supported for Digest 6538 * Authorization. 6539 * Currently it is always not supported. 6540 * @note Available since #MHD_VERSION 0x00097701 6541 */ 6542 MHD_FEATURE_DIGEST_AUTH_ALGO_SESSION = 30, 6543 6544 /** 6545 * Get whether 'userhash' is supported for Digest Authorization. 6546 * It is always supported since #MHD_VERSION 0x00097701 if Digest Auth 6547 * module is built. 6548 * @note Available since #MHD_VERSION 0x00097701 6549 */ 6550 MHD_FEATURE_DIGEST_AUTH_USERHASH = 31, 6551 6552 /** 6553 * Get whether any of hashing algorithms is implemented by external 6554 * function (like TLS library) and may fail due to external conditions, 6555 * like "out-of-memory". 6556 * 6557 * If result is #MHD_YES then functions which use hash calculations 6558 * like #MHD_digest_auth_calc_userhash(), #MHD_digest_auth_check3() and others 6559 * potentially may fail even with valid input because of out-of-memory error 6560 * or crypto accelerator device failure, however in practice such fails are 6561 * unlikely. 6562 * @note Available since #MHD_VERSION 0x00097701 6563 */ 6564 MHD_FEATURE_EXTERN_HASH = 32, 6565 6566 /** 6567 * Get whether MHD was built with asserts enabled. 6568 * For debug builds the error log is always enabled even if #MHD_USE_ERROR_LOG 6569 * is not specified for daemon. 6570 * @note Available since #MHD_VERSION 0x00097701 6571 */ 6572 MHD_FEATURE_DEBUG_BUILD = 33, 6573 6574 /** 6575 * Get whether MHD was build with support for overridable FD_SETSIZE. 6576 * This feature should be always available when the relevant platform ability 6577 * is detected. 6578 * @sa #MHD_OPTION_APP_FD_SETSIZE 6579 * @note Available since #MHD_VERSION 0x00097705 6580 */ 6581 MHD_FEATURE_FLEXIBLE_FD_SETSIZE = 34 6582 }; 6583 6584 #define MHD_FEATURE_HTTPS_COOKIE_PARSING _MHD_DEPR_IN_MACRO ( \ 6585 "Value MHD_FEATURE_HTTPS_COOKIE_PARSING is deprecated, use MHD_FEATURE_COOKIE_PARSING" \ 6586 ) MHD_FEATURE_COOKIE_PARSING 6587 6588 /** 6589 * Get information about supported MHD features. 6590 * Indicate that MHD was compiled with or without support for 6591 * particular feature. Some features require additional support 6592 * by kernel. Kernel support is not checked by this function. 6593 * 6594 * @param feature type of requested information 6595 * @return #MHD_YES if feature is supported by MHD, #MHD_NO if 6596 * feature is not supported or feature is unknown. 6597 * @ingroup specialized 6598 */ 6599 _MHD_EXTERN enum MHD_Result 6600 MHD_is_feature_supported (enum MHD_FEATURE feature); 6601 6602 6603 MHD_C_DECLRATIONS_FINISH_HERE_ 6604 6605 #endif