1 /* 2 This file is part of libmicrohttpd 3 Copyright (C) 2006-2015 Christian Grothoff (and other contributing authors) 4 5 This library is free software; you can redistribute it and/or 6 modify it under the terms of the GNU Lesser General Public 7 License as published by the Free Software Foundation; either 8 version 2.1 of the License, or (at your option) any later version. 9 10 This library is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Lesser General Public License for more details. 14 15 You should have received a copy of the GNU Lesser General Public 16 License along with this library; if not, write to the Free Software 17 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 18 */ 19 20 /** 21 * @file microhttpd.h 22 * @brief public interface to libmicrohttpd 23 * @author Christian Grothoff 24 * @author Chris GauthierDickey 25 * 26 * All symbols defined in this header start with MHD. MHD is a small 27 * HTTP daemon library. As such, it does not have any API for logging 28 * errors (you can only enable or disable logging to stderr). Also, 29 * it may not support all of the HTTP features directly, where 30 * applicable, portions of HTTP may have to be handled by clients of 31 * the library. 32 * 33 * The library is supposed to handle everything that it must handle 34 * (because the API would not allow clients to do this), such as basic 35 * connection management; however, detailed interpretations of headers 36 * -- such as range requests -- and HTTP methods are left to clients. 37 * The library does understand HEAD and will only send the headers of 38 * the response and not the body, even if the client supplied a body. 39 * The library also understands headers that control connection 40 * management (specifically, "Connection: close" and "Expect: 100 41 * continue" are understood and handled automatically). 42 * 43 * MHD understands POST data and is able to decode certain formats 44 * (at the moment only "application/x-www-form-urlencoded" and 45 * "mulitpart/formdata"). Unsupported encodings and large POST 46 * submissions may require the application to manually process 47 * the stream, which is provided to the main application (and thus can be 48 * processed, just not conveniently by MHD). 49 * 50 * The header file defines various constants used by the HTTP protocol. 51 * This does not mean that MHD actually interprets all of these 52 * values. The provided constants are exported as a convenience 53 * for users of the library. MHD does not verify that transmitted 54 * HTTP headers are part of the standard specification; users of the 55 * library are free to define their own extensions of the HTTP 56 * standard and use those with MHD. 57 * 58 * All functions are guaranteed to be completely reentrant and 59 * thread-safe (with the exception of #MHD_set_connection_value, 60 * which must only be used in a particular context). 61 * 62 * NEW: Before including "microhttpd.h" you should add the necessary 63 * includes to define the `uint64_t`, `size_t`, `fd_set`, `socklen_t` 64 * and `struct sockaddr` data types (which headers are needed may 65 * depend on your platform; for possible suggestions consult 66 * "platform.h" in the MHD distribution). If you have done so, you 67 * should also have a line with "#define MHD_PLATFORM_H" which will 68 * prevent this header from trying (and, depending on your platform, 69 * failing) to include the right headers. 70 * 71 * @defgroup event event-loop control 72 * MHD API to start and stop the HTTP server and manage the event loop. 73 * @defgroup response generation of responses 74 * MHD API used to generate responses. 75 * @defgroup request handling of requests 76 * MHD API used to access information about requests. 77 * @defgroup authentication HTTP authentication 78 * MHD API related to basic and digest HTTP authentication. 79 * @defgroup logging logging 80 * MHD API to mange logging and error handling 81 * @defgroup specialized misc. specialized functions 82 * This group includes functions that do not fit into any particular 83 * category and that are rarely used. 84 */ 85 86 #ifndef MHD_MICROHTTPD_H 87 #define MHD_MICROHTTPD_H 88 89 #ifdef __cplusplus 90 extern "C" 91 { 92 #if 0 /* keep Emacsens' auto-indent happy */ 93 } 94 #endif 95 #endif 96 97 /* While we generally would like users to use a configure-driven 98 build process which detects which headers are present and 99 hence works on any platform, we use "standard" includes here 100 to build out-of-the-box for beginning users on common systems. 101 102 Once you have a proper build system and go for more exotic 103 platforms, you should define MHD_PLATFORM_H in some header that 104 you always include *before* "microhttpd.h". Then the following 105 "standard" includes won't be used (which might be a good 106 idea, especially on platforms where they do not exist). */ 107 #ifndef MHD_PLATFORM_H 108 #include <stdarg.h> 109 #include <stdint.h> 110 #include <sys/types.h> 111 #if defined(_WIN32) && !defined(__CYGWIN__) 112 #include <ws2tcpip.h> 113 #if defined(_MSC_FULL_VER) && !defined (_SSIZE_T_DEFINED) 114 #define _SSIZE_T_DEFINED 115 typedef intptr_t ssize_t; 116 #endif // !_SSIZE_T_DEFINED */ 117 #else 118 #include <unistd.h> 119 #include <sys/time.h> 120 #include <sys/socket.h> 121 #endif 122 #endif 123 124 #if defined(__CYGWIN__) && !defined(_SYS_TYPES_FD_SET) 125 /* Do not define __USE_W32_SOCKETS under Cygwin! */ 126 #error Cygwin with winsock fd_set is not supported 127 #endif 128 129 /** 130 * Current version of the library. 131 * 0x01093001 = 1.9.30-1. 132 */ 133 #define MHD_VERSION 0x00094200 134 135 /** 136 * MHD-internal return code for "YES". 137 */ 138 #define MHD_YES 1 139 140 /** 141 * MHD-internal return code for "NO". 142 */ 143 #define MHD_NO 0 144 145 /** 146 * MHD digest auth internal code for an invalid nonce. 147 */ 148 #define MHD_INVALID_NONCE -1 149 150 /** 151 * Constant used to indicate unknown size (use when 152 * creating a response). 153 */ 154 #ifdef UINT64_MAX 155 #define MHD_SIZE_UNKNOWN UINT64_MAX 156 #else 157 #define MHD_SIZE_UNKNOWN ((uint64_t) -1LL) 158 #endif 159 160 #ifdef SIZE_MAX 161 #define MHD_CONTENT_READER_END_OF_STREAM SIZE_MAX 162 #define MHD_CONTENT_READER_END_WITH_ERROR (SIZE_MAX - 1) 163 #else 164 #define MHD_CONTENT_READER_END_OF_STREAM ((size_t) -1LL) 165 #define MHD_CONTENT_READER_END_WITH_ERROR (((size_t) -1LL) - 1) 166 #endif 167 168 #ifndef _MHD_EXTERN 169 #if defined(_WIN32) && defined(MHD_W32LIB) 170 #define _MHD_EXTERN extern 171 #elif defined (_WIN32) && defined(MHD_W32DLL) 172 /* Define MHD_W32DLL when using MHD as W32 .DLL to speed up linker a little */ 173 #define _MHD_EXTERN __declspec(dllimport) 174 #else 175 #define _MHD_EXTERN extern 176 #endif 177 #endif 178 179 #ifndef MHD_SOCKET_DEFINED 180 /** 181 * MHD_socket is type for socket FDs 182 */ 183 #if !defined(_WIN32) || defined(_SYS_TYPES_FD_SET) 184 #define MHD_POSIX_SOCKETS 1 185 typedef int MHD_socket; 186 #define MHD_INVALID_SOCKET (-1) 187 #else /* !defined(_WIN32) || defined(_SYS_TYPES_FD_SET) */ 188 #define MHD_WINSOCK_SOCKETS 1 189 #include <winsock2.h> 190 typedef SOCKET MHD_socket; 191 #define MHD_INVALID_SOCKET (INVALID_SOCKET) 192 #endif /* !defined(_WIN32) || defined(_SYS_TYPES_FD_SET) */ 193 #define MHD_SOCKET_DEFINED 1 194 #endif /* MHD_SOCKET_DEFINED */ 195 196 /** 197 * Not all architectures and `printf()`'s support the `long long` type. 198 * This gives the ability to replace `long long` with just a `long`, 199 * standard `int` or a `short`. 200 */ 201 #ifndef MHD_LONG_LONG 202 /** 203 * @deprecated use #MHD_UNSIGNED_LONG_LONG instead! 204 */ 205 #define MHD_LONG_LONG long long 206 #define MHD_UNSIGNED_LONG_LONG unsigned long long 207 #endif 208 /** 209 * Format string for printing a variable of type #MHD_LONG_LONG. 210 * You should only redefine this if you also define #MHD_LONG_LONG. 211 */ 212 #ifndef MHD_LONG_LONG_PRINTF 213 /** 214 * @deprecated use #MHD_UNSIGNED_LONG_LONG_PRINTF instead! 215 */ 216 #define MHD_LONG_LONG_PRINTF "ll" 217 #define MHD_UNSIGNED_LONG_LONG_PRINTF "%llu" 218 #endif 219 220 221 /** 222 * @defgroup httpcode HTTP response codes. 223 * These are the status codes defined for HTTP responses. 224 * @{ 225 */ 226 #define MHD_HTTP_CONTINUE 100 227 #define MHD_HTTP_SWITCHING_PROTOCOLS 101 228 #define MHD_HTTP_PROCESSING 102 229 230 #define MHD_HTTP_OK 200 231 #define MHD_HTTP_CREATED 201 232 #define MHD_HTTP_ACCEPTED 202 233 #define MHD_HTTP_NON_AUTHORITATIVE_INFORMATION 203 234 #define MHD_HTTP_NO_CONTENT 204 235 #define MHD_HTTP_RESET_CONTENT 205 236 #define MHD_HTTP_PARTIAL_CONTENT 206 237 #define MHD_HTTP_MULTI_STATUS 207 238 239 #define MHD_HTTP_MULTIPLE_CHOICES 300 240 #define MHD_HTTP_MOVED_PERMANENTLY 301 241 #define MHD_HTTP_FOUND 302 242 #define MHD_HTTP_SEE_OTHER 303 243 #define MHD_HTTP_NOT_MODIFIED 304 244 #define MHD_HTTP_USE_PROXY 305 245 #define MHD_HTTP_SWITCH_PROXY 306 246 #define MHD_HTTP_TEMPORARY_REDIRECT 307 247 248 #define MHD_HTTP_BAD_REQUEST 400 249 #define MHD_HTTP_UNAUTHORIZED 401 250 #define MHD_HTTP_PAYMENT_REQUIRED 402 251 #define MHD_HTTP_FORBIDDEN 403 252 #define MHD_HTTP_NOT_FOUND 404 253 #define MHD_HTTP_METHOD_NOT_ALLOWED 405 254 #define MHD_HTTP_NOT_ACCEPTABLE 406 255 /** @deprecated */ 256 #define MHD_HTTP_METHOD_NOT_ACCEPTABLE 406 257 #define MHD_HTTP_PROXY_AUTHENTICATION_REQUIRED 407 258 #define MHD_HTTP_REQUEST_TIMEOUT 408 259 #define MHD_HTTP_CONFLICT 409 260 #define MHD_HTTP_GONE 410 261 #define MHD_HTTP_LENGTH_REQUIRED 411 262 #define MHD_HTTP_PRECONDITION_FAILED 412 263 #define MHD_HTTP_REQUEST_ENTITY_TOO_LARGE 413 264 #define MHD_HTTP_REQUEST_URI_TOO_LONG 414 265 #define MHD_HTTP_UNSUPPORTED_MEDIA_TYPE 415 266 #define MHD_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE 416 267 #define MHD_HTTP_EXPECTATION_FAILED 417 268 #define MHD_HTTP_UNPROCESSABLE_ENTITY 422 269 #define MHD_HTTP_LOCKED 423 270 #define MHD_HTTP_FAILED_DEPENDENCY 424 271 #define MHD_HTTP_UNORDERED_COLLECTION 425 272 #define MHD_HTTP_UPGRADE_REQUIRED 426 273 #define MHD_HTTP_NO_RESPONSE 444 274 #define MHD_HTTP_RETRY_WITH 449 275 #define MHD_HTTP_BLOCKED_BY_WINDOWS_PARENTAL_CONTROLS 450 276 #define MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS 451 277 278 #define MHD_HTTP_INTERNAL_SERVER_ERROR 500 279 #define MHD_HTTP_NOT_IMPLEMENTED 501 280 #define MHD_HTTP_BAD_GATEWAY 502 281 #define MHD_HTTP_SERVICE_UNAVAILABLE 503 282 #define MHD_HTTP_GATEWAY_TIMEOUT 504 283 #define MHD_HTTP_HTTP_VERSION_NOT_SUPPORTED 505 284 #define MHD_HTTP_VARIANT_ALSO_NEGOTIATES 506 285 #define MHD_HTTP_INSUFFICIENT_STORAGE 507 286 #define MHD_HTTP_BANDWIDTH_LIMIT_EXCEEDED 509 287 #define MHD_HTTP_NOT_EXTENDED 510 288 289 /** @} */ /* end of group httpcode */ 290 291 /** 292 * Flag to be or-ed with MHD_HTTP status code for 293 * SHOUTcast. This will cause the response to begin 294 * with the SHOUTcast "ICY" line instad of "HTTP". 295 * @ingroup specialized 296 */ 297 #define MHD_ICY_FLAG ((uint32_t)(((uint32_t)1) << 31)) 298 299 /** 300 * @defgroup headers HTTP headers 301 * These are the standard headers found in HTTP requests and responses. 302 * @{ 303 */ 304 /* See also: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html */ 305 #define MHD_HTTP_HEADER_ACCEPT "Accept" 306 #define MHD_HTTP_HEADER_ACCEPT_CHARSET "Accept-Charset" 307 #define MHD_HTTP_HEADER_ACCEPT_ENCODING "Accept-Encoding" 308 #define MHD_HTTP_HEADER_ACCEPT_LANGUAGE "Accept-Language" 309 #define MHD_HTTP_HEADER_ACCEPT_RANGES "Accept-Ranges" 310 #define MHD_HTTP_HEADER_AGE "Age" 311 #define MHD_HTTP_HEADER_ALLOW "Allow" 312 #define MHD_HTTP_HEADER_AUTHORIZATION "Authorization" 313 #define MHD_HTTP_HEADER_CACHE_CONTROL "Cache-Control" 314 #define MHD_HTTP_HEADER_CONNECTION "Connection" 315 #define MHD_HTTP_HEADER_CONTENT_ENCODING "Content-Encoding" 316 #define MHD_HTTP_HEADER_CONTENT_LANGUAGE "Content-Language" 317 #define MHD_HTTP_HEADER_CONTENT_LENGTH "Content-Length" 318 #define MHD_HTTP_HEADER_CONTENT_LOCATION "Content-Location" 319 #define MHD_HTTP_HEADER_CONTENT_MD5 "Content-MD5" 320 #define MHD_HTTP_HEADER_CONTENT_RANGE "Content-Range" 321 #define MHD_HTTP_HEADER_CONTENT_TYPE "Content-Type" 322 #define MHD_HTTP_HEADER_COOKIE "Cookie" 323 #define MHD_HTTP_HEADER_DATE "Date" 324 #define MHD_HTTP_HEADER_ETAG "ETag" 325 #define MHD_HTTP_HEADER_EXPECT "Expect" 326 #define MHD_HTTP_HEADER_EXPIRES "Expires" 327 #define MHD_HTTP_HEADER_FROM "From" 328 #define MHD_HTTP_HEADER_HOST "Host" 329 #define MHD_HTTP_HEADER_IF_MATCH "If-Match" 330 #define MHD_HTTP_HEADER_IF_MODIFIED_SINCE "If-Modified-Since" 331 #define MHD_HTTP_HEADER_IF_NONE_MATCH "If-None-Match" 332 #define MHD_HTTP_HEADER_IF_RANGE "If-Range" 333 #define MHD_HTTP_HEADER_IF_UNMODIFIED_SINCE "If-Unmodified-Since" 334 #define MHD_HTTP_HEADER_LAST_MODIFIED "Last-Modified" 335 #define MHD_HTTP_HEADER_LOCATION "Location" 336 #define MHD_HTTP_HEADER_MAX_FORWARDS "Max-Forwards" 337 #define MHD_HTTP_HEADER_PRAGMA "Pragma" 338 #define MHD_HTTP_HEADER_PROXY_AUTHENTICATE "Proxy-Authenticate" 339 #define MHD_HTTP_HEADER_PROXY_AUTHORIZATION "Proxy-Authorization" 340 #define MHD_HTTP_HEADER_RANGE "Range" 341 /* This is not a typo, see HTTP spec */ 342 #define MHD_HTTP_HEADER_REFERER "Referer" 343 #define MHD_HTTP_HEADER_RETRY_AFTER "Retry-After" 344 #define MHD_HTTP_HEADER_SERVER "Server" 345 #define MHD_HTTP_HEADER_SET_COOKIE "Set-Cookie" 346 #define MHD_HTTP_HEADER_SET_COOKIE2 "Set-Cookie2" 347 #define MHD_HTTP_HEADER_TE "TE" 348 #define MHD_HTTP_HEADER_TRAILER "Trailer" 349 #define MHD_HTTP_HEADER_TRANSFER_ENCODING "Transfer-Encoding" 350 #define MHD_HTTP_HEADER_UPGRADE "Upgrade" 351 #define MHD_HTTP_HEADER_USER_AGENT "User-Agent" 352 #define MHD_HTTP_HEADER_VARY "Vary" 353 #define MHD_HTTP_HEADER_VIA "Via" 354 #define MHD_HTTP_HEADER_WARNING "Warning" 355 #define MHD_HTTP_HEADER_WWW_AUTHENTICATE "WWW-Authenticate" 356 #define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN "Access-Control-Allow-Origin" 357 358 /** @} */ /* end of group headers */ 359 360 /** 361 * @defgroup versions HTTP versions 362 * These strings should be used to match against the first line of the 363 * HTTP header. 364 * @{ 365 */ 366 #define MHD_HTTP_VERSION_1_0 "HTTP/1.0" 367 #define MHD_HTTP_VERSION_1_1 "HTTP/1.1" 368 369 /** @} */ /* end of group versions */ 370 371 /** 372 * @defgroup methods HTTP methods 373 * Standard HTTP methods (as strings). 374 * @{ 375 */ 376 #define MHD_HTTP_METHOD_CONNECT "CONNECT" 377 #define MHD_HTTP_METHOD_DELETE "DELETE" 378 #define MHD_HTTP_METHOD_GET "GET" 379 #define MHD_HTTP_METHOD_HEAD "HEAD" 380 #define MHD_HTTP_METHOD_OPTIONS "OPTIONS" 381 #define MHD_HTTP_METHOD_POST "POST" 382 #define MHD_HTTP_METHOD_PUT "PUT" 383 #define MHD_HTTP_METHOD_PATCH "PATCH" 384 #define MHD_HTTP_METHOD_TRACE "TRACE" 385 386 /** @} */ /* end of group methods */ 387 388 /** 389 * @defgroup postenc HTTP POST encodings 390 * See also: http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4 391 * @{ 392 */ 393 #define MHD_HTTP_POST_ENCODING_FORM_URLENCODED "application/x-www-form-urlencoded" 394 #define MHD_HTTP_POST_ENCODING_MULTIPART_FORMDATA "multipart/form-data" 395 396 /** @} */ /* end of group postenc */ 397 398 399 /** 400 * @brief Handle for the daemon (listening on a socket for HTTP traffic). 401 * @ingroup event 402 */ 403 struct MHD_Daemon; 404 405 /** 406 * @brief Handle for a connection / HTTP request. 407 * 408 * With HTTP/1.1, multiple requests can be run over the same 409 * connection. However, MHD will only show one request per TCP 410 * connection to the client at any given time. 411 * @ingroup request 412 */ 413 struct MHD_Connection; 414 415 /** 416 * @brief Handle for a response. 417 * @ingroup response 418 */ 419 struct MHD_Response; 420 421 /** 422 * @brief Handle for POST processing. 423 * @ingroup response 424 */ 425 struct MHD_PostProcessor; 426 427 428 /** 429 * @brief Flags for the `struct MHD_Daemon`. 430 * 431 * Note that if neither #MHD_USE_THREAD_PER_CONNECTION nor 432 * #MHD_USE_SELECT_INTERNALLY is used, the client wants control over 433 * the process and will call the appropriate microhttpd callbacks. 434 * 435 * Starting the daemon may also fail if a particular option is not 436 * implemented or not supported on the target platform (i.e. no 437 * support for SSL, threads or IPv6). 438 */ 439 enum MHD_FLAG 440 { 441 /** 442 * No options selected. 443 */ 444 MHD_NO_FLAG = 0, 445 446 /** 447 * Run in debug mode. If this flag is used, the library should 448 * print error messages and warnings to `stderr`. 449 */ 450 MHD_USE_DEBUG = 1, 451 452 /** 453 * Run in HTTPS mode. 454 */ 455 MHD_USE_SSL = 2, 456 457 /** 458 * Run using one thread per connection. 459 */ 460 MHD_USE_THREAD_PER_CONNECTION = 4, 461 462 /** 463 * Run using an internal thread (or thread pool) doing `select()`. 464 */ 465 MHD_USE_SELECT_INTERNALLY = 8, 466 467 /** 468 * Run using the IPv6 protocol (otherwise, MHD will just support 469 * IPv4). If you want MHD to support IPv4 and IPv6 using a single 470 * socket, pass #MHD_USE_DUAL_STACK, otherwise, if you only pass 471 * this option, MHD will try to bind to IPv6-only (resulting in 472 * no IPv4 support). 473 */ 474 MHD_USE_IPv6 = 16, 475 476 /** 477 * Be pedantic about the protocol (as opposed to as tolerant as 478 * possible). Specifically, at the moment, this flag causes MHD to 479 * reject HTTP 1.1 connections without a "Host" header. This is 480 * required by the standard, but of course in violation of the "be 481 * as liberal as possible in what you accept" norm. It is 482 * recommended to turn this ON if you are testing clients against 483 * MHD, and OFF in production. 484 */ 485 MHD_USE_PEDANTIC_CHECKS = 32, 486 487 /** 488 * Use `poll()` instead of `select()`. This allows sockets with `fd >= 489 * FD_SETSIZE`. This option is not compatible with using an 490 * 'external' `select()` mode (as there is no API to get the file 491 * descriptors for the external select from MHD) and must also not 492 * be used in combination with #MHD_USE_EPOLL_LINUX_ONLY. 493 */ 494 MHD_USE_POLL = 64, 495 496 /** 497 * Run using an internal thread (or thread pool) doing `poll()`. 498 */ 499 MHD_USE_POLL_INTERNALLY = MHD_USE_SELECT_INTERNALLY | MHD_USE_POLL, 500 501 /** 502 * Suppress (automatically) adding the 'Date:' header to HTTP responses. 503 * This option should ONLY be used on systems that do not have a clock 504 * and that DO provide other mechanisms for cache control. See also 505 * RFC 2616, section 14.18 (exception 3). 506 */ 507 MHD_SUPPRESS_DATE_NO_CLOCK = 128, 508 509 /** 510 * Run without a listen socket. This option only makes sense if 511 * #MHD_add_connection is to be used exclusively to connect HTTP 512 * clients to the HTTP server. This option is incompatible with 513 * using a thread pool; if it is used, #MHD_OPTION_THREAD_POOL_SIZE 514 * is ignored. 515 */ 516 MHD_USE_NO_LISTEN_SOCKET = 256, 517 518 /** 519 * Use `epoll()` instead of `select()` or `poll()` for the event loop. 520 * This option is only available on Linux; using the option on 521 * non-Linux systems will cause #MHD_start_daemon to fail. 522 */ 523 MHD_USE_EPOLL_LINUX_ONLY = 512, 524 525 /** 526 * Run using an internal thread (or thread pool) doing `epoll()`. 527 * This option is only available on Linux; using the option on 528 * non-Linux systems will cause #MHD_start_daemon to fail. 529 */ 530 MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY = MHD_USE_SELECT_INTERNALLY | MHD_USE_EPOLL_LINUX_ONLY, 531 532 /** 533 * Force MHD to use a signal pipe to notify the event loop (of 534 * threads) of our shutdown. This is required if an appliction uses 535 * #MHD_USE_SELECT_INTERNALLY or #MHD_USE_THREAD_PER_CONNECTION and 536 * then performs #MHD_quiesce_daemon (which eliminates our ability 537 * to signal termination via the listen socket). In these modes, 538 * #MHD_quiesce_daemon will fail if this option was not set. Also, 539 * use of this option is automatic (as in, you do not even have to 540 * specify it), if #MHD_USE_NO_LISTEN_SOCKET is specified. In 541 * "external" `select()` mode, this option is always simply ignored. 542 * MHD can be build for use a pair of sockets instead of a pipe. 543 * Pair of sockets is forced on W32. 544 * 545 * You must also use this option if you use internal select mode 546 * or a thread pool in conjunction with #MHD_add_connection. 547 */ 548 MHD_USE_PIPE_FOR_SHUTDOWN = 1024, 549 550 /** 551 * Use a single socket for IPv4 and IPv6. 552 */ 553 MHD_USE_DUAL_STACK = MHD_USE_IPv6 | 2048, 554 555 /** 556 * Enable `epoll()` turbo. Disables certain calls to `shutdown()` 557 * and enables aggressive non-blocking optimisitc reads. 558 * Most effects only happen with #MHD_USE_EPOLL_LINUX_ONLY. 559 * Enalbed always on W32 as winsock does not properly behave 560 * with `shutdown()` and this then fixes potential problems. 561 */ 562 MHD_USE_EPOLL_TURBO = 4096, 563 564 /** 565 * Enable suspend/resume functions, which also implies setting up 566 * pipes to signal resume. 567 */ 568 MHD_USE_SUSPEND_RESUME = 8192 | MHD_USE_PIPE_FOR_SHUTDOWN, 569 570 /** 571 * Enable TCP_FASTOPEN option. This option is only available on Linux with a 572 * kernel >= 3.6. On other systems, using this option cases #MHD_start_daemon 573 * to fail. 574 */ 575 MHD_USE_TCP_FASTOPEN = 16384 576 577 }; 578 579 580 /** 581 * Type of a callback function used for logging by MHD. 582 * 583 * @param cls closure 584 * @param fm format string (`printf()`-style) 585 * @param ap arguments to @a fm 586 * @ingroup logging 587 */ 588 typedef void (*MHD_LogCallback)(void *cls, const char *fm, va_list ap); 589 590 591 /** 592 * @brief MHD options. 593 * 594 * Passed in the varargs portion of #MHD_start_daemon. 595 */ 596 enum MHD_OPTION 597 { 598 599 /** 600 * No more options / last option. This is used 601 * to terminate the VARARGs list. 602 */ 603 MHD_OPTION_END = 0, 604 605 /** 606 * Maximum memory size per connection (followed by a `size_t`). 607 * Default is 32 kb (#MHD_POOL_SIZE_DEFAULT). 608 * Values above 128k are unlikely to result in much benefit, as half 609 * of the memory will be typically used for IO, and TCP buffers are 610 * unlikely to support window sizes above 64k on most systems. 611 */ 612 MHD_OPTION_CONNECTION_MEMORY_LIMIT = 1, 613 614 /** 615 * Maximum number of concurrent connections to 616 * accept (followed by an `unsigned int`). 617 */ 618 MHD_OPTION_CONNECTION_LIMIT = 2, 619 620 /** 621 * After how many seconds of inactivity should a 622 * connection automatically be timed out? (followed 623 * by an `unsigned int`; use zero for no timeout). 624 */ 625 MHD_OPTION_CONNECTION_TIMEOUT = 3, 626 627 /** 628 * Register a function that should be called whenever a request has 629 * been completed (this can be used for application-specific clean 630 * up). Requests that have never been presented to the application 631 * (via #MHD_AccessHandlerCallback) will not result in 632 * notifications. 633 * 634 * This option should be followed by TWO pointers. First a pointer 635 * to a function of type #MHD_RequestCompletedCallback and second a 636 * pointer to a closure to pass to the request completed callback. 637 * The second pointer maybe NULL. 638 */ 639 MHD_OPTION_NOTIFY_COMPLETED = 4, 640 641 /** 642 * Limit on the number of (concurrent) connections made to the 643 * server from the same IP address. Can be used to prevent one 644 * IP from taking over all of the allowed connections. If the 645 * same IP tries to establish more than the specified number of 646 * connections, they will be immediately rejected. The option 647 * should be followed by an `unsigned int`. The default is 648 * zero, which means no limit on the number of connections 649 * from the same IP address. 650 */ 651 MHD_OPTION_PER_IP_CONNECTION_LIMIT = 5, 652 653 /** 654 * Bind daemon to the supplied `struct sockaddr`. This option should 655 * be followed by a `struct sockaddr *`. If #MHD_USE_IPv6 is 656 * specified, the `struct sockaddr*` should point to a `struct 657 * sockaddr_in6`, otherwise to a `struct sockaddr_in`. 658 */ 659 MHD_OPTION_SOCK_ADDR = 6, 660 661 /** 662 * Specify a function that should be called before parsing the URI from 663 * the client. The specified callback function can be used for processing 664 * the URI (including the options) before it is parsed. The URI after 665 * parsing will no longer contain the options, which maybe inconvenient for 666 * logging. This option should be followed by two arguments, the first 667 * one must be of the form 668 * 669 * void * my_logger(void *cls, const char *uri, struct MHD_Connection *con) 670 * 671 * where the return value will be passed as 672 * (`* con_cls`) in calls to the #MHD_AccessHandlerCallback 673 * when this request is processed later; returning a 674 * value of NULL has no special significance (however, 675 * note that if you return non-NULL, you can no longer 676 * rely on the first call to the access handler having 677 * `NULL == *con_cls` on entry;) 678 * "cls" will be set to the second argument following 679 * #MHD_OPTION_URI_LOG_CALLBACK. Finally, uri will 680 * be the 0-terminated URI of the request. 681 * 682 * Note that during the time of this call, most of the connection's 683 * state is not initialized (as we have not yet parsed he headers). 684 * However, information about the connecting client (IP, socket) 685 * is available. 686 */ 687 MHD_OPTION_URI_LOG_CALLBACK = 7, 688 689 /** 690 * Memory pointer for the private key (key.pem) to be used by the 691 * HTTPS daemon. This option should be followed by a 692 * `const char *` argument. 693 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_CERT. 694 */ 695 MHD_OPTION_HTTPS_MEM_KEY = 8, 696 697 /** 698 * Memory pointer for the certificate (cert.pem) to be used by the 699 * HTTPS daemon. This option should be followed by a 700 * `const char *` argument. 701 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY. 702 */ 703 MHD_OPTION_HTTPS_MEM_CERT = 9, 704 705 /** 706 * Daemon credentials type. 707 * Followed by an argument of type 708 * `gnutls_credentials_type_t`. 709 */ 710 MHD_OPTION_HTTPS_CRED_TYPE = 10, 711 712 /** 713 * Memory pointer to a `const char *` specifying the 714 * cipher algorithm (default: "NORMAL"). 715 */ 716 MHD_OPTION_HTTPS_PRIORITIES = 11, 717 718 /** 719 * Pass a listen socket for MHD to use (systemd-style). If this 720 * option is used, MHD will not open its own listen socket(s). The 721 * argument passed must be of type `int` and refer to an 722 * existing socket that has been bound to a port and is listening. 723 */ 724 MHD_OPTION_LISTEN_SOCKET = 12, 725 726 /** 727 * Use the given function for logging error messages. This option 728 * must be followed by two arguments; the first must be a pointer to 729 * a function of type #MHD_LogCallback and the second a pointer 730 * `void *` which will be passed as the first argument to the log 731 * callback. 732 * 733 * Note that MHD will not generate any log messages 734 * if it was compiled without the "--enable-messages" 735 * flag being set. 736 */ 737 MHD_OPTION_EXTERNAL_LOGGER = 13, 738 739 /** 740 * Number (`unsigned int`) of threads in thread pool. Enable 741 * thread pooling by setting this value to to something 742 * greater than 1. Currently, thread model must be 743 * #MHD_USE_SELECT_INTERNALLY if thread pooling is enabled 744 * (#MHD_start_daemon returns NULL for an unsupported thread 745 * model). 746 */ 747 MHD_OPTION_THREAD_POOL_SIZE = 14, 748 749 /** 750 * Additional options given in an array of `struct MHD_OptionItem`. 751 * The array must be terminated with an entry `{MHD_OPTION_END, 0, NULL}`. 752 * An example for code using #MHD_OPTION_ARRAY is: 753 * 754 * struct MHD_OptionItem ops[] = { 755 * { MHD_OPTION_CONNECTION_LIMIT, 100, NULL }, 756 * { MHD_OPTION_CONNECTION_TIMEOUT, 10, NULL }, 757 * { MHD_OPTION_END, 0, NULL } 758 * }; 759 * d = MHD_start_daemon (0, 8080, NULL, NULL, dh, NULL, 760 * MHD_OPTION_ARRAY, ops, 761 * MHD_OPTION_END); 762 * 763 * For options that expect a single pointer argument, the 764 * second member of the `struct MHD_OptionItem` is ignored. 765 * For options that expect two pointer arguments, the first 766 * argument must be cast to `intptr_t`. 767 */ 768 MHD_OPTION_ARRAY = 15, 769 770 /** 771 * Specify a function that should be called for unescaping escape 772 * sequences in URIs and URI arguments. Note that this function 773 * will NOT be used by the `struct MHD_PostProcessor`. If this 774 * option is not specified, the default method will be used which 775 * decodes escape sequences of the form "%HH". This option should 776 * be followed by two arguments, the first one must be of the form 777 * 778 * size_t my_unescaper(void *cls, 779 * struct MHD_Connection *c, 780 * char *s) 781 * 782 * where the return value must be "strlen(s)" and "s" should be 783 * updated. Note that the unescape function must not lengthen "s" 784 * (the result must be shorter than the input and still be 785 * 0-terminated). "cls" will be set to the second argument 786 * following #MHD_OPTION_UNESCAPE_CALLBACK. 787 */ 788 MHD_OPTION_UNESCAPE_CALLBACK = 16, 789 790 /** 791 * Memory pointer for the random values to be used by the Digest 792 * Auth module. This option should be followed by two arguments. 793 * First an integer of type `size_t` which specifies the size 794 * of the buffer pointed to by the second argument in bytes. 795 * Note that the application must ensure that the buffer of the 796 * second argument remains allocated and unmodified while the 797 * deamon is running. 798 */ 799 MHD_OPTION_DIGEST_AUTH_RANDOM = 17, 800 801 /** 802 * Size of the internal array holding the map of the nonce and 803 * the nonce counter. This option should be followed by an `unsigend int` 804 * argument. 805 */ 806 MHD_OPTION_NONCE_NC_SIZE = 18, 807 808 /** 809 * Desired size of the stack for threads created by MHD. Followed 810 * by an argument of type `size_t`. Use 0 for system default. 811 */ 812 MHD_OPTION_THREAD_STACK_SIZE = 19, 813 814 /** 815 * Memory pointer for the certificate (ca.pem) to be used by the 816 * HTTPS daemon for client authentification. 817 * This option should be followed by a `const char *` argument. 818 */ 819 MHD_OPTION_HTTPS_MEM_TRUST = 20, 820 821 /** 822 * Increment to use for growing the read buffer (followed by a 823 * `size_t`). Must fit within #MHD_OPTION_CONNECTION_MEMORY_LIMIT. 824 */ 825 MHD_OPTION_CONNECTION_MEMORY_INCREMENT = 21, 826 827 /** 828 * Use a callback to determine which X.509 certificate should be 829 * used for a given HTTPS connection. This option should be 830 * followed by a argument of type `gnutls_certificate_retrieve_function2 *`. 831 * This option provides an 832 * alternative to #MHD_OPTION_HTTPS_MEM_KEY, 833 * #MHD_OPTION_HTTPS_MEM_CERT. You must use this version if 834 * multiple domains are to be hosted at the same IP address using 835 * TLS's Server Name Indication (SNI) extension. In this case, 836 * the callback is expected to select the correct certificate 837 * based on the SNI information provided. The callback is expected 838 * to access the SNI data using `gnutls_server_name_get()`. 839 * Using this option requires GnuTLS 3.0 or higher. 840 */ 841 MHD_OPTION_HTTPS_CERT_CALLBACK = 22, 842 843 /** 844 * When using #MHD_USE_TCP_FASTOPEN, this option changes the default TCP 845 * fastopen queue length of 50. Note that having a larger queue size can 846 * cause resource exhaustion attack as the TCP stack has to now allocate 847 * resources for the SYN packet along with its DATA. This option should be 848 * followed by an `unsigned int` argument. 849 */ 850 MHD_OPTION_TCP_FASTOPEN_QUEUE_SIZE = 23, 851 852 /** 853 * Memory pointer for the Diffie-Hellman parameters (dh.pem) to be used by the 854 * HTTPS daemon for key exchange. 855 * This option must be followed by a `const char *` argument. 856 */ 857 MHD_OPTION_HTTPS_MEM_DHPARAMS = 24, 858 859 /** 860 * If present and set to true, allow reusing address:port socket 861 * (by using SO_REUSEPORT on most platform, or platform-specific ways). 862 * If present and set to false, disallow reusing address:port socket 863 * (does nothing on most plaform, but uses SO_EXCLUSIVEADDRUSE on Windows). 864 * This option must be followed by a `unsigned int` argument. 865 */ 866 MHD_OPTION_LISTENING_ADDRESS_REUSE = 25, 867 868 /** 869 * Memory pointer for a password that decrypts the private key (key.pem) 870 * to be used by the HTTPS daemon. This option should be followed by a 871 * `const char *` argument. 872 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY. 873 * @sa ::MHD_FEATURE_HTTPS_KEY_PASSWORD 874 */ 875 MHD_OPTION_HTTPS_KEY_PASSWORD = 26, 876 877 /** 878 * Register a function that should be called whenever a connection is 879 * started or closed. 880 * 881 * This option should be followed by TWO pointers. First a pointer 882 * to a function of type #MHD_NotifyConnectionCallback and second a 883 * pointer to a closure to pass to the request completed callback. 884 * The second pointer maybe NULL. 885 */ 886 MHD_OPTION_NOTIFY_CONNECTION = 27 887 888 }; 889 890 891 /** 892 * Entry in an #MHD_OPTION_ARRAY. 893 */ 894 struct MHD_OptionItem 895 { 896 /** 897 * Which option is being given. Use #MHD_OPTION_END 898 * to terminate the array. 899 */ 900 enum MHD_OPTION option; 901 902 /** 903 * Option value (for integer arguments, and for options requiring 904 * two pointer arguments); should be 0 for options that take no 905 * arguments or only a single pointer argument. 906 */ 907 intptr_t value; 908 909 /** 910 * Pointer option value (use NULL for options taking no arguments 911 * or only an integer option). 912 */ 913 void *ptr_value; 914 915 }; 916 917 918 /** 919 * The `enum MHD_ValueKind` specifies the source of 920 * the key-value pairs in the HTTP protocol. 921 */ 922 enum MHD_ValueKind 923 { 924 925 /** 926 * Response header 927 */ 928 MHD_RESPONSE_HEADER_KIND = 0, 929 930 /** 931 * HTTP header. 932 */ 933 MHD_HEADER_KIND = 1, 934 935 /** 936 * Cookies. Note that the original HTTP header containing 937 * the cookie(s) will still be available and intact. 938 */ 939 MHD_COOKIE_KIND = 2, 940 941 /** 942 * POST data. This is available only if a content encoding 943 * supported by MHD is used (currently only URL encoding), 944 * and only if the posted content fits within the available 945 * memory pool. Note that in that case, the upload data 946 * given to the #MHD_AccessHandlerCallback will be 947 * empty (since it has already been processed). 948 */ 949 MHD_POSTDATA_KIND = 4, 950 951 /** 952 * GET (URI) arguments. 953 */ 954 MHD_GET_ARGUMENT_KIND = 8, 955 956 /** 957 * HTTP footer (only for HTTP 1.1 chunked encodings). 958 */ 959 MHD_FOOTER_KIND = 16 960 }; 961 962 963 /** 964 * The `enum MHD_RequestTerminationCode` specifies reasons 965 * why a request has been terminated (or completed). 966 * @ingroup request 967 */ 968 enum MHD_RequestTerminationCode 969 { 970 971 /** 972 * We finished sending the response. 973 * @ingroup request 974 */ 975 MHD_REQUEST_TERMINATED_COMPLETED_OK = 0, 976 977 /** 978 * Error handling the connection (resources 979 * exhausted, other side closed connection, 980 * application error accepting request, etc.) 981 * @ingroup request 982 */ 983 MHD_REQUEST_TERMINATED_WITH_ERROR = 1, 984 985 /** 986 * No activity on the connection for the number 987 * of seconds specified using 988 * #MHD_OPTION_CONNECTION_TIMEOUT. 989 * @ingroup request 990 */ 991 MHD_REQUEST_TERMINATED_TIMEOUT_REACHED = 2, 992 993 /** 994 * We had to close the session since MHD was being 995 * shut down. 996 * @ingroup request 997 */ 998 MHD_REQUEST_TERMINATED_DAEMON_SHUTDOWN = 3, 999 1000 /** 1001 * We tried to read additional data, but the other side closed the 1002 * connection. This error is similar to 1003 * #MHD_REQUEST_TERMINATED_WITH_ERROR, but specific to the case where 1004 * the connection died because the other side did not send expected 1005 * data. 1006 * @ingroup request 1007 */ 1008 MHD_REQUEST_TERMINATED_READ_ERROR = 4, 1009 1010 /** 1011 * The client terminated the connection by closing the socket 1012 * for writing (TCP half-closed); MHD aborted sending the 1013 * response according to RFC 2616, section 8.1.4. 1014 * @ingroup request 1015 */ 1016 MHD_REQUEST_TERMINATED_CLIENT_ABORT = 5 1017 1018 }; 1019 1020 1021 /** 1022 * The `enum MHD_ConnectionNotificationCode` specifies types 1023 * of connection notifications. 1024 * @ingroup request 1025 */ 1026 enum MHD_ConnectionNotificationCode 1027 { 1028 1029 /** 1030 * A new connection has been started. 1031 * @ingroup request 1032 */ 1033 MHD_CONNECTION_NOTIFY_STARTED = 0, 1034 1035 /** 1036 * A connection is closed. 1037 * @ingroup request 1038 */ 1039 MHD_CONNECTION_NOTIFY_CLOSED = 1 1040 1041 }; 1042 1043 1044 /** 1045 * Information about a connection. 1046 */ 1047 union MHD_ConnectionInfo 1048 { 1049 1050 /** 1051 * Cipher algorithm used, as a string. 1052 */ 1053 const char* cipher_algorithm; 1054 1055 /** 1056 * Protocol used, as a string. 1057 */ 1058 const char* protocol; 1059 1060 /** 1061 * Connect socket 1062 */ 1063 MHD_socket connect_fd; 1064 1065 /** 1066 * TLS session handle, of type "SSL". 1067 */ 1068 void * /* SSL */ tls_session; 1069 1070 /** 1071 * TLS client certificate handle, of type "X509". 1072 */ 1073 void * /* X509 */ client_cert; 1074 1075 /** 1076 * Address information for the client. 1077 */ 1078 struct sockaddr *client_addr; 1079 1080 /** 1081 * Which daemon manages this connection (useful in case there are many 1082 * daemons running). 1083 */ 1084 struct MHD_Daemon *daemon; 1085 1086 /** 1087 * Socket-specific client context. Points to the same address as 1088 * the "socket_context" of the #MHD_NotifyConnectionCallback. 1089 */ 1090 void **socket_context; 1091 }; 1092 1093 1094 /** 1095 * Values of this enum are used to specify what 1096 * information about a connection is desired. 1097 * @ingroup request 1098 */ 1099 enum MHD_ConnectionInfoType 1100 { 1101 /** 1102 * What cipher algorithm is being used. 1103 * Takes no extra arguments. 1104 * @ingroup request 1105 */ 1106 MHD_CONNECTION_INFO_CIPHER_ALGO, 1107 1108 /** 1109 * 1110 * Takes no extra arguments. 1111 * @ingroup request 1112 */ 1113 MHD_CONNECTION_INFO_PROTOCOL, 1114 1115 /** 1116 * Obtain IP address of the client. Takes no extra arguments. 1117 * Returns essentially a `struct sockaddr **` (since the API returns 1118 * a `union MHD_ConnectionInfo *` and that union contains a `struct 1119 * sockaddr *`). 1120 * @ingroup request 1121 */ 1122 MHD_CONNECTION_INFO_CLIENT_ADDRESS, 1123 1124 /** 1125 * Get the TLS session handle. 1126 * @ingroup request 1127 */ 1128 MHD_CONNECTION_INFO_TLS_SESSION, 1129 1130 /** 1131 * Get the gnuTLS client certificate handle. Dysfunctional (never 1132 * implemented, deprecated). Use #MHD_CONNECTION_INFO_TLS_SESSION 1133 * to get the `SSL` and then call 1134 * SSL_get_peer_certificate() or SSL_get_peer_cert_chain(). 1135 */ 1136 MHD_CONNECTION_INFO_TLS_CLIENT_CERT, 1137 1138 /** 1139 * Get the `struct MHD_Daemon *` responsible for managing this connection. 1140 * @ingroup request 1141 */ 1142 MHD_CONNECTION_INFO_DAEMON, 1143 1144 /** 1145 * Request the file descriptor for the listening socket. 1146 * No extra arguments should be passed. 1147 * @ingroup request 1148 */ 1149 MHD_CONNECTION_INFO_CONNECTION_FD, 1150 1151 /** 1152 * Returns the client-specific pointer to a `void *` that was (possibly) 1153 * set during a #MHD_NotifyConnectionCallback when the socket was 1154 * first accepted. Note that this is NOT the same as the "con_cls" 1155 * argument of the #MHD_AccessHandlerCallback. The "con_cls" is 1156 * fresh for each HTTP request, while the "socket_context" is fresh 1157 * for each socket. 1158 */ 1159 MHD_CONNECTION_INFO_SOCKET_CONTEXT 1160 1161 }; 1162 1163 1164 /** 1165 * Values of this enum are used to specify what 1166 * information about a deamon is desired. 1167 */ 1168 enum MHD_DaemonInfoType 1169 { 1170 /** 1171 * No longer supported (will return NULL). 1172 */ 1173 MHD_DAEMON_INFO_KEY_SIZE, 1174 1175 /** 1176 * No longer supported (will return NULL). 1177 */ 1178 MHD_DAEMON_INFO_MAC_KEY_SIZE, 1179 1180 /** 1181 * Request the file descriptor for the listening socket. 1182 * No extra arguments should be passed. 1183 */ 1184 MHD_DAEMON_INFO_LISTEN_FD, 1185 1186 /** 1187 * Request the file descriptor for the external epoll. 1188 * No extra arguments should be passed. 1189 */ 1190 MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY, 1191 1192 /** 1193 * Request the number of current connections handled by the daemon. 1194 * No extra arguments should be passed. 1195 */ 1196 MHD_DAEMON_INFO_CURRENT_CONNECTIONS 1197 }; 1198 1199 1200 /** 1201 * Callback for serious error condition. The default action is to print 1202 * an error message and `abort()`. 1203 * 1204 * @param cls user specified value 1205 * @param file where the error occured 1206 * @param line where the error occured 1207 * @param reason error detail, may be NULL 1208 * @ingroup logging 1209 */ 1210 typedef void 1211 (*MHD_PanicCallback) (void *cls, 1212 const char *file, 1213 unsigned int line, 1214 const char *reason); 1215 1216 /** 1217 * Allow or deny a client to connect. 1218 * 1219 * @param cls closure 1220 * @param addr address information from the client 1221 * @param addrlen length of @a addr 1222 * @return #MHD_YES if connection is allowed, #MHD_NO if not 1223 */ 1224 typedef int 1225 (*MHD_AcceptPolicyCallback) (void *cls, 1226 const struct sockaddr *addr, 1227 socklen_t addrlen); 1228 1229 1230 /** 1231 * A client has requested the given url using the given method 1232 * (#MHD_HTTP_METHOD_GET, #MHD_HTTP_METHOD_PUT, 1233 * #MHD_HTTP_METHOD_DELETE, #MHD_HTTP_METHOD_POST, etc). The callback 1234 * must call MHD callbacks to provide content to give back to the 1235 * client and return an HTTP status code (i.e. #MHD_HTTP_OK, 1236 * #MHD_HTTP_NOT_FOUND, etc.). 1237 * 1238 * @param cls argument given together with the function 1239 * pointer when the handler was registered with MHD 1240 * @param url the requested url 1241 * @param method the HTTP method used (#MHD_HTTP_METHOD_GET, 1242 * #MHD_HTTP_METHOD_PUT, etc.) 1243 * @param version the HTTP version string (i.e. 1244 * #MHD_HTTP_VERSION_1_1) 1245 * @param upload_data the data being uploaded (excluding HEADERS, 1246 * for a POST that fits into memory and that is encoded 1247 * with a supported encoding, the POST data will NOT be 1248 * given in upload_data and is instead available as 1249 * part of #MHD_get_connection_values; very large POST 1250 * data *will* be made available incrementally in 1251 * @a upload_data) 1252 * @param upload_data_size set initially to the size of the 1253 * @a upload_data provided; the method must update this 1254 * value to the number of bytes NOT processed; 1255 * @param con_cls pointer that the callback can set to some 1256 * address and that will be preserved by MHD for future 1257 * calls for this request; since the access handler may 1258 * be called many times (i.e., for a PUT/POST operation 1259 * with plenty of upload data) this allows the application 1260 * to easily associate some request-specific state. 1261 * If necessary, this state can be cleaned up in the 1262 * global #MHD_RequestCompletedCallback (which 1263 * can be set with the #MHD_OPTION_NOTIFY_COMPLETED). 1264 * Initially, `*con_cls` will be NULL. 1265 * @return #MHD_YES if the connection was handled successfully, 1266 * #MHD_NO if the socket must be closed due to a serios 1267 * error while handling the request 1268 */ 1269 typedef int 1270 (*MHD_AccessHandlerCallback) (void *cls, 1271 struct MHD_Connection *connection, 1272 const char *url, 1273 const char *method, 1274 const char *version, 1275 const char *upload_data, 1276 size_t *upload_data_size, 1277 void **con_cls); 1278 1279 1280 /** 1281 * Signature of the callback used by MHD to notify the 1282 * application about completed requests. 1283 * 1284 * @param cls client-defined closure 1285 * @param connection connection handle 1286 * @param con_cls value as set by the last call to 1287 * the #MHD_AccessHandlerCallback 1288 * @param toe reason for request termination 1289 * @see #MHD_OPTION_NOTIFY_COMPLETED 1290 * @ingroup request 1291 */ 1292 typedef void 1293 (*MHD_RequestCompletedCallback) (void *cls, 1294 struct MHD_Connection *connection, 1295 void **con_cls, 1296 enum MHD_RequestTerminationCode toe); 1297 1298 /** 1299 * Signature of the callback used by MHD to notify the 1300 * application about started/stopped connections 1301 * 1302 * @param cls client-defined closure 1303 * @param connection connection handle 1304 * @param socket_context socket-specific pointer where the 1305 * client can associate some state specific 1306 * to the TCP connection; note that this is 1307 * different from the "con_cls" which is per 1308 * HTTP request. The client can initialize 1309 * during #MHD_CONNECTION_NOTIFY_STARTED and 1310 * cleanup during #MHD_CONNECTION_NOTIFY_CLOSED 1311 * and access in the meantime using 1312 * #MHD_CONNECTION_INFO_SOCKET_CONTEXT. 1313 * @param toe reason for connection notification 1314 * @see #MHD_OPTION_NOTIFY_CONNECTION 1315 * @ingroup request 1316 */ 1317 typedef void 1318 (*MHD_NotifyConnectionCallback) (void *cls, 1319 struct MHD_Connection *connection, 1320 void **socket_context, 1321 enum MHD_ConnectionNotificationCode toe); 1322 1323 1324 /** 1325 * Iterator over key-value pairs. This iterator 1326 * can be used to iterate over all of the cookies, 1327 * headers, or POST-data fields of a request, and 1328 * also to iterate over the headers that have been 1329 * added to a response. 1330 * 1331 * @param cls closure 1332 * @param kind kind of the header we are looking at 1333 * @param key key for the value, can be an empty string 1334 * @param value corresponding value, can be NULL 1335 * @return #MHD_YES to continue iterating, 1336 * #MHD_NO to abort the iteration 1337 * @ingroup request 1338 */ 1339 typedef int 1340 (*MHD_KeyValueIterator) (void *cls, 1341 enum MHD_ValueKind kind, 1342 const char *key, 1343 const char *value); 1344 1345 1346 /** 1347 * Callback used by libmicrohttpd in order to obtain content. The 1348 * callback is to copy at most @a max bytes of content into @a buf. The 1349 * total number of bytes that has been placed into @a buf should be 1350 * returned. 1351 * 1352 * Note that returning zero will cause libmicrohttpd to try again. 1353 * Thus, returning zero should only be used in conjunction 1354 * with MHD_suspend_connection() to avoid busy waiting. 1355 * 1356 * @param cls extra argument to the callback 1357 * @param pos position in the datastream to access; 1358 * note that if a `struct MHD_Response` object is re-used, 1359 * it is possible for the same content reader to 1360 * be queried multiple times for the same data; 1361 * however, if a `struct MHD_Response` is not re-used, 1362 * libmicrohttpd guarantees that "pos" will be 1363 * the sum of all non-negative return values 1364 * obtained from the content reader so far. 1365 * @param buf where to copy the data 1366 * @param max maximum number of bytes to copy to @a buf (size of @a buf) 1367 * @return number of bytes written to @a buf; 1368 * 0 is legal unless we are running in internal select mode (since 1369 * this would cause busy-waiting); 0 in external select mode 1370 * will cause this function to be called again once the external 1371 * select calls MHD again; 1372 * #MHD_CONTENT_READER_END_OF_STREAM (-1) for the regular 1373 * end of transmission (with chunked encoding, MHD will then 1374 * terminate the chunk and send any HTTP footers that might be 1375 * present; without chunked encoding and given an unknown 1376 * response size, MHD will simply close the connection; note 1377 * that while returning #MHD_CONTENT_READER_END_OF_STREAM is not technically 1378 * legal if a response size was specified, MHD accepts this 1379 * and treats it just as #MHD_CONTENT_READER_END_WITH_ERROR; 1380 * #MHD_CONTENT_READER_END_WITH_ERROR (-2) to indicate a server 1381 * error generating the response; this will cause MHD to simply 1382 * close the connection immediately. If a response size was 1383 * given or if chunked encoding is in use, this will indicate 1384 * an error to the client. Note, however, that if the client 1385 * does not know a response size and chunked encoding is not in 1386 * use, then clients will not be able to tell the difference between 1387 * #MHD_CONTENT_READER_END_WITH_ERROR and #MHD_CONTENT_READER_END_OF_STREAM. 1388 * This is not a limitation of MHD but rather of the HTTP protocol. 1389 */ 1390 typedef ssize_t 1391 (*MHD_ContentReaderCallback) (void *cls, 1392 uint64_t pos, 1393 char *buf, 1394 size_t max); 1395 1396 1397 /** 1398 * This method is called by libmicrohttpd if we 1399 * are done with a content reader. It should 1400 * be used to free resources associated with the 1401 * content reader. 1402 * 1403 * @param cls closure 1404 * @ingroup response 1405 */ 1406 typedef void 1407 (*MHD_ContentReaderFreeCallback) (void *cls); 1408 1409 1410 /** 1411 * Iterator over key-value pairs where the value 1412 * maybe made available in increments and/or may 1413 * not be zero-terminated. Used for processing 1414 * POST data. 1415 * 1416 * @param cls user-specified closure 1417 * @param kind type of the value, always #MHD_POSTDATA_KIND when called from MHD 1418 * @param key 0-terminated key for the value 1419 * @param filename name of the uploaded file, NULL if not known 1420 * @param content_type mime-type of the data, NULL if not known 1421 * @param transfer_encoding encoding of the data, NULL if not known 1422 * @param data pointer to @a size bytes of data at the 1423 * specified offset 1424 * @param off offset of data in the overall value 1425 * @param size number of bytes in @a data available 1426 * @return #MHD_YES to continue iterating, 1427 * #MHD_NO to abort the iteration 1428 */ 1429 typedef int 1430 (*MHD_PostDataIterator) (void *cls, 1431 enum MHD_ValueKind kind, 1432 const char *key, 1433 const char *filename, 1434 const char *content_type, 1435 const char *transfer_encoding, 1436 const char *data, 1437 uint64_t off, 1438 size_t size); 1439 1440 /* **************** Daemon handling functions ***************** */ 1441 1442 /** 1443 * Start a webserver on the given port. 1444 * 1445 * @param flags combination of `enum MHD_FLAG` values 1446 * @param port port to bind to (in host byte order) 1447 * @param apc callback to call to check which clients 1448 * will be allowed to connect; you can pass NULL 1449 * in which case connections from any IP will be 1450 * accepted 1451 * @param apc_cls extra argument to apc 1452 * @param dh handler called for all requests (repeatedly) 1453 * @param dh_cls extra argument to @a dh 1454 * @param ap list of options (type-value pairs, 1455 * terminated with #MHD_OPTION_END). 1456 * @return NULL on error, handle to daemon on success 1457 * @ingroup event 1458 */ 1459 _MHD_EXTERN struct MHD_Daemon * 1460 MHD_start_daemon_va (unsigned int flags, 1461 uint16_t port, 1462 MHD_AcceptPolicyCallback apc, void *apc_cls, 1463 MHD_AccessHandlerCallback dh, void *dh_cls, 1464 va_list ap); 1465 1466 1467 /** 1468 * Start a webserver on the given port. Variadic version of 1469 * #MHD_start_daemon_va. 1470 * 1471 * @param flags combination of `enum MHD_FLAG` values 1472 * @param port port to bind to 1473 * @param apc callback to call to check which clients 1474 * will be allowed to connect; you can pass NULL 1475 * in which case connections from any IP will be 1476 * accepted 1477 * @param apc_cls extra argument to apc 1478 * @param dh handler called for all requests (repeatedly) 1479 * @param dh_cls extra argument to @a dh 1480 * @return NULL on error, handle to daemon on success 1481 * @ingroup event 1482 */ 1483 _MHD_EXTERN struct MHD_Daemon * 1484 MHD_start_daemon (unsigned int flags, 1485 uint16_t port, 1486 MHD_AcceptPolicyCallback apc, void *apc_cls, 1487 MHD_AccessHandlerCallback dh, void *dh_cls, 1488 ...); 1489 1490 1491 /** 1492 * Stop accepting connections from the listening socket. Allows 1493 * clients to continue processing, but stops accepting new 1494 * connections. Note that the caller is responsible for closing the 1495 * returned socket; however, if MHD is run using threads (anything but 1496 * external select mode), it must not be closed until AFTER 1497 * #MHD_stop_daemon has been called (as it is theoretically possible 1498 * that an existing thread is still using it). 1499 * 1500 * Note that some thread modes require the caller to have passed 1501 * #MHD_USE_PIPE_FOR_SHUTDOWN when using this API. If this daemon is 1502 * in one of those modes and this option was not given to 1503 * #MHD_start_daemon, this function will return #MHD_INVALID_SOCKET. 1504 * 1505 * @param daemon daemon to stop accepting new connections for 1506 * @return old listen socket on success, #MHD_INVALID_SOCKET if 1507 * the daemon was already not listening anymore 1508 * @ingroup specialized 1509 */ 1510 _MHD_EXTERN MHD_socket 1511 MHD_quiesce_daemon (struct MHD_Daemon *daemon); 1512 1513 1514 /** 1515 * Shutdown an HTTP daemon. 1516 * 1517 * @param daemon daemon to stop 1518 * @ingroup event 1519 */ 1520 _MHD_EXTERN void 1521 MHD_stop_daemon (struct MHD_Daemon *daemon); 1522 1523 1524 /** 1525 * Add another client connection to the set of connections managed by 1526 * MHD. This API is usually not needed (since MHD will accept inbound 1527 * connections on the server socket). Use this API in special cases, 1528 * for example if your HTTP server is behind NAT and needs to connect 1529 * out to the HTTP client, or if you are building a proxy. 1530 * 1531 * If you use this API in conjunction with a internal select or a 1532 * thread pool, you must set the option 1533 * #MHD_USE_PIPE_FOR_SHUTDOWN to ensure that the freshly added 1534 * connection is immediately processed by MHD. 1535 * 1536 * The given client socket will be managed (and closed!) by MHD after 1537 * this call and must no longer be used directly by the application 1538 * afterwards. 1539 * 1540 * Per-IP connection limits are ignored when using this API. 1541 * 1542 * @param daemon daemon that manages the connection 1543 * @param client_socket socket to manage (MHD will expect 1544 * to receive an HTTP request from this socket next). 1545 * @param addr IP address of the client 1546 * @param addrlen number of bytes in @a addr 1547 * @return #MHD_YES on success, #MHD_NO if this daemon could 1548 * not handle the connection (i.e. `malloc()` failed, etc). 1549 * The socket will be closed in any case; `errno` is 1550 * set to indicate further details about the error. 1551 * @ingroup specialized 1552 */ 1553 _MHD_EXTERN int 1554 MHD_add_connection (struct MHD_Daemon *daemon, 1555 MHD_socket client_socket, 1556 const struct sockaddr *addr, 1557 socklen_t addrlen); 1558 1559 1560 /** 1561 * Obtain the `select()` sets for this daemon. 1562 * Daemon's FDs will be added to fd_sets. To get only 1563 * daemon FDs in fd_sets, call FD_ZERO for each fd_set 1564 * before calling this function. FD_SETSIZE is assumed 1565 * to be platform's default. 1566 * 1567 * @param daemon daemon to get sets from 1568 * @param read_fd_set read set 1569 * @param write_fd_set write set 1570 * @param except_fd_set except set 1571 * @param max_fd increased to largest FD added (if larger 1572 * than existing value); can be NULL 1573 * @return #MHD_YES on success, #MHD_NO if this 1574 * daemon was not started with the right 1575 * options for this call or any FD didn't 1576 * fit fd_set. 1577 * @ingroup event 1578 */ 1579 _MHD_EXTERN int 1580 MHD_get_fdset (struct MHD_Daemon *daemon, 1581 fd_set *read_fd_set, 1582 fd_set *write_fd_set, 1583 fd_set *except_fd_set, 1584 MHD_socket *max_fd); 1585 1586 1587 /** 1588 * Obtain the `select()` sets for this daemon. 1589 * Daemon's FDs will be added to fd_sets. To get only 1590 * daemon FDs in fd_sets, call FD_ZERO for each fd_set 1591 * before calling this function. Passing custom FD_SETSIZE 1592 * as @a fd_setsize allow usage of larger/smaller than 1593 * platform's default fd_sets. 1594 * 1595 * @param daemon daemon to get sets from 1596 * @param read_fd_set read set 1597 * @param write_fd_set write set 1598 * @param except_fd_set except set 1599 * @param max_fd increased to largest FD added (if larger 1600 * than existing value); can be NULL 1601 * @param fd_setsize value of FD_SETSIZE 1602 * @return #MHD_YES on success, #MHD_NO if this 1603 * daemon was not started with the right 1604 * options for this call or any FD didn't 1605 * fit fd_set. 1606 * @ingroup event 1607 */ 1608 _MHD_EXTERN int 1609 MHD_get_fdset2 (struct MHD_Daemon *daemon, 1610 fd_set *read_fd_set, 1611 fd_set *write_fd_set, 1612 fd_set *except_fd_set, 1613 MHD_socket *max_fd, 1614 unsigned int fd_setsize); 1615 1616 1617 /** 1618 * Obtain the `select()` sets for this daemon. 1619 * Daemon's FDs will be added to fd_sets. To get only 1620 * daemon FDs in fd_sets, call FD_ZERO for each fd_set 1621 * before calling this function. Size of fd_set is 1622 * determined by current value of FD_SETSIZE. 1623 * 1624 * @param daemon daemon to get sets from 1625 * @param read_fd_set read set 1626 * @param write_fd_set write set 1627 * @param except_fd_set except set 1628 * @param max_fd increased to largest FD added (if larger 1629 * than existing value); can be NULL 1630 * @return #MHD_YES on success, #MHD_NO if this 1631 * daemon was not started with the right 1632 * options for this call or any FD didn't 1633 * fit fd_set. 1634 * @ingroup event 1635 */ 1636 #define MHD_get_fdset(daemon,read_fd_set,write_fd_set,except_fd_set,max_fd) \ 1637 MHD_get_fdset2((daemon),(read_fd_set),(write_fd_set),(except_fd_set),(max_fd),FD_SETSIZE) 1638 1639 1640 /** 1641 * Obtain timeout value for `select()` for this daemon (only needed if 1642 * connection timeout is used). The returned value is how many milliseconds 1643 * `select()` or `poll()` should at most block, not the timeout value set for 1644 * connections. This function MUST NOT be called if MHD is running with 1645 * #MHD_USE_THREAD_PER_CONNECTION. 1646 * 1647 * @param daemon daemon to query for timeout 1648 * @param timeout set to the timeout (in milliseconds) 1649 * @return #MHD_YES on success, #MHD_NO if timeouts are 1650 * not used (or no connections exist that would 1651 * necessiate the use of a timeout right now). 1652 * @ingroup event 1653 */ 1654 _MHD_EXTERN int 1655 MHD_get_timeout (struct MHD_Daemon *daemon, 1656 MHD_UNSIGNED_LONG_LONG *timeout); 1657 1658 1659 /** 1660 * Run webserver operations (without blocking unless in client 1661 * callbacks). This method should be called by clients in combination 1662 * with #MHD_get_fdset if the client-controlled select method is used. 1663 * 1664 * This function is a convenience method, which is useful if the 1665 * fd_sets from #MHD_get_fdset were not directly passed to `select()`; 1666 * with this function, MHD will internally do the appropriate `select()` 1667 * call itself again. While it is always safe to call #MHD_run (in 1668 * external select mode), you should call #MHD_run_from_select if 1669 * performance is important (as it saves an expensive call to 1670 * `select()`). 1671 * 1672 * @param daemon daemon to run 1673 * @return #MHD_YES on success, #MHD_NO if this 1674 * daemon was not started with the right 1675 * options for this call. 1676 * @ingroup event 1677 */ 1678 _MHD_EXTERN int 1679 MHD_run (struct MHD_Daemon *daemon); 1680 1681 1682 /** 1683 * Run webserver operations. This method should be called by clients 1684 * in combination with #MHD_get_fdset if the client-controlled select 1685 * method is used. 1686 * 1687 * You can use this function instead of #MHD_run if you called 1688 * `select()` on the result from #MHD_get_fdset. File descriptors in 1689 * the sets that are not controlled by MHD will be ignored. Calling 1690 * this function instead of #MHD_run is more efficient as MHD will 1691 * not have to call `select()` again to determine which operations are 1692 * ready. 1693 * 1694 * @param daemon daemon to run select loop for 1695 * @param read_fd_set read set 1696 * @param write_fd_set write set 1697 * @param except_fd_set except set (not used, can be NULL) 1698 * @return #MHD_NO on serious errors, #MHD_YES on success 1699 * @ingroup event 1700 */ 1701 _MHD_EXTERN int 1702 MHD_run_from_select (struct MHD_Daemon *daemon, 1703 const fd_set *read_fd_set, 1704 const fd_set *write_fd_set, 1705 const fd_set *except_fd_set); 1706 1707 1708 1709 1710 /* **************** Connection handling functions ***************** */ 1711 1712 /** 1713 * Get all of the headers from the request. 1714 * 1715 * @param connection connection to get values from 1716 * @param kind types of values to iterate over 1717 * @param iterator callback to call on each header; 1718 * maybe NULL (then just count headers) 1719 * @param iterator_cls extra argument to @a iterator 1720 * @return number of entries iterated over 1721 * @ingroup request 1722 */ 1723 _MHD_EXTERN int 1724 MHD_get_connection_values (struct MHD_Connection *connection, 1725 enum MHD_ValueKind kind, 1726 MHD_KeyValueIterator iterator, void *iterator_cls); 1727 1728 1729 /** 1730 * This function can be used to add an entry to the HTTP headers of a 1731 * connection (so that the #MHD_get_connection_values function will 1732 * return them -- and the `struct MHD_PostProcessor` will also see 1733 * them). This maybe required in certain situations (see Mantis 1734 * #1399) where (broken) HTTP implementations fail to supply values 1735 * needed by the post processor (or other parts of the application). 1736 * 1737 * This function MUST only be called from within the 1738 * #MHD_AccessHandlerCallback (otherwise, access maybe improperly 1739 * synchronized). Furthermore, the client must guarantee that the key 1740 * and value arguments are 0-terminated strings that are NOT freed 1741 * until the connection is closed. (The easiest way to do this is by 1742 * passing only arguments to permanently allocated strings.). 1743 * 1744 * @param connection the connection for which a 1745 * value should be set 1746 * @param kind kind of the value 1747 * @param key key for the value 1748 * @param value the value itself 1749 * @return #MHD_NO if the operation could not be 1750 * performed due to insufficient memory; 1751 * #MHD_YES on success 1752 * @ingroup request 1753 */ 1754 _MHD_EXTERN int 1755 MHD_set_connection_value (struct MHD_Connection *connection, 1756 enum MHD_ValueKind kind, 1757 const char *key, 1758 const char *value); 1759 1760 1761 /** 1762 * Sets the global error handler to a different implementation. @a cb 1763 * will only be called in the case of typically fatal, serious 1764 * internal consistency issues. These issues should only arise in the 1765 * case of serious memory corruption or similar problems with the 1766 * architecture. While @a cb is allowed to return and MHD will then 1767 * try to continue, this is never safe. 1768 * 1769 * The default implementation that is used if no panic function is set 1770 * simply prints an error message and calls `abort()`. Alternative 1771 * implementations might call `exit()` or other similar functions. 1772 * 1773 * @param cb new error handler 1774 * @param cls passed to @a cb 1775 * @ingroup logging 1776 */ 1777 _MHD_EXTERN void 1778 MHD_set_panic_func (MHD_PanicCallback cb, void *cls); 1779 1780 1781 /** 1782 * Process escape sequences ('%HH') Updates val in place; the 1783 * result should be UTF-8 encoded and cannot be larger than the input. 1784 * The result must also still be 0-terminated. 1785 * 1786 * @param val value to unescape (modified in the process) 1787 * @return length of the resulting val (`strlen(val)` may be 1788 * shorter afterwards due to elimination of escape sequences) 1789 */ 1790 _MHD_EXTERN size_t 1791 MHD_http_unescape (char *val); 1792 1793 1794 /** 1795 * Get a particular header value. If multiple 1796 * values match the kind, return any one of them. 1797 * 1798 * @param connection connection to get values from 1799 * @param kind what kind of value are we looking for 1800 * @param key the header to look for, NULL to lookup 'trailing' value without a key 1801 * @return NULL if no such item was found 1802 * @ingroup request 1803 */ 1804 _MHD_EXTERN const char * 1805 MHD_lookup_connection_value (struct MHD_Connection *connection, 1806 enum MHD_ValueKind kind, 1807 const char *key); 1808 1809 1810 /** 1811 * Queue a response to be transmitted to the client (as soon as 1812 * possible but after #MHD_AccessHandlerCallback returns). 1813 * 1814 * @param connection the connection identifying the client 1815 * @param status_code HTTP status code (i.e. #MHD_HTTP_OK) 1816 * @param response response to transmit 1817 * @return #MHD_NO on error (i.e. reply already sent), 1818 * #MHD_YES on success or if message has been queued 1819 * @ingroup response 1820 */ 1821 _MHD_EXTERN int 1822 MHD_queue_response (struct MHD_Connection *connection, 1823 unsigned int status_code, 1824 struct MHD_Response *response); 1825 1826 1827 /** 1828 * Suspend handling of network data for a given connection. This can 1829 * be used to dequeue a connection from MHD's event loop (external 1830 * select, internal select or thread pool; not applicable to 1831 * thread-per-connection!) for a while. 1832 * 1833 * If you use this API in conjunction with a internal select or a 1834 * thread pool, you must set the option #MHD_USE_PIPE_FOR_SHUTDOWN to 1835 * ensure that a resumed connection is immediately processed by MHD. 1836 * 1837 * Suspended connections continue to count against the total number of 1838 * connections allowed (per daemon, as well as per IP, if such limits 1839 * are set). Suspended connections will NOT time out; timeouts will 1840 * restart when the connection handling is resumed. While a 1841 * connection is suspended, MHD will not detect disconnects by the 1842 * client. 1843 * 1844 * The only safe time to suspend a connection is from the 1845 * #MHD_AccessHandlerCallback. 1846 * 1847 * Finally, it is an API violation to call #MHD_stop_daemon while 1848 * having suspended connections (this will at least create memory and 1849 * socket leaks or lead to undefined behavior). You must explicitly 1850 * resume all connections before stopping the daemon. 1851 * 1852 * @param connection the connection to suspend 1853 */ 1854 _MHD_EXTERN void 1855 MHD_suspend_connection (struct MHD_Connection *connection); 1856 1857 1858 /** 1859 * Resume handling of network data for suspended connection. It is 1860 * safe to resume a suspended connection at any time. Calling this 1861 * function on a connection that was not previously suspended will 1862 * result in undefined behavior. 1863 * 1864 * @param connection the connection to resume 1865 */ 1866 _MHD_EXTERN void 1867 MHD_resume_connection (struct MHD_Connection *connection); 1868 1869 1870 /* **************** Response manipulation functions ***************** */ 1871 1872 1873 /** 1874 * Flags for special handling of responses. 1875 */ 1876 enum MHD_ResponseFlags 1877 { 1878 /** 1879 * Default: no special flags. 1880 */ 1881 MHD_RF_NONE = 0, 1882 1883 /** 1884 * Only respond in conservative HTTP 1.0-mode. In particular, 1885 * do not (automatically) sent "Connection" headers and always 1886 * close the connection after generating the response. 1887 */ 1888 MHD_RF_HTTP_VERSION_1_0_ONLY = 1 1889 1890 }; 1891 1892 1893 /** 1894 * MHD options (for future extensions). 1895 */ 1896 enum MHD_ResponseOptions 1897 { 1898 /** 1899 * End of the list of options. 1900 */ 1901 MHD_RO_END = 0 1902 }; 1903 1904 1905 /** 1906 * Set special flags and options for a response. 1907 * 1908 * @param response the response to modify 1909 * @param flags to set for the response 1910 * @param ... #MHD_RO_END terminated list of options 1911 * @return #MHD_YES on success, #MHD_NO on error 1912 */ 1913 _MHD_EXTERN int 1914 MHD_set_response_options (struct MHD_Response *response, 1915 enum MHD_ResponseFlags flags, 1916 ...); 1917 1918 1919 /** 1920 * Create a response object. The response object can be extended with 1921 * header information and then be used any number of times. 1922 * 1923 * @param size size of the data portion of the response, #MHD_SIZE_UNKNOWN for unknown 1924 * @param block_size preferred block size for querying crc (advisory only, 1925 * MHD may still call @a crc using smaller chunks); this 1926 * is essentially the buffer size used for IO, clients 1927 * should pick a value that is appropriate for IO and 1928 * memory performance requirements 1929 * @param crc callback to use to obtain response data 1930 * @param crc_cls extra argument to @a crc 1931 * @param crfc callback to call to free @a crc_cls resources 1932 * @return NULL on error (i.e. invalid arguments, out of memory) 1933 * @ingroup response 1934 */ 1935 _MHD_EXTERN struct MHD_Response * 1936 MHD_create_response_from_callback (uint64_t size, 1937 size_t block_size, 1938 MHD_ContentReaderCallback crc, void *crc_cls, 1939 MHD_ContentReaderFreeCallback crfc); 1940 1941 1942 /** 1943 * Create a response object. The response object can be extended with 1944 * header information and then be used any number of times. 1945 * 1946 * @param size size of the @a data portion of the response 1947 * @param data the data itself 1948 * @param must_free libmicrohttpd should free data when done 1949 * @param must_copy libmicrohttpd must make a copy of @a data 1950 * right away, the data maybe released anytime after 1951 * this call returns 1952 * @return NULL on error (i.e. invalid arguments, out of memory) 1953 * @deprecated use #MHD_create_response_from_buffer instead 1954 * @ingroup response 1955 */ 1956 _MHD_EXTERN struct MHD_Response * 1957 MHD_create_response_from_data (size_t size, 1958 void *data, 1959 int must_free, 1960 int must_copy); 1961 1962 1963 /** 1964 * Specification for how MHD should treat the memory buffer 1965 * given for the response. 1966 * @ingroup response 1967 */ 1968 enum MHD_ResponseMemoryMode 1969 { 1970 1971 /** 1972 * Buffer is a persistent (static/global) buffer that won't change 1973 * for at least the lifetime of the response, MHD should just use 1974 * it, not free it, not copy it, just keep an alias to it. 1975 * @ingroup response 1976 */ 1977 MHD_RESPMEM_PERSISTENT, 1978 1979 /** 1980 * Buffer is heap-allocated with `malloc()` (or equivalent) and 1981 * should be freed by MHD after processing the response has 1982 * concluded (response reference counter reaches zero). 1983 * @ingroup response 1984 */ 1985 MHD_RESPMEM_MUST_FREE, 1986 1987 /** 1988 * Buffer is in transient memory, but not on the heap (for example, 1989 * on the stack or non-`malloc()` allocated) and only valid during the 1990 * call to #MHD_create_response_from_buffer. MHD must make its 1991 * own private copy of the data for processing. 1992 * @ingroup response 1993 */ 1994 MHD_RESPMEM_MUST_COPY 1995 1996 }; 1997 1998 1999 /** 2000 * Create a response object. The response object can be extended with 2001 * header information and then be used any number of times. 2002 * 2003 * @param size size of the data portion of the response 2004 * @param buffer size bytes containing the response's data portion 2005 * @param mode flags for buffer management 2006 * @return NULL on error (i.e. invalid arguments, out of memory) 2007 * @ingroup response 2008 */ 2009 _MHD_EXTERN struct MHD_Response * 2010 MHD_create_response_from_buffer (size_t size, 2011 void *buffer, 2012 enum MHD_ResponseMemoryMode mode); 2013 2014 2015 /** 2016 * Create a response object. The response object can be extended with 2017 * header information and then be used any number of times. 2018 * 2019 * @param size size of the data portion of the response 2020 * @param fd file descriptor referring to a file on disk with the 2021 * data; will be closed when response is destroyed; 2022 * fd should be in 'blocking' mode 2023 * @return NULL on error (i.e. invalid arguments, out of memory) 2024 * @ingroup response 2025 */ 2026 _MHD_EXTERN struct MHD_Response * 2027 MHD_create_response_from_fd (size_t size, 2028 int fd); 2029 2030 2031 /** 2032 * Create a response object. The response object can be extended with 2033 * header information and then be used any number of times. 2034 * 2035 * @param size size of the data portion of the response 2036 * @param fd file descriptor referring to a file on disk with the 2037 * data; will be closed when response is destroyed; 2038 * fd should be in 'blocking' mode 2039 * @param offset offset to start reading from in the file; 2040 * Be careful! `off_t` may have been compiled to be a 2041 * 64-bit variable for MHD, in which case your application 2042 * also has to be compiled using the same options! Read 2043 * the MHD manual for more details. 2044 * @return NULL on error (i.e. invalid arguments, out of memory) 2045 * @ingroup response 2046 */ 2047 _MHD_EXTERN struct MHD_Response * 2048 MHD_create_response_from_fd_at_offset (size_t size, 2049 int fd, 2050 off_t offset); 2051 2052 2053 #if 0 2054 /** 2055 * Enumeration for actions MHD should perform on the underlying socket 2056 * of the upgrade. This API is not finalized, and in particular 2057 * the final set of actions is yet to be decided. This is just an 2058 * idea for what we might want. 2059 */ 2060 enum MHD_UpgradeAction 2061 { 2062 2063 /** 2064 * Close the socket, the application is done with it. 2065 * 2066 * Takes no extra arguments. 2067 * 2068 * NOTE: it is unclear if we want to have this in the 2069 * "final" API, this is all just ideas. 2070 */ 2071 MHD_UPGRADE_ACTION_CLOSE = 0, 2072 2073 /** 2074 * Uncork the TCP write buffer (that is, tell the OS to transmit all 2075 * bytes in the buffer now, and to not use TCP-CORKing). 2076 * 2077 * Takes no extra arguments. 2078 * 2079 * NOTE: it is unclear if we want to have this in the 2080 * "final" API, this is all just ideas. 2081 */ 2082 MHD_UPGRADE_ACTION_CORK 2083 2084 }; 2085 2086 2087 /** 2088 * This connection-specific callback is provided by MHD to 2089 * applications (unusual) during the #MHD_UpgradeHandler. 2090 * It allows applications to perform 'special' actions on 2091 * the underlying socket from the upgrade. 2092 * 2093 * @param cls the closure (from `upgrade_action_cls`) 2094 * @param action which action should be performed 2095 * @param ... arguments to the action (depends on the action) 2096 * @return #MHD_NO on error, #MHD_YES on success 2097 */ 2098 typedef int 2099 (*MHD_UpgradeActionCallback)(void *cls, 2100 enum MHD_UpgradeAction action, 2101 ...); 2102 2103 /** 2104 * Function called after a protocol "upgrade" response was sent 2105 * successfully and the socket should now be controlled by some 2106 * protocol other than HTTP. 2107 * 2108 * Any data received on the socket will be made available in 2109 * 'data_in'. The function should update 'data_in_size' to 2110 * reflect the number of bytes consumed from 'data_in' (the remaining 2111 * bytes will be made available in the next call to the handler). 2112 * 2113 * Any data that should be transmitted on the socket should be 2114 * stored in 'data_out'. '*data_out_size' is initially set to 2115 * the available buffer space in 'data_out'. It should be set to 2116 * the number of bytes stored in 'data_out' (which can be zero). 2117 * 2118 * The return value is a BITMASK that indicates how the function 2119 * intends to interact with the event loop. It can request to be 2120 * notified for reading, writing, request to UNCORK the send buffer 2121 * (which MHD is allowed to ignore, if it is not possible to uncork on 2122 * the local platform), to wait for the 'external' select loop to 2123 * trigger another round. It is also possible to specify "no events" 2124 * to terminate the connection; in this case, the 2125 * #MHD_RequestCompletedCallback will be called and all resources of 2126 * the connection will be released. 2127 * 2128 * Except when in 'thread-per-connection' mode, implementations 2129 * of this function should never block (as it will still be called 2130 * from within the main event loop). 2131 * 2132 * @param cls closure 2133 * @param connection original HTTP connection handle, 2134 * giving the function a last chance 2135 * to inspect the original HTTP request 2136 * @param sock socket to use for bi-directional communication 2137 * with the client. For HTTPS, this may not be a socket 2138 * that is directly connected to the client and thus certain 2139 * operations (TCP-specific setsockopt(), getsockopt(), etc.) 2140 * may not work as expected (as the socket could be from a 2141 * socketpair() or a TCP-loopback) 2142 * @param upgrade_action function that can be used to perform actions 2143 * on the @a sock (like those that cannot be done explicitly). 2144 * Applications must use this callback to perform the 2145 * close() action on the @a sock. 2146 * @param upgrade_action_cls closure that must be passed to @a upgrade_action 2147 */ 2148 typedef void 2149 (*MHD_UpgradeHandler)(void *cls, 2150 struct MHD_Connection *connection, 2151 MHD_SOCKET sock, 2152 MHD_UpgradeActionCallback upgrade_action, 2153 void *upgrade_action_cls); 2154 2155 2156 /** 2157 * Create a response object that can be used for 101 UPGRADE 2158 * responses, for example to implement WebSockets. After sending the 2159 * response, control over the data stream is given to the callback (which 2160 * can then, for example, start some bi-directional communication). 2161 * If the response is queued for multiple connections, the callback 2162 * will be called for each connection. The callback 2163 * will ONLY be called after the response header was successfully passed 2164 * to the OS; if there are communication errors before, the usual MHD 2165 * connection error handling code will be performed. 2166 * 2167 * Setting the correct HTTP code (i.e. MHD_HTTP_SWITCHING_PROTOCOLS) 2168 * and setting correct HTTP headers for the upgrade must be done 2169 * manually (this way, it is possible to implement most existing 2170 * WebSocket versions using this API; in fact, this API might be useful 2171 * for any protocol switch, not just WebSockets). Note that 2172 * draft-ietf-hybi-thewebsocketprotocol-00 cannot be implemented this 2173 * way as the header "HTTP/1.1 101 WebSocket Protocol Handshake" 2174 * cannot be generated; instead, MHD will always produce "HTTP/1.1 101 2175 * Switching Protocols" (if the response code 101 is used). 2176 * 2177 * As usual, the response object can be extended with header 2178 * information and then be used any number of times (as long as the 2179 * header information is not connection-specific). 2180 * 2181 * @param upgrade_handler function to call with the 'upgraded' socket 2182 * @param upgrade_handler_cls closure for @a upgrade_handler 2183 * @return NULL on error (i.e. invalid arguments, out of memory) 2184 */ 2185 struct MHD_Response * 2186 MHD_create_response_for_upgrade (MHD_UpgradeHandler upgrade_handler, 2187 void *upgrade_handler_cls); 2188 #endif 2189 2190 /** 2191 * Destroy a response object and associated resources. Note that 2192 * libmicrohttpd may keep some of the resources around if the response 2193 * is still in the queue for some clients, so the memory may not 2194 * necessarily be freed immediatley. 2195 * 2196 * @param response response to destroy 2197 * @ingroup response 2198 */ 2199 _MHD_EXTERN void 2200 MHD_destroy_response (struct MHD_Response *response); 2201 2202 2203 /** 2204 * Add a header line to the response. 2205 * 2206 * @param response response to add a header to 2207 * @param header the header to add 2208 * @param content value to add 2209 * @return #MHD_NO on error (i.e. invalid header or content format), 2210 * or out of memory 2211 * @ingroup response 2212 */ 2213 _MHD_EXTERN int 2214 MHD_add_response_header (struct MHD_Response *response, 2215 const char *header, 2216 const char *content); 2217 2218 2219 /** 2220 * Add a footer line to the response. 2221 * 2222 * @param response response to remove a header from 2223 * @param footer the footer to delete 2224 * @param content value to delete 2225 * @return #MHD_NO on error (i.e. invalid footer or content format). 2226 * @ingroup response 2227 */ 2228 _MHD_EXTERN int 2229 MHD_add_response_footer (struct MHD_Response *response, 2230 const char *footer, 2231 const char *content); 2232 2233 2234 /** 2235 * Delete a header (or footer) line from the response. 2236 * 2237 * @param response response to remove a header from 2238 * @param header the header to delete 2239 * @param content value to delete 2240 * @return #MHD_NO on error (no such header known) 2241 * @ingroup response 2242 */ 2243 _MHD_EXTERN int 2244 MHD_del_response_header (struct MHD_Response *response, 2245 const char *header, 2246 const char *content); 2247 2248 2249 /** 2250 * Get all of the headers (and footers) added to a response. 2251 * 2252 * @param response response to query 2253 * @param iterator callback to call on each header; 2254 * maybe NULL (then just count headers) 2255 * @param iterator_cls extra argument to @a iterator 2256 * @return number of entries iterated over 2257 * @ingroup response 2258 */ 2259 _MHD_EXTERN int 2260 MHD_get_response_headers (struct MHD_Response *response, 2261 MHD_KeyValueIterator iterator, void *iterator_cls); 2262 2263 2264 /** 2265 * Get a particular header (or footer) from the response. 2266 * 2267 * @param response response to query 2268 * @param key which header to get 2269 * @return NULL if header does not exist 2270 * @ingroup response 2271 */ 2272 _MHD_EXTERN const char * 2273 MHD_get_response_header (struct MHD_Response *response, 2274 const char *key); 2275 2276 2277 /* ********************** PostProcessor functions ********************** */ 2278 2279 /** 2280 * Create a `struct MHD_PostProcessor`. 2281 * 2282 * A `struct MHD_PostProcessor` can be used to (incrementally) parse 2283 * the data portion of a POST request. Note that some buggy browsers 2284 * fail to set the encoding type. If you want to support those, you 2285 * may have to call #MHD_set_connection_value with the proper encoding 2286 * type before creating a post processor (if no supported encoding 2287 * type is set, this function will fail). 2288 * 2289 * @param connection the connection on which the POST is 2290 * happening (used to determine the POST format) 2291 * @param buffer_size maximum number of bytes to use for 2292 * internal buffering (used only for the parsing, 2293 * specifically the parsing of the keys). A 2294 * tiny value (256-1024) should be sufficient. 2295 * Do NOT use a value smaller than 256. For good 2296 * performance, use 32 or 64k (i.e. 65536). 2297 * @param iter iterator to be called with the parsed data, 2298 * Must NOT be NULL. 2299 * @param iter_cls first argument to @a iter 2300 * @return NULL on error (out of memory, unsupported encoding), 2301 * otherwise a PP handle 2302 * @ingroup request 2303 */ 2304 _MHD_EXTERN struct MHD_PostProcessor * 2305 MHD_create_post_processor (struct MHD_Connection *connection, 2306 size_t buffer_size, 2307 MHD_PostDataIterator iter, void *iter_cls); 2308 2309 2310 /** 2311 * Parse and process POST data. Call this function when POST data is 2312 * available (usually during an #MHD_AccessHandlerCallback) with the 2313 * "upload_data" and "upload_data_size". Whenever possible, this will 2314 * then cause calls to the #MHD_PostDataIterator. 2315 * 2316 * @param pp the post processor 2317 * @param post_data @a post_data_len bytes of POST data 2318 * @param post_data_len length of @a post_data 2319 * @return #MHD_YES on success, #MHD_NO on error 2320 * (out-of-memory, iterator aborted, parse error) 2321 * @ingroup request 2322 */ 2323 _MHD_EXTERN int 2324 MHD_post_process (struct MHD_PostProcessor *pp, 2325 const char *post_data, size_t post_data_len); 2326 2327 2328 /** 2329 * Release PostProcessor resources. 2330 * 2331 * @param pp the PostProcessor to destroy 2332 * @return #MHD_YES if processing completed nicely, 2333 * #MHD_NO if there were spurious characters / formatting 2334 * problems; it is common to ignore the return 2335 * value of this function 2336 * @ingroup request 2337 */ 2338 _MHD_EXTERN int 2339 MHD_destroy_post_processor (struct MHD_PostProcessor *pp); 2340 2341 2342 /* ********************* Digest Authentication functions *************** */ 2343 2344 2345 /** 2346 * Constant to indicate that the nonce of the provided 2347 * authentication code was wrong. 2348 * @ingroup authentication 2349 */ 2350 #define MHD_INVALID_NONCE -1 2351 2352 2353 /** 2354 * Get the username from the authorization header sent by the client 2355 * 2356 * @param connection The MHD connection structure 2357 * @return NULL if no username could be found, a pointer 2358 * to the username if found 2359 * @ingroup authentication 2360 */ 2361 _MHD_EXTERN char * 2362 MHD_digest_auth_get_username (struct MHD_Connection *connection); 2363 2364 2365 /** 2366 * Authenticates the authorization header sent by the client 2367 * 2368 * @param connection The MHD connection structure 2369 * @param realm The realm presented to the client 2370 * @param username The username needs to be authenticated 2371 * @param password The password used in the authentication 2372 * @param nonce_timeout The amount of time for a nonce to be 2373 * invalid in seconds 2374 * @return #MHD_YES if authenticated, #MHD_NO if not, 2375 * #MHD_INVALID_NONCE if nonce is invalid 2376 * @ingroup authentication 2377 */ 2378 _MHD_EXTERN int 2379 MHD_digest_auth_check (struct MHD_Connection *connection, 2380 const char *realm, 2381 const char *username, 2382 const char *password, 2383 unsigned int nonce_timeout); 2384 2385 2386 /** 2387 * Queues a response to request authentication from the client 2388 * 2389 * @param connection The MHD connection structure 2390 * @param realm The realm presented to the client 2391 * @param opaque string to user for opaque value 2392 * @param response reply to send; should contain the "access denied" 2393 * body; note that this function will set the "WWW Authenticate" 2394 * header and that the caller should not do this 2395 * @param signal_stale #MHD_YES if the nonce is invalid to add 2396 * 'stale=true' to the authentication header 2397 * @return #MHD_YES on success, #MHD_NO otherwise 2398 * @ingroup authentication 2399 */ 2400 _MHD_EXTERN int 2401 MHD_queue_auth_fail_response (struct MHD_Connection *connection, 2402 const char *realm, 2403 const char *opaque, 2404 struct MHD_Response *response, 2405 int signal_stale); 2406 2407 2408 /** 2409 * Get the username and password from the basic authorization header sent by the client 2410 * 2411 * @param connection The MHD connection structure 2412 * @param password a pointer for the password 2413 * @return NULL if no username could be found, a pointer 2414 * to the username if found 2415 * @ingroup authentication 2416 */ 2417 _MHD_EXTERN char * 2418 MHD_basic_auth_get_username_password (struct MHD_Connection *connection, 2419 char** password); 2420 2421 2422 /** 2423 * Queues a response to request basic authentication from the client 2424 * The given response object is expected to include the payload for 2425 * the response; the "WWW-Authenticate" header will be added and the 2426 * response queued with the 'UNAUTHORIZED' status code. 2427 * 2428 * @param connection The MHD connection structure 2429 * @param realm the realm presented to the client 2430 * @param response response object to modify and queue 2431 * @return #MHD_YES on success, #MHD_NO otherwise 2432 * @ingroup authentication 2433 */ 2434 _MHD_EXTERN int 2435 MHD_queue_basic_auth_fail_response (struct MHD_Connection *connection, 2436 const char *realm, 2437 struct MHD_Response *response); 2438 2439 /* ********************** generic query functions ********************** */ 2440 2441 2442 /** 2443 * Obtain information about the given connection. 2444 * 2445 * @param connection what connection to get information about 2446 * @param info_type what information is desired? 2447 * @param ... depends on @a info_type 2448 * @return NULL if this information is not available 2449 * (or if the @a info_type is unknown) 2450 * @ingroup specialized 2451 */ 2452 _MHD_EXTERN const union MHD_ConnectionInfo * 2453 MHD_get_connection_info (struct MHD_Connection *connection, 2454 enum MHD_ConnectionInfoType info_type, 2455 ...); 2456 2457 2458 /** 2459 * MHD connection options. Given to #MHD_set_connection_option to 2460 * set custom options for a particular connection. 2461 */ 2462 enum MHD_CONNECTION_OPTION 2463 { 2464 2465 /** 2466 * Set a custom timeout for the given connection. Specified 2467 * as the number of seconds, given as an `unsigned int`. Use 2468 * zero for no timeout. 2469 */ 2470 MHD_CONNECTION_OPTION_TIMEOUT 2471 2472 }; 2473 2474 2475 /** 2476 * Set a custom option for the given connection, overriding defaults. 2477 * 2478 * @param connection connection to modify 2479 * @param option option to set 2480 * @param ... arguments to the option, depending on the option type 2481 * @return #MHD_YES on success, #MHD_NO if setting the option failed 2482 * @ingroup specialized 2483 */ 2484 _MHD_EXTERN int 2485 MHD_set_connection_option (struct MHD_Connection *connection, 2486 enum MHD_CONNECTION_OPTION option, 2487 ...); 2488 2489 2490 /** 2491 * Information about an MHD daemon. 2492 */ 2493 union MHD_DaemonInfo 2494 { 2495 /** 2496 * Size of the key, no longer supported. 2497 * @deprecated 2498 */ 2499 size_t key_size; 2500 2501 /** 2502 * Size of the mac key, no longer supported. 2503 * @deprecated 2504 */ 2505 size_t mac_key_size; 2506 2507 /** 2508 * Listen socket file descriptor, for #MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY 2509 * and #MHD_DAEMON_INFO_LISTEN_FD. 2510 */ 2511 MHD_socket listen_fd; 2512 2513 /** 2514 * Number of active connections, for #MHD_DAEMON_INFO_CURRENT_CONNECTIONS. 2515 */ 2516 unsigned int num_connections; 2517 }; 2518 2519 2520 /** 2521 * Obtain information about the given daemon 2522 * (not fully implemented!). 2523 * 2524 * @param daemon what daemon to get information about 2525 * @param info_type what information is desired? 2526 * @param ... depends on @a info_type 2527 * @return NULL if this information is not available 2528 * (or if the @a info_type is unknown) 2529 * @ingroup specialized 2530 */ 2531 _MHD_EXTERN const union MHD_DaemonInfo * 2532 MHD_get_daemon_info (struct MHD_Daemon *daemon, 2533 enum MHD_DaemonInfoType info_type, 2534 ...); 2535 2536 2537 /** 2538 * Obtain the version of this library 2539 * 2540 * @return static version string, e.g. "0.9.9" 2541 * @ingroup specialized 2542 */ 2543 _MHD_EXTERN const char* 2544 MHD_get_version (void); 2545 2546 2547 /** 2548 * Types of information about MHD features, 2549 * used by #MHD_is_feature_supported(). 2550 */ 2551 enum MHD_FEATURE 2552 { 2553 /** 2554 * Get whether messages are supported. If supported then in debug 2555 * mode messages can be printed to stderr or to external logger. 2556 */ 2557 MHD_FEATURE_MESSGES = 1, 2558 2559 /** 2560 * Get whether HTTPS is supported. If supported then flag 2561 * #MHD_USE_SSL and options #MHD_OPTION_HTTPS_MEM_KEY, 2562 * #MHD_OPTION_HTTPS_MEM_CERT, #MHD_OPTION_HTTPS_MEM_TRUST, 2563 * #MHD_OPTION_HTTPS_MEM_DHPARAMS, #MHD_OPTION_HTTPS_CRED_TYPE, 2564 * #MHD_OPTION_HTTPS_PRIORITIES can be used. 2565 */ 2566 MHD_FEATURE_SSL = 2, 2567 2568 /** 2569 * Get whether option #MHD_OPTION_HTTPS_CERT_CALLBACK is 2570 * supported. 2571 */ 2572 MHD_FEATURE_HTTPS_CERT_CALLBACK = 3, 2573 2574 /** 2575 * Get whether IPv6 is supported. If supported then flag 2576 * #MHD_USE_IPv6 can be used. 2577 */ 2578 MHD_FEATURE_IPv6 = 4, 2579 2580 /** 2581 * Get whether IPv6 without IPv4 is supported. If not supported 2582 * then IPv4 is always enabled in IPv6 sockets and 2583 * flag #MHD_USE_DUAL_STACK if always used when #MHD_USE_IPv6 is 2584 * specified. 2585 */ 2586 MHD_FEATURE_IPv6_ONLY = 5, 2587 2588 /** 2589 * Get whether `poll()` is supported. If supported then flag 2590 * #MHD_USE_POLL can be used. 2591 */ 2592 MHD_FEATURE_POLL = 6, 2593 2594 /** 2595 * Get whether `epoll()` is supported. If supported then Flags 2596 * #MHD_USE_EPOLL_LINUX_ONLY and 2597 * #MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY can be used. 2598 */ 2599 MHD_FEATURE_EPOLL = 7, 2600 2601 /** 2602 * Get whether shutdown on listen socket to signal other 2603 * threads is supported. If not supported flag 2604 * #MHD_USE_PIPE_FOR_SHUTDOWN is automatically forced. 2605 */ 2606 MHD_FEATURE_SHUTDOWN_LISTEN_SOCKET = 8, 2607 2608 /** 2609 * Get whether socketpair is used internally instead of pipe to 2610 * signal other threads. 2611 */ 2612 MHD_FEATURE_SOCKETPAIR = 9, 2613 2614 /** 2615 * Get whether TCP Fast Open is supported. If supported then 2616 * flag #MHD_USE_TCP_FASTOPEN and option 2617 * #MHD_OPTION_TCP_FASTOPEN_QUEUE_SIZE can be used. 2618 */ 2619 MHD_FEATURE_TCP_FASTOPEN = 10, 2620 2621 /** 2622 * Get whether HTTP Basic authorization is supported. If supported 2623 * then functions #MHD_basic_auth_get_username_password and 2624 * #MHD_queue_basic_auth_fail_response can be used. 2625 */ 2626 MHD_FEATURE_BASIC_AUTH = 11, 2627 2628 /** 2629 * Get whether HTTP Digest authorization is supported. If 2630 * supported then options #MHD_OPTION_DIGEST_AUTH_RANDOM, 2631 * #MHD_OPTION_NONCE_NC_SIZE and 2632 * #MHD_digest_auth_check() can be used. 2633 */ 2634 MHD_FEATURE_DIGEST_AUTH = 12, 2635 2636 /** 2637 * Get whether postprocessor is supported. If supported then 2638 * functions #MHD_create_post_processor(), #MHD_post_process() and 2639 * #MHD_destroy_post_processor() can 2640 * be used. 2641 */ 2642 MHD_FEATURE_POSTPROCESSOR = 13, 2643 2644 /** 2645 * Get whether password encrypted private key for HTTPS daemon is 2646 * supported. If supported then option 2647 * ::MHD_OPTION_HTTPS_KEY_PASSWORD can be used. 2648 */ 2649 MHD_FEATURE_HTTPS_KEY_PASSWORD = 14 2650 }; 2651 2652 2653 /** 2654 * Get information about supported MHD features. 2655 * Indicate that MHD was compiled with or without support for 2656 * particular feature. Some features require additional support 2657 * by kernel. Kernel support is not checked by this function. 2658 * 2659 * @param feature type of requested information 2660 * @return #MHD_YES if feature is supported by MHD, #MHD_NO if 2661 * feature is not supported or feature is unknown. 2662 * @ingroup specialized 2663 */ 2664 _MHD_EXTERN int 2665 MHD_is_feature_supported(enum MHD_FEATURE feature); 2666 2667 2668 #if 0 /* keep Emacsens' auto-indent happy */ 2669 { 2670 #endif 2671 #ifdef __cplusplus 2672 } 2673 #endif 2674 2675 #endif 2676