reprap: Progress

[simavr] / examples / shared / mongoose.h

// Copyright (c) 2004-2011 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 <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
  void *user_data;       // User-defined pointer passed to mg_start()\r
  char *request_method;  // "GET", "POST", etc\r
  char *uri;             // URL-decoded URI\r
  char *http_version;    // E.g. "1.0", "1.1"\r
  char *query_string;    // URL part after '?' (not including '?') or NULL\r
  char *remote_user;     // Authenticated user, or NULL if no auth used\r
  char *log_message;     // Mongoose error log message, MG_EVENT_LOG only\r
  long remote_ip;        // Client's IP address\r
  int remote_port;       // Client's port\r
  int status_code;       // HTTP reply status code, e.g. 200\r
  int is_ssl;            // 1 if SSL-ed, 0 if not\r
  int num_headers;       // Number of headers\r
  struct mg_header {\r
    char *name;          // HTTP header name\r
    char *value;         // HTTP header value\r
  } http_headers[64];    // Maximum 64 headers\r
};\r
\r
// Various events on which user-defined function is called by Mongoose.\r
enum mg_event {\r
  MG_NEW_REQUEST,   // New HTTP request has arrived from the client\r
  MG_HTTP_ERROR,    // HTTP error must be returned to the client\r
  MG_EVENT_LOG,     // Mongoose logs an event, request_info.log_message\r
  MG_INIT_SSL,      // Mongoose initializes SSL. Instead of mg_connection *,\r
                    // SSL context is passed to the callback function.\r
  MG_REQUEST_COMPLETE  // Mongoose has finished handling the request\r
};\r
\r
// Prototype for the user-defined function. Mongoose calls this function\r
// on every MG_* event.\r
//\r
// Parameters:\r
//   event: which event has been triggered.\r
//   conn: opaque connection handler. Could be used to read, write data to the\r
//         client, etc. See functions below that have "mg_connection *" arg.\r
//   request_info: Information about HTTP request.\r
//\r
// Return:\r
//   If handler returns non-NULL, that means that handler has processed the\r
//   request by sending appropriate HTTP reply to the client. Mongoose treats\r
//   the request as served.\r
//   If handler returns NULL, that means that handler has not processed\r
//   the request. Handler must not send any data to the client in this case.\r
//   Mongoose proceeds with request handling as if nothing happened.\r
typedef void * (*mg_callback_t)(enum mg_event event,\r
                                struct mg_connection *conn,\r
                                const struct mg_request_info *request_info);\r
\r
\r
// Start web server.\r
//\r
// Parameters:\r
//   callback: user defined event handling function or NULL.\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(mg_callback_t callback, void *user_data,\r
                            const char **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
// Send data to the client.\r
int mg_write(struct mg_connection *, const void *buf, size_t len);\r
\r
\r
// Send data to the browser using printf() semantics.\r
//\r
// Works exactly like mg_write(), but allows to do message formatting.\r
// Note that mg_printf() uses internal buffer of size IO_BUF_SIZE\r
// (8 Kb by default) as temporary message storage for formatting. Do not\r
// print data that is bigger than that, otherwise it will be truncated.\r
int mg_printf(struct mg_connection *, const char *fmt, ...)\r
#ifdef __GNUC__\r
__attribute__((format(printf, 2, 3)))\r
#endif\r
;\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
//   buf: destination buffer for the decoded variable\r
//   buf_len: length of the destination buffer\r
//\r
// Return:\r
//   On success, length of the decoded variable.\r
//   On error, -1 (variable not found, or destination buffer is too small).\r
//\r
// Destination buffer is guaranteed to be '\0' - terminated. In case of\r
// failure, dst[0] == '\0'.\r
int mg_get_var(const char *data, size_t data_len,\r
               const char *var_name, char *buf, size_t buf_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, 0 (either "Cookie:" header is not present at all, or the\r
//   requested parameter is not found, or destination buffer is too small\r
//   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
// 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, ...);\r
\r
\r
#ifdef __cplusplus\r
}\r
#endif // __cplusplus\r
\r
#endif // MONGOOSE_HEADER_INCLUDED\r