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