[b45feba] | 1 | /*
|
---|
| 2 | * Copyright (c) 2004-2009 Sergey Lyubka
|
---|
| 3 | *
|
---|
| 4 | * Permission is hereby granted, free of charge, to any person obtaining a copy
|
---|
| 5 | * of this software and associated documentation files (the "Software"), to deal
|
---|
| 6 | * in the Software without restriction, including without limitation the rights
|
---|
| 7 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
---|
| 8 | * copies of the Software, and to permit persons to whom the Software is
|
---|
| 9 | * furnished to do so, subject to the following conditions:
|
---|
| 10 | *
|
---|
| 11 | * The above copyright notice and this permission notice shall be included in
|
---|
| 12 | * all copies or substantial portions of the Software.
|
---|
| 13 | *
|
---|
| 14 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
---|
| 15 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
---|
| 16 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
---|
| 17 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
---|
| 18 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
---|
| 19 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
---|
| 20 | * THE SOFTWARE.
|
---|
| 21 | *
|
---|
| 22 | * $Id$
|
---|
| 23 | */
|
---|
| 24 |
|
---|
| 25 | #ifndef MONGOOSE_HEADER_INCLUDED
|
---|
| 26 | #define MONGOOSE_HEADER_INCLUDED
|
---|
| 27 |
|
---|
| 28 | #ifdef __cplusplus
|
---|
| 29 | extern "C" {
|
---|
| 30 | #endif /* __cplusplus */
|
---|
| 31 |
|
---|
| 32 | struct mg_context; /* Handle for the HTTP service itself */
|
---|
| 33 | struct mg_connection; /* Handle for the individual connection */
|
---|
| 34 |
|
---|
| 35 |
|
---|
| 36 | /*
|
---|
| 37 | * This structure contains full information about the HTTP request.
|
---|
| 38 | * It is passed to the user-specified callback function as a parameter.
|
---|
| 39 | */
|
---|
| 40 | struct mg_request_info {
|
---|
| 41 | char *request_method; /* "GET", "POST", etc */
|
---|
| 42 | char *uri; /* Normalized URI */
|
---|
| 43 | char *http_version; /* E.g. "1.0", "1.1" */
|
---|
| 44 | char *query_string; /* \0 - terminated */
|
---|
| 45 | char *post_data; /* POST data buffer */
|
---|
| 46 | char *remote_user; /* Authenticated user */
|
---|
| 47 | long remote_ip; /* Client's IP address */
|
---|
| 48 | int remote_port; /* Client's port */
|
---|
| 49 | int post_data_len; /* POST buffer length */
|
---|
| 50 | int status_code; /* HTTP status code */
|
---|
| 51 | int num_headers; /* Number of headers */
|
---|
| 52 | struct mg_header {
|
---|
| 53 | char *name; /* HTTP header name */
|
---|
| 54 | char *value; /* HTTP header value */
|
---|
| 55 | } http_headers[64]; /* Maximum 64 headers */
|
---|
| 56 | };
|
---|
| 57 |
|
---|
| 58 |
|
---|
| 59 | /*
|
---|
| 60 | * User-defined callback function prototype for URI handling, error handling,
|
---|
| 61 | * or logging server messages.
|
---|
| 62 | */
|
---|
| 63 | typedef void (*mg_callback_t)(struct mg_connection *,
|
---|
| 64 | const struct mg_request_info *info, void *user_data);
|
---|
| 65 |
|
---|
| 66 |
|
---|
| 67 | /*
|
---|
| 68 | * Start the web server.
|
---|
| 69 | * This must be the first function called by the application.
|
---|
| 70 | * It creates a serving thread, and returns a context structure that
|
---|
| 71 | * can be used to alter the configuration, and stop the server.
|
---|
| 72 | */
|
---|
| 73 | struct mg_context *mg_start(void);
|
---|
| 74 |
|
---|
| 75 |
|
---|
| 76 | /*
|
---|
| 77 | * Stop the web server.
|
---|
| 78 | * Must be called last, when an application wants to stop the web server and
|
---|
| 79 | * release all associated resources. This function blocks until all Mongoose
|
---|
| 80 | * threads are stopped. Context pointer becomes invalid.
|
---|
| 81 | */
|
---|
| 82 | void mg_stop(struct mg_context *);
|
---|
| 83 |
|
---|
| 84 |
|
---|
| 85 | /*
|
---|
| 86 | * Return current value of a particular option.
|
---|
| 87 | */
|
---|
| 88 | const char *mg_get_option(const struct mg_context *, const char *option_name);
|
---|
| 89 |
|
---|
| 90 |
|
---|
| 91 | /*
|
---|
| 92 | * Set a value for a particular option.
|
---|
| 93 | * Mongoose makes an internal copy of the option value string, which must be
|
---|
| 94 | * valid nul-terminated ASCII or UTF-8 string. It is safe to change any option
|
---|
| 95 | * at any time. The order of setting various options is also irrelevant with
|
---|
| 96 | * one exception: if "ports" option contains SSL listening ports, a "ssl_cert"
|
---|
| 97 | * option must be set BEFORE the "ports" option.
|
---|
| 98 | * Return value:
|
---|
| 99 | * -1 if option is unknown
|
---|
| 100 | * 0 if mg_set_option() failed
|
---|
| 101 | * 1 if mg_set_option() succeeded
|
---|
| 102 | */
|
---|
| 103 | int mg_set_option(struct mg_context *, const char *opt_name, const char *value);
|
---|
| 104 |
|
---|
| 105 |
|
---|
| 106 | /*
|
---|
| 107 | * Add, edit or delete the entry in the passwords file.
|
---|
| 108 | * This function allows an application to manipulate .htpasswd files on the
|
---|
| 109 | * fly by adding, deleting and changing user records. This is one of the two
|
---|
| 110 | * ways of implementing authentication on the server side. For another,
|
---|
| 111 | * cookie-based way please refer to the examples/authentication.c in the
|
---|
| 112 | * source tree.
|
---|
| 113 | * If password is not NULL, entry is added (or modified if already exists).
|
---|
| 114 | * If password is NULL, entry is deleted. Return:
|
---|
| 115 | * 1 on success
|
---|
| 116 | * 0 on error
|
---|
| 117 | */
|
---|
| 118 | int mg_modify_passwords_file(struct mg_context *ctx, const char *file_name,
|
---|
| 119 | const char *user_name, const char *password);
|
---|
| 120 |
|
---|
| 121 |
|
---|
| 122 | /*
|
---|
| 123 | * Register URI handler.
|
---|
| 124 | * It is possible to handle many URIs if using * in the uri_regex, which
|
---|
| 125 | * matches zero or more characters. user_data pointer will be passed to the
|
---|
| 126 | * handler as a third parameter. If func is NULL, then the previously installed
|
---|
| 127 | * handler for this uri_regex is removed.
|
---|
| 128 | */
|
---|
| 129 | void mg_set_uri_callback(struct mg_context *ctx, const char *uri_regex,
|
---|
| 130 | mg_callback_t func, void *user_data);
|
---|
| 131 |
|
---|
| 132 |
|
---|
| 133 | /*
|
---|
| 134 | * Register HTTP error handler.
|
---|
| 135 | * An application may use that function if it wants to customize the error
|
---|
| 136 | * page that user gets on the browser (for example, 404 File Not Found message).
|
---|
| 137 | * It is possible to specify a error handler for all errors by passing 0 as
|
---|
| 138 | * error_code. That '0' error handler must be set last, if more specific error
|
---|
| 139 | * handlers are also used. The actual error code value can be taken from
|
---|
| 140 | * the request info structure that is passed to the callback.
|
---|
| 141 | */
|
---|
| 142 | void mg_set_error_callback(struct mg_context *ctx, int error_code,
|
---|
| 143 | mg_callback_t func, void *user_data);
|
---|
| 144 |
|
---|
| 145 |
|
---|
| 146 | /*
|
---|
| 147 | * Register authorization handler.
|
---|
| 148 | * This function provides a mechanism to implement custom authorization,
|
---|
| 149 | * for example cookie based (look at examples/authorization.c).
|
---|
| 150 | * The callback function must analyze the request, and make its own judgement
|
---|
| 151 | * on wether it should be authorized or not. After the decision is made, a
|
---|
| 152 | * callback must call mg_authorize() if the request is authorized.
|
---|
| 153 | */
|
---|
| 154 | void mg_set_auth_callback(struct mg_context *ctx, const char *uri_regex,
|
---|
| 155 | mg_callback_t func, void *user_data);
|
---|
| 156 |
|
---|
| 157 |
|
---|
| 158 | /*
|
---|
| 159 | * Register log handler.
|
---|
| 160 | * By default, Mongoose logs all error messages to stderr. If "error_log"
|
---|
| 161 | * option is specified, the errors are written in the specified file. However,
|
---|
| 162 | * if an application registers its own log handler, Mongoose will not log
|
---|
| 163 | * anything but call the handler function, passing an error message as
|
---|
| 164 | * "user_data" callback argument.
|
---|
| 165 | */
|
---|
| 166 | void mg_set_log_callback(struct mg_context *ctx, mg_callback_t func);
|
---|
| 167 |
|
---|
| 168 |
|
---|
| 169 | /*
|
---|
| 170 | * Register SSL password handler.
|
---|
| 171 | * This is needed only if SSL certificate asks for a password. Instead of
|
---|
| 172 | * prompting for a password on a console a specified function will be called.
|
---|
| 173 | */
|
---|
| 174 | typedef int (*mg_spcb_t)(char *buf, int num, int w, void *key);
|
---|
| 175 | void mg_set_ssl_password_callback(struct mg_context *ctx, mg_spcb_t func);
|
---|
| 176 |
|
---|
| 177 |
|
---|
| 178 | /*
|
---|
| 179 | * Send data to the browser.
|
---|
| 180 | * Return number of bytes sent. If the number of bytes sent is less then
|
---|
| 181 | * requested or equals to -1, network error occured, usually meaning the
|
---|
| 182 | * remote side has closed the connection.
|
---|
| 183 | */
|
---|
| 184 | int mg_write(struct mg_connection *, const void *buf, int len);
|
---|
| 185 |
|
---|
| 186 |
|
---|
| 187 | /*
|
---|
| 188 | * Send data to the browser using printf() semantics.
|
---|
| 189 | * Works exactly like mg_write(), but allows to do message formatting.
|
---|
| 190 | * Note that mg_printf() uses internal buffer of size MAX_REQUEST_SIZE
|
---|
| 191 | * (8 Kb by default) as temporary message storage for formatting. Do not
|
---|
| 192 | * print data that is bigger than that, otherwise it will be truncated.
|
---|
| 193 | * Return number of bytes sent.
|
---|
| 194 | */
|
---|
| 195 | int mg_printf(struct mg_connection *, const char *fmt, ...);
|
---|
| 196 |
|
---|
| 197 |
|
---|
| 198 | /*
|
---|
| 199 | * Read data from the remote or local end.
|
---|
| 200 | */
|
---|
| 201 | int mg_read(struct mg_connection *, int local, void *buf, int len);
|
---|
| 202 |
|
---|
| 203 | /*
|
---|
| 204 | * Get the value of particular HTTP header.
|
---|
| 205 | * This is a helper function. It traverses request_info->http_headers array,
|
---|
| 206 | * and if the header is present in the array, returns its value. If it is
|
---|
| 207 | * not present, NULL is returned.
|
---|
| 208 | */
|
---|
| 209 | const char *mg_get_header(const struct mg_connection *, const char *hdr_name);
|
---|
| 210 |
|
---|
| 211 |
|
---|
| 212 | /*
|
---|
| 213 | * Authorize the request.
|
---|
| 214 | * See the documentation for mg_set_auth_callback() function.
|
---|
| 215 | */
|
---|
| 216 | void mg_authorize(struct mg_connection *);
|
---|
| 217 |
|
---|
| 218 |
|
---|
| 219 | /*
|
---|
| 220 | * Get a value of particular form variable.
|
---|
| 221 | * Both query string (whatever comes after '?' in the URL) and a POST buffer
|
---|
| 222 | * are scanned. If a variable is specified in both query string and POST
|
---|
| 223 | * buffer, POST buffer wins. Return value:
|
---|
| 224 | * NULL if the variable is not found
|
---|
| 225 | * non-NULL if found. NOTE: this returned value is dynamically allocated
|
---|
| 226 | * and is subject to mg_free() when no longer needed. It is
|
---|
| 227 | * an application's responsibility to mg_free() the variable.
|
---|
| 228 | */
|
---|
| 229 | char *mg_get_var(const struct mg_connection *, const char *var_name);
|
---|
| 230 |
|
---|
| 231 |
|
---|
| 232 | /*
|
---|
| 233 | * Free up memory returned by mg_get_var().
|
---|
| 234 | */
|
---|
| 235 | void mg_free(char *var);
|
---|
| 236 |
|
---|
| 237 |
|
---|
| 238 | /*
|
---|
| 239 | * Return Mongoose version.
|
---|
| 240 | */
|
---|
| 241 | const char *mg_version(void);
|
---|
| 242 |
|
---|
| 243 |
|
---|
| 244 | /*
|
---|
| 245 | * Print command line usage string.
|
---|
| 246 | */
|
---|
| 247 | void mg_show_usage_string(FILE *fp);
|
---|
| 248 |
|
---|
| 249 | #ifdef __cplusplus
|
---|
| 250 | }
|
---|
| 251 | #endif /* __cplusplus */
|
---|
| 252 |
|
---|
| 253 | #endif /* MONGOOSE_HEADER_INCLUDED */
|
---|