microhttpd.h

Go to the documentation of this file.

/*
     This file is part of libmicrohttpd
     (C) 2006, 2007, 2008, 2009, 2010, 2011 Christian Grothoff (and other contributing authors)

     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Lesser General Public
     License as published by the Free Software Foundation; either
     version 2.1 of the License, or (at your option) any later version.

     This library is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Lesser General Public License for more details.

     You should have received a copy of the GNU Lesser General Public
     License along with this library; if not, write to the Free Software
     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
*/

#ifndef MHD_MICROHTTPD_H
#define MHD_MICROHTTPD_H

#ifdef __cplusplus
extern "C"
{
#if 0                           /* keep Emacsens' auto-indent happy */
}
#endif
#endif

/* While we generally would like users to use a configure-driven
   build process which detects which headers are present and
   hence works on any platform, we use "standard" includes here
   to build out-of-the-box for beginning users on common systems.

   Once you have a proper build system and go for more exotic 
   platforms, you should define MHD_PLATFORM_H in some header that
   you always include *before* "microhttpd.h".  Then the following
   "standard" includes won't be used (which might be a good
   idea, especially on platforms where they do not exist). */
#ifndef MHD_PLATFORM_H
#include <unistd.h>
#include <stdarg.h>
#include <stdint.h>
#ifdef __MINGW32__
#include <ws2tcpip.h>
#else
#include <sys/time.h>
#include <sys/types.h>
#include <sys/socket.h>
#endif
#endif

#define MHD_VERSION 0x00091600

#define MHD_YES 1

#define MHD_NO 0

#define MHD_INVALID_NONCE -1

#ifdef UINT64_MAX
#define MHD_SIZE_UNKNOWN UINT64_MAX
#else
#define MHD_SIZE_UNKNOWN  ((uint64_t) -1LL)
#endif

#ifdef SIZE_MAX
#define MHD_CONTENT_READER_END_OF_STREAM SIZE_MAX
#define MHD_CONTENT_READER_END_WITH_ERROR (SIZE_MAX - 1)
#else
#define MHD_CONTENT_READER_END_OF_STREAM ((size_t) -1LL)
#define MHD_CONTENT_READER_END_WITH_ERROR (((size_t) -1LL) - 1)
#endif

#ifndef MHD_LONG_LONG
#define MHD_LONG_LONG long long
#endif
#ifndef MHD_LONG_LONG_PRINTF

#define MHD_LONG_LONG_PRINTF "ll"
#endif


#define MHD_HTTP_CONTINUE 100
#define MHD_HTTP_SWITCHING_PROTOCOLS 101
#define MHD_HTTP_PROCESSING 102

#define MHD_HTTP_OK 200
#define MHD_HTTP_CREATED 201
#define MHD_HTTP_ACCEPTED 202
#define MHD_HTTP_NON_AUTHORITATIVE_INFORMATION 203
#define MHD_HTTP_NO_CONTENT 204
#define MHD_HTTP_RESET_CONTENT 205
#define MHD_HTTP_PARTIAL_CONTENT 206
#define MHD_HTTP_MULTI_STATUS 207

#define MHD_HTTP_MULTIPLE_CHOICES 300
#define MHD_HTTP_MOVED_PERMANENTLY 301
#define MHD_HTTP_FOUND 302
#define MHD_HTTP_SEE_OTHER 303
#define MHD_HTTP_NOT_MODIFIED 304
#define MHD_HTTP_USE_PROXY 305
#define MHD_HTTP_SWITCH_PROXY 306
#define MHD_HTTP_TEMPORARY_REDIRECT 307

#define MHD_HTTP_BAD_REQUEST 400
#define MHD_HTTP_UNAUTHORIZED 401
#define MHD_HTTP_PAYMENT_REQUIRED 402
#define MHD_HTTP_FORBIDDEN 403
#define MHD_HTTP_NOT_FOUND 404
#define MHD_HTTP_METHOD_NOT_ALLOWED 405
#define MHD_HTTP_METHOD_NOT_ACCEPTABLE 406
#define MHD_HTTP_PROXY_AUTHENTICATION_REQUIRED 407
#define MHD_HTTP_REQUEST_TIMEOUT 408
#define MHD_HTTP_CONFLICT 409
#define MHD_HTTP_GONE 410
#define MHD_HTTP_LENGTH_REQUIRED 411
#define MHD_HTTP_PRECONDITION_FAILED 412
#define MHD_HTTP_REQUEST_ENTITY_TOO_LARGE 413
#define MHD_HTTP_REQUEST_URI_TOO_LONG 414
#define MHD_HTTP_UNSUPPORTED_MEDIA_TYPE 415
#define MHD_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE 416
#define MHD_HTTP_EXPECTATION_FAILED 417
#define MHD_HTTP_UNPROCESSABLE_ENTITY 422
#define MHD_HTTP_LOCKED 423
#define MHD_HTTP_FAILED_DEPENDENCY 424
#define MHD_HTTP_UNORDERED_COLLECTION 425
#define MHD_HTTP_UPGRADE_REQUIRED 426
#define MHD_HTTP_NO_RESPONSE 444
#define MHD_HTTP_RETRY_WITH 449
#define MHD_HTTP_BLOCKED_BY_WINDOWS_PARENTAL_CONTROLS 450
#define MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS 451

