1 | /*
|
---|
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 *http_version; /* E.g. "1.0", "1.1" */
|
---|
44 | char *query_string; /* \0 - terminated */
|
---|
45 | char *post_data; /* POST data buffer */
|
---|
46 | char *remote_user; /* Authenticated user */
|
---|
47 | long remote_ip; /* Client's IP address */
|
---|
48 | int remote_port; /* Client's port */
|
---|
49 | int post_data_len; /* POST buffer length */
|
---|
50 | int status_code; /* HTTP status code */
|
---|
51 | int num_headers; /* Number of headers */
|
---|
52 | struct mg_header {
|
---|
53 | char *name; /* HTTP header name */
|
---|
54 | char *value; /* HTTP header value */
|
---|
55 | } http_headers[64]; /* Maximum 64 headers */
|
---|
56 | };
|
---|
57 |
|
---|
58 |
|
---|
59 | /*
|
---|
60 | * User-defined callback function prototype for URI handling, error handling,
|
---|
61 | * or logging server messages.
|
---|
62 | */
|
---|
63 | typedef void (*mg_callback_t)(struct mg_connection *,
|
---|
64 | const struct mg_request_info *info, void *user_data);
|
---|
65 |
|
---|
66 |
|
---|
67 | /*
|
---|
68 | * Start the web server.
|
---|
69 | * This must be the first function called by the application.
|
---|
70 | * It creates a serving thread, and returns a context structure that
|
---|
71 | * can be used to alter the configuration, and stop the server.
|
---|
72 | */
|
---|
73 | struct mg_context *mg_start(void);
|
---|
74 |
|
---|
75 |
|
---|
76 | /*
|
---|
77 | * Stop the web server.
|
---|
78 | * Must be called last, when an application wants to stop the web server and
|
---|
79 | * release all associated resources. This function blocks until all Mongoose
|
---|
80 | * threads are stopped. Context pointer becomes invalid.
|
---|
81 | */
|
---|
82 | void mg_stop(struct mg_context *);
|
---|
83 |
|
---|
84 |
|
---|
85 | /*
|
---|
86 | * Return current value of a particular option.
|
---|
87 | */
|
---|
88 | const char *mg_get_option(const struct mg_context *, const char *option_name);
|
---|
89 |
|
---|
90 |
|
---|
91 | /*
|
---|
92 | * Set a value for a particular option.
|
---|
93 | * Mongoose makes an internal copy of the option value string, which must be
|
---|
94 | * valid nul-terminated ASCII or UTF-8 string. It is safe to change any option
|
---|
95 | * at any time. The order of setting various options is also irrelevant with
|
---|
96 | * one exception: if "ports" option contains SSL listening ports, a "ssl_cert"
|
---|
97 | * option must be set BEFORE the "ports" option.
|
---|
98 | * Return value:
|
---|
99 | * -1 if option is unknown
|
---|
100 | * 0 if mg_set_option() failed
|
---|
101 | * 1 if mg_set_option() succeeded
|
---|
102 | */
|
---|
103 | int mg_set_option(struct mg_context *, const char *opt_name, const char *value);
|
---|
104 |
|
---|
105 |
|
---|
106 | /*
|
---|
107 | * Add, edit or delete the entry in the passwords file.
|
---|
108 | * This function allows an application to manipulate .htpasswd files on the
|
---|
109 | * fly by adding, deleting and changing user records. This is one of the two
|
---|
110 | * ways of implementing authentication on the server side. For another,
|
---|
111 | * cookie-based way please refer to the examples/authentication.c in the
|
---|
112 | * source tree.
|
---|
113 | * If password is not NULL, entry is added (or modified if already exists).
|
---|
114 | * If password is NULL, entry is deleted. Return:
|
---|
115 | * 1 on success
|
---|
116 | * 0 on error
|
---|
117 | */
|
---|
118 | int mg_modify_passwords_file(struct mg_context *ctx, const char *file_name,
|
---|
119 | const char *user_name, const char *password);
|
---|
120 |
|
---|
121 |
|
---|
122 | /*
|
---|
123 | * Register URI handler.
|
---|
124 | * It is possible to handle many URIs if using * in the uri_regex, which
|
---|
125 | * matches zero or more characters. user_data pointer will be passed to the
|
---|
126 | * handler as a third parameter. If func is NULL, then the previously installed
|
---|
127 | * handler for this uri_regex is removed.
|
---|
128 | */
|
---|
129 | void mg_set_uri_callback(struct mg_context *ctx, const char *uri_regex,
|
---|
130 | mg_callback_t func, void *user_data);
|
---|
131 |
|
---|
132 |
|
---|
133 | /*
|
---|
134 | * Register HTTP error handler.
|
---|
135 | * An application may use that function if it wants to customize the error
|
---|
136 | * page that user gets on the browser (for example, 404 File Not Found message).
|
---|
137 | * It is possible to specify a error handler for all errors by passing 0 as
|
---|
138 | * error_code. That '0' error handler must be set last, if more specific error
|
---|
139 | * handlers are also used. The actual error code value can be taken from
|
---|
140 | * the request info structure that is passed to the callback.
|
---|
141 | */
|
---|
142 | void mg_set_error_callback(struct mg_context *ctx, int error_code,
|
---|
143 | mg_callback_t func, void *user_data);
|
---|
144 |
|
---|
145 |
|
---|
146 | /*
|
---|
147 | * Register authorization handler.
|
---|
148 | * This function provides a mechanism to implement custom authorization,
|
---|
149 | * for example cookie based (look at examples/authorization.c).
|
---|
150 | * The callback function must analyze the request, and make its own judgement
|
---|
151 | * on wether it should be authorized or not. After the decision is made, a
|
---|
152 | * callback must call mg_authorize() if the request is authorized.
|
---|
153 | */
|
---|
154 | void mg_set_auth_callback(struct mg_context *ctx, const char *uri_regex,
|
---|
155 | mg_callback_t func, void *user_data);
|
---|
156 |
|
---|
157 |
|
---|
158 | /*
|
---|
159 | * Register log handler.
|
---|
160 | * By default, Mongoose logs all error messages to stderr. If "error_log"
|
---|
161 | * option is specified, the errors are written in the specified file. However,
|
---|
162 | * if an application registers its own log handler, Mongoose will not log
|
---|
163 | * anything but call the handler function, passing an error message as
|
---|
164 | * "user_data" callback argument.
|
---|
165 | */
|
---|
166 | void mg_set_log_callback(struct mg_context *ctx, mg_callback_t func);
|
---|
167 |
|
---|
168 |
|
---|
169 | /*
|
---|
170 | * Register SSL password handler.
|
---|
171 | * This is needed only if SSL certificate asks for a password. Instead of
|
---|
172 | * prompting for a password on a console a specified function will be called.
|
---|
173 | */
|
---|
174 | typedef int (*mg_spcb_t)(char *buf, int num, int w, void *key);
|
---|
175 | void mg_set_ssl_password_callback(struct mg_context *ctx, mg_spcb_t func);
|
---|
176 |
|
---|
177 |
|
---|
178 | /*
|
---|
179 | * Send data to the browser.
|
---|
180 | * Return number of bytes sent. If the number of bytes sent is less then
|
---|
181 | * requested or equals to -1, network error occured, usually meaning the
|
---|
182 | * remote side has closed the connection.
|
---|
183 | */
|
---|
184 | int mg_write(struct mg_connection *, const void *buf, int len);
|
---|
185 |
|
---|
186 |
|
---|
187 | /*
|
---|
188 | * Send data to the browser using printf() semantics.
|
---|
189 | * Works exactly like mg_write(), but allows to do message formatting.
|
---|
190 | * Note that mg_printf() uses internal buffer of size MAX_REQUEST_SIZE
|
---|
191 | * (8 Kb by default) as temporary message storage for formatting. Do not
|
---|
192 | * print data that is bigger than that, otherwise it will be truncated.
|
---|
193 | * Return number of bytes sent.
|
---|
194 | */
|
---|
195 | int mg_printf(struct mg_connection *, const char *fmt, ...);
|
---|
196 |
|
---|
197 |
|
---|
198 | /*
|
---|
199 | * Read data from the remote or local end.
|
---|
200 | */
|
---|
201 | int mg_read(struct mg_connection *, int local, void *buf, int len);
|
---|
202 |
|
---|
203 | /*
|
---|
204 | * Get the value of particular HTTP header.
|
---|
205 | * This is a helper function. It traverses request_info->http_headers array,
|
---|
206 | * and if the header is present in the array, returns its value. If it is
|
---|
207 | * not present, NULL is returned.
|
---|
208 | */
|
---|
209 | const char *mg_get_header(const struct mg_connection *, const char *hdr_name);
|
---|
210 |
|
---|
211 |
|
---|
212 | /*
|
---|
213 | * Authorize the request.
|
---|
214 | * See the documentation for mg_set_auth_callback() function.
|
---|
215 | */
|
---|
216 | void mg_authorize(struct mg_connection *);
|
---|
217 |
|
---|
218 |
|
---|
219 | /*
|
---|
220 | * Get a value of particular form variable.
|
---|
221 | * Both query string (whatever comes after '?' in the URL) and a POST buffer
|
---|
222 | * are scanned. If a variable is specified in both query string and POST
|
---|
223 | * buffer, POST buffer wins. Return value:
|
---|
224 | * NULL if the variable is not found
|
---|
225 | * non-NULL if found. NOTE: this returned value is dynamically allocated
|
---|
226 | * and is subject to mg_free() when no longer needed. It is
|
---|
227 | * an application's responsibility to mg_free() the variable.
|
---|
228 | */
|
---|
229 | char *mg_get_var(const struct mg_connection *, const char *var_name);
|
---|
230 |
|
---|
231 |
|
---|
232 | /*
|
---|
233 | * Free up memory returned by mg_get_var().
|
---|
234 | */
|
---|
235 | void mg_free(char *var);
|
---|
236 |
|
---|
237 |
|
---|
238 | /*
|
---|
239 | * Return Mongoose version.
|
---|
240 | */
|
---|
241 | const char *mg_version(void);
|
---|
242 |
|
---|
243 |
|
---|
244 | /*
|
---|
245 | * Print command line usage string.
|
---|
246 | */
|
---|
247 | void mg_show_usage_string(FILE *fp);
|
---|
248 |
|
---|
249 | #ifdef __cplusplus
|
---|
250 | }
|
---|
251 | #endif /* __cplusplus */
|
---|
252 |
|
---|
253 | #endif /* MONGOOSE_HEADER_INCLUDED */
|
---|