mongoose.h
Go to the documentation of this file.
00001 // Copyright (c) 2004-2010 Sergey Lyubka
00002 //
00003 // Permission is hereby granted, free of charge, to any person obtaining a copy
00004 // of this software and associated documentation files (the "Software"), to deal
00005 // in the Software without restriction, including without limitation the rights
00006 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00007 // copies of the Software, and to permit persons to whom the Software is
00008 // furnished to do so, subject to the following conditions:
00009 //
00010 // The above copyright notice and this permission notice shall be included in
00011 // all copies or substantial portions of the Software.
00012 //
00013 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00014 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00015 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00016 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00017 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00018 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00019 // THE SOFTWARE.
00020 
00021 #ifndef MONGOOSE_HEADER_INCLUDED
00022 #define  MONGOOSE_HEADER_INCLUDED
00023 
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif // __cplusplus
00027 
00028 struct mg_context;     // Handle for the HTTP service itself
00029 struct mg_connection;  // Handle for the individual connection
00030 
00031 
00032 // This structure contains information about the HTTP request.
00033 struct mg_request_info {
00034   void *user_data;       // User-defined pointer passed to mg_start()
00035   char *request_method;  // "GET", "POST", etc
00036   char *uri;             // URL-decoded URI
00037   char *http_version;    // E.g. "1.0", "1.1"
00038   char *query_string;    // \0 - terminated
00039   char *remote_user;     // Authenticated user
00040   char *log_message;     // Mongoose error log message
00041   long remote_ip;        // Client's IP address
00042   int remote_port;       // Client's port
00043   int status_code;       // HTTP reply status code
00044   int is_ssl;            // 1 if SSL-ed, 0 if not
00045   int num_headers;       // Number of headers
00046   struct mg_header {
00047     char *name;          // HTTP header name
00048     char *value;         // HTTP header value
00049   } http_headers[64];    // Maximum 64 headers
00050 };
00051 
00052 // Various events on which user-defined function is called by Mongoose.
00053 enum mg_event {
00054   MG_NEW_REQUEST,   // New HTTP request has arrived from the client
00055   MG_HTTP_ERROR,    // HTTP error must be returned to the client
00056   MG_EVENT_LOG,     // Mongoose logs an event, request_info.log_message
00057   MG_INIT_SSL,      // Mongoose initializes SSL. Instead of mg_connection *,
00058                     // SSL context is passed to the callback function.
00059 };
00060 
00061 // Prototype for the user-defined function. Mongoose calls this function
00062 // on every event mentioned above.
00063 //
00064 // Parameters:
00065 //   event: which event has been triggered.
00066 //   conn: opaque connection handler. Could be used to read, write data to the
00067 //         client, etc. See functions below that accept "mg_connection *".
00068 //   request_info: Information about HTTP request.
00069 //
00070 // Return:
00071 //   If handler returns non-NULL, that means that handler has processed the
00072 //   request by sending appropriate HTTP reply to the client. Mongoose treats
00073 //   the request as served.
00074 //   If callback returns NULL, that means that callback has not processed
00075 //   the request. Handler must not send any data to the client in this case.
00076 //   Mongoose proceeds with request handling as if nothing happened.
00077 typedef void * (*mg_callback_t)(enum mg_event event,
00078                                 struct mg_connection *conn,
00079                                 const struct mg_request_info *request_info);
00080 
00081 
00082 // Start web server.
00083 //
00084 // Parameters:
00085 //   callback: user defined event handling function or NULL.
00086 //   options: NULL terminated list of option_name, option_value pairs that
00087 //            specify Mongoose configuration parameters.
00088 //
00089 // Example:
00090 //   const char *options[] = {
00091 //     "document_root", "/var/www",
00092 //     "listening_ports", "80,443s",
00093 //     NULL
00094 //   };
00095 //   struct mg_context *ctx = mg_start(&my_func, options);
00096 //
00097 // Please refer to http://code.google.com/p/mongoose/wiki/MongooseManual
00098 // for the list of valid option and their possible values.
00099 //
00100 // Return:
00101 //   web server context, or NULL on error.
00102 struct mg_context *mg_start(mg_callback_t callback, void *user_data,
00103                             const char **options);
00104 
00105 
00106 // Stop the web server.
00107 //
00108 // Must be called last, when an application wants to stop the web server and
00109 // release all associated resources. This function blocks until all Mongoose
00110 // threads are stopped. Context pointer becomes invalid.
00111 void mg_stop(struct mg_context *);
00112 
00113 
00114 // Get the value of particular configuration parameter.
00115 // The value returned is read-only. Mongoose does not allow changing
00116 // configuration at run time.
00117 // If given parameter name is not valid, NULL is returned. For valid
00118 // names, return value is guaranteed to be non-NULL. If parameter is not
00119 // set, zero-length string is returned.
00120 const char *mg_get_option(const struct mg_context *ctx, const char *name);
00121 
00122 
00123 // Return array of strings that represent valid configuration options.
00124 // For each option, a short name, long name, and default value is returned.
00125 // Array is NULL terminated.
00126 const char **mg_get_valid_option_names(void);
00127 
00128 
00129 // Add, edit or delete the entry in the passwords file.
00130 //
00131 // This function allows an application to manipulate .htpasswd files on the
00132 // fly by adding, deleting and changing user records. This is one of the
00133 // several ways of implementing authentication on the server side. For another,
00134 // cookie-based way please refer to the examples/chat.c in the source tree.
00135 //
00136 // If password is not NULL, entry is added (or modified if already exists).
00137 // If password is NULL, entry is deleted.
00138 //
00139 // Return:
00140 //   1 on success, 0 on error.
00141 int mg_modify_passwords_file(struct mg_context *ctx, 
00142     const char *passwords_file_name, const char *user, const char *password);
00143 
00144 // Send data to the client.
00145 int mg_write(struct mg_connection *, const void *buf, size_t len);
00146 
00147 
00148 // Send data to the browser using printf() semantics.
00149 //
00150 // Works exactly like mg_write(), but allows to do message formatting.
00151 // Note that mg_printf() uses internal buffer of size IO_BUF_SIZE
00152 // (8 Kb by default) as temporary message storage for formatting. Do not
00153 // print data that is bigger than that, otherwise it will be truncated.
00154 int mg_printf(struct mg_connection *, const char *fmt, ...);
00155 
00156 
00157 // Read data from the remote end, return number of bytes read.
00158 int mg_read(struct mg_connection *, void *buf, size_t len);
00159 
00160 
00161 // Get the value of particular HTTP header.
00162 //
00163 // This is a helper function. It traverses request_info->http_headers array,
00164 // and if the header is present in the array, returns its value. If it is
00165 // not present, NULL is returned.
00166 const char *mg_get_header(const struct mg_connection *, const char *name);
00167 
00168 
00169 // Get a value of particular form variable.
00170 //
00171 // Parameters:
00172 //   data: pointer to form-uri-encoded buffer. This could be either POST data,
00173 //         or request_info.query_string.
00174 //   data_len: length of the encoded data.
00175 //   var_name: variable name to decode from the buffer
00176 //   buf: destination buffer for the decoded variable
00177 //   buf_len: length of the destination buffer
00178 //
00179 // Return:
00180 //   On success, length of the decoded variable.
00181 //   On error, -1 (variable not found, or destination buffer is too small).
00182 //
00183 // Destination buffer is guaranteed to be '\0' - terminated. In case of
00184 // failure, dst[0] == '\0'.
00185 int mg_get_var(const char *data, size_t data_len,
00186     const char *var_name, char *buf, size_t buf_len);
00187 
00188 // Fetch value of certain cookie variable into the destination buffer.
00189 //
00190 // Destination buffer is guaranteed to be '\0' - terminated. In case of
00191 // failure, dst[0] == '\0'. Note that RFC allows many occurrences of the same
00192 // parameter. This function returns only first occurrence.
00193 //
00194 // Return:
00195 //   On success, value length.
00196 //   On error, -1 (either "Cookie:" header is not present at all, or the
00197 //   requested parameter is not found, or destination buffer is too small
00198 //   to hold the value).
00199 int mg_get_cookie(const struct mg_connection *,
00200     const char *cookie_name, char *buf, size_t buf_len);
00201 
00202 
00203 // Return Mongoose version.
00204 const char *mg_version(void);
00205 
00206 
00207 // MD5 hash given strings.
00208 // Buffer 'buf' must be 33 bytes long. Varargs is a NULL terminated list of
00209 // asciiz strings. When function returns, buf will contain human-readable
00210 // MD5 hash. Example:
00211 //   char buf[33];
00212 //   mg_md5(buf, "aa", "bb", NULL);
00213 void mg_md5(char *buf, ...);
00214 
00215 
00216 #ifdef __cplusplus
00217 }
00218 #endif // __cplusplus
00219 
00220 #endif // MONGOOSE_HEADER_INCLUDED


jpeg_streamer
Author(s): Ken Tossell
autogenerated on Sun Oct 5 2014 22:47:16