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