#define MHD_HTTP_INTERNAL_SERVER_ERROR 500
#define MHD_HTTP_NOT_IMPLEMENTED 501
#define MHD_HTTP_BAD_GATEWAY 502
#define MHD_HTTP_SERVICE_UNAVAILABLE 503
#define MHD_HTTP_GATEWAY_TIMEOUT 504
#define MHD_HTTP_HTTP_VERSION_NOT_SUPPORTED 505
#define MHD_HTTP_VARIANT_ALSO_NEGOTIATES 506
#define MHD_HTTP_INSUFFICIENT_STORAGE 507
#define MHD_HTTP_BANDWIDTH_LIMIT_EXCEEDED 509
#define MHD_HTTP_NOT_EXTENDED 510

#define MHD_ICY_FLAG ((uint32_t)(1 << 31))

/* See also: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html */
#define MHD_HTTP_HEADER_ACCEPT "Accept"
#define MHD_HTTP_HEADER_ACCEPT_CHARSET "Accept-Charset"
#define MHD_HTTP_HEADER_ACCEPT_ENCODING "Accept-Encoding"
#define MHD_HTTP_HEADER_ACCEPT_LANGUAGE "Accept-Language"
#define MHD_HTTP_HEADER_ACCEPT_RANGES "Accept-Ranges"
#define MHD_HTTP_HEADER_AGE "Age"
#define MHD_HTTP_HEADER_ALLOW "Allow"
#define MHD_HTTP_HEADER_AUTHORIZATION "Authorization"
#define MHD_HTTP_HEADER_CACHE_CONTROL "Cache-Control"
#define MHD_HTTP_HEADER_CONNECTION "Connection"
#define MHD_HTTP_HEADER_CONTENT_ENCODING "Content-Encoding"
#define MHD_HTTP_HEADER_CONTENT_LANGUAGE "Content-Language"
#define MHD_HTTP_HEADER_CONTENT_LENGTH "Content-Length"
#define MHD_HTTP_HEADER_CONTENT_LOCATION "Content-Location"
#define MHD_HTTP_HEADER_CONTENT_MD5 "Content-MD5"
#define MHD_HTTP_HEADER_CONTENT_RANGE "Content-Range"
#define MHD_HTTP_HEADER_CONTENT_TYPE "Content-Type"
#define MHD_HTTP_HEADER_COOKIE "Cookie"
#define MHD_HTTP_HEADER_DATE "Date"
#define MHD_HTTP_HEADER_ETAG "ETag"
#define MHD_HTTP_HEADER_EXPECT "Expect"
#define MHD_HTTP_HEADER_EXPIRES "Expires"
#define MHD_HTTP_HEADER_FROM "From"
#define MHD_HTTP_HEADER_HOST "Host"
#define MHD_HTTP_HEADER_IF_MATCH "If-Match"
#define MHD_HTTP_HEADER_IF_MODIFIED_SINCE "If-Modified-Since"
#define MHD_HTTP_HEADER_IF_NONE_MATCH "If-None-Match"
#define MHD_HTTP_HEADER_IF_RANGE "If-Range"
#define MHD_HTTP_HEADER_IF_UNMODIFIED_SINCE "If-Unmodified-Since"
#define MHD_HTTP_HEADER_LAST_MODIFIED "Last-Modified"
#define MHD_HTTP_HEADER_LOCATION "Location"
#define MHD_HTTP_HEADER_MAX_FORWARDS "Max-Forwards"
#define MHD_HTTP_HEADER_PRAGMA "Pragma"
#define MHD_HTTP_HEADER_PROXY_AUTHENTICATE "Proxy-Authenticate"
#define MHD_HTTP_HEADER_PROXY_AUTHORIZATION "Proxy-Authorization"
#define MHD_HTTP_HEADER_RANGE "Range"
#define MHD_HTTP_HEADER_REFERER "Referer"
#define MHD_HTTP_HEADER_RETRY_AFTER "Retry-After"
#define MHD_HTTP_HEADER_SERVER "Server"
#define MHD_HTTP_HEADER_SET_COOKIE "Set-Cookie"
#define MHD_HTTP_HEADER_SET_COOKIE2 "Set-Cookie2"
#define MHD_HTTP_HEADER_TE "TE"
#define MHD_HTTP_HEADER_TRAILER "Trailer"
#define MHD_HTTP_HEADER_TRANSFER_ENCODING "Transfer-Encoding"
#define MHD_HTTP_HEADER_UPGRADE "Upgrade"
#define MHD_HTTP_HEADER_USER_AGENT "User-Agent"
#define MHD_HTTP_HEADER_VARY "Vary"
#define MHD_HTTP_HEADER_VIA "Via"
#define MHD_HTTP_HEADER_WARNING "Warning"
#define MHD_HTTP_HEADER_WWW_AUTHENTICATE "WWW-Authenticate"

