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