New Makefile, min VDR now 1.7.35

[jsonserver.git] / mongoose.h

// Copyright (c) 2004-2012 Sergey Lyubka\r
//\r
// Permission is hereby granted, free of charge, to any person obtaining a copy\r
// of this software and associated documentation files (the "Software"), to deal\r
// in the Software without restriction, including without limitation the rights\r
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r
// copies of the Software, and to permit persons to whom the Software is\r
// furnished to do so, subject to the following conditions:\r
//\r
// The above copyright notice and this permission notice shall be included in\r
// all copies or substantial portions of the Software.\r
//\r
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\r
// THE SOFTWARE.\r
\r
#ifndef MONGOOSE_HEADER_INCLUDED\r
#define  MONGOOSE_HEADER_INCLUDED\r
\r
#include <stdio.h>\r
#include <stddef.h>\r
\r
#ifdef __cplusplus\r
extern "C" {\r
#endif // __cplusplus\r
\r
struct mg_context;     // Handle for the HTTP service itself\r
struct mg_connection;  // Handle for the individual connection\r
\r
\r
// This structure contains information about the HTTP request.\r
struct mg_request_info {\r
  const char *request_method; // "GET", "POST", etc\r
  const char *uri;            // URL-decoded URI\r
  const char *http_version;   // E.g. "1.0", "1.1"\r
  const char *query_string;   // URL part after '?', not including '?', or NULL\r
  const char *remote_user;    // Authenticated user, or NULL if no auth used\r
  long remote_ip;             // Client's IP address\r
  int remote_port;            // Client's port\r
  int is_ssl;                 // 1 if SSL-ed, 0 if not\r
  void *user_data;            // User data pointer passed to mg_start()\r
\r
  int num_headers;            // Number of HTTP headers\r
  struct mg_header {\r
    const char *name;         // HTTP header name\r
    const char *value;        // HTTP header value\r
  } http_headers[64];         // Maximum 64 headers\r
};\r
\r
\r
// This structure needs to be passed to mg_start(), to let mongoose know\r
// which callbacks to invoke. For detailed description, see\r
// https://github.com/valenok/mongoose/blob/master/UserManual.md\r
struct mg_callbacks {\r
  int  (*begin_request)(struct mg_connection *);\r
  void (*end_request)(const struct mg_connection *, int reply_status_code);\r
  int  (*log_message)(const struct mg_connection *, const char *message);\r
  int  (*init_ssl)(void *ssl_context);\r
  int (*websocket_connect)(const struct mg_connection *);\r
  void (*websocket_ready)(struct mg_connection *);\r
  int  (*websocket_data)(struct mg_connection *);\r
  const char * (*open_file)(const struct mg_connection *,\r
                             const char *path, size_t *data_len);\r
  void (*init_lua)(struct mg_connection *, void *lua_context);\r
  void (*upload)(struct mg_connection *, const char *file_name);\r
};\r
\r
// Start web server.\r
//\r
// Parameters:\r
//   callbacks: mg_callbacks structure with user-defined callbacks.\r
//   options: NULL terminated list of option_name, option_value pairs that\r
//            specify Mongoose configuration parameters.\r
//\r
// Side-effects: on UNIX, ignores SIGCHLD and SIGPIPE signals. If custom\r
//    processing is required for these, signal handlers must be set up\r
//    after calling mg_start().\r
//\r
//\r
// Example:\r
//   const char *options[] = {\r
//     "document_root", "/var/www",\r
//     "listening_ports", "80,443s",\r
//     NULL\r
//   };\r
//   struct mg_context *ctx = mg_start(&my_func, NULL, options);\r
//\r
// Please refer to http://code.google.com/p/mongoose/wiki/MongooseManual\r
// for the list of valid option and their possible values.\r
//\r
// Return:\r
//   web server context, or NULL on error.\r
struct mg_context *mg_start(const struct mg_callbacks *callbacks,\r
                            void *user_data,\r
                            const char **configuration_options);\r
\r
\r
// Stop the web server.\r
//\r
// Must be called last, when an application wants to stop the web server and\r
// release all associated resources. This function blocks until all Mongoose\r
// threads are stopped. Context pointer becomes invalid.\r
void mg_stop(struct mg_context *);\r
\r
\r
// Get the value of particular configuration parameter.\r
// The value returned is read-only. Mongoose does not allow changing\r
// configuration at run time.\r
// If given parameter name is not valid, NULL is returned. For valid\r
// names, return value is guaranteed to be non-NULL. If parameter is not\r
// set, zero-length string is returned.\r
const char *mg_get_option(const struct mg_context *ctx, const char *name);\r
\r
\r
// Return array of strings that represent valid configuration options.\r
// For each option, a short name, long name, and default value is returned.\r
// Array is NULL terminated.\r
const char **mg_get_valid_option_names(void);\r
\r
\r
// Add, edit or delete the entry in the passwords file.\r
//\r
// This function allows an application to manipulate .htpasswd files on the\r
// fly by adding, deleting and changing user records. This is one of the\r
// several ways of implementing authentication on the server side. For another,\r
// cookie-based way please refer to the examples/chat.c in the source tree.\r
//\r
// If password is not NULL, entry is added (or modified if already exists).\r
// If password is NULL, entry is deleted.\r
//\r
// Return:\r
//   1 on success, 0 on error.\r
int mg_modify_passwords_file(const char *passwords_file_name,\r
                             const char *domain,\r
                             const char *user,\r
                             const char *password);\r
\r
\r
// Return information associated with the request.\r
struct mg_request_info *mg_get_request_info(struct mg_connection *);\r
\r
\r
// Send data to the client.\r
// Return:\r
//  0   when the connection has been closed\r
//  -1  on error\r
//  number of bytes written on success\r
int mg_write(struct mg_connection *, const void *buf, size_t len);\r
\r
\r
#undef PRINTF_FORMAT_STRING\r
#if _MSC_VER >= 1400\r
#include <sal.h>\r
#if _MSC_VER > 1400\r
#define PRINTF_FORMAT_STRING(s) _Printf_format_string_ s\r
#else\r
#define PRINTF_FORMAT_STRING(s) __format_string s\r
#endif\r
#else\r
#define PRINTF_FORMAT_STRING(s) s\r
#endif\r
\r
#ifdef __GNUC__\r
#define PRINTF_ARGS(x, y) __attribute__((format(printf, x, y)))\r
#else\r
#define PRINTF_ARGS(x, y)\r
#endif\r
\r
// Send data to the browser using printf() semantics.\r
//\r
// Works exactly like mg_write(), but allows to do message formatting.\r
// Below are the macros for enabling compiler-specific checks for\r
// printf-like arguments.\r
int mg_printf(struct mg_connection *,\r
              PRINTF_FORMAT_STRING(const char *fmt), ...) PRINTF_ARGS(2, 3);\r
\r
\r
// Send contents of the entire file together with HTTP headers.\r
void mg_send_file(struct mg_connection *conn, const char *path);\r
\r
\r
// Read data from the remote end, return number of bytes read.\r
int mg_read(struct mg_connection *, void *buf, size_t len);\r
\r
\r
// Get the value of particular HTTP header.\r
//\r
// This is a helper function. It traverses request_info->http_headers array,\r
// and if the header is present in the array, returns its value. If it is\r
// not present, NULL is returned.\r
const char *mg_get_header(const struct mg_connection *, const char *name);\r
\r
\r
// Get a value of particular form variable.\r
//\r
// Parameters:\r
//   data: pointer to form-uri-encoded buffer. This could be either POST data,\r
//         or request_info.query_string.\r
//   data_len: length of the encoded data.\r
//   var_name: variable name to decode from the buffer\r
//   dst: destination buffer for the decoded variable\r
//   dst_len: length of the destination buffer\r
//\r
// Return:\r
//   On success, length of the decoded variable.\r
//   On error:\r
//      -1 (variable not found).\r
//      -2 (destination buffer is NULL, zero length or too small to hold the decoded variable).\r
//\r
// Destination buffer is guaranteed to be '\0' - terminated if it is not\r
// NULL or zero length.\r
int mg_get_var(const char *data, size_t data_len,\r
               const char *var_name, char *dst, size_t dst_len);\r
\r
// Fetch value of certain cookie variable into the destination buffer.\r
//\r
// Destination buffer is guaranteed to be '\0' - terminated. In case of\r
// failure, dst[0] == '\0'. Note that RFC allows many occurrences of the same\r
// parameter. This function returns only first occurrence.\r
//\r
// Return:\r
//   On success, value length.\r
//   On error:\r
//      -1 (either "Cookie:" header is not present at all or the requested parameter is not found).\r
//      -2 (destination buffer is NULL, zero length or too small to hold the value).\r
int mg_get_cookie(const struct mg_connection *,\r
                  const char *cookie_name, char *buf, size_t buf_len);\r
\r
\r
// Download data from the remote web server.\r
//   host: host name to connect to, e.g. "foo.com", or "10.12.40.1".\r
//   port: port number, e.g. 80.\r
//   use_ssl: wether to use SSL connection.\r
//   error_buffer, error_buffer_size: error message placeholder.\r
//   request_fmt,...: HTTP request.\r
// Return:\r
//   On success, valid pointer to the new connection, suitable for mg_read().\r
//   On error, NULL. error_buffer contains error message.\r
// Example:\r
//   char ebuf[100];\r
//   struct mg_connection *conn;\r
//   conn = mg_download("google.com", 80, 0, ebuf, sizeof(ebuf),\r
//                      "%s", "GET / HTTP/1.0\r\nHost: google.com\r\n\r\n");\r
struct mg_connection *mg_download(const char *host, int port, int use_ssl,\r
                                  char *error_buffer, size_t error_buffer_size,\r
                                  PRINTF_FORMAT_STRING(const char *request_fmt),\r
                                  ...) PRINTF_ARGS(6, 7);\r
\r
\r
// Close the connection opened by mg_download().\r
void mg_close_connection(struct mg_connection *conn);\r
\r
\r
// File upload functionality. Each uploaded file gets saved into a temporary\r
// file and MG_UPLOAD event is sent.\r
// Return number of uploaded files.\r
int mg_upload(struct mg_connection *conn, const char *destination_dir);\r
\r
\r
// Convenience function -- create detached thread.\r
// Return: 0 on success, non-0 on error.\r
typedef void * (*mg_thread_func_t)(void *);\r
int mg_start_thread(mg_thread_func_t f, void *p);\r
\r
\r
// Return builtin mime type for the given file name.\r
// For unrecognized extensions, "text/plain" is returned.\r
const char *mg_get_builtin_mime_type(const char *file_name);\r
\r
\r
// Return Mongoose version.\r
const char *mg_version(void);\r
\r
\r
// MD5 hash given strings.\r
// Buffer 'buf' must be 33 bytes long. Varargs is a NULL terminated list of\r
// ASCIIz strings. When function returns, buf will contain human-readable\r
// MD5 hash. Example:\r
//   char buf[33];\r
//   mg_md5(buf, "aa", "bb", NULL);\r
void mg_md5(char buf[33], ...);\r
\r
\r
#ifdef __cplusplus\r
}\r
#endif // __cplusplus\r
\r
#endif // MONGOOSE_HEADER_INCLUDED\r