#define MHD_HTTP_VERSION_1_0 "HTTP/1.0"
#define MHD_HTTP_VERSION_1_1 "HTTP/1.1"

#define MHD_HTTP_METHOD_CONNECT "CONNECT"
#define MHD_HTTP_METHOD_DELETE "DELETE"
#define MHD_HTTP_METHOD_GET "GET"
#define MHD_HTTP_METHOD_HEAD "HEAD"
#define MHD_HTTP_METHOD_OPTIONS "OPTIONS"
#define MHD_HTTP_METHOD_POST "POST"
#define MHD_HTTP_METHOD_PUT "PUT"
#define MHD_HTTP_METHOD_TRACE "TRACE"

#define MHD_HTTP_POST_ENCODING_FORM_URLENCODED "application/x-www-form-urlencoded"
#define MHD_HTTP_POST_ENCODING_MULTIPART_FORMDATA "multipart/form-data"

enum MHD_FLAG
{
  MHD_NO_FLAG = 0,

  MHD_USE_DEBUG = 1,

  MHD_USE_SSL = 2,

  MHD_USE_THREAD_PER_CONNECTION = 4,

  MHD_USE_SELECT_INTERNALLY = 8,

  MHD_USE_IPv6 = 16,

  MHD_USE_PEDANTIC_CHECKS = 32,

  MHD_USE_POLL = 64,

  MHD_SUPPRESS_DATE_NO_CLOCK = 128,

  MHD_USE_NO_LISTEN_SOCKET = 256

};


enum MHD_OPTION
{

  MHD_OPTION_END = 0,

  MHD_OPTION_CONNECTION_MEMORY_LIMIT = 1,

  MHD_OPTION_CONNECTION_LIMIT = 2,

  MHD_OPTION_CONNECTION_TIMEOUT = 3,

  MHD_OPTION_NOTIFY_COMPLETED = 4,

  MHD_OPTION_PER_IP_CONNECTION_LIMIT = 5,

  MHD_OPTION_SOCK_ADDR = 6,

  MHD_OPTION_URI_LOG_CALLBACK = 7,

  MHD_OPTION_HTTPS_MEM_KEY = 8,

  MHD_OPTION_HTTPS_MEM_CERT = 9,

  MHD_OPTION_HTTPS_CRED_TYPE = 10,

  MHD_OPTION_HTTPS_PRIORITIES = 11,

  MHD_OPTION_LISTEN_SOCKET = 12,

  MHD_OPTION_EXTERNAL_LOGGER = 13,

  MHD_OPTION_THREAD_POOL_SIZE = 14,

  MHD_OPTION_ARRAY = 15,

  MHD_OPTION_UNESCAPE_CALLBACK = 16,

  MHD_OPTION_DIGEST_AUTH_RANDOM = 17,

  MHD_OPTION_NONCE_NC_SIZE = 18,

  MHD_OPTION_THREAD_STACK_SIZE = 19,

  MHD_OPTION_HTTPS_MEM_TRUST =20
};


struct MHD_OptionItem
{
  enum MHD_OPTION option;

  intptr_t value;

  void *ptr_value;

};


enum MHD_ValueKind
{

  MHD_RESPONSE_HEADER_KIND = 0,

  MHD_HEADER_KIND = 1,

  MHD_COOKIE_KIND = 2,

  MHD_POSTDATA_KIND = 4,

  MHD_GET_ARGUMENT_KIND = 8,

  MHD_FOOTER_KIND = 16
};


