daemon_options.inc (39666B)
1 @node libmicrohttpd-daemon-workmode 2 @section Configuring the work mode 3 4 The work mode option determines how MHD should process connections 5 concurrently. The work mode is set by providing a @code{struct 6 MHD_WorkModeWithParam} that includes the various configuration 7 settings for the work mode. While @code{MHD_D_OPTION_WORK_MODE} can in 8 principle be used to set the work mode, the MHD API offers various 9 convenience APIs for each of the work modes. 10 11 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_WORK_MODE (struct MHD_WorkModeWithParam wmp) 12 13 Set MHD work (threading and polling) mode. 14 Consider use of @code{MHD_D_OPTION_WM_EXTERNAL_PERIODIC()}, 15 @code{MHD_D_OPTION_WM_EXTERNAL_EVENT_LOOP_CB_LEVEL()}, 16 @code{MHD_D_OPTION_WM_EXTERNAL_EVENT_LOOP_CB_EDGE()}, 17 @code{MHD_D_OPTION_WM_EXTERNAL_SINGLE_FD_WATCH()}, 18 @code{MHD_D_OPTION_WM_WORKER_THREADS()} or 19 @code{MHD_D_OPTION_WM_THREAD_PER_CONNECTION()} 20 instead of direct use of this option. 21 22 @table @var 23 24 @item wmp 25 the work mode setting, to be created by either @code{MHD_WM_OPTION_EXTERNAL_PERIODIC()}, @code{MHD_WM_OPTION_EXTERNAL_EVENT_LOOP_CB_LEVEL()}, @code{MHD_WM_OPTION_EXTERNAL_EVENT_LOOP_CB_EDGE()}, @code{MHD_WM_OPTION_EXTERNAL_SINGLE_FD_WATCH()}, @code{MHD_WM_OPTION_WORKER_THREADS()}, or @code{MHD_WM_OPTION_THREAD_PER_CONNECTION()}. 26 27 @end table 28 29 Returns the option to pass to @code{MHD_daemon_set_options()}. 30 @end deftypefun 31 32 As explained, the usual way to set the work mode is to use one of 33 the following convenience APIs instead of using 34 @code{MHD_D_OPTION_WORK_MODE()} directly. We will thus describe 35 each work mode together with the option used to set it. 36 37 @node libmicrohttpd-daemon-workmode-external-periodic 38 @subsection External periodic 39 40 In this mode, the application must periodical call 41 @code{MHD_daemon_process_blocking()}, where MHD internally checks all 42 sockets automatically. This is the default mode. It is the simplest 43 to use, but also inefficient as it requires busy-waiting by the 44 application. 45 46 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_WM_EXTERNAL_PERIODIC() 47 48 Create parameter for @code{MHD_daemon_set_options()} for work mode with 49 no internal threads and no support for event loops. 50 Returns an object of type @code{struct MHD_DaemonOptionAndValue} 51 with the requested settings. 52 53 @end deftypefun 54 55 When using this mode, it is critical that the application 56 frequently calls @code{MHD_daemon_process_blocking()}. 57 58 @anchor{MHD_daemon_process_blocking} 59 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_daemon_process_blocking (struct MHD_Daemon *daemon, uint_fast64_t microsec) 60 61 Run the websever operation with possible blocking. 62 63 Supported only in @code{MHD_WM_EXTERNAL_PERIODIC} mode. 64 65 This function does the following: waits for any network event not more 66 than specified number of microseconds, processes all incoming and 67 outgoing data, processes new connections, processes any timed-out 68 connection, and does other things required to run the webserver. Once all 69 connections are processed, the function returns. 70 71 This function is useful for quick and simple (lazy) webserver 72 implementation if an application needs to run only a single thread and 73 does not even have an event loop. 74 75 @table @var 76 77 @item daemon 78 the daemon to run 79 80 @item microsec 81 the maximum time in microseconds to wait for network and other 82 events. Theere is no guarantee that function blocks for the specified 83 amount of time. The real processing time can be shorter (if some data 84 or connection timeout comes earlier) or longer (if data processing 85 requires more time, especially in user callbacks). If set to '0' then 86 function does not block and processes only already available data (if 87 any). If set to @code{MHD_WAIT_INDEFINITELY}, this function waits for 88 events indefinitely (blocks until next network activity or connection 89 timeout). 90 91 @end table 92 93 Returns @code{MHD_SC_OK} on success, otherwise an error code. 94 @end deftypefun 95 96 97 98 99 @node libmicrohttpd-daemon-workmode-external-event-loop 100 @subsection External event loop 101 102 In this mode, the application must provide a callback to 103 MHD where MHD will inform the application about network events 104 it cares about. The application must then call 105 @ref{MHD_daemon_event_update,,@code{MHD_daemon_event_update()}} 106 and @ref{MHD_daemon_process_nonblocking,,@code{MHD_daemon_process_nonblocking()}} 107 to drive MHD's network interaction. 108 109 @anchor{MHD_D_OPTION_WM_EXTERNAL_EVENT_LOOP_CB_LEVEL} 110 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_WM_EXTERNAL_EVENT_LOOP_CB_LEVEL(MHD_SocketRegistrationUpdateCallback cb_val, void *cb_cls_val) 111 112 Create parameter for @code{MHD_daemon_set_options()} for work mode with 113 an external event loop with level triggers. 114 115 @table @var 116 117 @item cb_val 118 callback implemented by the application to learn about MHD's needs; 119 120 @item cb_cls_val 121 closure argument for @var{cb_val}; 122 123 @end table 124 125 Returns an object of type @code{struct MHD_DaemonOptionAndValue} 126 with the requested settings. 127 128 @end deftypefun 129 130 @anchor{MHD_D_OPTION_WM_EXTERNAL_EVENT_LOOP_CB_EDGE} 131 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_WM_EXTERNAL_EVENT_LOOP_CB_EDGE(MHD_SocketRegistrationUpdateCallback cb_val, void *cb_cls_val) 132 133 Create parameter for @code{MHD_daemon_set_options()} for work mode with 134 an external event loop with edge triggers. 135 136 @table @var 137 138 @item cb_val 139 callback implemented by the application to learn about MHD's needs; 140 141 @item cb_cls_val 142 closure argument for @var{cb_val}; 143 144 @end table 145 146 Returns an object of type @code{struct MHD_DaemonOptionAndValue} 147 with the requested settings. 148 149 @end deftypefun 150 151 How to use an external event loop is described in detail 152 in another chapter of this manual. 153 @xref{libmicrohttpd2-external,,Using external event loops}. 154 155 156 @node libmicrohttpd-daemon-workmode-external-single-fd 157 @subsection External single FD watch 158 159 160 @anchor{MHD_D_OPTION_WM_EXTERNAL_SINGLE_FD_WATCH} 161 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_WM_EXTERNAL_SINGLE_FD_WATCH() 162 163 Create parameter for @code{MHD_daemon_set_options()} to create a work 164 mode with no internal threads and an aggregate watch file descriptor (FD). 165 When using this setting, applications @emph{must} use 166 @ref{MHD_DAEMON_INFO_FIXED_AGGREGATE_FD,,@code{MHD_DAEMON_INFO_FIXED_AGGREGATE_FD}} 167 to get the single FD that gets triggered by any MHD event. This FD can 168 be watched as an aggregate indicator for all MHD events. This mode is 169 available only on selected platforms (currently GNU/Linux 170 only). @xref{MHD_LIB_INFO_FIXED_HAS_AGGREGATE_FD,,@code{MHD_LIB_INFO_FIXED_HAS_AGGREGATE_FD}}. When the FD is 171 triggered, @code{MHD_daemon_process_nonblocking()} should be called as 172 soon as possible by the application. 173 174 Returns an object of type @code{struct MHD_DaemonOptionAndValue} 175 with the requested settings. 176 @end deftypefun 177 178 @anchor{MHD_daemon_process_nonblocking} 179 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_daemon_process_nonblocking (struct MHD_Daemon *daemon) 180 181 Run the websever operation without blocking. 182 183 Supported only in @code{MHD_WM_EXTERNAL_SINGLE_FD_WATCH} mode. 184 185 This function does the following: checks for any network events that 186 are ready, processes all incoming and outgoing data, processes new 187 connections, processes any timed-out connection, and does other things 188 required to run the webserver. Once all network events have been 189 processed, the function immediately returns. 190 191 @table @var 192 193 @item daemon 194 the daemon to run; 195 196 @end table 197 198 Returns @code{MHD_SC_OK} on success, otherwise an error code. 199 @end deftypefun 200 201 202 203 @node libmicrohttpd-daemon-workmode-worker-threads 204 @subsection Worker threads 205 206 207 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_WM_WORKER_THREADS(unsigned int num_workers) 208 209 Create parameter for @code{MHD_daemon_set_options()} for work mode 210 with @var{num_workers} internal worker threads that each listen for 211 incoming connections and handle multiple clients. If number of 212 threads is one, then daemon starts with single worker thread that 213 handles all connections. If number of threads is larger than one, 214 then handling of connections is distributed among the workers. 215 216 217 @table @var 218 219 @item num_workers 220 the number of worker threads, zero is treated as one; 221 222 @end table 223 224 Returns an object of type @code{struct MHD_DaemonOptionAndValue} 225 with the requested settings. 226 227 @end deftypefun 228 229 @node libmicrohttpd-daemon-workmode-thread-per-connection 230 @subsection Thread per connection 231 232 233 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_WM_THREAD_PER_CONNECTION() 234 235 Create parameter for @code{MHD_daemon_set_options()} for work mode 236 one internal thread for listening, and additional internal threads per 237 connection. Use this if handling requests is CPU-intensive or blocking, 238 our application is thread-safe and you have plenty of memory (per 239 connection) as each thread requires its own stack. 240 Applications using this mode should strongly consider using 241 @ref{MHD_D_OPTION_GLOBAL_CONNECTION_LIMIT,,@code{MHD_D_OPTION_GLOBAL_CONNECTION_LIMIT}}. 242 243 Returns an object of type @code{struct MHD_DaemonOptionAndValue} 244 with the requested settings. 245 246 @end deftypefun 247 248 249 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_POLL_SYSCALL (enum MHD_SockPollSyscall els) 250 251 Select a sockets watch system call to be used for internal polling. 252 253 @table @var 254 255 @item els 256 mode to use; @code{MHD_SPS_AUTO} is the default if this 257 option is not set. @xref{MHD_SockPollSyscall} 258 259 @end table 260 261 Returns the option to pass to @code{MHD_daemon_set_options()} 262 @end deftypefun 263 264 @anchor{MHD_SockPollSyscall} 265 @deftp {Enumeration} MHD_SockPollSyscall 266 267 Possible ways for sockets polling for internal syscalls. 268 269 @table @code 270 271 @item MHD_SPS_AUTO 272 Automatic selection of the best-available method. This is also the 273 default. 274 275 @item MHD_SPS_SELECT 276 Force use of @code{select()}. 277 278 @item MHD_SPS_POLL 279 Force use of @code{poll()}. 280 281 @item MHD_SPS_EPOLL 282 Force use of @code{epoll()}. 283 @end table 284 @end deftp 285 286 287 @node libmicrohttpd-daemon-logging 288 @section Configuring logging and notifications 289 290 Options in this section allow an application to receive notifications 291 from MHD whenever the library's logic reaches a particular stage. This 292 includes general logging, but also daemons, connecitons or requests 293 reaching a particular stage of their respective lifecycle. 294 295 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_LOG_CALLBACK (MHD_LoggingCallback log_cb, void *log_cb_cls) 296 297 Set a callback to use for logging. 298 299 @table @var 300 301 @item log_cb 302 the callback to use for logging, 303 @code{NULL} to disable logging. 304 Logging to @code{stderr} is enabled by default; 305 306 @item log_cb_cls 307 the closure for the logging callback; 308 309 @end table 310 311 Returns the option to pass to @code{MHD_daemon_set_options()}. 312 @end deftypefun 313 314 315 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_EARLY_URI_LOGGER (MHD_EarlyUriLogCallback cb, void *cb_cls) 316 317 Set a callback to be called first for every request when the request line is received (before any parsing of the header). 318 This callback is the only way to get raw (unmodified) request URI as URI is parsed and modified by MHD in-place. 319 Mandatory URI modification may apply before this call, like binary zero replacement, as required by RFCs. 320 321 @table @var 322 323 @item cb 324 the early URI callback; 325 326 @item cb_cls 327 the closure for the callback; 328 329 @end table 330 331 Returns the option to pass to @code{MHD_daemon_set_options()}. 332 @end deftypefun 333 334 335 @anchor{MHD_EarlyUriLogCallback} 336 @deftypefn {Function Pointer} void (*MHD_EarlyUriLogCallback) (void *cls, const struct MHD_EarlyUriCbData *req_data, void **request_app_context_ptr) 337 338 Function called by MHD to allow the application to log the full URI of any new request. 339 This is the only moment when unmodified URI is provided. 340 After this callback MHD parses the URI and modifies it by extracting 341 URL arguments in-place. 342 343 If this callback is set then it is the first application function called 344 for every new request. 345 346 If a @ref{MHD_RequestEndedCallback} is also set then it is guaranteed 347 that @ref{MHD_RequestEndedCallback} is called for the same request 348 eventually. Application may allocate request specific data in this 349 callback and de-allocate the data in @ref{MHD_RequestEndedCallback}. 350 351 @table @var 352 @item cls 353 custom value provided by the application at callback registration time; 354 355 @item req_data 356 data about the client's request; 357 358 @item request_app_contex_ptr 359 pointer to a location that can be set to 360 an application context for the request; 361 initially the location is guaranteed to 362 point to @code{NULL}; 363 364 @end table 365 @end deftypefn 366 367 The @var{req_data} provides the following information 368 about the request: 369 370 371 @anchor{MHD_EarlyUriCbData} 372 @deftp {C Struct} struct MHD_EarlyUriCbData 373 374 Data for @ref{MHD_EarlyUriLogCallback}s. 375 376 @table @var 377 378 @item @code{struct MHD_Request *} request 379 The request handle. 380 Headers will not yet be available. 381 382 @item @code{struct MHD_String} full_uri 383 The full URI ("request target") from the HTTP request, including URI parameters (the part after '?'). 384 385 @item @code{enum MHD_HTTP_Method} method 386 The HTTP method of the request; 387 388 @end table 389 @end deftp 390 391 392 393 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_DAEMON_READY_CALLBACK (MHD_DaemonReadyCallback cb, void *cb_cls) 394 395 Set a callback to be called for pre-start finalisation. 396 397 The specified callback will be called one time, after network initialisation, TLS pre-initialisation, but before the start of the internal threads (if allowed) 398 399 @table @var 400 401 @item cb 402 the pre-start callback; 403 404 @item cb_cls 405 the closure for the callback; 406 407 @end table 408 409 Returns the option to pass to @code{MHD_daemon_set_options()}. 410 @end deftypefun 411 412 @anchor{MHD_DaemonReadyCallback} 413 @deftypefn {Function Pointer} void (*MHD_DaemonReadyCallback) (void *cls) 414 415 The specified callback will be called one time, 416 after network initialisation, TLS pre-initialisation, but before 417 the start of the internal threads (if we have any). 418 419 This callback may use introspection call to retrieve and adjust some 420 of the daemon's aspects. For example, the TLS backend handle could be 421 obtained via introspection and used to configure some additional 422 TLS-backend specific settings. 423 424 @table @var 425 @item cls 426 custom value provided by the application at callback registration time; 427 428 @end table 429 430 @end deftypefn 431 432 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_NOTIFY_CONNECTION (MHD_NotifyConnectionCallback ncc, void *ncc_cls) 433 434 Set a function that should be called whenever a connection is started or closed. 435 436 @table @var 437 438 @item ncc 439 the callback for notifications; 440 441 @item cls 442 the closure for the callback; 443 444 @end table 445 446 Returns the option to pass to @code{MHD_daemon_set_options()}. 447 @end deftypefun 448 449 450 @anchor{MHD_NotifyConnectionCallback} 451 @deftypefn {Function Pointer} void (*MHD_NotifyConnectionCallback) (void *cls, struct MHD_ConnectionNotificationData *data) 452 @c FIXME: why is 'data' not const? 453 @c FIXME: non-uniform: for requests, we have the 454 @c application context in the argument, here we have it 455 @c inside of data; not nice! 456 457 458 @table @var 459 @item cls 460 custom value provided by the application at callback registration time; 461 462 @item data 463 details about the connection; 464 465 @end table 466 467 @end deftypefn 468 469 @c FIXME: elaborate on MHD_ConnectionNotificationData 470 @c FIXME: but only after we revised it! 471 472 @c FIXME: elaborate on MHD_ConnectionNotificationCode 473 474 @anchor{MHD_ConnectionNotificationDetails} 475 @deftp {C Union} struct MHD_ConnectionNotificationDetails 476 477 @var{code}-specific details on how a request ended. 478 So far not used, only a placeholder. 479 480 @table @var 481 482 @item @code{void *} reserved 483 Placeholder. Do not used. 484 485 @end table 486 @end deftp 487 488 489 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_NOTIFY_STREAM (MHD_NotifyStreamCallback nsc, void *nsc_cls) 490 491 Register a function that should be called whenever a stream is started or closed. 492 For HTTP/1.1 this callback is called one time for every connection. 493 494 @table @var 495 496 @item nsc 497 the callback for notifications; 498 499 @item nsc_cls 500 the closure for the callback; 501 502 @end table 503 504 Returns the option to pass to @code{MHD_daemon_set_options()}. 505 @end deftypefun 506 507 508 @anchor{MHD_NotifyStreamCallback} 509 @deftypefn {Function Pointer} void (*MHD_NotifyStreamCallback) (void *cls, const struct MHD_StreamNotificationData *data) 510 @c FIXME: non-uniform: for requests and connections, we have an 511 @c application context in the argument, here have none! 512 513 514 @table @var 515 @item cls 516 custom value provided by the application at callback registration time; 517 518 @item data 519 details about the stream; 520 521 @end table 522 523 @end deftypefn 524 525 526 @anchor{MHD_StreamNotificationData} 527 @deftp {C Struct} struct MHD_StreamNotificationData 528 529 Data for functions of type @ref{MHD_NotifyStreamCallback}. 530 531 @table @var 532 533 @item @code{struct MHD_Stream *} stream 534 The stream handle; 535 536 @item @code{enum MHD_StreamNotificationCode} code 537 The code of the event; 538 539 @item @code{union MHD_StreamNotificationDetail} details 540 Detailed information about the event the notification is about; 541 542 @end table 543 @end deftp 544 545 546 @anchor{MHD_StreamNotificationCode} 547 @deftp {Enumeration} MHD_StreamNotificationCode 548 549 Type of stream notifications. 550 551 @table @code 552 553 @c FIXME: rename to OPENED? more symmetric! 554 @item MHD_STREAM_NOTIFY_STARTED 555 A new stream has been started. 556 557 @item MHD_STREAM_NOTIFY_CLOSED 558 A stream is being closed. 559 560 @end table 561 @end deftp 562 563 @c FIXME: ealborate on MHD_StreamNotificationDetail 564 @c FIXME: strongly consider inlining the started structure... 565 566 567 @node libmicrohttpd-daemon-listen 568 @section Configuring the listen socket 569 570 The options in this section determine how MHD will listen 571 for incoming connections. MHD can either be told to 572 open its own listen socket (in which case the application 573 must specify the address family and port, or the complete 574 socket address), or MHD can be given a listen socket that 575 is already pre-configured (for example, if systemd socket 576 activation is used). It is even possible to run MHD without 577 a listen socket, and only give it the (already accepted) 578 connections from clients. Note that these are mutually 579 exclusive choices, as a single daemon only ever uses a 580 single listen socket. 581 582 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_BIND_PORT (enum MHD_AddressFamily af, uint_least16_t port) 583 584 Bind to the given TCP port and address family. 585 586 Does not work with @code{MHD_D_OPTION_BIND_SA()} or 587 @code{MHD_D_OPTION_LISTEN_SOCKET()}. 588 589 If no listen socket options (@code{MHD_D_OPTION_BIND_PORT()}, @code{MHD_D_OPTION_BIND_SA()}, or @code{MHD_D_OPTION_LISTEN_SOCKET()}) are used, MHD does not listen for incoming connections. 590 591 @table @var 592 593 @item af 594 the address family to use, 595 Use the special @code{MHD_AF_NONE} to disable the listen socket (the same effect as if this option is not used). 596 597 @item port 598 port to use, 0 to let system assign any free port, 599 ignored if @var{af} is @code{MHD_AF_NONE} 600 601 @end table 602 603 Returns the option to pass to @code{MHD_daemon_set_options()}. 604 @end deftypefun 605 606 @deftp {Enumeration} MHD_AddressFamily 607 608 Address family to be used by MHD. 609 610 @table @code 611 612 @item MHD_AF_NONE 613 Option not given. Do not listen at all 614 (unless listen socket or address specified by 615 other means). 616 617 @item MHD_AF_AUTO 618 Pick "best" available method automatically. 619 620 @item MHD_AF_INET4 621 Use IPv4 only. 622 623 @item MHD_AF_INET6 624 Use IPv6 only. 625 626 @item MHD_AF_DUAL 627 Use dual stack (IPv4 and IPv6 on the same socket). 628 629 @item MHD_AF_DUAL_v4_OPTIONAL 630 Use dual stack (IPv4 and IPv6 on the same socket), 631 fallback to pure IPv6 if dual stack is not possible. 632 633 @item MHD_AF_DUAL_v6_OPTIONAL 634 Use dual stack (IPv4 and IPv6 on the same socket), 635 fallback to pure IPv4 if dual stack is not possible. 636 637 @end table 638 @end deftp 639 640 641 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_BIND_SA (size_t sa_len, const struct sockaddr *sa, enum MHD_Bool dual) 642 643 Bind to the given socket address. 644 645 Does not work in combination with @code{MHD_D_OPTION_BIND_PORT()} or @code{MHD_D_OPTION_LISTEN_SOCKET()}. 646 647 If no listen socket options (@code{MHD_D_OPTION_BIND_PORT()}, @code{MHD_D_OPTION_BIND_SA()}, or @code{MHD_D_OPTION_LISTEN_SOCKET()}) are used, MHD does not listen for incoming connections. 648 649 @table @var 650 651 @item sa_len 652 the size of the socket address pointed by @var{sa}. 653 654 @item sa 655 the address to bind to; can be IPv4 (AF_INET), IPv6 (AF_INET6) or even a UNIX domain socket (AF_UNIX) 656 657 @item dual 658 When a previous version of the protocol exists (like IPv4 when @var{v_sa} is IPv6) bind to both protocols (IPv6 and IPv4). 659 660 @end table 661 662 Returns the option to pass to @code{MHD_daemon_set_options()}. 663 @end deftypefun 664 665 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_LISTEN_SOCKET (MHD_Socket listen_fd) 666 667 Accept connections from the given socket. Socket 668 must be a TCP or UNIX domain (SOCK_STREAM) socket. 669 670 Does not work in combination with @code{MHD_D_OPTION_BIND_PORT()} or 671 @code{MHD_D_OPTION_BIND_SA()}. 672 673 If no listen socket options (@code{MHD_D_OPTION_BIND_PORT()}, @code{MHD_D_OPTION_BIND_SA()}, or @code{MHD_D_OPTION_LISTEN_SOCKET()}) are used, MHD does not listen for incoming connections. 674 675 @table @var 676 677 @item listen_fd 678 the listen socket to use, ignored if set to @code{MHD_INVALID_SOCKET}. 679 680 @end table 681 682 Returns the option to pass to @code{MHD_daemon_set_options()}. 683 @end deftypefun 684 685 686 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_LISTEN_ADDR_REUSE (enum MHD_DaemonOptionBindType reuse_type) 687 688 Select mode of reusing address:port listen address. 689 690 Works only when @code{MHD_D_OPTION_BIND_PORT()} or 691 @code{MHD_D_OPTION_BIND_SA()} are also used. 692 693 @table @var 694 695 @item reuse_type 696 address reuse options to use 697 698 @end table 699 700 Returns the option to pass to @code{MHD_daemon_set_options()}. 701 @end deftypefun 702 703 @anchor{MHD_DaemonOptionBindType} 704 @deftp {Enumeration} MHD_DaemonOptionBindType 705 706 Parameter for listen socket binding type. Determines what should 707 happen if multiple processes try to bind to the same port. 708 709 @table @code 710 711 @item MHD_D_OPTION_BIND_TYPE_SHARED 712 The listen socket binds to the networks address with sharing the address. 713 Several sockets can bind to the same address. 714 715 @item MHD_D_OPTION_BIND_TYPE_NOT_SHARED 716 The listen socket binds to the networks address without sharing the 717 address, except allowing binding to port/address which is only in 718 TIME_WAIT state (the state after closing connection). On some 719 platforms it may also allow to bind to specific address if other 720 socket already bound to the same port of wildcard address (or bind to 721 wildcard address when other socket already bond to specific address 722 with the same port). Typically achieved by enabling the 723 @code{SO_REUSEADDR} socket option. This is the default. 724 725 @item MHD_D_OPTION_BIND_TYPE_NOT_SHARED_STRICTER 726 The listen socket binds to the networks address without sharing the 727 address. The daemon way fail to start when any sockets still in 728 TIME_WAIT state on the same port, which effectively prevents quick 729 restart of the daemon on the same port. On W32 systems this option 730 works like @code{MHD_D_OPTION_BIND_TYPE_NOT_SHARED} due to OS 731 limitations. 732 733 @item MHD_D_OPTION_BIND_TYPE_EXCLUSIVE 734 The list socket binds to the networks address in explicit exclusive 735 mode. Works as @code{MHD_D_OPTION_BIND_TYPE_NOT_SHARED_STRICTER} on 736 platforms without support for the explicit exclusive socket use. 737 738 @end table 739 @end deftp 740 741 742 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_TCP_FASTOPEN (enum MHD_TCPFastOpenType option, unsigned int queue_length) 743 744 Configure TCP_FASTOPEN option, including setting a 745 custom @var{queue_length}. 746 747 Note that having a larger queue size can cause resource exhaustion 748 attack as the TCP stack has to now allocate resources for the SYN 749 packet along with its DATA. 750 751 Works only in combination with @code{MHD_D_OPTION_BIND_PORT()} or @code{MHD_D_OPTION_BIND_SA()}. 752 753 @table @var 754 755 @item option 756 the type use of of TCP FastOpen; @xref{MHD_TCPFastOpenType} 757 758 @item queue_length 759 the length of the queue, zero to use system or MHD default, 760 silently ignored on platforms without support for custom queue size. 761 762 @end table 763 764 Returns the option to pass to @code{MHD_daemon_set_options()}. 765 @end deftypefun 766 767 768 @anchor{MHD_TCPFastOpenType} 769 @deftp {Enumeration} MHD_TCPFastOpenType 770 771 Possible levels of support or enforcement for TCP_FASTOPEN. 772 773 @table @code 774 @item MHD_FOM_DISABLE 775 Disable use of TCP_FASTOPEN. 776 777 @item MHD_FOM_AUTO 778 Enable TCP_FASTOPEN where supported. 779 On GNU/Linux it works with a kernel >= 3.6. 780 This is the default. 781 782 @item MHD_FOM_REQUIRE 783 Require support for TCP_FASTOPEN. 784 This causes @code{MHD_daemon_start()} to fail 785 if TCP_FASTOPEN cannot be enabled! 786 787 @end table 788 @end deftp 789 790 791 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_LISTEN_BACKLOG (unsigned int backlog_size) 792 793 Use the given backlog for the @code{listen()} call. 794 795 Works only when @code{MHD_D_OPTION_BIND_PORT()} 796 or @code{MHD_D_OPTION_BIND_SA()} are used. 797 798 @table @var 799 800 @item backlog_size 801 Backlog to use. A value of zero implies to use MHD/system defaults. 802 803 @end table 804 805 Returns the option to pass to @code{MHD_daemon_set_options()}. 806 @end deftypefun 807 808 809 810 @node libmicrohttpd-daemon-tls 811 @section Configuring TLS 812 813 The following options can be used to configure 814 MHD to use TLS, turning an HTTP server into an 815 HTTPS server. 816 817 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_TLS (enum MHD_TlsBackend backend) 818 819 Enable TLS (HTTPS) and select TLS backend 820 821 @table @var 822 823 @item backend 824 the TLS backend to use, 825 @code{MHD_TLS_BACKEND_NONE} for non-TLS (plain TCP) connections 826 827 @end table 828 829 Returns the option to pass to @code{MHD_daemon_set_options()} 830 @end deftypefun 831 832 @c FIXME: const is commented out in C API!? 833 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_TLS_CERT_KEY (const char *mem_cert, const char *mem_key, const char *mem_pass) 834 835 Provide TLS key and certificate data in-memory. 836 Works only if TLS mode is enabled. 837 838 @table @var 839 840 @item mem_cert 841 The X.509 certificates chain in PEM format loaded into memory (not a filename). 842 The first certificate must be the server certificate, following by the chain of signing 843 certificates up to (but not including) CA root certificate. 844 845 @item mem_key 846 the private key in PEM format loaded into memory (not a filename) 847 848 @item mem_pass 849 the option passphrase phrase to decrypt the private key, 850 could be NULL if private key does not need a password 851 852 @end table 853 854 Returns the option to pass to @code{MHD_daemon_set_options()}. 855 @end deftypefun 856 857 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_TLS_CLIENT_CA (const char *mem_client_ca) 858 859 Provide the certificate of the certificate authority (CA) to be used by the MHD daemon for client authentication. 860 Works only if TLS mode is enabled. 861 862 @table @var 863 864 @item mem_client_ca 865 the CA certificate in memory (not a filename) 866 867 @end table 868 869 Returns the option to pass to @code{MHD_daemon_set_options()}. 870 @end deftypefun 871 872 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_TLS_PSK_CALLBACK (MHD_PskServerCredentialsCallback psk_cb, void *psk_cb_cls) 873 874 Configure PSK to use for the TLS key exchange. 875 876 @table @var 877 878 @item psk_cb 879 the function to call to obtain pre-shared key 880 881 @item psk_cb_cls 882 the closure for @var{psk_cb} 883 884 @end table 885 886 Returns the option to pass to @code{MHD_daemon_set_options()}. 887 @end deftypefun 888 889 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_NO_ALPN () 890 891 Control ALPN for TLS connection. 892 If this option is set but TLS is not enabled overall, 893 it is silently ignored (does not cause a failure). 894 By default ALPN is automatically used for TLS connections. 895 896 Returns the option to pass to @code{MHD_daemon_set_options()}. 897 @end deftypefun 898 899 900 @node libmicrohttpd-daemon-authentication 901 @section Configuring HTTP authentication 902 903 @c FIXME: const commented out in C API!? 904 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_RANDOM_ENTROPY (size_t buf_size, const void *buf) 905 906 Set strong random data to be used by MHD. 907 Currently the data is only used for digest authentication. 908 @c FIXME: is it NOT enabled if the option is not set? Unclear english! 909 Daemon support for digest authentication is enabled automatically when this option is used. 910 The recommended size is 32 bytes. 911 Sizes larger then 32 bytes are unlikely to increase 912 security (assuming a strong random number generator was 913 used to create @var{buf}). 914 915 @table @var 916 917 @item buf_size 918 the size of the buffer 919 920 @item buf 921 the buffer with strong random data, the content will be copied by MHD 922 923 @end table 924 925 Returns the option to pass to @code{MHD_daemon_set_options()} 926 @end deftypefun 927 928 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_AUTH_DIGEST_MAP_SIZE (size_t size) 929 930 Specify the size of the internal hash map array that tracks generated digest nonces usage. 931 When the size of the map is too small then need to handle concurrent digest authentication requests, many false-positive stale nonce responses might be produced. 932 By default, the digest nonce hash map size is 1000 entries. 933 934 @table @var 935 936 @item size 937 the size of the map array 938 939 @end table 940 941 Returns the option to pass to @code{MHD_daemon_set_options()}. 942 @end deftypefun 943 944 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_AUTH_DIGEST_NONCE_TIMEOUT (unsigned int timeout) 945 946 Configure nonce validity period for nonces used with HTTP digest 947 authentication. 948 949 @table @var 950 951 @item timeout 952 Validity period (in seconds) to apply for the nonces used in 953 digest authentication. 954 955 @end table 956 957 Returns the option to pass to @code{MHD_daemon_set_options()}. 958 @end deftypefun 959 960 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_AUTH_DIGEST_DEF_MAX_NC (uint_fast32_t max_nc) 961 962 Default maximum nonce counter (nc) value used ford digest authentication. 963 @xref{MHD_digest_auth_check_digest}. 964 965 @table @var 966 967 @item max_nc 968 Maximum nonce counter allowed. Zero is ignored. 969 970 @end table 971 972 Returns the option to pass to @code{MHD_daemon_set_options()}. 973 @end deftypefun 974 975 976 @node libmicrohttpd-daemon-limits 977 @section Configuring resource limits 978 979 This section is about daemon configuration options that 980 enable applications to configure resource limits. Setting 981 resource limits can help ensure that MHD does not use 982 too many resources, but also ensure that MHD uses enough 983 resources for optimum performance. 984 985 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_DEFAULT_TIMEOUT (unsigned int timeout) 986 987 Specify inactivity timeout for connection. 988 When no activity for specified time on connection, it is closed automatically. 989 Use zero for no timeout, which is also the (insecure!) default. It is highly recommended to set a non-zero timeout to ensure connections are not kept open forever. 990 991 @table @var 992 993 @item timeout 994 the in seconds, zero for no timeout 995 996 @end table 997 998 Returns the option to pass to @code{MHD_daemon_set_options()}. 999 @end deftypefun 1000 1001 @anchor{MHD_D_OPTION_GLOBAL_CONNECTION_LIMIT} 1002 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_GLOBAL_CONNECTION_LIMIT (unsigned int glob_limit) 1003 1004 Sets the maximum number of (concurrent) network connections served by the daemon. 1005 1006 @table @var 1007 1008 @item glob_limit 1009 Limit to apply. The real maximum number of network connections could 1010 still be smaller than requested due to the system limitations, 1011 like @code{FD_SETSIZE} when polling via @code{select()} is used. 1012 1013 @end table 1014 1015 Returns the option to pass to @code{MHD_daemon_set_options()}. 1016 @end deftypefun 1017 1018 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_PER_IP_LIMIT (unsigned int limit) 1019 1020 Sets a limit on the number of (concurrent) network connections made to the server from the same IP address. 1021 Can be used to prevent one IP from taking over all of the allowed connections. If the same IP tries to establish more than the specified number of connections, they will be immediately rejected. 1022 1023 @table @var 1024 1025 @item limit 1026 Connection limit to use. 0 for no limit. 1027 @c FIXME: 0 = no limit is correct? 1028 1029 @end table 1030 1031 Returns the option to pass to @code{MHD_daemon_set_options()}. 1032 @end deftypefun 1033 1034 1035 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_ACCEPT_POLICY (MHD_AcceptPolicyCallback apc, void *apc_cls) 1036 1037 Set a policy callback that accepts/rejects connections based on the client's IP address. The callbeck function will be called before servicing any new incoming connection. 1038 1039 @table @var 1040 1041 @item apc 1042 the accept policy callback 1043 1044 @item apc_cls 1045 the closure for the callback 1046 1047 @end table 1048 1049 Returns the option to pass to @code{MHD_daemon_set_options()} 1050 @end deftypefun 1051 1052 1053 @anchor{MHD_AcceptPolicyCallback} 1054 @deftypefn {Function Pointer} {enum MHD_Bool} (*MHD_AcceptPolicyCallback)(void *cls, size_t addr_len, const struct sockaddr *addr) 1055 1056 Allow or deny a client to connect. 1057 1058 @table @var 1059 1060 @item cls 1061 closure value provided by the application when registering 1062 the callback 1063 1064 @item addr_len 1065 length of @var{addr} 1066 1067 @item addr 1068 address information from the client 1069 1070 @end table 1071 The function must return @code{MHD_YES} if 1072 the connection should be allowed, and 1073 @code{MHD_NO} if it should be denied.\ 1074 @end deftypefn 1075 1076 1077 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_PROTOCOL_STRICT_LEVEL (enum MHD_ProtocolStrictLevel sl, enum MHD_UseStictLevel how) 1078 1079 Set how strictly MHD will enforce the HTTP protocol. 1080 1081 @table @var 1082 1083 @item sl 1084 the level of strictness 1085 1086 @item how 1087 the way how to use the requested level 1088 1089 @end table 1090 1091 Returns the option to pass to @code{MHD_daemon_set_options()} 1092 @end deftypefun 1093 1094 @c FIXME: define MHD_ProtocolStrictLevel 1095 @c FIXME: define MHD_UseStrictLevel 1096 1097 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_CONN_MEMORY_LIMIT (size_t value) 1098 1099 The default limit is only 32kb per connection. Applications should be 1100 careful to make sure that the given limit is large enough to fit all 1101 request headers (together with internal parsing information). Half of 1102 the memory will typically be used for I/O buffers. On embedded 1103 platforms, values above 128kb are unlikely to result in significant 1104 performance benefits as TCP buffers are unlikely to support window 1105 sizes above 64k on embedded systems. 1106 1107 @table @var 1108 1109 @item value 1110 Maximum memory size per connection in bytes. 1111 1112 @end table 1113 1114 Returns the option to pass to @code{MHD_daemon_set_options()}. 1115 @end deftypefun 1116 1117 @anchor{shared memory pool} 1118 @anchor{MHD_D_OPTION_LARGE_POOL_SIZE} 1119 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_LARGE_POOL_SIZE (size_t value) 1120 1121 The size of the shared memory pool for accumulated upload processing. 1122 The same large pool is shared for all connections server by MHD and used when application requests avoiding of incremental upload processing to accumulate complete content upload before giving it to the application. 1123 Default is 8Mb. 1124 Can be set to zero to disable use of the shared pool. 1125 1126 @table @var 1127 1128 @item value 1129 Size of the large memory pool in bytes. 1130 1131 @end table 1132 1133 Returns the option to pass to @code{MHD_daemon_set_options()}. 1134 @end deftypefun 1135 1136 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_STACK_SIZE () 1137 1138 Desired size of the stack for the threads started by MHD. 1139 Use 0 to use the operating system's default stack size, which is also the default value used by MHD. 1140 Works only with 1141 @code{MHD_D_OPTION_WM_WORKER_THREADS()} or 1142 @code{MHD_D_OPTION_WM_THREAD_PER_CONNECTION()}. 1143 1144 Returns the option to pass to @code{MHD_daemon_set_options()} 1145 @end deftypefun 1146 1147 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_FD_NUMBER_LIMIT (MHD_Socket max_fd) 1148 1149 The the maximum FD value. 1150 The limit is applied to all sockets used by MHD. 1151 If the listen socket FD is equal to or higher then the specified value, the daemon fail to start. 1152 If a new connection's FD is equal to or higher then the specified value, the connection is rejected. 1153 If an application uses @code{select()} for polling sockets, 1154 the system's @code{FD_SETSIZE} is a good value for this option. 1155 Silently ignored on W32 (WinSock sockets are not integers). 1156 1157 @table @var 1158 1159 @item max_fd 1160 Maximum file descriptor to allow (exclusive). 1161 @c FIXME: it is exclusive, right? 1162 1163 @end table 1164 1165 Returns the option to pass to @code{MHD_daemon_set_options()}. 1166 @end deftypefun 1167 1168 1169 1170 1171 1172 @node libmicrohttpd-daemon-performance 1173 @section Performance tuning options 1174 1175 1176 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_TURBO () 1177 1178 Enable `turbo`. 1179 Disables certain calls to @code{shutdown()}, enables aggressive non-blocking optimistic reads and other potentially unsafe optimisations. 1180 Most effects only happen with internal threads with @code{epoll()}. 1181 The 'turbo' mode is disabled by default. 1182 1183 Returns the option to pass to @code{MHD_daemon_set_options()}. 1184 @end deftypefun 1185 1186 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_DISABLE_THREAD_SAFETY () 1187 1188 Disable some internal thread safety. 1189 Indicates that MHD daemon will be used by application in single-threaded mode only. When this flag is set then application must call any MHD function only within a single thread. 1190 This flag turns off some internal thread-safety and allows MHD making some of the internal optimisations suitable only for single-threaded environments. 1191 Not compatible with any internal threads modes. 1192 If MHD is compiled with custom configuration for embedded projects without threads support, this option is mandatory. 1193 Thread safety is enabled by default. 1194 1195 Returns the option to pass to @code{MHD_daemon_set_options()}. 1196 @end deftypefun 1197 1198 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_DISALLOW_UPGRADE () 1199 1200 You need to set this option if you want to disable use of HTTP Upgrade. 1201 Upgrade may require usage of additional internal resources, which MHD can avoid allocating if they will not be used. 1202 You should only use this option if you do not use upgrade functionality and need a generally minor boost in performance and resources savings. 1203 HTTP upgrade is allowed by default. 1204 1205 Returns the option to pass to @code{MHD_daemon_set_options()}. 1206 @end deftypefun 1207 1208 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_DISALLOW_SUSPEND_RESUME () 1209 1210 Disable @ref{MHD_action_suspend,,@code{MHD_action_suspend()}} functionality. 1211 1212 You should only use this function if you do not use suspend functionality and need a generally minor boost in performance. 1213 Suspending requests is allowed by default. 1214 1215 Returns the option to pass to @code{MHD_daemon_set_options()} 1216 @end deftypefun 1217 1218 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_DISABLE_COOKIES () 1219 1220 Disable cookies parsing. 1221 1222 Disable automatic cookies processing if cookies are not used. 1223 Cookies are automatically parsed by default. 1224 1225 Returns the option to pass to @code{MHD_daemon_set_options()} 1226 @end deftypefun 1227 1228 1229 1230 1231 @node libmicrohttpd-daemon-other 1232 @section Other daemon options 1233 1234 1235 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_SIGPIPE_SUPPRESSED () 1236 1237 Inform that SIGPIPE is suppressed or handled by application. 1238 If suppressed/handled, MHD uses network functions that could generate SIGPIPE, like @code{sendfile()}. 1239 Silently ignored when MHD creates internal threads as for them SIGPIPE is suppressed automatically. 1240 1241 Returns the option to pass to @code{MHD_daemon_set_options()}. 1242 @end deftypefun 1243 1244 1245 1246 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_DISABLE_URI_QUERY_PLUS_AS_SPACE () 1247 1248 Disable converting plus ('+') character to space in URL arguments (URL part after '?'). 1249 Plus conversion is not required by HTTP RFCs, however it required by HTML specifications, see https://url.spec.whatwg.org/#application/x-www-form-urlencoded for details. 1250 By default plus is converted to space in the query part of a URL. 1251 1252 Returns the option to pass to @code{MHD_daemon_set_options()}. 1253 @end deftypefun 1254 1255 @cindex real-time clock 1256 @anchor{MHD_D_OPTION_SUPPRESS_DATE_HEADER} 1257 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_SUPPRESS_DATE_HEADER () 1258 1259 Suppresse use of 'Date:' header. 1260 According to RFC should be suppressed only if the system has no real-time clock (RTC). 1261 The 'Date:' is not suppressed (the header is enabled) by default. 1262 1263 Returns the option to pass to @code{MHD_daemon_set_options()}. 1264 @end deftypefun 1265 1266 @cindex Shoutcast 1267 @deftypefun {struct MHD_DaemonOptionAndValue} MHD_D_OPTION_ENABLE_SHOUTCAST () 1268 1269 Use SHOUTcast for responses. 1270 This will cause @emph{all} responses to begin with the SHOUTcast 'ICY' line instead of 'HTTP'. 1271 1272 Returns the option to pass to @code{MHD_daemon_set_options()}. 1273 @end deftypefun