LXR 6.1/​cpukit/​include/​mghttpd/​mongoose.h	Source navigation Diff markup Identifier search General search
	Version: 6.1 Revert   Change

File indexing completed on 2025-05-11 08:24:12

 // 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
 // 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
 
 #include <stdio.h>
 #include <stddef.h>
 
 #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 information about the HTTP request.
 struct mg_request_info {
   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 {
     const char *name;         // HTTP header name
     const char *value;        // HTTP header value
   } http_headers[64];         // Maximum 64 headers
 };
 
 
 // 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);
 
   // Called when mongoose needs to generate an HTTP etag.
   // Implementing this callback allows a custom etag to be generated. If
   // not implemented the standard etag generator is used which is the
   // modification time as a hex value and the file size.
   // Use this callback if the modification time cannot be controlled.
   // Parameters:
   //   path: path to the file being requested
   //   etag: buffer to write the etag into
   //   etag_len: the length of the etag buffer
   // Return value:
   int  (*http_etag)(const struct mg_connection *,
                     const char *path, char *etag, size_t etag_len);
 };
 
 // Start web server.
 //
 // Parameters:
 //   callbacks: mg_callbacks structure with user-defined callbacks.
 //   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);
 //
 // 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(const struct mg_callbacks *callbacks,
                             void *user_data,
                             const char **configuration_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 *);
 
 
 // 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, 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);
 
 
 // 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);
 
 
 // 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 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
 //
 // 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__
 #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);
 #ifdef __rtems__
 struct rtems_printer;
 void rtems_print_printer_mg_printf(struct rtems_printer *, struct mg_connection *);
 #endif /* __rtems__ */
 
 
 // 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.
 // 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);
 
 
 // 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
 //   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).
 //      -2 (destination buffer is NULL, zero length or too small to hold the
 //          decoded variable).
 //
 // 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 *dst, size_t dst_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:
 //      -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
 // MD5 hash. Example:
 //   char buf[33];
 //   mg_md5(buf, "aa", "bb", NULL);
 char *mg_md5(char buf[33], ...);
 
 
 #ifdef __cplusplus
 }
 #endif // __cplusplus
 
 #endif // MONGOOSE_HEADER_INCLUDED

This page was automatically generated by the 2.3.7 LXR engine. The LXR team