123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258 |
- // 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
- #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 {
- 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
- };
- // 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 *);
- // 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 IO_BUF_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.
- 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);
- // Connect to the remote web server.
- // Return:
- // On success, valid pointer to the new connection
- // On error, NULL
- struct mg_connection *mg_connect(struct mg_context *ctx,
- const char *host, int port, int use_ssl);
- // Download given URL to a given file.
- // url: URL to download
- // path: file name where to save the data
- // request_info: pointer to a structure that will hold parsed reply headers
- // Return:
- // On success, opened file stream to the downloaded contents. The stream
- // is positioned to the end of the file.
- // On error, NULL
- FILE *mg_fetch(struct mg_context *ctx, const char *url, const char *path,
- struct mg_request_info *request_info);
- // Return Mongoose version.
- const char *mg_version(void);
- // 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 // MONGOOSE_HEADER_INCLUDED
|