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