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 0x00091600
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 #define MHD_LONG_LONG long long
151 #endif
152 #ifndef MHD_LONG_LONG_PRINTF
153 
157 #define MHD_LONG_LONG_PRINTF "ll"
158 #endif
159 
160 
164 #define MHD_HTTP_CONTINUE 100
165 #define MHD_HTTP_SWITCHING_PROTOCOLS 101
166 #define MHD_HTTP_PROCESSING 102
167 
168 #define MHD_HTTP_OK 200
169 #define MHD_HTTP_CREATED 201
170 #define MHD_HTTP_ACCEPTED 202
171 #define MHD_HTTP_NON_AUTHORITATIVE_INFORMATION 203
172 #define MHD_HTTP_NO_CONTENT 204
173 #define MHD_HTTP_RESET_CONTENT 205
174 #define MHD_HTTP_PARTIAL_CONTENT 206
175 #define MHD_HTTP_MULTI_STATUS 207
176 
177 #define MHD_HTTP_MULTIPLE_CHOICES 300
178 #define MHD_HTTP_MOVED_PERMANENTLY 301
179 #define MHD_HTTP_FOUND 302
180 #define MHD_HTTP_SEE_OTHER 303
181 #define MHD_HTTP_NOT_MODIFIED 304
182 #define MHD_HTTP_USE_PROXY 305
183 #define MHD_HTTP_SWITCH_PROXY 306
184 #define MHD_HTTP_TEMPORARY_REDIRECT 307
185 
186 #define MHD_HTTP_BAD_REQUEST 400
187 #define MHD_HTTP_UNAUTHORIZED 401
188 #define MHD_HTTP_PAYMENT_REQUIRED 402
189 #define MHD_HTTP_FORBIDDEN 403
190 #define MHD_HTTP_NOT_FOUND 404
191 #define MHD_HTTP_METHOD_NOT_ALLOWED 405
192 #define MHD_HTTP_METHOD_NOT_ACCEPTABLE 406
193 #define MHD_HTTP_PROXY_AUTHENTICATION_REQUIRED 407
194 #define MHD_HTTP_REQUEST_TIMEOUT 408
195 #define MHD_HTTP_CONFLICT 409
196 #define MHD_HTTP_GONE 410
197 #define MHD_HTTP_LENGTH_REQUIRED 411
198 #define MHD_HTTP_PRECONDITION_FAILED 412
199 #define MHD_HTTP_REQUEST_ENTITY_TOO_LARGE 413
200 #define MHD_HTTP_REQUEST_URI_TOO_LONG 414
201 #define MHD_HTTP_UNSUPPORTED_MEDIA_TYPE 415
202 #define MHD_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE 416
203 #define MHD_HTTP_EXPECTATION_FAILED 417
204 #define MHD_HTTP_UNPROCESSABLE_ENTITY 422
205 #define MHD_HTTP_LOCKED 423
206 #define MHD_HTTP_FAILED_DEPENDENCY 424
207 #define MHD_HTTP_UNORDERED_COLLECTION 425
208 #define MHD_HTTP_UPGRADE_REQUIRED 426
209 #define MHD_HTTP_NO_RESPONSE 444
210 #define MHD_HTTP_RETRY_WITH 449
211 #define MHD_HTTP_BLOCKED_BY_WINDOWS_PARENTAL_CONTROLS 450
212 #define MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS 451
213 
214 #define MHD_HTTP_INTERNAL_SERVER_ERROR 500
215 #define MHD_HTTP_NOT_IMPLEMENTED 501
216 #define MHD_HTTP_BAD_GATEWAY 502
217 #define MHD_HTTP_SERVICE_UNAVAILABLE 503
218 #define MHD_HTTP_GATEWAY_TIMEOUT 504
219 #define MHD_HTTP_HTTP_VERSION_NOT_SUPPORTED 505
220 #define MHD_HTTP_VARIANT_ALSO_NEGOTIATES 506
221 #define MHD_HTTP_INSUFFICIENT_STORAGE 507
222 #define MHD_HTTP_BANDWIDTH_LIMIT_EXCEEDED 509
223 #define MHD_HTTP_NOT_EXTENDED 510
224 
230 #define MHD_ICY_FLAG ((uint32_t)(1 << 31))
231 
232 /* See also: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html */
233 #define MHD_HTTP_HEADER_ACCEPT "Accept"
234 #define MHD_HTTP_HEADER_ACCEPT_CHARSET "Accept-Charset"
235 #define MHD_HTTP_HEADER_ACCEPT_ENCODING "Accept-Encoding"
236 #define MHD_HTTP_HEADER_ACCEPT_LANGUAGE "Accept-Language"
237 #define MHD_HTTP_HEADER_ACCEPT_RANGES "Accept-Ranges"
238 #define MHD_HTTP_HEADER_AGE "Age"
239 #define MHD_HTTP_HEADER_ALLOW "Allow"
240 #define MHD_HTTP_HEADER_AUTHORIZATION "Authorization"
241 #define MHD_HTTP_HEADER_CACHE_CONTROL "Cache-Control"
242 #define MHD_HTTP_HEADER_CONNECTION "Connection"
243 #define MHD_HTTP_HEADER_CONTENT_ENCODING "Content-Encoding"
244 #define MHD_HTTP_HEADER_CONTENT_LANGUAGE "Content-Language"
245 #define MHD_HTTP_HEADER_CONTENT_LENGTH "Content-Length"
246 #define MHD_HTTP_HEADER_CONTENT_LOCATION "Content-Location"
247 #define MHD_HTTP_HEADER_CONTENT_MD5 "Content-MD5"
248 #define MHD_HTTP_HEADER_CONTENT_RANGE "Content-Range"
249 #define MHD_HTTP_HEADER_CONTENT_TYPE "Content-Type"
250 #define MHD_HTTP_HEADER_COOKIE "Cookie"
251 #define MHD_HTTP_HEADER_DATE "Date"
252 #define MHD_HTTP_HEADER_ETAG "ETag"
253 #define MHD_HTTP_HEADER_EXPECT "Expect"
254 #define MHD_HTTP_HEADER_EXPIRES "Expires"
255 #define MHD_HTTP_HEADER_FROM "From"
256 #define MHD_HTTP_HEADER_HOST "Host"
257 #define MHD_HTTP_HEADER_IF_MATCH "If-Match"
258 #define MHD_HTTP_HEADER_IF_MODIFIED_SINCE "If-Modified-Since"
259 #define MHD_HTTP_HEADER_IF_NONE_MATCH "If-None-Match"
260 #define MHD_HTTP_HEADER_IF_RANGE "If-Range"
261 #define MHD_HTTP_HEADER_IF_UNMODIFIED_SINCE "If-Unmodified-Since"
262 #define MHD_HTTP_HEADER_LAST_MODIFIED "Last-Modified"
263 #define MHD_HTTP_HEADER_LOCATION "Location"
264 #define MHD_HTTP_HEADER_MAX_FORWARDS "Max-Forwards"
265 #define MHD_HTTP_HEADER_PRAGMA "Pragma"
266 #define MHD_HTTP_HEADER_PROXY_AUTHENTICATE "Proxy-Authenticate"
267 #define MHD_HTTP_HEADER_PROXY_AUTHORIZATION "Proxy-Authorization"
268 #define MHD_HTTP_HEADER_RANGE "Range"
269 #define MHD_HTTP_HEADER_REFERER "Referer"
270 #define MHD_HTTP_HEADER_RETRY_AFTER "Retry-After"
271 #define MHD_HTTP_HEADER_SERVER "Server"
272 #define MHD_HTTP_HEADER_SET_COOKIE "Set-Cookie"
273 #define MHD_HTTP_HEADER_SET_COOKIE2 "Set-Cookie2"
274 #define MHD_HTTP_HEADER_TE "TE"
275 #define MHD_HTTP_HEADER_TRAILER "Trailer"
276 #define MHD_HTTP_HEADER_TRANSFER_ENCODING "Transfer-Encoding"
277 #define MHD_HTTP_HEADER_UPGRADE "Upgrade"
278 #define MHD_HTTP_HEADER_USER_AGENT "User-Agent"
279 #define MHD_HTTP_HEADER_VARY "Vary"
280 #define MHD_HTTP_HEADER_VIA "Via"
281 #define MHD_HTTP_HEADER_WARNING "Warning"
282 #define MHD_HTTP_HEADER_WWW_AUTHENTICATE "WWW-Authenticate"
283 
288 #define MHD_HTTP_VERSION_1_0 "HTTP/1.0"
289 #define MHD_HTTP_VERSION_1_1 "HTTP/1.1"
290 
294 #define MHD_HTTP_METHOD_CONNECT "CONNECT"
295 #define MHD_HTTP_METHOD_DELETE "DELETE"
296 #define MHD_HTTP_METHOD_GET "GET"
297 #define MHD_HTTP_METHOD_HEAD "HEAD"
298 #define MHD_HTTP_METHOD_OPTIONS "OPTIONS"
299 #define MHD_HTTP_METHOD_POST "POST"
300 #define MHD_HTTP_METHOD_PUT "PUT"
301 #define MHD_HTTP_METHOD_TRACE "TRACE"
302 
307 #define MHD_HTTP_POST_ENCODING_FORM_URLENCODED "application/x-www-form-urlencoded"
308 #define MHD_HTTP_POST_ENCODING_MULTIPART_FORMDATA "multipart/form-data"
309 
321 {
326 
333 
338 
343 
348 
354 
365 
370 
378 
387 
388 };
389 
390 
395 {
396 
402 
408 
414 
421 
435 
447 
454 
477 
485 
493 
500 
506 
514 
528 
538 
559 
579 
590 
597 
603 
610 };
611 
612 
617 {
623 
629  intptr_t value;
630 
635  void *ptr_value;
636 
637 };
638 
639 
645 {
646 
651 
656 
662 
672 
677 
682 };
683 
684 
690 {
691 
696 
703 
710 
716 
725 
726 };
727 
728 
734 {
740 
746 
754 
759 
767 
772 
773 };
774 
775 
781 {
789 
797 
803 };
804 
805 
809 struct MHD_Daemon;
810 
817 struct MHD_Connection;
818 
822 struct MHD_Response;
823 
827 struct MHD_PostProcessor;
828 
829 
839 typedef
840  void (*MHD_PanicCallback) (void *cls,
841  const char *file,
842  unsigned int line,
843  const char *reason);
844 
852 typedef int
854  const struct sockaddr * addr,
855  socklen_t addrlen);
856 
857 
893 typedef int
895  struct MHD_Connection * connection,
896  const char *url,
897  const char *method,
898  const char *version,
899  const char *upload_data,
900  size_t *upload_data_size,
901  void **con_cls);
902 
903 
915 typedef void
917  struct MHD_Connection * connection,
918  void **con_cls,
919  enum MHD_RequestTerminationCode toe);
920 
921 
932 typedef int
933  (*MHD_KeyValueIterator) (void *cls,
934  enum MHD_ValueKind kind,
935  const char *key, const char *value);
936 
937 
985 typedef ssize_t
987  uint64_t pos,
988  char *buf,
989  size_t max);
990 
991 
998 typedef void
1000 
1001 
1021 typedef int
1022  (*MHD_PostDataIterator) (void *cls,
1023  enum MHD_ValueKind kind,
1024  const char *key,
1025  const char *filename,
1026  const char *content_type,
1027  const char *transfer_encoding,
1028  const char *data,
1029  uint64_t off,
1030  size_t size);
1031 
1032 /* **************** Daemon handling functions ***************** */
1033 
1050 struct MHD_Daemon *
1051 MHD_start_daemon_va (unsigned int options,
1052  uint16_t port,
1054  MHD_AccessHandlerCallback dh, void *dh_cls,
1055  va_list ap);
1056 
1057 
1073 struct MHD_Daemon *
1074 MHD_start_daemon (unsigned int flags,
1075  uint16_t port,
1077  MHD_AccessHandlerCallback dh, void *dh_cls,
1078  ...);
1079 
1080 
1086 void
1087 MHD_stop_daemon (struct MHD_Daemon *daemon);
1088 
1089 
1111 int
1112 MHD_add_connection (struct MHD_Daemon *daemon,
1113  int client_socket,
1114  const struct sockaddr *addr,
1115  socklen_t addrlen);
1116 
1117 
1131 int
1132 MHD_get_fdset (struct MHD_Daemon *daemon,
1133  fd_set *read_fd_set,
1134  fd_set *write_fd_set,
1135  fd_set *except_fd_set,
1136  int *max_fd);
1137 
1138 
1152 int MHD_get_timeout (struct MHD_Daemon *daemon,
1153  unsigned MHD_LONG_LONG *timeout);
1154 
1155 
1167 int
1168 MHD_run (struct MHD_Daemon *daemon);
1169 
1170 
1171 /* **************** Connection handling functions ***************** */
1172 
1183 int
1184 MHD_get_connection_values (struct MHD_Connection *connection,
1185  enum MHD_ValueKind kind,
1186  MHD_KeyValueIterator iterator, void *iterator_cls);
1187 
1188 
1218 int
1219 MHD_set_connection_value (struct MHD_Connection *connection,
1220  enum MHD_ValueKind kind,
1221  const char *key,
1222  const char *value);
1223 
1224 
1240 void
1241 MHD_set_panic_func (MHD_PanicCallback cb, void *cls);
1242 
1243 
1253 const char *
1254 MHD_lookup_connection_value (struct MHD_Connection *connection,
1255  enum MHD_ValueKind kind,
1256  const char *key);
1257 
1258 
1269 int
1270 MHD_queue_response (struct MHD_Connection *connection,
1271  unsigned int status_code,
1272  struct MHD_Response *response);
1273 
1274 
1275 /* **************** Response manipulation functions ***************** */
1276 
1292 struct MHD_Response *
1293 MHD_create_response_from_callback (uint64_t size,
1294  size_t block_size,
1297 
1298 
1312 struct MHD_Response *
1313 MHD_create_response_from_data (size_t size,
1314  void *data,
1315  int must_free,
1316  int must_copy);
1317 
1318 
1324 
1331 
1338 
1346 
1347 };
1348 
1349 
1359 struct MHD_Response *
1360 MHD_create_response_from_buffer (size_t size,
1361  void *buffer,
1362  enum MHD_ResponseMemoryMode mode);
1363 
1364 
1375 struct MHD_Response *
1376 MHD_create_response_from_fd (size_t size,
1377  int fd);
1378 
1379 
1395 struct MHD_Response *
1397  int fd,
1398  off_t offset);
1399 
1400 
1424 typedef void (*MHD_UpgradeHandler)(void *cls,
1425  struct MHD_Connection *connection,
1426  void **con_cls,
1427  int upgrade_socket);
1428 
1429 #if 0
1430 
1459 struct MHD_Response *
1460 MHD_create_response_for_upgrade (MHD_UpgradeHandler upgrade_handler,
1461  void *upgrade_handler_cls);
1462 #endif
1463 
1472 void MHD_destroy_response (struct MHD_Response *response);
1473 
1474 
1484 int
1485 MHD_add_response_header (struct MHD_Response *response,
1486  const char *header, const char *content);
1487 
1488 
1497 int
1498 MHD_add_response_footer (struct MHD_Response *response,
1499  const char *footer, const char *content);
1500 
1501 
1510 int
1511 MHD_del_response_header (struct MHD_Response *response,
1512  const char *header, const char *content);
1513 
1523 int
1524 MHD_get_response_headers (struct MHD_Response *response,
1525  MHD_KeyValueIterator iterator, void *iterator_cls);
1526 
1527 
1535 const char *MHD_get_response_header (struct MHD_Response *response,
1536  const char *key);
1537 
1538 
1539 /* ********************** PostProcessor functions ********************** */
1540 
1564 struct MHD_PostProcessor *
1565 MHD_create_post_processor (struct MHD_Connection *connection,
1566  size_t buffer_size,
1567  MHD_PostDataIterator iter, void *cls);
1568 
1583 int
1584 MHD_post_process (struct MHD_PostProcessor *pp,
1585  const char *post_data, size_t post_data_len);
1586 
1596 int
1597 MHD_destroy_post_processor (struct MHD_PostProcessor *pp);
1598 
1599 
1600 /* ********************* Digest Authentication functions *************** */
1601 
1602 
1607 #define MHD_INVALID_NONCE -1
1608 
1609 
1617 char *
1618 MHD_digest_auth_get_username (struct MHD_Connection *connection);
1619 
1620 
1633 int
1634 MHD_digest_auth_check (struct MHD_Connection *connection,
1635  const char *realm,
1636  const char *username,
1637  const char *password,
1638  unsigned int nonce_timeout);
1639 
1640 
1654 int
1655 MHD_queue_auth_fail_response (struct MHD_Connection *connection,
1656  const char *realm,
1657  const char *opaque,
1658  struct MHD_Response *response,
1659  int signal_stale);
1660 
1661 
1670 char *
1672  char** password);
1673 
1681 int
1683  const char *realm,
1684  struct MHD_Response *response);
1685 
1686 /* ********************** generic query functions ********************** */
1687 
1692 {
1693 
1697  int /* enum gnutls_cipher_algorithm */ cipher_algorithm;
1698 
1702  int /* enum gnutls_protocol */ protocol;
1703 
1707  void * /* gnutls_session_t */ tls_session;
1708 
1712  void * /* gnutls_x509_crt_t */ client_cert;
1713 
1717  struct sockaddr *client_addr;
1718 
1724 };
1725 
1735 const union MHD_ConnectionInfo *
1736 MHD_get_connection_info (struct MHD_Connection *connection,
1737  enum MHD_ConnectionInfoType infoType,
1738  ...);
1739 
1740 
1746 {
1747 
1754 
1755 };
1756 
1757 
1766 int
1767 MHD_set_connection_option (struct MHD_Connection *connection,
1768  enum MHD_CONNECTION_OPTION option,
1769  ...);
1770 
1771 
1776 {
1780  size_t key_size;
1781 
1786 
1791 };
1792 
1803 const union MHD_DaemonInfo *
1804 MHD_get_daemon_info (struct MHD_Daemon *daemon,
1805  enum MHD_DaemonInfoType infoType,
1806  ...);
1807 
1808 
1814 const char*
1815 MHD_get_version (void);
1816 
1817 #if 0 /* keep Emacsens' auto-indent happy */
1818 {
1819 #endif
1820 #ifdef __cplusplus
1821 }
1822 #endif
1823 
1824 #endif