GNU libmicrohttpd  0.9.5
microhttpd.h
Go to the documentation of this file.
1 /*
2  This file is part of libmicrohttpd
3  (C) 2006, 2007, 2008, 2009, 2010, 2011 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 
72 #ifndef MHD_MICROHTTPD_H
73 #define MHD_MICROHTTPD_H
74 
75 #ifdef __cplusplus
76 extern "C"
77 {
78 #if 0 /* keep Emacsens' auto-indent happy */
79 }
80 #endif
81 #endif
82 
83 /* While we generally would like users to use a configure-driven
84  build process which detects which headers are present and
85  hence works on any platform, we use "standard" includes here
86  to build out-of-the-box for beginning users on common systems.
87 
88  Once you have a proper build system and go for more exotic
89  platforms, you should define MHD_PLATFORM_H in some header that
90  you always include *before* "microhttpd.h". Then the following
91  "standard" includes won't be used (which might be a good
92  idea, especially on platforms where they do not exist). */
93 #ifndef MHD_PLATFORM_H
94 #include <unistd.h>
95 #include <stdarg.h>
96 #include <stdint.h>
97 #ifdef __MINGW32__
98 #include <ws2tcpip.h>
99 #else
100 #include <sys/time.h>
101 #include <sys/types.h>
102 #include <sys/socket.h>
103 #endif
104 #endif
105 
109 #define MHD_VERSION 0x00092104
110 
114 #define MHD_YES 1
115 
119 #define MHD_NO 0
120 
124 #define MHD_INVALID_NONCE -1
125 
130 #ifdef UINT64_MAX
131 #define MHD_SIZE_UNKNOWN UINT64_MAX
132 #else
133 #define MHD_SIZE_UNKNOWN ((uint64_t) -1LL)
134 #endif
135 
136 #ifdef SIZE_MAX
137 #define MHD_CONTENT_READER_END_OF_STREAM SIZE_MAX
138 #define MHD_CONTENT_READER_END_WITH_ERROR (SIZE_MAX - 1)
139 #else
140 #define MHD_CONTENT_READER_END_OF_STREAM ((size_t) -1LL)
141 #define MHD_CONTENT_READER_END_WITH_ERROR (((size_t) -1LL) - 1)
142 #endif
143 
149 #ifndef MHD_LONG_LONG
150 
153 #define MHD_LONG_LONG long long
154 #define MHD_UNSIGNED_LONG_LONG unsigned long long
155 #endif
156 
160 #ifndef MHD_LONG_LONG_PRINTF
161 
164 #define MHD_LONG_LONG_PRINTF "ll"
165 #define MHD_UNSIGNED_LONG_LONG_PRINTF "%llu"
166 #endif
167 
168 
172 #define MHD_HTTP_CONTINUE 100
173 #define MHD_HTTP_SWITCHING_PROTOCOLS 101
174 #define MHD_HTTP_PROCESSING 102
175 
176 #define MHD_HTTP_OK 200
177 #define MHD_HTTP_CREATED 201
178 #define MHD_HTTP_ACCEPTED 202
179 #define MHD_HTTP_NON_AUTHORITATIVE_INFORMATION 203
180 #define MHD_HTTP_NO_CONTENT 204
181 #define MHD_HTTP_RESET_CONTENT 205
182 #define MHD_HTTP_PARTIAL_CONTENT 206
183 #define MHD_HTTP_MULTI_STATUS 207
184 
185 #define MHD_HTTP_MULTIPLE_CHOICES 300
186 #define MHD_HTTP_MOVED_PERMANENTLY 301
187 #define MHD_HTTP_FOUND 302
188 #define MHD_HTTP_SEE_OTHER 303
189 #define MHD_HTTP_NOT_MODIFIED 304
190 #define MHD_HTTP_USE_PROXY 305
191 #define MHD_HTTP_SWITCH_PROXY 306
192 #define MHD_HTTP_TEMPORARY_REDIRECT 307
193 
194 #define MHD_HTTP_BAD_REQUEST 400
195 #define MHD_HTTP_UNAUTHORIZED 401
196 #define MHD_HTTP_PAYMENT_REQUIRED 402
197 #define MHD_HTTP_FORBIDDEN 403
198 #define MHD_HTTP_NOT_FOUND 404
199 #define MHD_HTTP_METHOD_NOT_ALLOWED 405
200 #define MHD_HTTP_METHOD_NOT_ACCEPTABLE 406
201 #define MHD_HTTP_PROXY_AUTHENTICATION_REQUIRED 407
202 #define MHD_HTTP_REQUEST_TIMEOUT 408
203 #define MHD_HTTP_CONFLICT 409
204 #define MHD_HTTP_GONE 410
205 #define MHD_HTTP_LENGTH_REQUIRED 411
206 #define MHD_HTTP_PRECONDITION_FAILED 412
207 #define MHD_HTTP_REQUEST_ENTITY_TOO_LARGE 413
208 #define MHD_HTTP_REQUEST_URI_TOO_LONG 414
209 #define MHD_HTTP_UNSUPPORTED_MEDIA_TYPE 415
210 #define MHD_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE 416
211 #define MHD_HTTP_EXPECTATION_FAILED 417
212 #define MHD_HTTP_UNPROCESSABLE_ENTITY 422
213 #define MHD_HTTP_LOCKED 423
214 #define MHD_HTTP_FAILED_DEPENDENCY 424
215 #define MHD_HTTP_UNORDERED_COLLECTION 425
216 #define MHD_HTTP_UPGRADE_REQUIRED 426
217 #define MHD_HTTP_NO_RESPONSE 444
218 #define MHD_HTTP_RETRY_WITH 449
219 #define MHD_HTTP_BLOCKED_BY_WINDOWS_PARENTAL_CONTROLS 450
220 #define MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS 451
221 
222 #define MHD_HTTP_INTERNAL_SERVER_ERROR 500
223 #define MHD_HTTP_NOT_IMPLEMENTED 501
224 #define MHD_HTTP_BAD_GATEWAY 502
225 #define MHD_HTTP_SERVICE_UNAVAILABLE 503
226 #define MHD_HTTP_GATEWAY_TIMEOUT 504
227 #define MHD_HTTP_HTTP_VERSION_NOT_SUPPORTED 505
228 #define MHD_HTTP_VARIANT_ALSO_NEGOTIATES 506
229 #define MHD_HTTP_INSUFFICIENT_STORAGE 507
230 #define MHD_HTTP_BANDWIDTH_LIMIT_EXCEEDED 509
231 #define MHD_HTTP_NOT_EXTENDED 510
232 
238 #define MHD_ICY_FLAG ((uint32_t)(1 << 31))
239 
240 /* See also: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html */
241 #define MHD_HTTP_HEADER_ACCEPT "Accept"
242 #define MHD_HTTP_HEADER_ACCEPT_CHARSET "Accept-Charset"
243 #define MHD_HTTP_HEADER_ACCEPT_ENCODING "Accept-Encoding"
244 #define MHD_HTTP_HEADER_ACCEPT_LANGUAGE "Accept-Language"
245 #define MHD_HTTP_HEADER_ACCEPT_RANGES "Accept-Ranges"
246 #define MHD_HTTP_HEADER_AGE "Age"
247 #define MHD_HTTP_HEADER_ALLOW "Allow"
248 #define MHD_HTTP_HEADER_AUTHORIZATION "Authorization"
249 #define MHD_HTTP_HEADER_CACHE_CONTROL "Cache-Control"
250 #define MHD_HTTP_HEADER_CONNECTION "Connection"
251 #define MHD_HTTP_HEADER_CONTENT_ENCODING "Content-Encoding"
252 #define MHD_HTTP_HEADER_CONTENT_LANGUAGE "Content-Language"
253 #define MHD_HTTP_HEADER_CONTENT_LENGTH "Content-Length"
254 #define MHD_HTTP_HEADER_CONTENT_LOCATION "Content-Location"
255 #define MHD_HTTP_HEADER_CONTENT_MD5 "Content-MD5"
256 #define MHD_HTTP_HEADER_CONTENT_RANGE "Content-Range"
257 #define MHD_HTTP_HEADER_CONTENT_TYPE "Content-Type"
258 #define MHD_HTTP_HEADER_COOKIE "Cookie"
259 #define MHD_HTTP_HEADER_DATE "Date"
260 #define MHD_HTTP_HEADER_ETAG "ETag"
261 #define MHD_HTTP_HEADER_EXPECT "Expect"
262 #define MHD_HTTP_HEADER_EXPIRES "Expires"
263 #define MHD_HTTP_HEADER_FROM "From"
264 #define MHD_HTTP_HEADER_HOST "Host"
265 #define MHD_HTTP_HEADER_IF_MATCH "If-Match"
266 #define MHD_HTTP_HEADER_IF_MODIFIED_SINCE "If-Modified-Since"
267 #define MHD_HTTP_HEADER_IF_NONE_MATCH "If-None-Match"
268 #define MHD_HTTP_HEADER_IF_RANGE "If-Range"
269 #define MHD_HTTP_HEADER_IF_UNMODIFIED_SINCE "If-Unmodified-Since"
270 #define MHD_HTTP_HEADER_LAST_MODIFIED "Last-Modified"
271 #define MHD_HTTP_HEADER_LOCATION "Location"
272 #define MHD_HTTP_HEADER_MAX_FORWARDS "Max-Forwards"
273 #define MHD_HTTP_HEADER_PRAGMA "Pragma"
274 #define MHD_HTTP_HEADER_PROXY_AUTHENTICATE "Proxy-Authenticate"
275 #define MHD_HTTP_HEADER_PROXY_AUTHORIZATION "Proxy-Authorization"
276 #define MHD_HTTP_HEADER_RANGE "Range"
277 /* This is not a typo, see HTTP spec */
278 #define MHD_HTTP_HEADER_REFERER "Referer"
279 #define MHD_HTTP_HEADER_RETRY_AFTER "Retry-After"
280 #define MHD_HTTP_HEADER_SERVER "Server"
281 #define MHD_HTTP_HEADER_SET_COOKIE "Set-Cookie"
282 #define MHD_HTTP_HEADER_SET_COOKIE2 "Set-Cookie2"
283 #define MHD_HTTP_HEADER_TE "TE"
284 #define MHD_HTTP_HEADER_TRAILER "Trailer"
285 #define MHD_HTTP_HEADER_TRANSFER_ENCODING "Transfer-Encoding"
286 #define MHD_HTTP_HEADER_UPGRADE "Upgrade"
287 #define MHD_HTTP_HEADER_USER_AGENT "User-Agent"
288 #define MHD_HTTP_HEADER_VARY "Vary"
289 #define MHD_HTTP_HEADER_VIA "Via"
290 #define MHD_HTTP_HEADER_WARNING "Warning"
291 #define MHD_HTTP_HEADER_WWW_AUTHENTICATE "WWW-Authenticate"
292 
297 #define MHD_HTTP_VERSION_1_0 "HTTP/1.0"
298 #define MHD_HTTP_VERSION_1_1 "HTTP/1.1"
299 
303 #define MHD_HTTP_METHOD_CONNECT "CONNECT"
304 #define MHD_HTTP_METHOD_DELETE "DELETE"
305 #define MHD_HTTP_METHOD_GET "GET"
306 #define MHD_HTTP_METHOD_HEAD "HEAD"
307 #define MHD_HTTP_METHOD_OPTIONS "OPTIONS"
308 #define MHD_HTTP_METHOD_POST "POST"
309 #define MHD_HTTP_METHOD_PUT "PUT"
310 #define MHD_HTTP_METHOD_TRACE "TRACE"
311 
316 #define MHD_HTTP_POST_ENCODING_FORM_URLENCODED "application/x-www-form-urlencoded"
317 #define MHD_HTTP_POST_ENCODING_MULTIPART_FORMDATA "multipart/form-data"
318 
330 {
335 
342 
347 
352 
357 
366 
377 
386 
391 
399 
408 
415 
422 
435 
440 
446 
447 };
448 
449 
457 typedef void (*MHD_LogCallback)(void *cls, const char *fm, va_list ap);
458 
459 
464 {
465 
471 
480 
486 
493 
507 
519 
526 
549 
557 
565 
572 
578 
586 
601 
611 
632 
652 
663 
670 
676 
683 
689 };
690 
691 
696 {
702 
708  intptr_t value;
709 
714  void *ptr_value;
715 
716 };
717 
718 
724 {
725 
730 
735 
741 
751 
756 
761 };
762 
763 
769 {
770 
775 
782 
789 
795 
804 
805 };
806 
807 
813 {
819 
825 
833 
838 
846 
851 
852 
858 
859 };
860 
861 
867 {
876 
885 
891 
897 };
898 
899 
903 struct MHD_Daemon;
904 
911 struct MHD_Connection;
912 
916 struct MHD_Response;
917 
921 struct MHD_PostProcessor;
922 
923 
933 typedef
934  void (*MHD_PanicCallback) (void *cls,
935  const char *file,
936  unsigned int line,
937  const char *reason);
938 
946 typedef int
948  const struct sockaddr *addr,
949  socklen_t addrlen);
950 
951 
987 typedef int
989  struct MHD_Connection * connection,
990  const char *url,
991  const char *method,
992  const char *version,
993  const char *upload_data,
994  size_t *upload_data_size,
995  void **con_cls);
996 
997 
1009 typedef void
1011  struct MHD_Connection *connection,
1012  void **con_cls,
1013  enum MHD_RequestTerminationCode toe);
1014 
1015 
1026 typedef int
1027  (*MHD_KeyValueIterator) (void *cls,
1028  enum MHD_ValueKind kind,
1029  const char *key, const char *value);
1030 
1031 
1079 typedef ssize_t
1081  uint64_t pos,
1082  char *buf,
1083  size_t max);
1084 
1085 
1092 typedef void
1094 
1095 
1115 typedef int
1116  (*MHD_PostDataIterator) (void *cls,
1117  enum MHD_ValueKind kind,
1118  const char *key,
1119  const char *filename,
1120  const char *content_type,
1121  const char *transfer_encoding,
1122  const char *data,
1123  uint64_t off,
1124  size_t size);
1125 
1126 /* **************** Daemon handling functions ***************** */
1127 
1144 struct MHD_Daemon *
1145 MHD_start_daemon_va (unsigned int flags,
1146  uint16_t port,
1147  MHD_AcceptPolicyCallback apc, void *apc_cls,
1148  MHD_AccessHandlerCallback dh, void *dh_cls,
1149  va_list ap);
1150 
1151 
1167 struct MHD_Daemon *
1168 MHD_start_daemon (unsigned int flags,
1169  uint16_t port,
1170  MHD_AcceptPolicyCallback apc, void *apc_cls,
1171  MHD_AccessHandlerCallback dh, void *dh_cls,
1172  ...);
1173 
1174 
1193 int
1194 MHD_quiesce_daemon (struct MHD_Daemon *daemon);
1195 
1196 
1202 void
1203 MHD_stop_daemon (struct MHD_Daemon *daemon);
1204 
1205 
1227 int
1228 MHD_add_connection (struct MHD_Daemon *daemon,
1229  int client_socket,
1230  const struct sockaddr *addr,
1231  socklen_t addrlen);
1232 
1233 
1247 int
1248 MHD_get_fdset (struct MHD_Daemon *daemon,
1249  fd_set *read_fd_set,
1250  fd_set *write_fd_set,
1251  fd_set *except_fd_set,
1252  int *max_fd);
1253 
1254 
1268 int MHD_get_timeout (struct MHD_Daemon *daemon,
1269  MHD_UNSIGNED_LONG_LONG *timeout);
1270 
1271 
1291 int
1292 MHD_run (struct MHD_Daemon *daemon);
1293 
1294 
1313 int
1314 MHD_run_from_select (struct MHD_Daemon *daemon,
1315  const fd_set *read_fd_set,
1316  const fd_set *write_fd_set,
1317  const fd_set *except_fd_set);
1318 
1319 
1320 
1321 
1322 /* **************** Connection handling functions ***************** */
1323 
1334 int
1335 MHD_get_connection_values (struct MHD_Connection *connection,
1336  enum MHD_ValueKind kind,
1337  MHD_KeyValueIterator iterator, void *iterator_cls);
1338 
1339 
1369 int
1370 MHD_set_connection_value (struct MHD_Connection *connection,
1371  enum MHD_ValueKind kind,
1372  const char *key,
1373  const char *value);
1374 
1375 
1391 void
1392 MHD_set_panic_func (MHD_PanicCallback cb, void *cls);
1393 
1394 
1404 const char *
1405 MHD_lookup_connection_value (struct MHD_Connection *connection,
1406  enum MHD_ValueKind kind,
1407  const char *key);
1408 
1409 
1420 int
1421 MHD_queue_response (struct MHD_Connection *connection,
1422  unsigned int status_code,
1423  struct MHD_Response *response);
1424 
1425 
1426 /* **************** Response manipulation functions ***************** */
1427 
1443 struct MHD_Response *
1444 MHD_create_response_from_callback (uint64_t size,
1445  size_t block_size,
1446  MHD_ContentReaderCallback crc, void *crc_cls,
1448 
1449 
1463 struct MHD_Response *
1464 MHD_create_response_from_data (size_t size,
1465  void *data,
1466  int must_free,
1467  int must_copy);
1468 
1469 
1475 
1482 
1489 
1497 
1498 };
1499 
1500 
1510 struct MHD_Response *
1511 MHD_create_response_from_buffer (size_t size,
1512  void *buffer,
1513  enum MHD_ResponseMemoryMode mode);
1514 
1515 
1526 struct MHD_Response *
1527 MHD_create_response_from_fd (size_t size,
1528  int fd);
1529 
1530 
1546 struct MHD_Response *
1548  int fd,
1549  off_t offset);
1550 
1551 
1552 #if 0
1553 
1558 enum MHD_UpgradeEventMask
1559 {
1560 
1565  MHD_UPGRADE_EVENT_TERMINATE = 0,
1566 
1571  MHD_UPGRADE_EVENT_READ = 1,
1572 
1577  MHD_UPGRADE_EVENT_WRITE = 2,
1578 
1586  MHD_UPGRADE_EVENT_EXTERNAL = 4,
1587 
1595  MHD_UPGRADE_EVENT_CORK = 8
1596 
1597 };
1598 
1599 
1643 typedef enum MHD_UpgradeEventMask (*MHD_UpgradeHandler)(void *cls,
1644  struct MHD_Connection *connection,
1645  void **con_cls,
1646  size_t *data_in_size,
1647  const char *data_in,
1648  size_t *data_out_size,
1649  char *data_out);
1650 
1651 
1681 struct MHD_Response *
1682 MHD_create_response_for_upgrade (MHD_UpgradeHandler upgrade_handler,
1683  void *upgrade_handler_cls);
1684 #endif
1685 
1694 void MHD_destroy_response (struct MHD_Response *response);
1695 
1696 
1706 int
1707 MHD_add_response_header (struct MHD_Response *response,
1708  const char *header, const char *content);
1709 
1710 
1719 int
1720 MHD_add_response_footer (struct MHD_Response *response,
1721  const char *footer, const char *content);
1722 
1723 
1732 int
1733 MHD_del_response_header (struct MHD_Response *response,
1734  const char *header, const char *content);
1735 
1736 
1746 int
1747 MHD_get_response_headers (struct MHD_Response *response,
1748  MHD_KeyValueIterator iterator, void *iterator_cls);
1749 
1750 
1758 const char *MHD_get_response_header (struct MHD_Response *response,
1759  const char *key);
1760 
1761 
1762 /* ********************** PostProcessor functions ********************** */
1763 
1788 struct MHD_PostProcessor *
1789 MHD_create_post_processor (struct MHD_Connection *connection,
1790  size_t buffer_size,
1791  MHD_PostDataIterator iter, void *iter_cls);
1792 
1807 int
1808 MHD_post_process (struct MHD_PostProcessor *pp,
1809  const char *post_data, size_t post_data_len);
1810 
1820 int
1821 MHD_destroy_post_processor (struct MHD_PostProcessor *pp);
1822 
1823 
1824 /* ********************* Digest Authentication functions *************** */
1825 
1826 
1831 #define MHD_INVALID_NONCE -1
1832 
1833 
1841 char *
1842 MHD_digest_auth_get_username (struct MHD_Connection *connection);
1843 
1844 
1857 int
1858 MHD_digest_auth_check (struct MHD_Connection *connection,
1859  const char *realm,
1860  const char *username,
1861  const char *password,
1862  unsigned int nonce_timeout);
1863 
1864 
1878 int
1879 MHD_queue_auth_fail_response (struct MHD_Connection *connection,
1880  const char *realm,
1881  const char *opaque,
1882  struct MHD_Response *response,
1883  int signal_stale);
1884 
1885 
1894 char *
1895 MHD_basic_auth_get_username_password (struct MHD_Connection *connection,
1896  char** password);
1897 
1909 int
1910 MHD_queue_basic_auth_fail_response (struct MHD_Connection *connection,
1911  const char *realm,
1912  struct MHD_Response *response);
1913 
1914 /* ********************** generic query functions ********************** */
1915 
1920 {
1921 
1925  int /* enum gnutls_cipher_algorithm */ cipher_algorithm;
1926 
1930  int /* enum gnutls_protocol */ protocol;
1931 
1936 
1940  void * /* gnutls_session_t */ tls_session;
1941 
1945  void * /* gnutls_x509_crt_t */ client_cert;
1946 
1950  struct sockaddr *client_addr;
1951 
1956  struct MHD_Daemon *daemon;
1957 };
1958 
1968 const union MHD_ConnectionInfo *
1969 MHD_get_connection_info (struct MHD_Connection *connection,
1970  enum MHD_ConnectionInfoType infoType,
1971  ...);
1972 
1973 
1979 {
1980 
1987 
1988 };
1989 
1990 
1999 int
2000 MHD_set_connection_option (struct MHD_Connection *connection,
2001  enum MHD_CONNECTION_OPTION option,
2002  ...);
2003 
2004 
2009 {
2013  size_t key_size;
2014 
2019 
2024 };
2025 
2036 const union MHD_DaemonInfo *
2037 MHD_get_daemon_info (struct MHD_Daemon *daemon,
2038  enum MHD_DaemonInfoType infoType,
2039  ...);
2040 
2041 
2047 const char*
2048 MHD_get_version (void);
2049 
2050 #if 0 /* keep Emacsens' auto-indent happy */
2051 {
2052 #endif
2053 #ifdef __cplusplus
2054 }
2055 #endif
2056 
2057 #endif