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 0x00092100
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 
363 
374 
379 
387 
396 
397 };
398 
399 
407 typedef void (*MHD_LogCallback)(void *cls, const char *fm, va_list ap);
408 
409 
414 {
415 
421 
430 
436 
443 
457 
469 
476 
499 
507 
515 
522 
528 
536 
551 
561 
582 
602 
613 
620 
626 
633 };
634 
635 
640 {
646 
652  intptr_t value;
653 
658  void *ptr_value;
659 
660 };
661 
662 
668 {
669 
674 
679 
685 
695 
700 
705 };
706 
707 
713 {
714 
719 
726 
733 
739 
748 
749 };
750 
751 
757 {
763 
769 
777 
782 
790 
795 
796 };
797 
798 
804 {
812 
820 
826 };
827 
828 
832 struct MHD_Daemon;
833 
840 struct MHD_Connection;
841 
845 struct MHD_Response;
846 
850 struct MHD_PostProcessor;
851 
852 
862 typedef
863  void (*MHD_PanicCallback) (void *cls,
864  const char *file,
865  unsigned int line,
866  const char *reason);
867 
875 typedef int
877  const struct sockaddr * addr,
878  socklen_t addrlen);
879 
880 
916 typedef int
918  struct MHD_Connection * connection,
919  const char *url,
920  const char *method,
921  const char *version,
922  const char *upload_data,
923  size_t *upload_data_size,
924  void **con_cls);
925 
926 
938 typedef void
940  struct MHD_Connection *connection,
941  void **con_cls,
942  enum MHD_RequestTerminationCode toe);
943 
944 
955 typedef int
956  (*MHD_KeyValueIterator) (void *cls,
957  enum MHD_ValueKind kind,
958  const char *key, const char *value);
959 
960 
1008 typedef ssize_t
1010  uint64_t pos,
1011  char *buf,
1012  size_t max);
1013 
1014 
1021 typedef void
1023 
1024 
1044 typedef int
1045  (*MHD_PostDataIterator) (void *cls,
1046  enum MHD_ValueKind kind,
1047  const char *key,
1048  const char *filename,
1049  const char *content_type,
1050  const char *transfer_encoding,
1051  const char *data,
1052  uint64_t off,
1053  size_t size);
1054 
1055 /* **************** Daemon handling functions ***************** */
1056 
1073 struct MHD_Daemon *
1074 MHD_start_daemon_va (unsigned int flags,
1075  uint16_t port,
1076  MHD_AcceptPolicyCallback apc, void *apc_cls,
1077  MHD_AccessHandlerCallback dh, void *dh_cls,
1078  va_list ap);
1079 
1080 
1096 struct MHD_Daemon *
1097 MHD_start_daemon (unsigned int flags,
1098  uint16_t port,
1099  MHD_AcceptPolicyCallback apc, void *apc_cls,
1100  MHD_AccessHandlerCallback dh, void *dh_cls,
1101  ...);
1102 
1103 
1117 int
1118 MHD_quiesce_daemon (struct MHD_Daemon *daemon);
1119 
1120 
1126 void
1127 MHD_stop_daemon (struct MHD_Daemon *daemon);
1128 
1129 
1151 int
1152 MHD_add_connection (struct MHD_Daemon *daemon,
1153  int client_socket,
1154  const struct sockaddr *addr,
1155  socklen_t addrlen);
1156 
1157 
1171 int
1172 MHD_get_fdset (struct MHD_Daemon *daemon,
1173  fd_set *read_fd_set,
1174  fd_set *write_fd_set,
1175  fd_set *except_fd_set,
1176  int *max_fd);
1177 
1178 
1192 int MHD_get_timeout (struct MHD_Daemon *daemon,
1193  MHD_UNSIGNED_LONG_LONG *timeout);
1194 
1195 
1215 int
1216 MHD_run (struct MHD_Daemon *daemon);
1217 
1218 
1237 int
1238 MHD_run_from_select (struct MHD_Daemon *daemon,
1239  const fd_set *read_fd_set,
1240  const fd_set *write_fd_set,
1241  const fd_set *except_fd_set);
1242 
1243 
1244 /* **************** Connection handling functions ***************** */
1245 
1256 int
1257 MHD_get_connection_values (struct MHD_Connection *connection,
1258  enum MHD_ValueKind kind,
1259  MHD_KeyValueIterator iterator, void *iterator_cls);
1260 
1261 
1291 int
1292 MHD_set_connection_value (struct MHD_Connection *connection,
1293  enum MHD_ValueKind kind,
1294  const char *key,
1295  const char *value);
1296 
1297 
1313 void
1314 MHD_set_panic_func (MHD_PanicCallback cb, void *cls);
1315 
1316 
1326 const char *
1327 MHD_lookup_connection_value (struct MHD_Connection *connection,
1328  enum MHD_ValueKind kind,
1329  const char *key);
1330 
1331 
1342 int
1343 MHD_queue_response (struct MHD_Connection *connection,
1344  unsigned int status_code,
1345  struct MHD_Response *response);
1346 
1347 
1348 /* **************** Response manipulation functions ***************** */
1349 
1365 struct MHD_Response *
1366 MHD_create_response_from_callback (uint64_t size,
1367  size_t block_size,
1368  MHD_ContentReaderCallback crc, void *crc_cls,
1370 
1371 
1385 struct MHD_Response *
1386 MHD_create_response_from_data (size_t size,
1387  void *data,
1388  int must_free,
1389  int must_copy);
1390 
1391 
1397 
1404 
1411 
1419 
1420 };
1421 
1422 
1432 struct MHD_Response *
1433 MHD_create_response_from_buffer (size_t size,
1434  void *buffer,
1435  enum MHD_ResponseMemoryMode mode);
1436 
1437 
1448 struct MHD_Response *
1449 MHD_create_response_from_fd (size_t size,
1450  int fd);
1451 
1452 
1468 struct MHD_Response *
1470  int fd,
1471  off_t offset);
1472 
1473 
1474 #if 0
1475 
1480 enum MHD_UpgradeEventMask
1481 {
1482 
1487  MHD_UPGRADE_EVENT_TERMINATE = 0,
1488 
1493  MHD_UPGRADE_EVENT_READ = 1,
1494 
1499  MHD_UPGRADE_EVENT_WRITE = 2,
1500 
1508  MHD_UPGRADE_EVENT_EXTERNAL = 4,
1509 
1517  MHD_UPGRADE_EVENT_CORK = 8
1518 
1519 };
1520 
1521 
1565 typedef enum MHD_UpgradeEventMask (*MHD_UpgradeHandler)(void *cls,
1566  struct MHD_Connection *connection,
1567  void **con_cls,
1568  size_t *data_in_size,
1569  const char *data_in,
1570  size_t *data_out_size,
1571  char *data_out);
1572 
1573 
1603 struct MHD_Response *
1604 MHD_create_response_for_upgrade (MHD_UpgradeHandler upgrade_handler,
1605  void *upgrade_handler_cls);
1606 #endif
1607 
1616 void MHD_destroy_response (struct MHD_Response *response);
1617 
1618 
1628 int
1629 MHD_add_response_header (struct MHD_Response *response,
1630  const char *header, const char *content);
1631 
1632 
1641 int
1642 MHD_add_response_footer (struct MHD_Response *response,
1643  const char *footer, const char *content);
1644 
1645 
1654 int
1655 MHD_del_response_header (struct MHD_Response *response,
1656  const char *header, const char *content);
1657 
1658 
1668 int
1669 MHD_get_response_headers (struct MHD_Response *response,
1670  MHD_KeyValueIterator iterator, void *iterator_cls);
1671 
1672 
1680 const char *MHD_get_response_header (struct MHD_Response *response,
1681  const char *key);
1682 
1683 
1684 /* ********************** PostProcessor functions ********************** */
1685 
1710 struct MHD_PostProcessor *
1711 MHD_create_post_processor (struct MHD_Connection *connection,
1712  size_t buffer_size,
1713  MHD_PostDataIterator iter, void *iter_cls);
1714 
1729 int
1730 MHD_post_process (struct MHD_PostProcessor *pp,
1731  const char *post_data, size_t post_data_len);
1732 
1742 int
1743 MHD_destroy_post_processor (struct MHD_PostProcessor *pp);
1744 
1745 
1746 /* ********************* Digest Authentication functions *************** */
1747 
1748 
1753 #define MHD_INVALID_NONCE -1
1754 
1755 
1763 char *
1764 MHD_digest_auth_get_username (struct MHD_Connection *connection);
1765 
1766 
1779 int
1780 MHD_digest_auth_check (struct MHD_Connection *connection,
1781  const char *realm,
1782  const char *username,
1783  const char *password,
1784  unsigned int nonce_timeout);
1785 
1786 
1800 int
1801 MHD_queue_auth_fail_response (struct MHD_Connection *connection,
1802  const char *realm,
1803  const char *opaque,
1804  struct MHD_Response *response,
1805  int signal_stale);
1806 
1807 
1816 char *
1817 MHD_basic_auth_get_username_password (struct MHD_Connection *connection,
1818  char** password);
1819 
1831 int
1832 MHD_queue_basic_auth_fail_response (struct MHD_Connection *connection,
1833  const char *realm,
1834  struct MHD_Response *response);
1835 
1836 /* ********************** generic query functions ********************** */
1837 
1842 {
1843 
1847  int /* enum gnutls_cipher_algorithm */ cipher_algorithm;
1848 
1852  int /* enum gnutls_protocol */ protocol;
1853 
1857  void * /* gnutls_session_t */ tls_session;
1858 
1862  void * /* gnutls_x509_crt_t */ client_cert;
1863 
1867  struct sockaddr *client_addr;
1868 
1873  struct MHD_Daemon *daemon;
1874 };
1875 
1885 const union MHD_ConnectionInfo *
1886 MHD_get_connection_info (struct MHD_Connection *connection,
1887  enum MHD_ConnectionInfoType infoType,
1888  ...);
1889 
1890 
1896 {
1897 
1904 
1905 };
1906 
1907 
1916 int
1917 MHD_set_connection_option (struct MHD_Connection *connection,
1918  enum MHD_CONNECTION_OPTION option,
1919  ...);
1920 
1921 
1926 {
1930  size_t key_size;
1931 
1936 
1941 };
1942 
1953 const union MHD_DaemonInfo *
1954 MHD_get_daemon_info (struct MHD_Daemon *daemon,
1955  enum MHD_DaemonInfoType infoType,
1956  ...);
1957 
1958 
1964 const char*
1965 MHD_get_version (void);
1966 
1967 #if 0 /* keep Emacsens' auto-indent happy */
1968 {
1969 #endif
1970 #ifdef __cplusplus
1971 }
1972 #endif
1973 
1974 #endif