enum MHD_RequestTerminationCode
{

  MHD_REQUEST_TERMINATED_COMPLETED_OK = 0,

  MHD_REQUEST_TERMINATED_WITH_ERROR = 1,

  MHD_REQUEST_TERMINATED_TIMEOUT_REACHED = 2,

  MHD_REQUEST_TERMINATED_DAEMON_SHUTDOWN = 3,

  MHD_REQUEST_TERMINATED_READ_ERROR = 4

};


enum MHD_ConnectionInfoType
{
  MHD_CONNECTION_INFO_CIPHER_ALGO,

  MHD_CONNECTION_INFO_PROTOCOL,

  MHD_CONNECTION_INFO_CLIENT_ADDRESS,

  MHD_CONNECTION_INFO_GNUTLS_SESSION,

  MHD_CONNECTION_INFO_GNUTLS_CLIENT_CERT,

  MHD_CONNECTION_INFO_DAEMON

};


enum MHD_DaemonInfoType
{
  MHD_DAEMON_INFO_KEY_SIZE,

  MHD_DAEMON_INFO_MAC_KEY_SIZE,

  MHD_DAEMON_INFO_LISTEN_FD
};


struct MHD_Daemon;

struct MHD_Connection;

struct MHD_Response;

struct MHD_PostProcessor;


typedef 
  void (*MHD_PanicCallback) (void *cls,
                             const char *file,
                             unsigned int line,
                             const char *reason);

typedef int
  (*MHD_AcceptPolicyCallback) (void *cls,
                               const struct sockaddr * addr,
                               socklen_t addrlen);


typedef int
  (*MHD_AccessHandlerCallback) (void *cls,
                                struct MHD_Connection * connection,
                                const char *url,
                                const char *method,
                                const char *version,
                                const char *upload_data,
                                size_t *upload_data_size,
                                void **con_cls);


typedef void
  (*MHD_RequestCompletedCallback) (void *cls,
                                   struct MHD_Connection * connection,
                                   void **con_cls,
                                   enum MHD_RequestTerminationCode toe);


typedef int
  (*MHD_KeyValueIterator) (void *cls,
                           enum MHD_ValueKind kind,
                           const char *key, const char *value);


typedef ssize_t
  (*MHD_ContentReaderCallback) (void *cls,
                                uint64_t pos,
                                char *buf,
                                size_t max);


typedef void 
  (*MHD_ContentReaderFreeCallback) (void *cls);


typedef int
  (*MHD_PostDataIterator) (void *cls,
                           enum MHD_ValueKind kind,
                           const char *key,
                           const char *filename,
                           const char *content_type,
                           const char *transfer_encoding,
                           const char *data, 
                           uint64_t off, 
                           size_t size);

/* **************** Daemon handling functions ***************** */

struct MHD_Daemon *
MHD_start_daemon_va (unsigned int options,
                     uint16_t port,
                     MHD_AcceptPolicyCallback apc, void *apc_cls,
                     MHD_AccessHandlerCallback dh, void *dh_cls, 
                     va_list ap);


struct MHD_Daemon *
MHD_start_daemon (unsigned int flags,
                  uint16_t port,
                  MHD_AcceptPolicyCallback apc, void *apc_cls,
                  MHD_AccessHandlerCallback dh, void *dh_cls, 
                  ...);


void 
MHD_stop_daemon (struct MHD_Daemon *daemon);


int 
MHD_add_connection (struct MHD_Daemon *daemon, 
                    int client_socket,
                    const struct sockaddr *addr,
                    socklen_t addrlen);


int
MHD_get_fdset (struct MHD_Daemon *daemon,
               fd_set *read_fd_set,
               fd_set *write_fd_set, 
               fd_set *except_fd_set, 
               int *max_fd);


int MHD_get_timeout (struct MHD_Daemon *daemon, 
                     unsigned MHD_LONG_LONG *timeout);


int 
MHD_run (struct MHD_Daemon *daemon);


/* **************** Connection handling functions ***************** */

int
MHD_get_connection_values (struct MHD_Connection *connection,
                           enum MHD_ValueKind kind,
                           MHD_KeyValueIterator iterator, void *iterator_cls);


int
MHD_set_connection_value (struct MHD_Connection *connection,
                          enum MHD_ValueKind kind,
                          const char *key, 
                          const char *value);


void 
MHD_set_panic_func (MHD_PanicCallback cb, void *cls);


const char *
MHD_lookup_connection_value (struct MHD_Connection *connection,
                             enum MHD_ValueKind kind,
                             const char *key);


