diff --git a/mongoose.h b/mongoose.h index 213c72de..1b0819ba 100644 --- a/mongoose.h +++ b/mongoose.h @@ -1,246 +1,211 @@ -/* - * 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: mongoose.h 517 2010-05-03 12:54:59Z valenok $ - */ +// Copyright (c) 2004-2010 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 #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 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 */ - char *log_message; /* Mongoose error log message */ - 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 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 */ + char *request_method; // "GET", "POST", etc + char *uri; // URL-decoded 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 + char *log_message; // Mongoose error log message + 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 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 }; - -/* - * User-defined handler function. It must return MG_SUCCESS or MG_ERROR. - * - * If handler returns MG_SUCCESS, that means that handler has processed the - * request by sending appropriate HTTP reply to the client. Mongoose treats - * the request as served. - * - * If callback returns MG_ERROR, that means that callback 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. - * - * NOTE: ssl_password_handler must have the following prototype: - * int (*)(char *, int, int, void *) - * Refer to OpenSSL documentation for more details. - */ - +// User-defined handler function. It must return MG_SUCCESS or MG_ERROR. +// +// If handler returns MG_SUCCESS, that means that handler has processed the +// request by sending appropriate HTTP reply to the client. Mongoose treats +// the request as served. +// +// If callback returns MG_ERROR, that means that callback 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. +// +// NOTE: ssl_password_handler must have the following prototype: +// int (*)(char *, int, int, void *) +// Refer to OpenSSL documentation for more details. enum mg_error_t { - MG_ERROR, - MG_SUCCESS, - MG_NOT_FOUND, - MG_BUFFER_TOO_SMALL + MG_ERROR, + MG_SUCCESS, + MG_NOT_FOUND, + MG_BUFFER_TOO_SMALL }; typedef enum mg_error_t (*mg_callback_t)(struct mg_connection *, - const struct mg_request_info *); + const struct mg_request_info *); -/* - * This structure describes Mongoose configuration. - */ +// This structure describes Mongoose configuration. struct mg_config { - char *document_root; - char *index_files; - char *ssl_certificate; - char *listening_ports; - char *cgi_extensions; - char *cgi_interpreter; - char *cgi_environment; - char *ssi_extensions; - char *auth_domain; - char *protect; - char *global_passwords_file; - char *put_delete_passwords_file; - char *access_log_file; - char *error_log_file; - char *acl; - char *uid; - char *mime_types; - char *enable_directory_listing; - char *num_threads; + char *document_root; + char *index_files; + char *ssl_certificate; + char *listening_ports; + char *cgi_extensions; + char *cgi_interpreter; + char *cgi_environment; + char *ssi_extensions; + char *auth_domain; + char *protect; + char *global_passwords_file; + char *put_delete_passwords_file; + char *access_log_file; + char *error_log_file; + char *acl; + char *uid; + char *mime_types; + char *enable_directory_listing; + char *num_threads; - mg_callback_t new_request_handler; - mg_callback_t http_error_handler; - mg_callback_t event_log_handler; - mg_callback_t ssl_password_handler; + mg_callback_t new_request_handler; + mg_callback_t http_error_handler; + mg_callback_t event_log_handler; + mg_callback_t ssl_password_handler; }; -/* - * 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 stop the server. - * After calling mg_start(), configuration data must not be changed. - */ +// 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 stop the server. +// After calling mg_start(), configuration data must not be changed. struct mg_context *mg_start(struct mg_config *); -/* - * 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. - */ +// 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 *); -/* - * 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: - * MG_ERROR, MG_SUCCESS - */ +// 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: +// MG_ERROR, MG_SUCCESS enum mg_error_t mg_modify_passwords_file(struct mg_context *ctx, - const char *file_name, const char *user, const char *password); + const char *file_name, const char *user, const char *password); - -/* - * Send data to the client. - */ +// 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. - */ +// 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, ...); -/* - * Read data from the remote or local end. - */ +// Read data from the remote or local end. 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. - */ +// 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. - * - * Either request_info->query_string or read POST data can be scanned. - * mg_get_qsvar() is convenience method to get variable from the query string. - * Destination buffer is guaranteed to be '\0' - terminated. In case of - * failure, dst[0] == '\0'. - * - * Return: - * MG_SUCCESS Variable value was successfully copied in the buffer. - * MG_NOT_FOUND Requested variable not found. - * MG_BUFFER_TOO_SMALL Destination buffer is too small to hold the value. - */ +// Get a value of particular form variable. +// +// Either request_info->query_string or read POST data can be scanned. +// mg_get_qsvar() is convenience method to get variable from the query string. +// Destination buffer is guaranteed to be '\0' - terminated. In case of +// failure, dst[0] == '\0'. +// +// Return: +// MG_SUCCESS Variable value was successfully copied in the buffer. +// MG_NOT_FOUND Requested variable not found. +// MG_BUFFER_TOO_SMALL Destination buffer is too small to hold the value. enum mg_error_t 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 *buf, size_t buf_len); enum mg_error_t mg_get_qsvar(const struct mg_request_info *, - const char *var_name, char *buf, size_t buf_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 occurences of the same - * parameter. This function returns only first occurance. - * - * Return: - * MG_SUCCESS Cookie parameter was successfully copied in the buffer. - * MG_NOT_FOUND Either "Cookie:" header is not present at all, or the - * requested parameter is not found. - * MG_BUFFER_TOO_SMALL Destination buffer is too small to hold the value. - */ +// 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 occurences of the same +// parameter. This function returns only first occurance. +// +// Return: +// MG_SUCCESS Cookie parameter was successfully copied in the buffer. +// MG_NOT_FOUND Either "Cookie:" header is not present at all, or the +// requested parameter is not found. +// MG_BUFFER_TOO_SMALL Destination buffer is too small to hold the value. enum mg_error_t mg_get_cookie(const struct mg_connection *, - const char *cookie_name, char *buf, size_t buf_len); + const char *cookie_name, char *buf, size_t buf_len); -/* - * Return Mongoose version. - */ + +// 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); - */ +// 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