1 // Copyright (c) 2004-2011 Sergey Lyubka 2 // 3 // Permission is hereby granted, free of charge, to any person obtaining a copy 4 // of this software and associated documentation files (the "Software"), to deal 5 // in the Software without restriction, including without limitation the rights 6 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 7 // copies of the Software, and to permit persons to whom the Software is 8 // furnished to do so, subject to the following conditions: 9 // 10 // The above copyright notice and this permission notice shall be included in 11 // all copies or substantial portions of the Software. 12 // 13 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 14 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 15 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 16 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 17 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 18 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 19 // THE SOFTWARE. 20 21 #ifndef MONGOOSE_HEADER_INCLUDED 22 #define MONGOOSE_HEADER_INCLUDED 23 24 #include <stddef.h> 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif // __cplusplus 29 30 struct mg_context; // Handle for the HTTP service itself 31 struct mg_connection; // Handle for the individual connection 32 33 34 // This structure contains information about the HTTP request. 35 struct mg_request_info { 36 void *user_data; // User-defined pointer passed to mg_start() 37 char *request_method; // "GET", "POST", etc 38 char *uri; // URL-decoded URI 39 char *http_version; // E.g. "1.0", "1.1" 40 char *query_string; // \0 - terminated 41 char *remote_user; // Authenticated user 42 char *log_message; // Mongoose error log message 43 long remote_ip; // Client's IP address 44 int remote_port; // Client's port 45 int status_code; // HTTP reply status code 46 int is_ssl; // 1 if SSL-ed, 0 if not 47 int num_headers; // Number of headers 48 struct mg_header { 49 char *name; // HTTP header name 50 char *value; // HTTP header value 51 } http_headers[64]; // Maximum 64 headers 52 }; 53 54 // Various events on which user-defined function is called by Mongoose. 55 enum mg_event { 56 MG_NEW_REQUEST, // New HTTP request has arrived from the client 57 MG_HTTP_ERROR, // HTTP error must be returned to the client 58 MG_EVENT_LOG, // Mongoose logs an event, request_info.log_message 59 MG_INIT_SSL // Mongoose initializes SSL. Instead of mg_connection *, 60 // SSL context is passed to the callback function. 61 }; 62 63 // Prototype for the user-defined function. Mongoose calls this function 64 // on every event mentioned above. 65 // 66 // Parameters: 67 // event: which event has been triggered. 68 // conn: opaque connection handler. Could be used to read, write data to the 69 // client, etc. See functions below that accept "mg_connection *". 70 // request_info: Information about HTTP request. 71 // 72 // Return: 73 // If handler returns non-NULL, that means that handler has processed the 74 // request by sending appropriate HTTP reply to the client. Mongoose treats 75 // the request as served. 76 // If callback returns NULL, that means that callback has not processed 77 // the request. Handler must not send any data to the client in this case. 78 // Mongoose proceeds with request handling as if nothing happened. 79 typedef void * (*mg_callback_t)(enum mg_event event, 80 struct mg_connection *conn, 81 const struct mg_request_info *request_info); 82 83 84 // Start web server. 85 // 86 // Parameters: 87 // callback: user defined event handling function or NULL. 88 // options: NULL terminated list of option_name, option_value pairs that 89 // specify Mongoose configuration parameters. 90 // 91 // Side-effects: on UNIX, ignores SIGCHLD and SIGPIPE signals. If custom 92 // processing is required for these, signal handlers must be set up 93 // after calling mg_start(). 94 // 95 // 96 // Example: 97 // const char *options[] = { 98 // "document_root", "/var/www", 99 // "listening_ports", "80,443s", 100 // NULL 101 // }; 102 // struct mg_context *ctx = mg_start(&my_func, NULL, options); 103 // 104 // Please refer to http://code.google.com/p/mongoose/wiki/MongooseManual 105 // for the list of valid option and their possible values. 106 // 107 // Return: 108 // web server context, or NULL on error. 109 struct mg_context *mg_start(mg_callback_t callback, void *user_data, 110 const char **options); 111 112 113 // Stop the web server. 114 // 115 // Must be called last, when an application wants to stop the web server and 116 // release all associated resources. This function blocks until all Mongoose 117 // threads are stopped. Context pointer becomes invalid. 118 void mg_stop(struct mg_context *); 119 120 121 // Get the value of particular configuration parameter. 122 // The value returned is read-only. Mongoose does not allow changing 123 // configuration at run time. 124 // If given parameter name is not valid, NULL is returned. For valid 125 // names, return value is guaranteed to be non-NULL. If parameter is not 126 // set, zero-length string is returned. 127 const char *mg_get_option(const struct mg_context *ctx, const char *name); 128 129 130 // Return array of strings that represent valid configuration options. 131 // For each option, a short name, long name, and default value is returned. 132 // Array is NULL terminated. 133 const char **mg_get_valid_option_names(void); 134 135 136 // Add, edit or delete the entry in the passwords file. 137 // 138 // This function allows an application to manipulate .htpasswd files on the 139 // fly by adding, deleting and changing user records. This is one of the 140 // several ways of implementing authentication on the server side. For another, 141 // cookie-based way please refer to the examples/chat.c in the source tree. 142 // 143 // If password is not NULL, entry is added (or modified if already exists). 144 // If password is NULL, entry is deleted. 145 // 146 // Return: 147 // 1 on success, 0 on error. 148 int mg_modify_passwords_file(const char *passwords_file_name, 149 const char *domain, 150 const char *user, 151 const char *password); 152 153 // Send data to the client. 154 int mg_write(struct mg_connection *, const void *buf, size_t len); 155 156 157 // Send data to the browser using printf() semantics. 158 // 159 // Works exactly like mg_write(), but allows to do message formatting. 160 // Note that mg_printf() uses internal buffer of size IO_BUF_SIZE 161 // (8 Kb by default) as temporary message storage for formatting. Do not 162 // print data that is bigger than that, otherwise it will be truncated. 163 int mg_printf(struct mg_connection *, const char *fmt, ...); 164 165 166 // Send contents of the entire file together with HTTP headers. 167 void mg_send_file(struct mg_connection *conn, const char *path); 168 169 170 // Read data from the remote end, return number of bytes read. 171 int mg_read(struct mg_connection *, void *buf, size_t len); 172 173 174 // Get the value of particular HTTP header. 175 // 176 // This is a helper function. It traverses request_info->http_headers array, 177 // and if the header is present in the array, returns its value. If it is 178 // not present, NULL is returned. 179 const char *mg_get_header(const struct mg_connection *, const char *name); 180 181 182 // Get a value of particular form variable. 183 // 184 // Parameters: 185 // data: pointer to form-uri-encoded buffer. This could be either POST data, 186 // or request_info.query_string. 187 // data_len: length of the encoded data. 188 // var_name: variable name to decode from the buffer 189 // buf: destination buffer for the decoded variable 190 // buf_len: length of the destination buffer 191 // 192 // Return: 193 // On success, length of the decoded variable. 194 // On error, -1 (variable not found, or destination buffer is too small). 195 // 196 // Destination buffer is guaranteed to be '\0' - terminated. In case of 197 // failure, dst[0] == '\0'. 198 int mg_get_var(const char *data, size_t data_len, 199 const char *var_name, char *buf, size_t buf_len); 200 201 // Fetch value of certain cookie variable into the destination buffer. 202 // 203 // Destination buffer is guaranteed to be '\0' - terminated. In case of 204 // failure, dst[0] == '\0'. Note that RFC allows many occurrences of the same 205 // parameter. This function returns only first occurrence. 206 // 207 // Return: 208 // On success, value length. 209 // On error, 0 (either "Cookie:" header is not present at all, or the 210 // requested parameter is not found, or destination buffer is too small 211 // to hold the value). 212 int mg_get_cookie(const struct mg_connection *, 213 const char *cookie_name, char *buf, size_t buf_len); 214 215 216 // Return Mongoose version. 217 const char *mg_version(void); 218 219 220 // MD5 hash given strings. 221 // Buffer 'buf' must be 33 bytes long. Varargs is a NULL terminated list of 222 // asciiz strings. When function returns, buf will contain human-readable 223 // MD5 hash. Example: 224 // char buf[33]; 225 // mg_md5(buf, "aa", "bb", NULL); 226 void mg_md5(char *buf, ...); 227 228 229 #ifdef __cplusplus 230 } 231 #endif // __cplusplus 232 233 #endif // MONGOOSE_HEADER_INCLUDED 234
