diff options
Diffstat (limited to 'cpukit/mghttpd/mongoose.h')
| -rw-r--r-- | cpukit/mghttpd/mongoose.h | 290 |
1 files changed, 219 insertions, 71 deletions
diff --git a/cpukit/mghttpd/mongoose.h b/cpukit/mghttpd/mongoose.h index c130fe7b84..ad7c40f2dd 100644 --- a/cpukit/mghttpd/mongoose.h +++ b/cpukit/mghttpd/mongoose.h @@ -1,4 +1,4 @@ -// Copyright (c) 2004-2011 Sergey Lyubka +// Copyright (c) 2004-2012 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 @@ -21,6 +21,7 @@ #ifndef MONGOOSE_HEADER_INCLUDED #define MONGOOSE_HEADER_INCLUDED +#include <stdio.h> #include <stddef.h> #ifdef __cplusplus @@ -33,59 +34,102 @@ struct mg_connection; // Handle for the individual connection // This structure contains information about the HTTP request. struct mg_request_info { - 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 + const char *request_method; // "GET", "POST", etc + const char *uri; // URL-decoded URI + const char *http_version; // E.g. "1.0", "1.1" + const char *query_string; // URL part after '?', not including '?', or NULL + const char *remote_user; // Authenticated user, or NULL if no auth used + long remote_ip; // Client's IP address + int remote_port; // Client's port + int is_ssl; // 1 if SSL-ed, 0 if not + void *user_data; // User data pointer passed to mg_start() + void *conn_data; // Connection-specific user data + + int num_headers; // Number of HTTP headers struct mg_header { - char *name; // HTTP header name - char *value; // HTTP header value - } http_headers[64]; // Maximum 64 headers + const char *name; // HTTP header name + const 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 -}; - -// 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); +// This structure needs to be passed to mg_start(), to let mongoose know +// which callbacks to invoke. For detailed description, see +// https://github.com/valenok/mongoose/blob/master/UserManual.md +struct mg_callbacks { + // Called when mongoose has received new HTTP request. + // If callback returns non-zero, + // callback must process the request by sending valid HTTP headers and body, + // and mongoose will not do any further processing. + // If callback returns 0, mongoose processes the request itself. In this case, + // callback must not send any data to the client. + int (*begin_request)(struct mg_connection *); + + // Called when mongoose has finished processing request. + void (*end_request)(const struct mg_connection *, int reply_status_code); + + // Called when mongoose is about to log a message. If callback returns + // non-zero, mongoose does not log anything. + int (*log_message)(const struct mg_connection *, const char *message); + + // Called when mongoose initializes SSL library. + int (*init_ssl)(void *ssl_context, void *user_data); + + // Called when websocket request is received, before websocket handshake. + // If callback returns 0, mongoose proceeds with handshake, otherwise + // cinnection is closed immediately. + int (*websocket_connect)(const struct mg_connection *); + + // Called when websocket handshake is successfully completed, and + // connection is ready for data exchange. + void (*websocket_ready)(struct mg_connection *); + + // Called when data frame has been received from the client. + // Parameters: + // bits: first byte of the websocket frame, see websocket RFC at + // http://tools.ietf.org/html/rfc6455, section 5.2 + // data, data_len: payload, with mask (if any) already applied. + // Return value: + // non-0: keep this websocket connection opened. + // 0: close this websocket connection. + int (*websocket_data)(struct mg_connection *, int bits, + char *data, size_t data_len); + + // Called when mongoose tries to open a file. Used to intercept file open + // calls, and serve file data from memory instead. + // Parameters: + // path: Full path to the file to open. + // data_len: Placeholder for the file size, if file is served from memory. + // Return value: + // NULL: do not serve file from memory, proceed with normal file open. + // non-NULL: pointer to the file contents in memory. data_len must be + // initilized with the size of the memory block. + const char * (*open_file)(const struct mg_connection *, + const char *path, size_t *data_len); + + // Called when mongoose is about to serve Lua server page (.lp file), if + // Lua support is enabled. + // Parameters: + // lua_context: "lua_State *" pointer. + void (*init_lua)(struct mg_connection *, void *lua_context); + + // Called when mongoose has uploaded a file to a temporary directory as a + // result of mg_upload() call. + // Parameters: + // file_file: full path name to the uploaded file. + void (*upload)(struct mg_connection *, const char *file_name); + + // Called when mongoose is about to send HTTP error to the client. + // Implementing this callback allows to create custom error pages. + // Parameters: + // status: HTTP error status code. + int (*http_error)(struct mg_connection *, int status); +}; // Start web server. // // Parameters: -// callback: user defined event handling function or NULL. +// callbacks: mg_callbacks structure with user-defined callbacks. // options: NULL terminated list of option_name, option_value pairs that // specify Mongoose configuration parameters. // @@ -102,13 +146,14 @@ typedef void * (*mg_callback_t)(enum mg_event event, // }; // struct mg_context *ctx = mg_start(&my_func, NULL, options); // -// Please refer to http://code.google.com/p/mongoose/wiki/MongooseManual +// Refer to https://github.com/valenok/mongoose/blob/master/UserManual.md // 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); +struct mg_context *mg_start(const struct mg_callbacks *callbacks, + void *user_data, + const char **configuration_options); // Stop the web server. @@ -129,7 +174,8 @@ 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. +// For each option, option name and default value is returned, i.e. the +// number of entries in the array equals to number_of_options x 2. // Array is NULL terminated. const char **mg_get_valid_option_names(void); @@ -151,21 +197,65 @@ int mg_modify_passwords_file(const char *passwords_file_name, const char *user, const char *password); + +// Return information associated with the request. +struct mg_request_info *mg_get_request_info(struct mg_connection *); + + // Send data to the client. +// Return: +// 0 when the connection has been closed +// -1 on error +// >0 number of bytes written on success int mg_write(struct mg_connection *, const void *buf, size_t len); -// Send data to the browser using printf() semantics. +// Send data to a websocket client wrapped in a websocket frame. +// It is unsafe to read/write to this connection from another thread. +// This function is available when mongoose is compiled with -DUSE_WEBSOCKET // -// 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, ...) +// Return: +// 0 when the connection has been closed +// -1 on error +// >0 number of bytes written on success +int mg_websocket_write(struct mg_connection* conn, int opcode, + const char *data, size_t data_len); + +// Opcodes, from http://tools.ietf.org/html/rfc6455 +enum { + WEBSOCKET_OPCODE_CONTINUATION = 0x0, + WEBSOCKET_OPCODE_TEXT = 0x1, + WEBSOCKET_OPCODE_BINARY = 0x2, + WEBSOCKET_OPCODE_CONNECTION_CLOSE = 0x8, + WEBSOCKET_OPCODE_PING = 0x9, + WEBSOCKET_OPCODE_PONG = 0xa +}; + + +// Macros for enabling compiler-specific checks for printf-like arguments. +#undef PRINTF_FORMAT_STRING +#if defined(_MSC_VER) && _MSC_VER >= 1400 +#include <sal.h> +#if defined(_MSC_VER) && _MSC_VER > 1400 +#define PRINTF_FORMAT_STRING(s) _Printf_format_string_ s +#else +#define PRINTF_FORMAT_STRING(s) __format_string s +#endif +#else +#define PRINTF_FORMAT_STRING(s) s +#endif + #ifdef __GNUC__ -__attribute__((format(printf, 2, 3))) +#define PRINTF_ARGS(x, y) __attribute__((format(printf, x, y))) +#else +#define PRINTF_ARGS(x, y) #endif -; + +// Send data to the client using printf() semantics. +// +// Works exactly like mg_write(), but allows to do message formatting. +int mg_printf(struct mg_connection *, + PRINTF_FORMAT_STRING(const char *fmt), ...) PRINTF_ARGS(2, 3); // Send contents of the entire file together with HTTP headers. @@ -173,6 +263,10 @@ void mg_send_file(struct mg_connection *conn, const char *path); // Read data from the remote end, return number of bytes read. +// Return: +// 0 connection has been closed by peer. No more data could be read. +// < 0 read error. No more data could be read from the connection. +// > 0 number of bytes read into the buffer. int mg_read(struct mg_connection *, void *buf, size_t len); @@ -191,17 +285,20 @@ const char *mg_get_header(const struct mg_connection *, const char *name); // 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 +// dst: destination buffer for the decoded variable +// dst_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). +// On error: +// -1 (variable not found). +// -2 (destination buffer is NULL, zero length or too small to hold the +// decoded variable). // -// Destination buffer is guaranteed to be '\0' - terminated. In case of -// failure, dst[0] == '\0'. +// Destination buffer is guaranteed to be '\0' - terminated if it is not +// NULL or zero length. int mg_get_var(const char *data, size_t data_len, - const char *var_name, char *buf, size_t buf_len); + const char *var_name, char *dst, size_t dst_len); // Fetch value of certain cookie variable into the destination buffer. // @@ -211,24 +308,75 @@ int mg_get_var(const char *data, size_t data_len, // // 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); +// On error: +// -1 (either "Cookie:" header is not present at all or the requested +// parameter is not found). +// -2 (destination buffer is NULL, zero length or too small to hold the +// value). +int mg_get_cookie(const char *cookie, const char *var_name, + char *buf, size_t buf_len); + + +// Download data from the remote web server. +// host: host name to connect to, e.g. "foo.com", or "10.12.40.1". +// port: port number, e.g. 80. +// use_ssl: wether to use SSL connection. +// error_buffer, error_buffer_size: error message placeholder. +// request_fmt,...: HTTP request. +// Return: +// On success, valid pointer to the new connection, suitable for mg_read(). +// On error, NULL. error_buffer contains error message. +// Example: +// char ebuf[100]; +// struct mg_connection *conn; +// conn = mg_download("google.com", 80, 0, ebuf, sizeof(ebuf), +// "%s", "GET / HTTP/1.0\r\nHost: google.com\r\n\r\n"); +struct mg_connection *mg_download(const char *host, int port, int use_ssl, + char *error_buffer, size_t error_buffer_size, + PRINTF_FORMAT_STRING(const char *request_fmt), + ...) PRINTF_ARGS(6, 7); + + +// Close the connection opened by mg_download(). +void mg_close_connection(struct mg_connection *conn); + + +// File upload functionality. Each uploaded file gets saved into a temporary +// file and MG_UPLOAD event is sent. +// Return number of uploaded files. +int mg_upload(struct mg_connection *conn, const char *destination_dir); + + +// Convenience function -- create detached thread. +// Return: 0 on success, non-0 on error. +typedef void * (*mg_thread_func_t)(void *); +int mg_start_thread(mg_thread_func_t f, void *p); + + +// Return builtin mime type for the given file name. +// For unrecognized extensions, "text/plain" is returned. +const char *mg_get_builtin_mime_type(const char *file_name); // Return Mongoose version. const char *mg_version(void); +// URL-decode input buffer into destination buffer. +// 0-terminate the destination buffer. +// form-url-encoded data differs from URI encoding in a way that it +// uses '+' as character for space, see RFC 1866 section 8.2.1 +// http://ftp.ics.uci.edu/pub/ietf/html/rfc1866.txt +// Return: length of the decoded data, or -1 if dst buffer is too small. +int mg_url_decode(const char *src, int src_len, char *dst, + int dst_len, int is_form_url_encoded); // 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 +// 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, ...); +char *mg_md5(char buf[33], ...); #ifdef __cplusplus |