third_party/mongoose/mongoose.h - chromium/src - Git at Google

 /*
  * 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 404 2009-05-28 10:05:48Z valenok $
  */

 #ifndef MONGOOSE_H_
 #define MONGOOSE_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 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  *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 http_version_major;
   int http_version_minor;
   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[128];   /* Maximum 128 headers */
 };


 /*
  * 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.
  */
 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, ...);


 /*
  * 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.
  */
 const char *mg_version(void);


 /*
  * Print command line usage string.
  */
 void mg_show_usage_string(FILE *fp);

 #ifdef __cplusplus
 }
 #endif /* __cplusplus */

 #endif  // MONGOOSE_H_
	/*
	* 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 404 2009-05-28 10:05:48Z valenok $
	*/

	#ifndef MONGOOSE_H_
	#define MONGOOSE_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 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 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 http_version_major;
	int http_version_minor;
	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[128]; /* Maximum 128 headers */
	};


	/*
	* 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.
	*/
	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, ...);


	/*
	* 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.
	*/
	const char *mg_version(void);


	/*
	* Print command line usage string.
	*/
	void mg_show_usage_string(FILE *fp);

	#ifdef __cplusplus
	}
	#endif /* __cplusplus */

	#endif // MONGOOSE_H_