source: rtems/cpukit/mghttpd/mongoose.h @ dd1569b

4.104.11
Last change on this file since dd1569b was dd1569b, checked in by Ralf Corsepius <ralf.corsepius@…>, on Nov 17, 2009 at 4:58:36 PM

Convert to unix encoding.

  • Property mode set to 100644
File size: 8.6 KB
Line 
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
29extern "C" {
30#endif /* __cplusplus */
31
32struct mg_context;      /* Handle for the HTTP service itself   */
33struct 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 */
40struct 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 */
63typedef 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 */
73struct 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 */
82void mg_stop(struct mg_context *);
83
84
85/*
86 * Return current value of a particular option.
87 */
88const 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 */
103int 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 */
118int 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 */
129void 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 */
142void 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 */
154void 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 */
166void 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 */
174typedef int (*mg_spcb_t)(char *buf, int num, int w, void *key);
175void 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 */
184int 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 */
195int mg_printf(struct mg_connection *, const char *fmt, ...);
196
197
198/*
199 * Read data from the remote or local end.
200 */
201int 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 */
209const 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 */
216void 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 */
229char *mg_get_var(const struct mg_connection *, const char *var_name);
230
231
232/*
233 * Free up memory returned by mg_get_var().
234 */
235void mg_free(char *var);
236
237
238/*
239 * Return Mongoose version.
240 */
241const char *mg_version(void);
242
243
244/*
245 * Print command line usage string.
246 */
247void mg_show_usage_string(FILE *fp);
248
249#ifdef __cplusplus
250}
251#endif /* __cplusplus */
252
253#endif /* MONGOOSE_HEADER_INCLUDED */
Note: See TracBrowser for help on using the repository browser.