mongoose/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 517 2010-05-03 12:54:59Z valenok $
 */

#ifndef MONGOOSE_HEADER_INCLUDED
#define	MONGOOSE_HEADER_INCLUDED

#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	*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.
 */

enum mg_error_t {
	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 *);

/*
 * 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;

	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.
 */
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.
 */
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
 */
enum mg_error_t mg_modify_passwords_file(struct mg_context *ctx, 
		const char *file_name, 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, ...);


/*
 * 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.
 */
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.
 */
enum mg_error_t mg_get_var(const char *data, size_t data_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);


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

/*
 * 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 */