diff options
Diffstat (limited to 'cpukit/mghttpd/mongoose.h')
| -rw-r--r-- | cpukit/mghttpd/mongoose.h | 445 |
1 files changed, 216 insertions, 229 deletions
diff --git a/cpukit/mghttpd/mongoose.h b/cpukit/mghttpd/mongoose.h index 5a71e6095d..c130fe7b84 100644 --- a/cpukit/mghttpd/mongoose.h +++ b/cpukit/mghttpd/mongoose.h @@ -1,251 +1,238 @@ -/* - * 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. - */ +// Copyright (c) 2004-2011 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. #ifndef MONGOOSE_HEADER_INCLUDED -#define MONGOOSE_HEADER_INCLUDED +#define MONGOOSE_HEADER_INCLUDED + +#include <stddef.h> #ifdef __cplusplus extern "C" { -#endif /* __cplusplus */ +#endif // __cplusplus -struct mg_context; /* Handle for the HTTP service itself */ -struct mg_connection; /* Handle for the individual connection */ +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. - */ +// This structure contains information about the HTTP request. 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 */ + void *user_data; // User-defined pointer passed to mg_start() + char *request_method; // "GET", "POST", etc + char *uri; // URL-decoded URI + char *http_version; // E.g. "1.0", "1.1" + char *query_string; // URL part after '?' (not including '?') or NULL + char *remote_user; // Authenticated user, or NULL if no auth used + char *log_message; // Mongoose error log message, MG_EVENT_LOG only + long remote_ip; // Client's IP address + int remote_port; // Client's port + int status_code; // HTTP reply status code, e.g. 200 + int is_ssl; // 1 if SSL-ed, 0 if not + 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 }; +// Various events on which user-defined function is called by Mongoose. +enum mg_event { + MG_NEW_REQUEST, // New HTTP request has arrived from the client + MG_HTTP_ERROR, // HTTP error must be returned to the client + MG_EVENT_LOG, // Mongoose logs an event, request_info.log_message + MG_INIT_SSL, // Mongoose initializes SSL. Instead of mg_connection *, + // SSL context is passed to the callback function. + MG_REQUEST_COMPLETE // Mongoose has finished handling the request +}; -/* - * 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. - */ +// Prototype for the user-defined function. Mongoose calls this function +// on every MG_* event. +// +// Parameters: +// event: which event has been triggered. +// conn: opaque connection handler. Could be used to read, write data to the +// client, etc. See functions below that have "mg_connection *" arg. +// request_info: Information about HTTP request. +// +// Return: +// If handler returns non-NULL, that means that handler has processed the +// request by sending appropriate HTTP reply to the client. Mongoose treats +// the request as served. +// If handler returns NULL, that means that handler has not processed +// the request. Handler must not send any data to the client in this case. +// Mongoose proceeds with request handling as if nothing happened. +typedef void * (*mg_callback_t)(enum mg_event event, + struct mg_connection *conn, + const struct mg_request_info *request_info); + + +// Start web server. +// +// Parameters: +// callback: user defined event handling function or NULL. +// options: NULL terminated list of option_name, option_value pairs that +// specify Mongoose configuration parameters. +// +// Side-effects: on UNIX, ignores SIGCHLD and SIGPIPE signals. If custom +// processing is required for these, signal handlers must be set up +// after calling mg_start(). +// +// +// Example: +// const char *options[] = { +// "document_root", "/var/www", +// "listening_ports", "80,443s", +// NULL +// }; +// struct mg_context *ctx = mg_start(&my_func, NULL, options); +// +// Please refer to http://code.google.com/p/mongoose/wiki/MongooseManual +// for the list of valid option and their possible values. +// +// Return: +// web server context, or NULL on error. +struct mg_context *mg_start(mg_callback_t callback, void *user_data, + const char **options); + + +// 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. - */ +// Get the value of particular configuration parameter. +// The value returned is read-only. Mongoose does not allow changing +// configuration at run time. +// If given parameter name is not valid, NULL is returned. For valid +// names, return value is guaranteed to be non-NULL. If parameter is not +// set, zero-length string is returned. +const char *mg_get_option(const struct mg_context *ctx, const char *name); + + +// Return array of strings that represent valid configuration options. +// For each option, a short name, long name, and default value is returned. +// Array is NULL terminated. +const char **mg_get_valid_option_names(void); + + +// 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 +// several ways of implementing authentication on the server side. For another, +// cookie-based way please refer to the examples/chat.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(const char *passwords_file_name, + const char *domain, + const char *user, + const char *password); + +// Send data to the client. +int mg_write(struct mg_connection *, const void *buf, size_t 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 BUFSIZ defined in <stdio.h> +// (8 KiB on most Linux systems) as temporary message storage for formatting. +// Do not print data that is bigger than that, otherwise it will be truncated. +int mg_printf(struct mg_connection *, const char *fmt, ...) +#ifdef __GNUC__ +__attribute__((format(printf, 2, 3))) +#endif +; + + +// Send contents of the entire file together with HTTP headers. +void mg_send_file(struct mg_connection *conn, const char *path); + + +// Read data from the remote end, return number of bytes read. +int mg_read(struct mg_connection *, void *buf, size_t 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 *name); + + +// Get a value of particular form variable. +// +// Parameters: +// data: pointer to form-uri-encoded buffer. This could be either POST data, +// or request_info.query_string. +// data_len: length of the encoded data. +// var_name: variable name to decode from the buffer +// buf: destination buffer for the decoded variable +// buf_len: length of the destination buffer +// +// Return: +// On success, length of the decoded variable. +// On error, -1 (variable not found, or destination buffer is too small). +// +// Destination buffer is guaranteed to be '\0' - terminated. In case of +// failure, dst[0] == '\0'. +int mg_get_var(const char *data, size_t data_len, + const char *var_name, char *buf, size_t buf_len); + +// Fetch value of certain cookie variable into the destination buffer. +// +// Destination buffer is guaranteed to be '\0' - terminated. In case of +// failure, dst[0] == '\0'. Note that RFC allows many occurrences of the same +// parameter. This function returns only first occurrence. +// +// Return: +// On success, value length. +// On error, 0 (either "Cookie:" header is not present at all, or the +// requested parameter is not found, or destination buffer is too small +// to hold the value). +int mg_get_cookie(const struct mg_connection *, + const char *cookie_name, char *buf, size_t buf_len); + + +// Return Mongoose version. const char *mg_version(void); -/* - * Print command line usage string. - */ -void mg_show_usage_string(FILE *fp); +// MD5 hash given strings. +// Buffer 'buf' must be 33 bytes long. Varargs is a NULL terminated list of +// asciiz strings. When function returns, buf will contain human-readable +// MD5 hash. Example: +// char buf[33]; +// mg_md5(buf, "aa", "bb", NULL); +void mg_md5(char *buf, ...); + #ifdef __cplusplus } -#endif /* __cplusplus */ +#endif // __cplusplus -#endif /* MONGOOSE_HEADER_INCLUDED */ +#endif // MONGOOSE_HEADER_INCLUDED |