int
MHD_queue_response (struct MHD_Connection *connection,
                    unsigned int status_code, 
                    struct MHD_Response *response);


/* **************** Response manipulation functions ***************** */

struct MHD_Response *
MHD_create_response_from_callback (uint64_t size,
                                   size_t block_size,
                                   MHD_ContentReaderCallback crc, void *crc_cls,
                                   MHD_ContentReaderFreeCallback crfc);


struct MHD_Response *
MHD_create_response_from_data (size_t size,
                               void *data,
                               int must_free,
                               int must_copy);


enum MHD_ResponseMemoryMode {

  MHD_RESPMEM_PERSISTENT,

  MHD_RESPMEM_MUST_FREE,

  MHD_RESPMEM_MUST_COPY

};


struct MHD_Response *
MHD_create_response_from_buffer (size_t size,
                                 void *buffer,
                                 enum MHD_ResponseMemoryMode mode);


struct MHD_Response *
MHD_create_response_from_fd (size_t size,
                             int fd);


struct MHD_Response *
MHD_create_response_from_fd_at_offset (size_t size,
                                       int fd,
                                       off_t offset);


typedef void (*MHD_UpgradeHandler)(void *cls,
                                   struct MHD_Connection *connection,
                                   void **con_cls,
                                   int upgrade_socket);

#if 0

struct MHD_Response *
MHD_create_response_for_upgrade (MHD_UpgradeHandler upgrade_handler,
                                 void *upgrade_handler_cls);
#endif

void MHD_destroy_response (struct MHD_Response *response);


int
MHD_add_response_header (struct MHD_Response *response,
                         const char *header, const char *content);


int
MHD_add_response_footer (struct MHD_Response *response,
                         const char *footer, const char *content);


int
MHD_del_response_header (struct MHD_Response *response,
                         const char *header, const char *content);

int
MHD_get_response_headers (struct MHD_Response *response,
                          MHD_KeyValueIterator iterator, void *iterator_cls);


const char *MHD_get_response_header (struct MHD_Response *response,
                                     const char *key);


/* ********************** PostProcessor functions ********************** */

struct MHD_PostProcessor *
MHD_create_post_processor (struct MHD_Connection *connection,
                           size_t buffer_size,
                           MHD_PostDataIterator iter, void *cls);

int
MHD_post_process (struct MHD_PostProcessor *pp,
                  const char *post_data, size_t post_data_len);

int 
MHD_destroy_post_processor (struct MHD_PostProcessor *pp);


/* ********************* Digest Authentication functions *************** */


#define MHD_INVALID_NONCE -1


char *
MHD_digest_auth_get_username (struct MHD_Connection *connection);


int
MHD_digest_auth_check (struct MHD_Connection *connection,
                       const char *realm,
                       const char *username,
                       const char *password,
                       unsigned int nonce_timeout);


int
MHD_queue_auth_fail_response (struct MHD_Connection *connection,
                              const char *realm,
                              const char *opaque,
                              struct MHD_Response *response,
                              int signal_stale);


char *
MHD_basic_auth_get_username_password (struct MHD_Connection *connection,
                                      char** password);

int
MHD_queue_basic_auth_fail_response (struct MHD_Connection *connection,
                                    const char *realm,
                                    struct MHD_Response *response);

/* ********************** generic query functions ********************** */

union MHD_ConnectionInfo
{

  int /* enum gnutls_cipher_algorithm */ cipher_algorithm;

  int /* enum gnutls_protocol */ protocol;

  void * /* gnutls_session_t */ tls_session;

  void * /* gnutls_x509_crt_t */ client_cert;

  struct sockaddr *client_addr;

  struct MHD_Daemon *daemon;
};

const union MHD_ConnectionInfo *
MHD_get_connection_info (struct MHD_Connection *connection,
                         enum MHD_ConnectionInfoType infoType, 
                         ...);


enum MHD_CONNECTION_OPTION
{

  MHD_CONNECTION_OPTION_TIMEOUT

};


int 
MHD_set_connection_option (struct MHD_Connection *connection,
                           enum MHD_CONNECTION_OPTION option,
                           ...);
                           

union MHD_DaemonInfo
{
  size_t key_size;

  size_t mac_key_size;

  int listen_fd;
};

const union MHD_DaemonInfo *
MHD_get_daemon_info (struct MHD_Daemon *daemon,
                     enum MHD_DaemonInfoType infoType, 
                     ...);


const char* 
MHD_get_version (void);

#if 0                           /* keep Emacsens' auto-indent happy */
{
#endif
#ifdef __cplusplus
}
#endif

#endif