aboutsummaryrefslogtreecommitdiff
path: root/src/include/microhttpd.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/microhttpd.h')
-rw-r--r--src/include/microhttpd.h558
1 files changed, 251 insertions, 307 deletions
diff --git a/src/include/microhttpd.h b/src/include/microhttpd.h
index 2798c50a..7fda89de 100644
--- a/src/include/microhttpd.h
+++ b/src/include/microhttpd.h
@@ -60,23 +60,20 @@
60 * which must only be used in a particular context). 60 * which must only be used in a particular context).
61 * 61 *
62 * NEW: Before including "microhttpd.h" you should add the necessary 62 * NEW: Before including "microhttpd.h" you should add the necessary
63 * includes to define the "uint64_t", "size_t", "fd_set", "socklen_t" 63 * includes to define the `uint64_t`, `size_t`, `fd_set`, `socklen_t`
64 * and "struct sockaddr" data types (which headers are needed may 64 * and `struct sockaddr` data types (which headers are needed may
65 * depend on your platform; for possible suggestions consult 65 * depend on your platform; for possible suggestions consult
66 * "platform.h" in the MHD distribution). If you have done so, you 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 67 * should also have a line with "#define MHD_PLATFORM_H" which will
68 * prevent this header from trying (and, depending on your platform, 68 * prevent this header from trying (and, depending on your platform,
69 * failing) to include the right headers. 69 * failing) to include the right headers.
70 * 70 *
71 * @defgroup tls HTTPS/SSL/TLS control
72 * @defgroup event event-loop control 71 * @defgroup event event-loop control
73 * @defgroup response generation of responses 72 * @defgroup response generation of responses
74 * @defgroup request handling of requests 73 * @defgroup request handling of requests
75 * @defgroup authentication HTTP authentication 74 * @defgroup authentication HTTP authentication
76 * @defgroup logging logging and error handling 75 * @defgroup logging logging and error handling
77 * @defgroup networking general networking
78 * @defgroup specialized misc. specialized functions 76 * @defgroup specialized misc. specialized functions
79 * @defgroup limits configuring resource limitations
80 */ 77 */
81 78
82#ifndef MHD_MICROHTTPD_H 79#ifndef MHD_MICROHTTPD_H
@@ -152,24 +149,24 @@ extern "C"
152#endif 149#endif
153 150
154/** 151/**
155 * Not all architectures and printf's support the long long type. 152 * Not all architectures and `printf()`'s support the `long long` type.
156 * This gives the ability to replace long long with just a long, 153 * This gives the ability to replace `long long` with just a `long`,
157 * standard int or a short. 154 * standard `int` or a `short`.
158 */ 155 */
159#ifndef MHD_LONG_LONG 156#ifndef MHD_LONG_LONG
160/** 157/**
161 * @deprecated use MHD_UNSIGNED_LONG_LONG instead! 158 * @deprecated use #MHD_UNSIGNED_LONG_LONG instead!
162 */ 159 */
163#define MHD_LONG_LONG long long 160#define MHD_LONG_LONG long long
164#define MHD_UNSIGNED_LONG_LONG unsigned long long 161#define MHD_UNSIGNED_LONG_LONG unsigned long long
165#endif 162#endif
166/** 163/**
167 * Format string for printing a variable of type 'MHD_LONG_LONG'. 164 * Format string for printing a variable of type #MHD_LONG_LONG.
168 * You should only redefine this if you also define MHD_LONG_LONG. 165 * You should only redefine this if you also define #MHD_LONG_LONG.
169 */ 166 */
170#ifndef MHD_LONG_LONG_PRINTF 167#ifndef MHD_LONG_LONG_PRINTF
171/** 168/**
172 * @deprecated use MHD_UNSIGNED_LONG_LONG_PRINTF instead! 169 * @deprecated use #MHD_UNSIGNED_LONG_LONG_PRINTF instead!
173 */ 170 */
174#define MHD_LONG_LONG_PRINTF "ll" 171#define MHD_LONG_LONG_PRINTF "ll"
175#define MHD_UNSIGNED_LONG_LONG_PRINTF "%llu" 172#define MHD_UNSIGNED_LONG_LONG_PRINTF "%llu"
@@ -244,7 +241,7 @@ extern "C"
244/** @} */ /* end of group httpcode */ 241/** @} */ /* end of group httpcode */
245 242
246/** 243/**
247 * Flag to be "OR"ed with MHD_HTTP status code for 244 * Flag to be or-ed with MHD_HTTP status code for
248 * SHOUTcast. This will cause the response to begin 245 * SHOUTcast. This will cause the response to begin
249 * with the SHOUTcast "ICY" line instad of "HTTP". 246 * with the SHOUTcast "ICY" line instad of "HTTP".
250 * @ingroup specialized 247 * @ingroup specialized
@@ -345,6 +342,35 @@ extern "C"
345 342
346/** @} */ /* end of group postenc */ 343/** @} */ /* end of group postenc */
347 344
345
346/**
347 * Handle for the daemon (listening on a socket for HTTP traffic).
348 * @ingroup event
349 */
350struct MHD_Daemon;
351
352/**
353 * Handle for a connection / HTTP request. With HTTP/1.1, multiple
354 * requests can be run over the same connection. However, MHD will
355 * only show one request per TCP connection to the client at any given
356 * time.
357 * @ingroup request
358 */
359struct MHD_Connection;
360
361/**
362 * Handle for a response.
363 * @ingroup response
364 */
365struct MHD_Response;
366
367/**
368 * Handle for POST processing.
369 * @ingroup response
370 */
371struct MHD_PostProcessor;
372
373
348/** 374/**
349 * Options for the MHD daemon. Note that if neither 375 * Options for the MHD daemon. Note that if neither
350 * #MHD_USE_THREAD_PER_CONNECTION nor #MHD_USE_SELECT_INTERNALLY is 376 * #MHD_USE_THREAD_PER_CONNECTION nor #MHD_USE_SELECT_INTERNALLY is
@@ -363,28 +389,23 @@ enum MHD_FLAG
363 MHD_NO_FLAG = 0, 389 MHD_NO_FLAG = 0,
364 390
365 /** 391 /**
366 * Run in debug mode. If this flag is used, the 392 * Run in debug mode. If this flag is used, the library should
367 * library should print error messages and warnings 393 * print error messages and warnings to `stderr`.
368 * to stderr.
369 * @ingroup logging
370 */ 394 */
371 MHD_USE_DEBUG = 1, 395 MHD_USE_DEBUG = 1,
372 396
373 /** 397 /**
374 * Run in HTTPS mode. 398 * Run in HTTPS mode.
375 * @ingroup tls
376 */ 399 */
377 MHD_USE_SSL = 2, 400 MHD_USE_SSL = 2,
378 401
379 /** 402 /**
380 * Run using one thread per connection. 403 * Run using one thread per connection.
381 * @ingroup event
382 */ 404 */
383 MHD_USE_THREAD_PER_CONNECTION = 4, 405 MHD_USE_THREAD_PER_CONNECTION = 4,
384 406
385 /** 407 /**
386 * Run using an internal thread (or thread pool) doing select(). 408 * Run using an internal thread (or thread pool) doing `select()`.
387 * @ingroup event
388 */ 409 */
389 MHD_USE_SELECT_INTERNALLY = 8, 410 MHD_USE_SELECT_INTERNALLY = 8,
390 411
@@ -394,7 +415,6 @@ enum MHD_FLAG
394 * socket, pass #MHD_USE_DUAL_STACK, otherwise, if you only pass 415 * socket, pass #MHD_USE_DUAL_STACK, otherwise, if you only pass
395 * this option, MHD will try to bind to IPv6-only (resulting in 416 * this option, MHD will try to bind to IPv6-only (resulting in
396 * no IPv4 support). 417 * no IPv4 support).
397 * @ingroup networking
398 */ 418 */
399 MHD_USE_IPv6 = 16, 419 MHD_USE_IPv6 = 16,
400 420
@@ -406,23 +426,20 @@ enum MHD_FLAG
406 * as liberal as possible in what you accept" norm. It is 426 * as liberal as possible in what you accept" norm. It is
407 * recommended to turn this ON if you are testing clients against 427 * recommended to turn this ON if you are testing clients against
408 * MHD, and OFF in production. 428 * MHD, and OFF in production.
409 * @ingroup logging
410 */ 429 */
411 MHD_USE_PEDANTIC_CHECKS = 32, 430 MHD_USE_PEDANTIC_CHECKS = 32,
412 431
413 /** 432 /**
414 * Use poll instead of select. This allows sockets with fd >= 433 * Use `poll()` instead of `select()`. This allows sockets with `fd >=
415 * FD_SETSIZE. This option is not compatible with using an 434 * FD_SETSIZE`. This option is not compatible with using an
416 * 'external' select() mode (as there is no API to get the file 435 * 'external' `select()` mode (as there is no API to get the file
417 * descriptors for the external select from MHD) and must also not 436 * descriptors for the external select from MHD) and must also not
418 * be used in combination with #MHD_USE_EPOLL_LINUX_ONLY. 437 * be used in combination with #MHD_USE_EPOLL_LINUX_ONLY.
419 * @ingroup event
420 */ 438 */
421 MHD_USE_POLL = 64, 439 MHD_USE_POLL = 64,
422 440
423 /** 441 /**
424 * Run using an internal thread (or thread pool) doing poll(). 442 * Run using an internal thread (or thread pool) doing `poll()`.
425 * @ingroup event
426 */ 443 */
427 MHD_USE_POLL_INTERNALLY = MHD_USE_SELECT_INTERNALLY | MHD_USE_POLL, 444 MHD_USE_POLL_INTERNALLY = MHD_USE_SELECT_INTERNALLY | MHD_USE_POLL,
428 445
@@ -431,7 +448,6 @@ enum MHD_FLAG
431 * This option should ONLY be used on systems that do not have a clock 448 * This option should ONLY be used on systems that do not have a clock
432 * and that DO provide other mechanisms for cache control. See also 449 * and that DO provide other mechanisms for cache control. See also
433 * RFC 2616, section 14.18 (exception 3). 450 * RFC 2616, section 14.18 (exception 3).
434 * @ingroup specialized
435 */ 451 */
436 MHD_SUPPRESS_DATE_NO_CLOCK = 128, 452 MHD_SUPPRESS_DATE_NO_CLOCK = 128,
437 453
@@ -441,57 +457,51 @@ enum MHD_FLAG
441 * clients to the HTTP server. This option is incompatible with 457 * clients to the HTTP server. This option is incompatible with
442 * using a thread pool; if it is used, #MHD_OPTION_THREAD_POOL_SIZE 458 * using a thread pool; if it is used, #MHD_OPTION_THREAD_POOL_SIZE
443 * is ignored. 459 * is ignored.
444 * @ingroup specialized
445 */ 460 */
446 MHD_USE_NO_LISTEN_SOCKET = 256, 461 MHD_USE_NO_LISTEN_SOCKET = 256,
447 462
448 /** 463 /**
449 * Use epoll() instead of select() or poll() for the event loop. 464 * Use `epoll()` instead of `select()` or `poll()` for the event loop.
450 * This option is only available on Linux; using the option on 465 * This option is only available on Linux; using the option on
451 * non-Linux systems will cause #MHD_start_daemon to fail. 466 * non-Linux systems will cause #MHD_start_daemon to fail.
452 * @ingroup event
453 */ 467 */
454 MHD_USE_EPOLL_LINUX_ONLY = 512, 468 MHD_USE_EPOLL_LINUX_ONLY = 512,
455 469
456 /** 470 /**
457 * Run using an internal thread (or thread pool) doing epoll(). 471 * Run using an internal thread (or thread pool) doing `epoll()`.
458 * This option is only available on Linux; using the option on 472 * This option is only available on Linux; using the option on
459 * non-Linux systems will cause #MHD_start_daemon to fail. 473 * non-Linux systems will cause #MHD_start_daemon to fail.
460 * @ingroup event
461 */ 474 */
462 MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY = MHD_USE_SELECT_INTERNALLY | MHD_USE_EPOLL_LINUX_ONLY, 475 MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY = MHD_USE_SELECT_INTERNALLY | MHD_USE_EPOLL_LINUX_ONLY,
463 476
464 /** 477 /**
465 * Force MHD to use a signal pipe to notify the event loop (of 478 * Force MHD to use a signal pipe to notify the event loop (of
466 * threads) of our shutdown. This is required if an appliction uses 479 * threads) of our shutdown. This is required if an appliction uses
467 * #MHD_USE_INTERNAL_SELECT or #MHD_USE_THREAD_PER_CONNECTION and 480 * #MHD_USE_SELECT_INTERNALLY or #MHD_USE_THREAD_PER_CONNECTION and
468 * then performs #MHD_quiesce_daemon (which eliminates our ability 481 * then performs #MHD_quiesce_daemon (which eliminates our ability
469 * to signal termination via the listen socket). In these modes, 482 * to signal termination via the listen socket). In these modes,
470 * #MHD_quiesce_daemon will fail if this option was not set. Also, 483 * #MHD_quiesce_daemon will fail if this option was not set. Also,
471 * use of this option is automatic (as in, you do not even have to 484 * use of this option is automatic (as in, you do not even have to
472 * specify it), if #MHD_USE_NO_LISTEN_SOCKET is specified. In 485 * specify it), if #MHD_USE_NO_LISTEN_SOCKET is specified. In
473 * "external" select() mode, this option is always simply ignored. 486 * "external" `select()` mode, this option is always simply ignored.
474 * On W32 a pair of sockets is used instead of a pipe. 487 * On W32 a pair of sockets is used instead of a pipe.
475 * 488 *
476 * You must also use this option if you use internal select mode 489 * You must also use this option if you use internal select mode
477 * or a thread pool in conjunction with #MHD_add_connection. 490 * or a thread pool in conjunction with #MHD_add_connection.
478 * @ingroup event
479 */ 491 */
480 MHD_USE_PIPE_FOR_SHUTDOWN = 1024, 492 MHD_USE_PIPE_FOR_SHUTDOWN = 1024,
481 493
482 /** 494 /**
483 * Use a single socket for IPv4 and IPv6. 495 * Use a single socket for IPv4 and IPv6.
484 * @ingroup networking
485 */ 496 */
486 MHD_USE_DUAL_STACK = MHD_USE_IPv6 | 2048, 497 MHD_USE_DUAL_STACK = MHD_USE_IPv6 | 2048,
487 498
488 /** 499 /**
489 * Enable epoll() turbo. Disables certain calls to shutdown() 500 * Enable `epoll()` turbo. Disables certain calls to `shutdown()`
490 * and enables aggressive non-blocking optimisitc reads. 501 * and enables aggressive non-blocking optimisitc reads.
491 * Most effects only happen with #MHD_USE_EPOLL_LINUX_ONLY. 502 * Most effects only happen with #MHD_USE_EPOLL_LINUX_ONLY.
492 * Enalbed always on W32 as winsock does not properly behave 503 * Enalbed always on W32 as winsock does not properly behave
493 * with shutdown() and this then fixes potential problems. 504 * with `shutdown()` and this then fixes potential problems.
494 * @ingroup event
495 */ 505 */
496 MHD_USE_EPOLL_TURBO = 4096 506 MHD_USE_EPOLL_TURBO = 4096
497 507
@@ -502,7 +512,7 @@ enum MHD_FLAG
502 * Type of a callback function used for logging by MHD. 512 * Type of a callback function used for logging by MHD.
503 * 513 *
504 * @param cls closure 514 * @param cls closure
505 * @param fm format string (printf()-style) 515 * @param fm format string (`printf()`-style)
506 * @param ap arguments to @a fm 516 * @param ap arguments to @a fm
507 * @ingroup logging 517 * @ingroup logging
508 */ 518 */
@@ -522,27 +532,24 @@ enum MHD_OPTION
522 MHD_OPTION_END = 0, 532 MHD_OPTION_END = 0,
523 533
524 /** 534 /**
525 * Maximum memory size per connection (followed by a size_t). 535 * Maximum memory size per connection (followed by a `size_t`).
526 * Default is 32 kb (#MHD_POOL_SIZE_DEFAULT). 536 * Default is 32 kb (#MHD_POOL_SIZE_DEFAULT).
527 * Values above 128k are unlikely to result in much benefit, as half 537 * Values above 128k are unlikely to result in much benefit, as half
528 * of the memory will be typically used for IO, and TCP buffers are 538 * of the memory will be typically used for IO, and TCP buffers are
529 * unlikely to support window sizes above 64k on most systems. 539 * unlikely to support window sizes above 64k on most systems.
530 * @ingroup limits
531 */ 540 */
532 MHD_OPTION_CONNECTION_MEMORY_LIMIT = 1, 541 MHD_OPTION_CONNECTION_MEMORY_LIMIT = 1,
533 542
534 /** 543 /**
535 * Maximum number of concurrent connections to 544 * Maximum number of concurrent connections to
536 * accept (followed by an unsigned int). 545 * accept (followed by an `unsigned int`).
537 * @ingroup limits
538 */ 546 */
539 MHD_OPTION_CONNECTION_LIMIT = 2, 547 MHD_OPTION_CONNECTION_LIMIT = 2,
540 548
541 /** 549 /**
542 * After how many seconds of inactivity should a 550 * After how many seconds of inactivity should a
543 * connection automatically be timed out? (followed 551 * connection automatically be timed out? (followed
544 * by an unsigned int; use zero for no timeout). 552 * by an `unsigned int`; use zero for no timeout).
545 * @ingroup limits
546 */ 553 */
547 MHD_OPTION_CONNECTION_TIMEOUT = 3, 554 MHD_OPTION_CONNECTION_TIMEOUT = 3,
548 555
@@ -550,14 +557,13 @@ enum MHD_OPTION
550 * Register a function that should be called whenever a request has 557 * Register a function that should be called whenever a request has
551 * been completed (this can be used for application-specific clean 558 * been completed (this can be used for application-specific clean
552 * up). Requests that have never been presented to the application 559 * up). Requests that have never been presented to the application
553 * (via MHD_AccessHandlerCallback) will not result in 560 * (via #MHD_AccessHandlerCallback) will not result in
554 * notifications. 561 * notifications.
555 * 562 *
556 * This option should be followed by TWO pointers. First a pointer 563 * This option should be followed by TWO pointers. First a pointer
557 * to a function of type "MHD_RequestCompletedCallback" and second a 564 * to a function of type #MHD_RequestCompletedCallback and second a
558 * pointer to a closure to pass to the request completed callback. 565 * pointer to a closure to pass to the request completed callback.
559 * The second pointer maybe NULL. 566 * The second pointer maybe NULL.
560 * @ingroup request
561 */ 567 */
562 MHD_OPTION_NOTIFY_COMPLETED = 4, 568 MHD_OPTION_NOTIFY_COMPLETED = 4,
563 569
@@ -567,18 +573,17 @@ enum MHD_OPTION
567 * IP from taking over all of the allowed connections. If the 573 * IP from taking over all of the allowed connections. If the
568 * same IP tries to establish more than the specified number of 574 * same IP tries to establish more than the specified number of
569 * connections, they will be immediately rejected. The option 575 * connections, they will be immediately rejected. The option
570 * should be followed by an "unsigned int". The default is 576 * should be followed by an `unsigned int`. The default is
571 * zero, which means no limit on the number of connections 577 * zero, which means no limit on the number of connections
572 * from the same IP address. 578 * from the same IP address.
573 * @ingroup limits
574 */ 579 */
575 MHD_OPTION_PER_IP_CONNECTION_LIMIT = 5, 580 MHD_OPTION_PER_IP_CONNECTION_LIMIT = 5,
576 581
577 /** 582 /**
578 * Bind daemon to the supplied sockaddr. this option should be followed by a 583 * Bind daemon to the supplied `struct sockaddr`. This option should
579 * 'struct sockaddr *'. If #MHD_USE_IPv6 is specified, the 'struct sockaddr*' 584 * be followed by a `struct sockaddr *`. If #MHD_USE_IPv6 is
580 * should point to a 'struct sockaddr_in6', otherwise to a 'struct sockaddr_in'. 585 * specified, the `struct sockaddr*` should point to a `struct
581 * @ingroup networking 586 * sockaddr_in6`, otherwise to a `struct sockaddr_in`.
582 */ 587 */
583 MHD_OPTION_SOCK_ADDR = 6, 588 MHD_OPTION_SOCK_ADDR = 6,
584 589
@@ -589,11 +594,11 @@ enum MHD_OPTION
589 * parsing will no longer contain the options, which maybe inconvenient for 594 * parsing will no longer contain the options, which maybe inconvenient for
590 * logging. This option should be followed by two arguments, the first 595 * logging. This option should be followed by two arguments, the first
591 * one must be of the form 596 * one must be of the form
592 * <pre> 597 *
593 * void * my_logger(void *cls, const char *uri) 598 * void * my_logger(void *cls, const char *uri)
594 * </pre> 599 *
595 * where the return value will be passed as 600 * where the return value will be passed as
596 * (*con_cls) in calls to the MHD_AccessHandlerCallback 601 * (`* con_cls`) in calls to the #MHD_AccessHandlerCallback
597 * when this request is processed later; returning a 602 * when this request is processed later; returning a
598 * value of NULL has no special significance (however, 603 * value of NULL has no special significance (however,
599 * note that if you return non-NULL, you can no longer 604 * note that if you return non-NULL, you can no longer
@@ -602,161 +607,144 @@ enum MHD_OPTION
602 * "cls" will be set to the second argument following 607 * "cls" will be set to the second argument following
603 * #MHD_OPTION_URI_LOG_CALLBACK. Finally, uri will 608 * #MHD_OPTION_URI_LOG_CALLBACK. Finally, uri will
604 * be the 0-terminated URI of the request. 609 * be the 0-terminated URI of the request.
605 * @ingroup logging
606 */ 610 */
607 MHD_OPTION_URI_LOG_CALLBACK = 7, 611 MHD_OPTION_URI_LOG_CALLBACK = 7,
608 612
609 /** 613 /**
610 * Memory pointer for the private key (key.pem) to be used by the 614 * Memory pointer for the private key (key.pem) to be used by the
611 * HTTPS daemon. This option should be followed by an 615 * HTTPS daemon. This option should be followed by a
612 * "const char *" argument. 616 * `const char *` argument.
613 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_CERT. 617 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_CERT.
614 * @ingroup tls
615 */ 618 */
616 MHD_OPTION_HTTPS_MEM_KEY = 8, 619 MHD_OPTION_HTTPS_MEM_KEY = 8,
617 620
618 /** 621 /**
619 * Memory pointer for the certificate (cert.pem) to be used by the 622 * Memory pointer for the certificate (cert.pem) to be used by the
620 * HTTPS daemon. This option should be followed by an 623 * HTTPS daemon. This option should be followed by a
621 * "const char *" argument. 624 * `const char *` argument.
622 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY. 625 * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY.
623 * @ingroup tls
624 */ 626 */
625 MHD_OPTION_HTTPS_MEM_CERT = 9, 627 MHD_OPTION_HTTPS_MEM_CERT = 9,
626 628
627 /** 629 /**
628 * Daemon credentials type. 630 * Daemon credentials type.
629 * Followed by an argument of type 631 * Followed by an argument of type
630 * "gnutls_credentials_type_t". 632 * `gnutls_credentials_type_t`.
631 * @ingroup tls
632 */ 633 */
633 MHD_OPTION_HTTPS_CRED_TYPE = 10, 634 MHD_OPTION_HTTPS_CRED_TYPE = 10,
634 635
635 /** 636 /**
636 * Memory pointer to a "const char *" specifying the 637 * Memory pointer to a `const char *` specifying the
637 * cipher algorithm (default: "NORMAL"). 638 * cipher algorithm (default: "NORMAL").
638 * @ingroup tls
639 */ 639 */
640 MHD_OPTION_HTTPS_PRIORITIES = 11, 640 MHD_OPTION_HTTPS_PRIORITIES = 11,
641 641
642 /** 642 /**
643 * Pass a listen socket for MHD to use (systemd-style). If this 643 * Pass a listen socket for MHD to use (systemd-style). If this
644 * option is used, MHD will not open its own listen socket(s). The 644 * option is used, MHD will not open its own listen socket(s). The
645 * argument passed must be of type "int" and refer to an 645 * argument passed must be of type `int` and refer to an
646 * existing socket that has been bound to a port and is listening. 646 * existing socket that has been bound to a port and is listening.
647 * @ingroup specialized
648 */ 647 */
649 MHD_OPTION_LISTEN_SOCKET = 12, 648 MHD_OPTION_LISTEN_SOCKET = 12,
650 649
651 /** 650 /**
652 * Use the given function for logging error messages. 651 * Use the given function for logging error messages. This option
653 * This option must be followed by two arguments; the 652 * must be followed by two arguments; the first must be a pointer to
654 * first must be a pointer to a function 653 * a function of type #MHD_LogCallback and the second a pointer
655 * of type `void fun (void *arg, const char *fmt, va_list ap)` 654 * `void *` which will be passed as the first argument to the log
656 * (also known as MHD_LogCallback) 655 * callback.
657 * and the second a pointer "void *" which will 656 *
658 * be passed as the "arg" argument to "fun".
659 * <p>
660 * Note that MHD will not generate any log messages 657 * Note that MHD will not generate any log messages
661 * if it was compiled without the "--enable-messages" 658 * if it was compiled without the "--enable-messages"
662 * flag being set. 659 * flag being set.
663 * @ingroup logging
664 */ 660 */
665 MHD_OPTION_EXTERNAL_LOGGER = 13, 661 MHD_OPTION_EXTERNAL_LOGGER = 13,
666 662
667 /** 663 /**
668 * Number (unsigned int) of threads in thread pool. Enable 664 * Number (`unsigned int`) of threads in thread pool. Enable
669 * thread pooling by setting this value to to something 665 * thread pooling by setting this value to to something
670 * greater than 1. Currently, thread model must be 666 * greater than 1. Currently, thread model must be
671 * #MHD_USE_SELECT_INTERNALLY if thread pooling is enabled 667 * #MHD_USE_SELECT_INTERNALLY if thread pooling is enabled
672 * (#MHD_start_daemon returns NULL for an unsupported thread 668 * (#MHD_start_daemon returns NULL for an unsupported thread
673 * model). 669 * model).
674 * @ingroup event
675 */ 670 */
676 MHD_OPTION_THREAD_POOL_SIZE = 14, 671 MHD_OPTION_THREAD_POOL_SIZE = 14,
677 672
678 /** 673 /**
679 * Additional options given in an array of "struct MHD_OptionItem". 674 * Additional options given in an array of `struct MHD_OptionItem`.
680 * The array must be terminated with an entry '{MHD_OPTION_END, 0, NULL}'. 675 * The array must be terminated with an entry `{MHD_OPTION_END, 0, NULL}`.
681 * An example for code using #MHD_OPTION_ARRAY is: 676 * An example for code using #MHD_OPTION_ARRAY is:
682 * <code> 677 *
683 * struct MHD_OptionItem ops[] = { 678 * struct MHD_OptionItem ops[] = {
684 * { MHD_OPTION_CONNECTION_LIMIT, 100, NULL }, 679 * { MHD_OPTION_CONNECTION_LIMIT, 100, NULL },
685 * { MHD_OPTION_CONNECTION_TIMEOUT, 10, NULL }, 680 * { MHD_OPTION_CONNECTION_TIMEOUT, 10, NULL },
686 * { MHD_OPTION_END, 0, NULL } 681 * { MHD_OPTION_END, 0, NULL }
687 * }; 682 * };
688 * d = MHD_start_daemon(0, 8080, NULL, NULL, dh, NULL, 683 * d = MHD_start_daemon (0, 8080, NULL, NULL, dh, NULL,
689 * MHD_OPTION_ARRAY, ops, 684 * MHD_OPTION_ARRAY, ops,
690 * MHD_OPTION_END); 685 * MHD_OPTION_END);
691 * </code> 686 *
692 * For options that expect a single pointer argument, the 687 * For options that expect a single pointer argument, the
693 * second member of the struct MHD_OptionItem is ignored. 688 * second member of the `struct MHD_OptionItem` is ignored.
694 * For options that expect two pointer arguments, the first 689 * For options that expect two pointer arguments, the first
695 * argument must be cast to 'intptr_t'. 690 * argument must be cast to `intptr_t`.
696 * @ingroup specialized
697 */ 691 */
698 MHD_OPTION_ARRAY = 15, 692 MHD_OPTION_ARRAY = 15,
699 693
700 /** 694 /**
701 * Specify a function that should be called for unescaping escape 695 * Specify a function that should be called for unescaping escape
702 * sequences in URIs and URI arguments. Note that this function 696 * sequences in URIs and URI arguments. Note that this function
703 * will NOT be used by the MHD_PostProcessor. If this option is 697 * will NOT be used by the `struct MHD_PostProcessor`. If this
704 * not specified, the default method will be used which decodes 698 * option is not specified, the default method will be used which
705 * escape sequences of the form "%HH". 699 * decodes escape sequences of the form "%HH". This option should
706 * This option should be followed by two arguments, the first 700 * be followed by two arguments, the first one must be of the form
707 * one must be of the form 701 *
708 * <pre> 702 * size_t my_unescaper(void *cls,
709 * size_t my_unescaper(void *cls, struct MHD_Connection *c, char *s) 703 * struct MHD_Connection *c,
710 * </pre> 704 * char *s)
711 * where the return value must be "strlen(s)" and 705 *
712 * "s" should be updated. Note that the unescape function 706 * where the return value must be "strlen(s)" and "s" should be
713 * must not lengthen "s" (the result must be shorter than 707 * updated. Note that the unescape function must not lengthen "s"
714 * the input and still be 0-terminated). 708 * (the result must be shorter than the input and still be
715 * "cls" will be set to the second argument following 709 * 0-terminated). "cls" will be set to the second argument
716 * #MHD_OPTION_UNESCAPE_CALLBACK. 710 * following #MHD_OPTION_UNESCAPE_CALLBACK.
717 * @ingroup specialized
718 */ 711 */
719 MHD_OPTION_UNESCAPE_CALLBACK = 16, 712 MHD_OPTION_UNESCAPE_CALLBACK = 16,
720 713
721 /** 714 /**
722 * Memory pointer for the random values to be used by the Digest 715 * Memory pointer for the random values to be used by the Digest
723 * Auth module. This option should be followed by two arguments. 716 * Auth module. This option should be followed by two arguments.
724 * First an integer of type "size_t" which specifies the size 717 * First an integer of type `size_t` which specifies the size
725 * of the buffer pointed to by the second argument in bytes. 718 * of the buffer pointed to by the second argument in bytes.
726 * Note that the application must ensure that the buffer of the 719 * Note that the application must ensure that the buffer of the
727 * second argument remains allocated and unmodified while the 720 * second argument remains allocated and unmodified while the
728 * deamon is running. 721 * deamon is running.
729 * @ingroup auth
730 */ 722 */
731 MHD_OPTION_DIGEST_AUTH_RANDOM = 17, 723 MHD_OPTION_DIGEST_AUTH_RANDOM = 17,
732 724
733 /** 725 /**
734 * Size of the internal array holding the map of the nonce and 726 * Size of the internal array holding the map of the nonce and
735 * the nonce counter. This option should be followed by a "unsigend int" 727 * the nonce counter. This option should be followed by an `unsigend int`
736 * argument. 728 * argument.
737 * @ingroup auth
738 */ 729 */
739 MHD_OPTION_NONCE_NC_SIZE = 18, 730 MHD_OPTION_NONCE_NC_SIZE = 18,
740 731
741 /** 732 /**
742 * Desired size of the stack for threads created by MHD. Followed 733 * Desired size of the stack for threads created by MHD. Followed
743 * by an argument of type 'size_t'. Use 0 for system 'default'. 734 * by an argument of type `size_t`. Use 0 for system default.
744 * @ingroup event
745 */ 735 */
746 MHD_OPTION_THREAD_STACK_SIZE = 19, 736 MHD_OPTION_THREAD_STACK_SIZE = 19,
747 737
748 /** 738 /**
749 * Memory pointer for the certificate (ca.pem) to be used by the 739 * Memory pointer for the certificate (ca.pem) to be used by the
750 * HTTPS daemon for client authentification. 740 * HTTPS daemon for client authentification.
751 * This option should be followed by a "const char*" argument. 741 * This option should be followed by a `const char *` argument.
752 * @ingroup tls
753 */ 742 */
754 MHD_OPTION_HTTPS_MEM_TRUST = 20, 743 MHD_OPTION_HTTPS_MEM_TRUST = 20,
755 744
756 /** 745 /**
757 * Increment to use for growing the read buffer (followed by a 746 * Increment to use for growing the read buffer (followed by a
758 * size_t). Must fit within #MHD_OPTION_CONNECTION_MEMORY_LIMIT. 747 * `size_t`). Must fit within #MHD_OPTION_CONNECTION_MEMORY_LIMIT.
759 * @ingroup limits
760 */ 748 */
761 MHD_OPTION_CONNECTION_MEMORY_INCREMENT = 21 749 MHD_OPTION_CONNECTION_MEMORY_INCREMENT = 21
762}; 750};
@@ -764,7 +752,6 @@ enum MHD_OPTION
764 752
765/** 753/**
766 * Entry in an #MHD_OPTION_ARRAY. 754 * Entry in an #MHD_OPTION_ARRAY.
767 * @ingroup specialized
768 */ 755 */
769struct MHD_OptionItem 756struct MHD_OptionItem
770{ 757{
@@ -791,29 +778,25 @@ struct MHD_OptionItem
791 778
792 779
793/** 780/**
794 * The MHD_ValueKind specifies the source of 781 * The `enum MHD_ValueKind` specifies the source of
795 * the key-value pairs in the HTTP protocol. 782 * the key-value pairs in the HTTP protocol.
796 * @ingroup request
797 */ 783 */
798enum MHD_ValueKind 784enum MHD_ValueKind
799{ 785{
800 786
801 /** 787 /**
802 * Response header 788 * Response header
803 * @ingroup response
804 */ 789 */
805 MHD_RESPONSE_HEADER_KIND = 0, 790 MHD_RESPONSE_HEADER_KIND = 0,
806 791
807 /** 792 /**
808 * HTTP header. 793 * HTTP header.
809 * @ingroup request
810 */ 794 */
811 MHD_HEADER_KIND = 1, 795 MHD_HEADER_KIND = 1,
812 796
813 /** 797 /**
814 * Cookies. Note that the original HTTP header containing 798 * Cookies. Note that the original HTTP header containing
815 * the cookie(s) will still be available and intact. 799 * the cookie(s) will still be available and intact.
816 * @ingroup request
817 */ 800 */
818 MHD_COOKIE_KIND = 2, 801 MHD_COOKIE_KIND = 2,
819 802
@@ -822,28 +805,25 @@ enum MHD_ValueKind
822 * supported by MHD is used (currently only URL encoding), 805 * supported by MHD is used (currently only URL encoding),
823 * and only if the posted content fits within the available 806 * and only if the posted content fits within the available
824 * memory pool. Note that in that case, the upload data 807 * memory pool. Note that in that case, the upload data
825 * given to the MHD_AccessHandlerCallback will be 808 * given to the #MHD_AccessHandlerCallback will be
826 * empty (since it has already been processed). 809 * empty (since it has already been processed).
827 * @ingroup request
828 */ 810 */
829 MHD_POSTDATA_KIND = 4, 811 MHD_POSTDATA_KIND = 4,
830 812
831 /** 813 /**
832 * GET (URI) arguments. 814 * GET (URI) arguments.
833 * @ingroup request
834 */ 815 */
835 MHD_GET_ARGUMENT_KIND = 8, 816 MHD_GET_ARGUMENT_KIND = 8,
836 817
837 /** 818 /**
838 * HTTP footer (only for http 1.1 chunked encodings). 819 * HTTP footer (only for HTTP 1.1 chunked encodings).
839 * @ingroup request
840 */ 820 */
841 MHD_FOOTER_KIND = 16 821 MHD_FOOTER_KIND = 16
842}; 822};
843 823
844 824
845/** 825/**
846 * The MHD_RequestTerminationCode specifies reasons 826 * The `enum MHD_RequestTerminationCode` specifies reasons
847 * why a request has been terminated (or completed). 827 * why a request has been terminated (or completed).
848 * @ingroup request 828 * @ingroup request
849 */ 829 */
@@ -893,6 +873,50 @@ enum MHD_RequestTerminationCode
893 873
894 874
895/** 875/**
876 * Information about a connection.
877 */
878union MHD_ConnectionInfo
879{
880
881 /**
882 * Cipher algorithm used, of type "enum gnutls_cipher_algorithm".
883 */
884 int /* enum gnutls_cipher_algorithm */ cipher_algorithm;
885
886 /**
887 * Protocol used, of type "enum gnutls_protocol".
888 */
889 int /* enum gnutls_protocol */ protocol;
890
891 /**
892 * Connect socket
893 */
894 int connect_fd;
895
896 /**
897 * GNUtls session handle, of type "gnutls_session_t".
898 */
899 void * /* gnutls_session_t */ tls_session;
900
901 /**
902 * GNUtls client certificate handle, of type "gnutls_x509_crt_t".
903 */
904 void * /* gnutls_x509_crt_t */ client_cert;
905
906 /**
907 * Address information for the client.
908 */
909 struct sockaddr *client_addr;
910
911 /**
912 * Which daemon manages this connection (useful in case there are many
913 * daemons running).
914 */
915 struct MHD_Daemon *daemon;
916};
917
918
919/**
896 * Values of this enum are used to specify what 920 * Values of this enum are used to specify what
897 * information about a connection is desired. 921 * information about a connection is desired.
898 * @ingroup request 922 * @ingroup request
@@ -915,9 +939,9 @@ enum MHD_ConnectionInfoType
915 939
916 /** 940 /**
917 * Obtain IP address of the client. Takes no extra arguments. 941 * Obtain IP address of the client. Takes no extra arguments.
918 * Returns essentially a "struct sockaddr **" (since the API returns 942 * Returns essentially a `struct sockaddr **` (since the API returns
919 * a "union MHD_ConnectionInfo *" and that union contains a "struct 943 * a `union MHD_ConnectionInfo *` and that union contains a `struct
920 * sockaddr *"). 944 * sockaddr *`).
921 * @ingroup request 945 * @ingroup request
922 */ 946 */
923 MHD_CONNECTION_INFO_CLIENT_ADDRESS, 947 MHD_CONNECTION_INFO_CLIENT_ADDRESS,
@@ -930,14 +954,14 @@ enum MHD_ConnectionInfoType
930 954
931 /** 955 /**
932 * Get the gnuTLS client certificate handle. Dysfunctional (never 956 * Get the gnuTLS client certificate handle. Dysfunctional (never
933 * implemented, deprecated). Use MHD_CONNECTION_INFO_GNUTLS_SESSION 957 * implemented, deprecated). Use #MHD_CONNECTION_INFO_GNUTLS_SESSION
934 * to get the gnutls_session_t and then call 958 * to get the `gnutls_session_t` and then call
935 * gnutls_certificate_get_peers(). 959 * gnutls_certificate_get_peers().
936 */ 960 */
937 MHD_CONNECTION_INFO_GNUTLS_CLIENT_CERT, 961 MHD_CONNECTION_INFO_GNUTLS_CLIENT_CERT,
938 962
939 /** 963 /**
940 * Get the 'struct MHD_Daemon' responsible for managing this connection. 964 * Get the `struct MHD_Daemon *` responsible for managing this connection.
941 * @ingroup request 965 * @ingroup request
942 */ 966 */
943 MHD_CONNECTION_INFO_DAEMON, 967 MHD_CONNECTION_INFO_DAEMON,
@@ -959,19 +983,11 @@ enum MHD_ConnectionInfoType
959enum MHD_DaemonInfoType 983enum MHD_DaemonInfoType
960{ 984{
961 /** 985 /**
962 * Request information about the key size for
963 * a particular cipher algorithm. The cipher
964 * algorithm should be passed as an extra
965 * argument (of type 'enum MHD_GNUTLS_CipherAlgorithm').
966 * No longer supported (will return NULL). 986 * No longer supported (will return NULL).
967 */ 987 */
968 MHD_DAEMON_INFO_KEY_SIZE, 988 MHD_DAEMON_INFO_KEY_SIZE,
969 989
970 /** 990 /**
971 * Request information about the key size for
972 * a particular cipher algorithm. The cipher
973 * algorithm should be passed as an extra
974 * argument (of type 'enum MHD_GNUTLS_HashAlgorithm').
975 * No longer supported (will return NULL). 991 * No longer supported (will return NULL).
976 */ 992 */
977 MHD_DAEMON_INFO_MAC_KEY_SIZE, 993 MHD_DAEMON_INFO_MAC_KEY_SIZE,
@@ -979,50 +995,20 @@ enum MHD_DaemonInfoType
979 /** 995 /**
980 * Request the file descriptor for the listening socket. 996 * Request the file descriptor for the listening socket.
981 * No extra arguments should be passed. 997 * No extra arguments should be passed.
982 * @ingroup networking
983 */ 998 */
984 MHD_DAEMON_INFO_LISTEN_FD, 999 MHD_DAEMON_INFO_LISTEN_FD,
985 1000
986 /** 1001 /**
987 * Request the file descriptor for the external epoll. 1002 * Request the file descriptor for the external epoll.
988 * No extra arguments should be passed. 1003 * No extra arguments should be passed.
989 * @ingroup event
990 */ 1004 */
991 MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY 1005 MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY
992}; 1006};
993 1007
994 1008
995/** 1009/**
996 * Handle for the daemon (listening on a socket for HTTP traffic).
997 * @ingroup event
998 */
999struct MHD_Daemon;
1000
1001/**
1002 * Handle for a connection / HTTP request. With HTTP/1.1, multiple
1003 * requests can be run over the same connection. However, MHD will
1004 * only show one request per TCP connection to the client at any given
1005 * time.
1006 * @ingroup request
1007 */
1008struct MHD_Connection;
1009
1010/**
1011 * Handle for a response.
1012 * @ingroup response
1013 */
1014struct MHD_Response;
1015
1016/**
1017 * Handle for POST processing.
1018 * @ingroup response
1019 */
1020struct MHD_PostProcessor;
1021
1022
1023/**
1024 * Callback for serious error condition. The default action is to print 1010 * Callback for serious error condition. The default action is to print
1025 * an error message and abort(). 1011 * an error message and `abort()`.
1026 * 1012 *
1027 * @param cls user specified value 1013 * @param cls user specified value
1028 * @param file where the error occured 1014 * @param file where the error occured
@@ -1050,21 +1036,25 @@ typedef int
1050 1036
1051 1037
1052/** 1038/**
1053 * A client has requested the given url using the given method ("GET", 1039 * A client has requested the given url using the given method
1054 * "PUT", "DELETE", "POST", etc). The callback must call MHS 1040 * (#MHD_HTTP_METHOD_GET, #MHD_HTTP_METHOD_PUT,
1055 * callbacks to provide content to give back to the client and return 1041 * #MHD_HTTP_METHOD_DELETE, #MHD_HTTP_METHOD_POST, etc). The callback
1056 * an HTTP status code (i.e. 200 for OK, 404, etc.). 1042 * must call MHD callbacks to provide content to give back to the
1043 * client and return an HTTP status code (i.e. #MHD_HTTP_OK,
1044 * #MHD_HTTP_NOT_FOUND, etc.).
1057 * 1045 *
1058 * @param cls argument given together with the function 1046 * @param cls argument given together with the function
1059 * pointer when the handler was registered with MHD 1047 * pointer when the handler was registered with MHD
1060 * @param url the requested url 1048 * @param url the requested url
1061 * @param method the HTTP method used ("GET", "PUT", etc.) 1049 * @param method the HTTP method used (#MHD_HTTP_METHOD_GET,
1062 * @param version the HTTP version string (i.e. "HTTP/1.1") 1050 * #MHD_HTTP_METHOD_PUT, etc.)
1051 * @param version the HTTP version string (i.e.
1052 * #MHD_HTTP_VERSION_1_1)
1063 * @param upload_data the data being uploaded (excluding HEADERS, 1053 * @param upload_data the data being uploaded (excluding HEADERS,
1064 * for a POST that fits into memory and that is encoded 1054 * for a POST that fits into memory and that is encoded
1065 * with a supported encoding, the POST data will NOT be 1055 * with a supported encoding, the POST data will NOT be
1066 * given in upload_data and is instead available as 1056 * given in upload_data and is instead available as
1067 * part of MHD_get_connection_values; very large POST 1057 * part of #MHD_get_connection_values; very large POST
1068 * data *will* be made available incrementally in 1058 * data *will* be made available incrementally in
1069 * @a upload_data) 1059 * @a upload_data)
1070 * @param upload_data_size set initially to the size of the 1060 * @param upload_data_size set initially to the size of the
@@ -1077,11 +1067,11 @@ typedef int
1077 * with plenty of upload data) this allows the application 1067 * with plenty of upload data) this allows the application
1078 * to easily associate some request-specific state. 1068 * to easily associate some request-specific state.
1079 * If necessary, this state can be cleaned up in the 1069 * If necessary, this state can be cleaned up in the
1080 * global "MHD_RequestCompleted" callback (which 1070 * global #MHD_RequestCompleted callback (which
1081 * can be set with the #MHD_OPTION_NOTIFY_COMPLETED). 1071 * can be set with the #MHD_OPTION_NOTIFY_COMPLETED).
1082 * Initially, <tt>*con_cls</tt> will be NULL. 1072 * Initially, `*con_cls` will be NULL.
1083 * @return #MHS_YES if the connection was handled successfully, 1073 * @return #MHD_YES if the connection was handled successfully,
1084 * #MHS_NO if the socket must be closed due to a serios 1074 * #MHD_NO if the socket must be closed due to a serios
1085 * error while handling the request 1075 * error while handling the request
1086 */ 1076 */
1087typedef int 1077typedef int
@@ -1102,7 +1092,7 @@ typedef int
1102 * @param cls client-defined closure 1092 * @param cls client-defined closure
1103 * @param connection connection handle 1093 * @param connection connection handle
1104 * @param con_cls value as set by the last call to 1094 * @param con_cls value as set by the last call to
1105 * the MHD_AccessHandlerCallback 1095 * the #MHD_AccessHandlerCallback
1106 * @param toe reason for request termination 1096 * @param toe reason for request termination
1107 * @see #MHD_OPTION_NOTIFY_COMPLETED 1097 * @see #MHD_OPTION_NOTIFY_COMPLETED
1108 * @ingroup request 1098 * @ingroup request
@@ -1135,21 +1125,21 @@ typedef int
1135 * Callback used by libmicrohttpd in order to obtain content. The 1125 * Callback used by libmicrohttpd in order to obtain content. The
1136 * callback is to copy at most @a max bytes of content into @a buf. The 1126 * callback is to copy at most @a max bytes of content into @a buf. The
1137 * total number of bytes that has been placed into @a buf should be 1127 * total number of bytes that has been placed into @a buf should be
1138 * returned.<p> 1128 * returned.
1139 * 1129 *
1140 * Note that returning zero will cause libmicrohttpd to try again, 1130 * Note that returning zero will cause libmicrohttpd to try again,
1141 * either "immediately" if in multi-threaded mode (in which case the 1131 * either "immediately" if in multi-threaded mode (in which case the
1142 * callback may want to do blocking operations) or in the next round 1132 * callback may want to do blocking operations) or in the next round
1143 * if #MHD_run is used. Returning 0 for a daemon that runs in internal 1133 * if #MHD_run is used. Returning 0 for a daemon that runs in internal
1144 * select mode is an error (since it would result in busy waiting) and 1134 * select mode is an error (since it would result in busy waiting) and
1145 * will cause the program to be aborted (abort()). 1135 * will cause the program to be aborted (via `abort()`).
1146 * 1136 *
1147 * @param cls extra argument to the callback 1137 * @param cls extra argument to the callback
1148 * @param pos position in the datastream to access; 1138 * @param pos position in the datastream to access;
1149 * note that if an MHD_Response object is re-used, 1139 * note that if a `struct MHD_Response` object is re-used,
1150 * it is possible for the same content reader to 1140 * it is possible for the same content reader to
1151 * be queried multiple times for the same data; 1141 * be queried multiple times for the same data;
1152 * however, if an MHD_Response is not re-used, 1142 * however, if a `struct MHD_Response` is not re-used,
1153 * libmicrohttpd guarantees that "pos" will be 1143 * libmicrohttpd guarantees that "pos" will be
1154 * the sum of all non-negative return values 1144 * the sum of all non-negative return values
1155 * obtained from the content reader so far. 1145 * obtained from the content reader so far.
@@ -1233,8 +1223,8 @@ typedef int
1233/** 1223/**
1234 * Start a webserver on the given port. 1224 * Start a webserver on the given port.
1235 * 1225 *
1236 * @param flags combination of MHD_FLAG values 1226 * @param flags combination of `enum MHD_FLAG` values
1237 * @param port port to bind to 1227 * @param port port to bind to (in host byte order)
1238 * @param apc callback to call to check which clients 1228 * @param apc callback to call to check which clients
1239 * will be allowed to connect; you can pass NULL 1229 * will be allowed to connect; you can pass NULL
1240 * in which case connections from any IP will be 1230 * in which case connections from any IP will be
@@ -1259,7 +1249,7 @@ MHD_start_daemon_va (unsigned int flags,
1259 * Start a webserver on the given port. Variadic version of 1249 * Start a webserver on the given port. Variadic version of
1260 * #MHD_start_daemon_va. 1250 * #MHD_start_daemon_va.
1261 * 1251 *
1262 * @param flags combination of MHD_FLAG values 1252 * @param flags combination of `enum MHD_FLAG` values
1263 * @param port port to bind to 1253 * @param port port to bind to
1264 * @param apc callback to call to check which clients 1254 * @param apc callback to call to check which clients
1265 * will be allowed to connect; you can pass NULL 1255 * will be allowed to connect; you can pass NULL
@@ -1303,7 +1293,7 @@ MHD_quiesce_daemon (struct MHD_Daemon *daemon);
1303 1293
1304 1294
1305/** 1295/**
1306 * Shutdown an http daemon. 1296 * Shutdown an HTTP daemon.
1307 * 1297 *
1308 * @param daemon daemon to stop 1298 * @param daemon daemon to stop
1309 * @ingroup event 1299 * @ingroup event
@@ -1328,14 +1318,16 @@ MHD_stop_daemon (struct MHD_Daemon *daemon);
1328 * this call and must no longer be used directly by the application 1318 * this call and must no longer be used directly by the application
1329 * afterwards. 1319 * afterwards.
1330 * 1320 *
1321 * Per-IP connection limits are ignored when using this API.
1322 *
1331 * @param daemon daemon that manages the connection 1323 * @param daemon daemon that manages the connection
1332 * @param client_socket socket to manage (MHD will expect 1324 * @param client_socket socket to manage (MHD will expect
1333 * to receive an HTTP request from this socket next). 1325 * to receive an HTTP request from this socket next).
1334 * @param addr IP address of the client 1326 * @param addr IP address of the client
1335 * @param addrlen number of bytes in @a addr 1327 * @param addrlen number of bytes in @a addr
1336 * @return #MHD_YES on success, #MHD_NO if this daemon could 1328 * @return #MHD_YES on success, #MHD_NO if this daemon could
1337 * not handle the connection (i.e. malloc() failed, etc). 1329 * not handle the connection (i.e. `malloc()` failed, etc).
1338 * The socket will be closed in any case; @code{errno} is 1330 * The socket will be closed in any case; `errno` is
1339 * set to indicate further details about the error. 1331 * set to indicate further details about the error.
1340 * @ingroup specialized 1332 * @ingroup specialized
1341 */ 1333 */
@@ -1347,7 +1339,7 @@ MHD_add_connection (struct MHD_Daemon *daemon,
1347 1339
1348 1340
1349/** 1341/**
1350 * Obtain the select sets for this daemon. 1342 * Obtain the `select()` sets for this daemon.
1351 * 1343 *
1352 * @param daemon daemon to get sets from 1344 * @param daemon daemon to get sets from
1353 * @param read_fd_set read set 1345 * @param read_fd_set read set
@@ -1369,9 +1361,9 @@ MHD_get_fdset (struct MHD_Daemon *daemon,
1369 1361
1370 1362
1371/** 1363/**
1372 * Obtain timeout value for select() for this daemon (only needed if 1364 * Obtain timeout value for `select()` for this daemon (only needed if
1373 * connection timeout is used). The returned value is how long 1365 * connection timeout is used). The returned value is how long
1374 * select() or poll() should at most block, not the timeout value set 1366 * `select()` or `poll()` should at most block, not the timeout value set
1375 * for connections. This function MUST NOT be called if MHD is 1367 * for connections. This function MUST NOT be called if MHD is
1376 * running with #MHD_USE_THREAD_PER_CONNECTION. 1368 * running with #MHD_USE_THREAD_PER_CONNECTION.
1377 * 1369 *
@@ -1382,8 +1374,9 @@ MHD_get_fdset (struct MHD_Daemon *daemon,
1382 * necessiate the use of a timeout right now). 1374 * necessiate the use of a timeout right now).
1383 * @ingroup event 1375 * @ingroup event
1384 */ 1376 */
1385int MHD_get_timeout (struct MHD_Daemon *daemon, 1377int
1386 MHD_UNSIGNED_LONG_LONG *timeout); 1378MHD_get_timeout (struct MHD_Daemon *daemon,
1379 MHD_UNSIGNED_LONG_LONG *timeout);
1387 1380
1388 1381
1389/** 1382/**
@@ -1392,12 +1385,12 @@ int MHD_get_timeout (struct MHD_Daemon *daemon,
1392 * with #MHD_get_fdset if the client-controlled select method is used. 1385 * with #MHD_get_fdset if the client-controlled select method is used.
1393 * 1386 *
1394 * This function is a convenience method, which is useful if the 1387 * This function is a convenience method, which is useful if the
1395 * fd_sets from #MHD_get_fdset were not directly passed to select(); 1388 * fd_sets from #MHD_get_fdset were not directly passed to `select()`;
1396 * with this function, MHD will internally do the appropriate select() 1389 * with this function, MHD will internally do the appropriate `select()`
1397 * call itself again. While it is always safe to call #MHD_run (in 1390 * call itself again. While it is always safe to call #MHD_run (in
1398 * external select mode), you should call #MHD_run_from_select if 1391 * external select mode), you should call #MHD_run_from_select if
1399 * performance is important (as it saves an expensive call to 1392 * performance is important (as it saves an expensive call to
1400 * select()). 1393 * `select()`).
1401 * 1394 *
1402 * @param daemon daemon to run 1395 * @param daemon daemon to run
1403 * @return #MHD_YES on success, #MHD_NO if this 1396 * @return #MHD_YES on success, #MHD_NO if this
@@ -1415,10 +1408,10 @@ MHD_run (struct MHD_Daemon *daemon);
1415 * method is used. 1408 * method is used.
1416 * 1409 *
1417 * You can use this function instead of #MHD_run if you called 1410 * You can use this function instead of #MHD_run if you called
1418 * select() on the result from #MHD_get_fdset. File descriptors in 1411 * `select()` on the result from #MHD_get_fdset. File descriptors in
1419 * the sets that are not controlled by MHD will be ignored. Calling 1412 * the sets that are not controlled by MHD will be ignored. Calling
1420 * this function instead of #MHD_run is more efficient as MHD will 1413 * this function instead of #MHD_run is more efficient as MHD will
1421 * not have to call select() again to determine which operations are 1414 * not have to call `select()` again to determine which operations are
1422 * ready. 1415 * ready.
1423 * 1416 *
1424 * @param daemon daemon to run select loop for 1417 * @param daemon daemon to run select loop for
@@ -1426,6 +1419,7 @@ MHD_run (struct MHD_Daemon *daemon);
1426 * @param write_fd_set write set 1419 * @param write_fd_set write set
1427 * @param except_fd_set except set (not used, can be NULL) 1420 * @param except_fd_set except set (not used, can be NULL)
1428 * @return #MHD_NO on serious errors, #MHD_YES on success 1421 * @return #MHD_NO on serious errors, #MHD_YES on success
1422 * @ingroup event
1429 */ 1423 */
1430int 1424int
1431MHD_run_from_select (struct MHD_Daemon *daemon, 1425MHD_run_from_select (struct MHD_Daemon *daemon,
@@ -1458,13 +1452,13 @@ MHD_get_connection_values (struct MHD_Connection *connection,
1458/** 1452/**
1459 * This function can be used to add an entry to the HTTP headers of a 1453 * This function can be used to add an entry to the HTTP headers of a
1460 * connection (so that the #MHD_get_connection_values function will 1454 * connection (so that the #MHD_get_connection_values function will
1461 * return them -- and the MHD PostProcessor will also see them). This 1455 * return them -- and the `struct MHD_PostProcessor` will also see
1462 * maybe required in certain situations (see Mantis #1399) where 1456 * them). This maybe required in certain situations (see Mantis
1463 * (broken) HTTP implementations fail to supply values needed by the 1457 * #1399) where (broken) HTTP implementations fail to supply values
1464 * post processor (or other parts of the application). 1458 * needed by the post processor (or other parts of the application).
1465 * 1459 *
1466 * This function MUST only be called from within the 1460 * This function MUST only be called from within the
1467 * MHD_AccessHandlerCallback (otherwise, access maybe improperly 1461 * #MHD_AccessHandlerCallback (otherwise, access maybe improperly
1468 * synchronized). Furthermore, the client must guarantee that the key 1462 * synchronized). Furthermore, the client must guarantee that the key
1469 * and value arguments are 0-terminated strings that are NOT freed 1463 * and value arguments are 0-terminated strings that are NOT freed
1470 * until the connection is closed. (The easiest way to do this is by 1464 * until the connection is closed. (The easiest way to do this is by
@@ -1496,8 +1490,8 @@ MHD_set_connection_value (struct MHD_Connection *connection,
1496 * try to continue, this is never safe. 1490 * try to continue, this is never safe.
1497 * 1491 *
1498 * The default implementation that is used if no panic function is set 1492 * The default implementation that is used if no panic function is set
1499 * simply prints an error message and calls abort(). Alternative 1493 * simply prints an error message and calls `abort()`. Alternative
1500 * implementations might call exit() or other similar functions. 1494 * implementations might call `exit()` or other similar functions.
1501 * 1495 *
1502 * @param cb new error handler 1496 * @param cb new error handler
1503 * @param cls passed to @a cb 1497 * @param cls passed to @a cb
@@ -1525,10 +1519,10 @@ MHD_lookup_connection_value (struct MHD_Connection *connection,
1525 1519
1526/** 1520/**
1527 * Queue a response to be transmitted to the client (as soon as 1521 * Queue a response to be transmitted to the client (as soon as
1528 * possible but after MHD_AccessHandlerCallback returns). 1522 * possible but after #MHD_AccessHandlerCallback returns).
1529 * 1523 *
1530 * @param connection the connection identifying the client 1524 * @param connection the connection identifying the client
1531 * @param status_code HTTP status code (i.e. 200 for OK) 1525 * @param status_code HTTP status code (i.e. #MHD_HTTP_OK)
1532 * @param response response to transmit 1526 * @param response response to transmit
1533 * @return #MHD_NO on error (i.e. reply already sent), 1527 * @return #MHD_NO on error (i.e. reply already sent),
1534 * #MHD_YES on success or if message has been queued 1528 * #MHD_YES on success or if message has been queued
@@ -1603,7 +1597,7 @@ enum MHD_ResponseMemoryMode
1603 MHD_RESPMEM_PERSISTENT, 1597 MHD_RESPMEM_PERSISTENT,
1604 1598
1605 /** 1599 /**
1606 * Buffer is heap-allocated with malloc() (or equivalent) and 1600 * Buffer is heap-allocated with `malloc()` (or equivalent) and
1607 * should be freed by MHD after processing the response has 1601 * should be freed by MHD after processing the response has
1608 * concluded (response reference counter reaches zero). 1602 * concluded (response reference counter reaches zero).
1609 * @ingroup response 1603 * @ingroup response
@@ -1612,7 +1606,7 @@ enum MHD_ResponseMemoryMode
1612 1606
1613 /** 1607 /**
1614 * Buffer is in transient memory, but not on the heap (for example, 1608 * Buffer is in transient memory, but not on the heap (for example,
1615 * on the stack or non-malloc allocated) and only valid during the 1609 * on the stack or non-`malloc()` allocated) and only valid during the
1616 * call to #MHD_create_response_from_buffer. MHD must make its 1610 * call to #MHD_create_response_from_buffer. MHD must make its
1617 * own private copy of the data for processing. 1611 * own private copy of the data for processing.
1618 * @ingroup response 1612 * @ingroup response
@@ -1663,7 +1657,7 @@ MHD_create_response_from_fd (size_t size,
1663 * data; will be closed when response is destroyed; 1657 * data; will be closed when response is destroyed;
1664 * fd should be in 'blocking' mode 1658 * fd should be in 'blocking' mode
1665 * @param offset offset to start reading from in the file; 1659 * @param offset offset to start reading from in the file;
1666 * Be careful! 'off_t' may have been compiled to be a 1660 * Be careful! `off_t` may have been compiled to be a
1667 * 64-bit variable for MHD, in which case your application 1661 * 64-bit variable for MHD, in which case your application
1668 * also has to be compiled using the same options! Read 1662 * also has to be compiled using the same options! Read
1669 * the MHD manual for more details. 1663 * the MHD manual for more details.
@@ -1835,7 +1829,8 @@ MHD_destroy_response (struct MHD_Response *response);
1835 */ 1829 */
1836int 1830int
1837MHD_add_response_header (struct MHD_Response *response, 1831MHD_add_response_header (struct MHD_Response *response,
1838 const char *header, const char *content); 1832 const char *header,
1833 const char *content);
1839 1834
1840 1835
1841/** 1836/**
@@ -1849,7 +1844,8 @@ MHD_add_response_header (struct MHD_Response *response,
1849 */ 1844 */
1850int 1845int
1851MHD_add_response_footer (struct MHD_Response *response, 1846MHD_add_response_footer (struct MHD_Response *response,
1852 const char *footer, const char *content); 1847 const char *footer,
1848 const char *content);
1853 1849
1854 1850
1855/** 1851/**
@@ -1863,7 +1859,8 @@ MHD_add_response_footer (struct MHD_Response *response,
1863 */ 1859 */
1864int 1860int
1865MHD_del_response_header (struct MHD_Response *response, 1861MHD_del_response_header (struct MHD_Response *response,
1866 const char *header, const char *content); 1862 const char *header,
1863 const char *content);
1867 1864
1868 1865
1869/** 1866/**
@@ -1897,14 +1894,14 @@ MHD_get_response_header (struct MHD_Response *response,
1897/* ********************** PostProcessor functions ********************** */ 1894/* ********************** PostProcessor functions ********************** */
1898 1895
1899/** 1896/**
1900 * Create a PostProcessor. 1897 * Create a `struct MHD_PostProcessor`.
1901 * 1898 *
1902 * A PostProcessor can be used to (incrementally) parse the data 1899 * A `struct MHD_PostProcessor` can be used to (incrementally) parse
1903 * portion of a POST request. Note that some buggy browsers fail to 1900 * the data portion of a POST request. Note that some buggy browsers
1904 * set the encoding type. If you want to support those, you may have 1901 * fail to set the encoding type. If you want to support those, you
1905 * to call #MHD_set_connection_value with the proper encoding type 1902 * may have to call #MHD_set_connection_value with the proper encoding
1906 * before creating a post processor (if no supported encoding type is 1903 * type before creating a post processor (if no supported encoding
1907 * set, this function will fail). 1904 * type is set, this function will fail).
1908 * 1905 *
1909 * @param connection the connection on which the POST is 1906 * @param connection the connection on which the POST is
1910 * happening (used to determine the POST format) 1907 * happening (used to determine the POST format)
@@ -1929,9 +1926,9 @@ MHD_create_post_processor (struct MHD_Connection *connection,
1929 1926
1930/** 1927/**
1931 * Parse and process POST data. Call this function when POST data is 1928 * Parse and process POST data. Call this function when POST data is
1932 * available (usually during an MHD_AccessHandlerCallback) with the 1929 * available (usually during an #MHD_AccessHandlerCallback) with the
1933 * upload_data and upload_data_size. Whenever possible, this will 1930 * "upload_data" and "upload_data_size". Whenever possible, this will
1934 * then cause calls to the MHD_IncrementalKeyValueIterator. 1931 * then cause calls to the #MHD_IncrementalKeyValueIterator.
1935 * 1932 *
1936 * @param pp the post processor 1933 * @param pp the post processor
1937 * @param post_data @a post_data_len bytes of POST data 1934 * @param post_data @a post_data_len bytes of POST data
@@ -2038,6 +2035,7 @@ char *
2038MHD_basic_auth_get_username_password (struct MHD_Connection *connection, 2035MHD_basic_auth_get_username_password (struct MHD_Connection *connection,
2039 char** password); 2036 char** password);
2040 2037
2038
2041/** 2039/**
2042 * Queues a response to request basic authentication from the client 2040 * Queues a response to request basic authentication from the client
2043 * The given response object is expected to include the payload for 2041 * The given response object is expected to include the payload for
@@ -2057,86 +2055,34 @@ MHD_queue_basic_auth_fail_response (struct MHD_Connection *connection,
2057 2055
2058/* ********************** generic query functions ********************** */ 2056/* ********************** generic query functions ********************** */
2059 2057
2060/**
2061 * Information about a connection.
2062 */
2063union MHD_ConnectionInfo
2064{
2065
2066 /**
2067 * Cipher algorithm used, of type "enum gnutls_cipher_algorithm".
2068 * @ingroup tls
2069 */
2070 int /* enum gnutls_cipher_algorithm */ cipher_algorithm;
2071
2072 /**
2073 * Protocol used, of type "enum gnutls_protocol".
2074 * @ingroup tls
2075 */
2076 int /* enum gnutls_protocol */ protocol;
2077
2078 /**
2079 * Connect socket
2080 * @ingroup networking
2081 */
2082 int connect_fd;
2083
2084 /**
2085 * GNUtls session handle, of type "gnutls_session_t".
2086 * @ingroup tls
2087 */
2088 void * /* gnutls_session_t */ tls_session;
2089
2090 /**
2091 * GNUtls client certificate handle, of type "gnutls_x509_crt_t".
2092 * @ingroup tls
2093 */
2094 void * /* gnutls_x509_crt_t */ client_cert;
2095
2096 /**
2097 * Address information for the client.
2098 * @ingroup networking
2099 */
2100 struct sockaddr *client_addr;
2101
2102 /**
2103 * Which daemon manages this connection (useful in case there are many
2104 * daemons running).
2105 * @ingroup specialized
2106 */
2107 struct MHD_Daemon *daemon;
2108};
2109
2110 2058
2111/** 2059/**
2112 * Obtain information about the given connection. 2060 * Obtain information about the given connection.
2113 * 2061 *
2114 * @param connection what connection to get information about 2062 * @param connection what connection to get information about
2115 * @param infoType what information is desired? 2063 * @param info_type what information is desired?
2116 * @param ... depends on infoType 2064 * @param ... depends on @a info_type
2117 * @return NULL if this information is not available 2065 * @return NULL if this information is not available
2118 * (or if the infoType is unknown) 2066 * (or if the @a info_type is unknown)
2119 * @ingroup specialized 2067 * @ingroup specialized
2120 */ 2068 */
2121const union MHD_ConnectionInfo * 2069const union MHD_ConnectionInfo *
2122MHD_get_connection_info (struct MHD_Connection *connection, 2070MHD_get_connection_info (struct MHD_Connection *connection,
2123 enum MHD_ConnectionInfoType infoType, 2071 enum MHD_ConnectionInfoType info_type,
2124 ...); 2072 ...);
2125 2073
2126 2074
2127/** 2075/**
2128 * MHD connection options. Given to #MHD_set_connection_option to 2076 * MHD connection options. Given to #MHD_set_connection_option to
2129 * set custom options for a particular connection. 2077 * set custom options for a particular connection.
2130 * @ingroup specialized
2131 */ 2078 */
2132enum MHD_CONNECTION_OPTION 2079enum MHD_CONNECTION_OPTION
2133{ 2080{
2134 2081
2135 /** 2082 /**
2136 * Set a custom timeout for the given connection. Specified 2083 * Set a custom timeout for the given connection. Specified
2137 * as the number of seconds, given as an 'unsigned int'. Use 2084 * as the number of seconds, given as an `unsigned int`. Use
2138 * zero for no timeout. 2085 * zero for no timeout.
2139 * @ingroup limits
2140 */ 2086 */
2141 MHD_CONNECTION_OPTION_TIMEOUT 2087 MHD_CONNECTION_OPTION_TIMEOUT
2142 2088
@@ -2160,25 +2106,23 @@ MHD_set_connection_option (struct MHD_Connection *connection,
2160 2106
2161/** 2107/**
2162 * Information about an MHD daemon. 2108 * Information about an MHD daemon.
2163 * @ingroup specialized
2164 */ 2109 */
2165union MHD_DaemonInfo 2110union MHD_DaemonInfo
2166{ 2111{
2167 /** 2112 /**
2168 * Size of the key (unit??) 2113 * Size of the key.
2169 * @ingroup tls 2114 * @deprecated
2170 */ 2115 */
2171 size_t key_size; 2116 size_t key_size;
2172 2117
2173 /** 2118 /**
2174 * Size of the mac key (unit??) 2119 * Size of the mac key.
2175 * @ingroup tls 2120 * @deprecated
2176 */ 2121 */
2177 size_t mac_key_size; 2122 size_t mac_key_size;
2178 2123
2179 /** 2124 /**
2180 * Listen socket file descriptor 2125 * Listen socket file descriptor
2181 * @ingroup networking
2182 */ 2126 */
2183 int listen_fd; 2127 int listen_fd;
2184}; 2128};
@@ -2189,15 +2133,15 @@ union MHD_DaemonInfo
2189 * (not fully implemented!). 2133 * (not fully implemented!).
2190 * 2134 *
2191 * @param daemon what daemon to get information about 2135 * @param daemon what daemon to get information about
2192 * @param infoType what information is desired? 2136 * @param info_type what information is desired?
2193 * @param ... depends on infoType 2137 * @param ... depends on @a info_type
2194 * @return NULL if this information is not available 2138 * @return NULL if this information is not available
2195 * (or if the infoType is unknown) 2139 * (or if the @a info_type is unknown)
2196 * @ingroup specialized 2140 * @ingroup specialized
2197 */ 2141 */
2198const union MHD_DaemonInfo * 2142const union MHD_DaemonInfo *
2199MHD_get_daemon_info (struct MHD_Daemon *daemon, 2143MHD_get_daemon_info (struct MHD_Daemon *daemon,
2200 enum MHD_DaemonInfoType infoType, 2144 enum MHD_DaemonInfoType info_type,
2201 ...); 2145 ...);
2202 2146
2203 2147