smsdaemon/embedded-http/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$
 */

#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    *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[64];             /* Maximum 64 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_HEADER_INCLUDED */
1	torben	675	/*
2			* Copyright (c) 2004-2009 Sergey Lyubka
3			*
4			* Permission is hereby granted, free of charge, to any person obtaining a copy
5			* of this software and associated documentation files (the "Software"), to deal
6			* in the Software without restriction, including without limitation the rights
7			* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8			* copies of the Software, and to permit persons to whom the Software is
9			* furnished to do so, subject to the following conditions:
10			*
11			* The above copyright notice and this permission notice shall be included in
12			* all copies or substantial portions of the Software.
13			*
14			* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15			* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16			* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17			* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18			* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19			* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20			* THE SOFTWARE.
21			*
22			* $Id$
23			*/
24
25			#ifndef MONGOOSE_HEADER_INCLUDED
26			#define MONGOOSE_HEADER_INCLUDED
27
28			#ifdef __cplusplus
29			extern "C" {
30			#endif /* __cplusplus */
31
32			struct mg_context; /* Handle for the HTTP service itself */
33			struct mg_connection; /* Handle for the individual connection */
34
35
36			/*
37			* This structure contains full information about the HTTP request.
38			* It is passed to the user-specified callback function as a parameter.
39			*/
40			struct mg_request_info {
41			char request_method; / "GET", "POST", etc */
42			char uri; / Normalized URI */
43			char query_string; / \0 - terminated */
44			char post_data; / POST data buffer */
45			char remote_user; / Authenticated user */
46			long remote_ip; /* Client's IP address */
47			int remote_port; /* Client's port */
48			int post_data_len; /* POST buffer length */
49			int http_version_major;
50			int http_version_minor;
51			int status_code; /* HTTP status code */
52			int num_headers; /* Number of headers */
53			struct mg_header {
54			char name; / HTTP header name */
55			char value; / HTTP header value */
56			} http_headers[64]; /* Maximum 64 headers */
57			};
58
59
60			/*
61			* User-defined callback function prototype for URI handling, error handling,
62			* or logging server messages.
63			*/
64			typedef void (mg_callback_t)(struct mg_connection ,
65			const struct mg_request_info info, void user_data);
66
67
68			/*
69			* Start the web server.
70			* This must be the first function called by the application.
71			* It creates a serving thread, and returns a context structure that
72			* can be used to alter the configuration, and stop the server.
73			*/
74			struct mg_context *mg_start(void);
75
76
77			/*
78			* Stop the web server.
79			* Must be called last, when an application wants to stop the web server and
80			* release all associated resources. This function blocks until all Mongoose
81			* threads are stopped. Context pointer becomes invalid.
82			*/
83			void mg_stop(struct mg_context *);
84
85
86			/*
87			* Return current value of a particular option.
88			*/
89			const char mg_get_option(const struct mg_context , const char *option_name);
90
91
92			/*
93			* Set a value for a particular option.
94			* Mongoose makes an internal copy of the option value string, which must be
95			* valid nul-terminated ASCII or UTF-8 string. It is safe to change any option
96			* at any time. The order of setting various options is also irrelevant with
97			* one exception: if "ports" option contains SSL listening ports, a "ssl_cert"
98			* option must be set BEFORE the "ports" option.
99			* Return value:
100			* -1 if option is unknown
101			* 0 if mg_set_option() failed
102			* 1 if mg_set_option() succeeded
103			*/
104			int mg_set_option(struct mg_context , const char opt_name, const char *value);
105
106
107			/*
108			* Add, edit or delete the entry in the passwords file.
109			* This function allows an application to manipulate .htpasswd files on the
110			* fly by adding, deleting and changing user records. This is one of the two
111			* ways of implementing authentication on the server side. For another,
112			* cookie-based way please refer to the examples/authentication.c in the
113			* source tree.
114			* If password is not NULL, entry is added (or modified if already exists).
115			* If password is NULL, entry is deleted. Return:
116			* 1 on success
117			* 0 on error
118			*/
119			int mg_modify_passwords_file(struct mg_context ctx, const char file_name,
120			const char user_name, const char password);
121
122
123			/*
124			* Register URI handler.
125			* It is possible to handle many URIs if using * in the uri_regex, which
126			* matches zero or more characters. user_data pointer will be passed to the
127			* handler as a third parameter. If func is NULL, then the previously installed
128			* handler for this uri_regex is removed.
129			*/
130			void mg_set_uri_callback(struct mg_context ctx, const char uri_regex,
131			mg_callback_t func, void *user_data);
132
133
134			/*
135			* Register HTTP error handler.
136			* An application may use that function if it wants to customize the error
137			* page that user gets on the browser (for example, 404 File Not Found message).
138			* It is possible to specify a error handler for all errors by passing 0 as
139			* error_code. That '0' error handler must be set last, if more specific error
140			* handlers are also used. The actual error code value can be taken from
141			* the request info structure that is passed to the callback.
142			*/
143			void mg_set_error_callback(struct mg_context *ctx, int error_code,
144			mg_callback_t func, void *user_data);
145
146
147			/*
148			* Register authorization handler.
149			* This function provides a mechanism to implement custom authorization,
150			* for example cookie based (look at examples/authorization.c).
151			* The callback function must analyze the request, and make its own judgement
152			* on wether it should be authorized or not. After the decision is made, a
153			* callback must call mg_authorize() if the request is authorized.
154			*/
155			void mg_set_auth_callback(struct mg_context ctx, const char uri_regex,
156			mg_callback_t func, void *user_data);
157
158
159			/*
160			* Register log handler.
161			* By default, Mongoose logs all error messages to stderr. If "error_log"
162			* option is specified, the errors are written in the specified file. However,
163			* if an application registers its own log handler, Mongoose will not log
164			* anything but call the handler function, passing an error message as
165			* "user_data" callback argument.
166			*/
167			void mg_set_log_callback(struct mg_context *ctx, mg_callback_t func);
168
169
170			/*
171			* Register SSL password handler.
172			* This is needed only if SSL certificate asks for a password. Instead of
173			* prompting for a password on a console a specified function will be called.
174			*/
175			typedef int (mg_spcb_t)(char buf, int num, int w, void *key);
176			void mg_set_ssl_password_callback(struct mg_context *ctx, mg_spcb_t func);
177
178
179			/*
180			* Send data to the browser.
181			* Return number of bytes sent. If the number of bytes sent is less then
182			* requested or equals to -1, network error occured, usually meaning the
183			* remote side has closed the connection.
184			*/
185			int mg_write(struct mg_connection , const void buf, int len);
186
187
188			/*
189			* Send data to the browser using printf() semantics.
190			* Works exactly like mg_write(), but allows to do message formatting.
191			* Note that mg_printf() uses internal buffer of size MAX_REQUEST_SIZE
192			* (8 Kb by default) as temporary message storage for formatting. Do not
193			* print data that is bigger than that, otherwise it will be truncated.
194			* Return number of bytes sent.
195			*/
196			int mg_printf(struct mg_connection , const char fmt, ...);
197
198
199			/*
200			* Get the value of particular HTTP header.
201			* This is a helper function. It traverses request_info->http_headers array,
202			* and if the header is present in the array, returns its value. If it is
203			* not present, NULL is returned.
204			*/
205			const char mg_get_header(const struct mg_connection , const char *hdr_name);
206
207
208			/*
209			* Authorize the request.
210			* See the documentation for mg_set_auth_callback() function.
211			*/
212			void mg_authorize(struct mg_connection *);
213
214
215			/*
216			* Get a value of particular form variable.
217			* Both query string (whatever comes after '?' in the URL) and a POST buffer
218			* are scanned. If a variable is specified in both query string and POST
219			* buffer, POST buffer wins. Return value:
220			* NULL if the variable is not found
221			* non-NULL if found. NOTE: this returned value is dynamically allocated
222			* and is subject to mg_free() when no longer needed. It is
223			* an application's responsibility to mg_free() the variable.
224			*/
225			char mg_get_var(const struct mg_connection , const char *var_name);
226
227
228			/*
229			* Free up memory returned by mg_get_var().
230			*/
231			void mg_free(char *var);
232
233
234			/*
235			* Return Mongoose version.
236			*/
237			const char *mg_version(void);
238
239
240			/*
241			* Print command line usage string.
242			*/
243			void mg_show_usage_string(FILE *fp);
244
245			#ifdef __cplusplus
246			}
247			#endif /* __cplusplus */
248
249			#endif /* MONGOOSE_HEADER_INCLUDED */