diff options
Diffstat (limited to 'cpukit/mghttpd/mongoose.h')
| -rw-r--r-- | cpukit/mghttpd/mongoose.h | 253 |
1 files changed, 253 insertions, 0 deletions
diff --git a/cpukit/mghttpd/mongoose.h b/cpukit/mghttpd/mongoose.h new file mode 100644 index 0000000000..6ff2c28d7f --- /dev/null +++ b/cpukit/mghttpd/mongoose.h @@ -0,0 +1,253 @@ +/* + * Copyright (c) 2004-2009 Sergey Lyubka + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + * + * $Id$ + */ + +#ifndef MONGOOSE_HEADER_INCLUDED +#define MONGOOSE_HEADER_INCLUDED + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +struct mg_context; /* Handle for the HTTP service itself */ +struct mg_connection; /* Handle for the individual connection */ + + +/* + * This structure contains full information about the HTTP request. + * It is passed to the user-specified callback function as a parameter. + */ +struct mg_request_info { + char *request_method; /* "GET", "POST", etc */ + char *uri; /* Normalized URI */ + char *http_version; /* E.g. "1.0", "1.1" */ + char *query_string; /* \0 - terminated */ + char *post_data; /* POST data buffer */ + char *remote_user; /* Authenticated user */ + long remote_ip; /* Client's IP address */ + int remote_port; /* Client's port */ + int post_data_len; /* POST buffer length */ + int status_code; /* HTTP status code */ + int num_headers; /* Number of headers */ + struct mg_header { + char *name; /* HTTP header name */ + char *value; /* HTTP header value */ + } http_headers[64]; /* Maximum 64 headers */ +}; + + +/* + * User-defined callback function prototype for URI handling, error handling, + * or logging server messages. + */ +typedef void (*mg_callback_t)(struct mg_connection *, + const struct mg_request_info *info, void *user_data); + + +/* + * Start the web server. + * This must be the first function called by the application. + * It creates a serving thread, and returns a context structure that + * can be used to alter the configuration, and stop the server. + */ +struct mg_context *mg_start(void); + + +/* + * Stop the web server. + * Must be called last, when an application wants to stop the web server and + * release all associated resources. This function blocks until all Mongoose + * threads are stopped. Context pointer becomes invalid. + */ +void mg_stop(struct mg_context *); + + +/* + * Return current value of a particular option. + */ +const char *mg_get_option(const struct mg_context *, const char *option_name); + + +/* + * Set a value for a particular option. + * Mongoose makes an internal copy of the option value string, which must be + * valid nul-terminated ASCII or UTF-8 string. It is safe to change any option + * at any time. The order of setting various options is also irrelevant with + * one exception: if "ports" option contains SSL listening ports, a "ssl_cert" + * option must be set BEFORE the "ports" option. + * Return value: + * -1 if option is unknown + * 0 if mg_set_option() failed + * 1 if mg_set_option() succeeded + */ +int mg_set_option(struct mg_context *, const char *opt_name, const char *value); + + +/* + * Add, edit or delete the entry in the passwords file. + * This function allows an application to manipulate .htpasswd files on the + * fly by adding, deleting and changing user records. This is one of the two + * ways of implementing authentication on the server side. For another, + * cookie-based way please refer to the examples/authentication.c in the + * source tree. + * If password is not NULL, entry is added (or modified if already exists). + * If password is NULL, entry is deleted. Return: + * 1 on success + * 0 on error + */ +int mg_modify_passwords_file(struct mg_context *ctx, const char *file_name, + const char *user_name, const char *password); + + +/* + * Register URI handler. + * It is possible to handle many URIs if using * in the uri_regex, which + * matches zero or more characters. user_data pointer will be passed to the + * handler as a third parameter. If func is NULL, then the previously installed + * handler for this uri_regex is removed. + */ +void mg_set_uri_callback(struct mg_context *ctx, const char *uri_regex, + mg_callback_t func, void *user_data); + + +/* + * Register HTTP error handler. + * An application may use that function if it wants to customize the error + * page that user gets on the browser (for example, 404 File Not Found message). + * It is possible to specify a error handler for all errors by passing 0 as + * error_code. That '0' error handler must be set last, if more specific error + * handlers are also used. The actual error code value can be taken from + * the request info structure that is passed to the callback. + */ +void mg_set_error_callback(struct mg_context *ctx, int error_code, + mg_callback_t func, void *user_data); + + +/* + * Register authorization handler. + * This function provides a mechanism to implement custom authorization, + * for example cookie based (look at examples/authorization.c). + * The callback function must analyze the request, and make its own judgement + * on wether it should be authorized or not. After the decision is made, a + * callback must call mg_authorize() if the request is authorized. + */ +void mg_set_auth_callback(struct mg_context *ctx, const char *uri_regex, + mg_callback_t func, void *user_data); + + +/* + * Register log handler. + * By default, Mongoose logs all error messages to stderr. If "error_log" + * option is specified, the errors are written in the specified file. However, + * if an application registers its own log handler, Mongoose will not log + * anything but call the handler function, passing an error message as + * "user_data" callback argument. + */ +void mg_set_log_callback(struct mg_context *ctx, mg_callback_t func); + + +/* + * Register SSL password handler. + * This is needed only if SSL certificate asks for a password. Instead of + * prompting for a password on a console a specified function will be called. + */ +typedef int (*mg_spcb_t)(char *buf, int num, int w, void *key); +void mg_set_ssl_password_callback(struct mg_context *ctx, mg_spcb_t func); + + +/* + * Send data to the browser. + * Return number of bytes sent. If the number of bytes sent is less then + * requested or equals to -1, network error occured, usually meaning the + * remote side has closed the connection. + */ +int mg_write(struct mg_connection *, const void *buf, int len); + + +/* + * Send data to the browser using printf() semantics. + * Works exactly like mg_write(), but allows to do message formatting. + * Note that mg_printf() uses internal buffer of size MAX_REQUEST_SIZE + * (8 Kb by default) as temporary message storage for formatting. Do not + * print data that is bigger than that, otherwise it will be truncated. + * Return number of bytes sent. + */ +int mg_printf(struct mg_connection *, const char *fmt, ...); + + +/* + * Read data from the remote or local end. + */ +int mg_read(struct mg_connection *, int local, void *buf, int len); + +/* + * Get the value of particular HTTP header. + * This is a helper function. It traverses request_info->http_headers array, + * and if the header is present in the array, returns its value. If it is + * not present, NULL is returned. + */ +const char *mg_get_header(const struct mg_connection *, const char *hdr_name); + + +/* + * Authorize the request. + * See the documentation for mg_set_auth_callback() function. + */ +void mg_authorize(struct mg_connection *); + + +/* + * Get a value of particular form variable. + * Both query string (whatever comes after '?' in the URL) and a POST buffer + * are scanned. If a variable is specified in both query string and POST + * buffer, POST buffer wins. Return value: + * NULL if the variable is not found + * non-NULL if found. NOTE: this returned value is dynamically allocated + * and is subject to mg_free() when no longer needed. It is + * an application's responsibility to mg_free() the variable. + */ +char *mg_get_var(const struct mg_connection *, const char *var_name); + + +/* + * Free up memory returned by mg_get_var(). + */ +void mg_free(char *var); + + +/* + * Return Mongoose version. + */ +const char *mg_version(void); + + +/* + * Print command line usage string. + */ +void mg_show_usage_string(FILE *fp); + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif /* MONGOOSE_HEADER_INCLUDED */ |