1 // Copyright (c) 2004-2012 Sergey Lyubka
\r
3 // Permission is hereby granted, free of charge, to any person obtaining a copy
\r
4 // of this software and associated documentation files (the "Software"), to deal
\r
5 // in the Software without restriction, including without limitation the rights
\r
6 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
\r
7 // copies of the Software, and to permit persons to whom the Software is
\r
8 // furnished to do so, subject to the following conditions:
\r
10 // The above copyright notice and this permission notice shall be included in
\r
11 // all copies or substantial portions of the Software.
\r
13 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
\r
14 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
\r
15 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
\r
16 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
\r
17 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
\r
18 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
\r
21 #ifndef MONGOOSE_HEADER_INCLUDED
\r
22 #define MONGOOSE_HEADER_INCLUDED
\r
29 #endif // __cplusplus
\r
31 struct mg_context; // Handle for the HTTP service itself
\r
32 struct mg_connection; // Handle for the individual connection
\r
35 // This structure contains information about the HTTP request.
\r
36 struct mg_request_info {
\r
37 const char *request_method; // "GET", "POST", etc
\r
38 const char *uri; // URL-decoded URI
\r
39 const char *http_version; // E.g. "1.0", "1.1"
\r
40 const char *query_string; // URL part after '?', not including '?', or NULL
\r
41 const char *remote_user; // Authenticated user, or NULL if no auth used
\r
42 long remote_ip; // Client's IP address
\r
43 int remote_port; // Client's port
\r
44 int is_ssl; // 1 if SSL-ed, 0 if not
\r
45 void *user_data; // User data pointer passed to mg_start()
\r
47 int num_headers; // Number of HTTP headers
\r
49 const char *name; // HTTP header name
\r
50 const char *value; // HTTP header value
\r
51 } http_headers[64]; // Maximum 64 headers
\r
55 // This structure needs to be passed to mg_start(), to let mongoose know
\r
56 // which callbacks to invoke. For detailed description, see
\r
57 // https://github.com/valenok/mongoose/blob/master/UserManual.md
\r
58 struct mg_callbacks {
\r
59 int (*begin_request)(struct mg_connection *);
\r
60 void (*end_request)(const struct mg_connection *, int reply_status_code);
\r
61 int (*log_message)(const struct mg_connection *, const char *message);
\r
62 int (*init_ssl)(void *ssl_context);
\r
63 int (*websocket_connect)(const struct mg_connection *);
\r
64 void (*websocket_ready)(struct mg_connection *);
\r
65 int (*websocket_data)(struct mg_connection *);
\r
66 const char * (*open_file)(const struct mg_connection *,
\r
67 const char *path, size_t *data_len);
\r
68 void (*init_lua)(struct mg_connection *, void *lua_context);
\r
69 void (*upload)(struct mg_connection *, const char *file_name);
\r
72 // Start web server.
\r
75 // callbacks: mg_callbacks structure with user-defined callbacks.
\r
76 // options: NULL terminated list of option_name, option_value pairs that
\r
77 // specify Mongoose configuration parameters.
\r
79 // Side-effects: on UNIX, ignores SIGCHLD and SIGPIPE signals. If custom
\r
80 // processing is required for these, signal handlers must be set up
\r
81 // after calling mg_start().
\r
85 // const char *options[] = {
\r
86 // "document_root", "/var/www",
\r
87 // "listening_ports", "80,443s",
\r
90 // struct mg_context *ctx = mg_start(&my_func, NULL, options);
\r
92 // Please refer to http://code.google.com/p/mongoose/wiki/MongooseManual
\r
93 // for the list of valid option and their possible values.
\r
96 // web server context, or NULL on error.
\r
97 struct mg_context *mg_start(const struct mg_callbacks *callbacks,
\r
99 const char **configuration_options);
\r
102 // Stop the web server.
\r
104 // Must be called last, when an application wants to stop the web server and
\r
105 // release all associated resources. This function blocks until all Mongoose
\r
106 // threads are stopped. Context pointer becomes invalid.
\r
107 void mg_stop(struct mg_context *);
\r
110 // Get the value of particular configuration parameter.
\r
111 // The value returned is read-only. Mongoose does not allow changing
\r
112 // configuration at run time.
\r
113 // If given parameter name is not valid, NULL is returned. For valid
\r
114 // names, return value is guaranteed to be non-NULL. If parameter is not
\r
115 // set, zero-length string is returned.
\r
116 const char *mg_get_option(const struct mg_context *ctx, const char *name);
\r
119 // Return array of strings that represent valid configuration options.
\r
120 // For each option, a short name, long name, and default value is returned.
\r
121 // Array is NULL terminated.
\r
122 const char **mg_get_valid_option_names(void);
\r
125 // Add, edit or delete the entry in the passwords file.
\r
127 // This function allows an application to manipulate .htpasswd files on the
\r
128 // fly by adding, deleting and changing user records. This is one of the
\r
129 // several ways of implementing authentication on the server side. For another,
\r
130 // cookie-based way please refer to the examples/chat.c in the source tree.
\r
132 // If password is not NULL, entry is added (or modified if already exists).
\r
133 // If password is NULL, entry is deleted.
\r
136 // 1 on success, 0 on error.
\r
137 int mg_modify_passwords_file(const char *passwords_file_name,
\r
138 const char *domain,
\r
140 const char *password);
\r
143 // Return information associated with the request.
\r
144 struct mg_request_info *mg_get_request_info(struct mg_connection *);
\r
147 // Send data to the client.
\r
149 // 0 when the connection has been closed
\r
151 // number of bytes written on success
\r
152 int mg_write(struct mg_connection *, const void *buf, size_t len);
\r
155 #undef PRINTF_FORMAT_STRING
\r
156 #if _MSC_VER >= 1400
\r
158 #if _MSC_VER > 1400
\r
159 #define PRINTF_FORMAT_STRING(s) _Printf_format_string_ s
\r
161 #define PRINTF_FORMAT_STRING(s) __format_string s
\r
164 #define PRINTF_FORMAT_STRING(s) s
\r
168 #define PRINTF_ARGS(x, y) __attribute__((format(printf, x, y)))
\r
170 #define PRINTF_ARGS(x, y)
\r
173 // Send data to the browser using printf() semantics.
\r
175 // Works exactly like mg_write(), but allows to do message formatting.
\r
176 // Below are the macros for enabling compiler-specific checks for
\r
177 // printf-like arguments.
\r
178 int mg_printf(struct mg_connection *,
\r
179 PRINTF_FORMAT_STRING(const char *fmt), ...) PRINTF_ARGS(2, 3);
\r
182 // Send contents of the entire file together with HTTP headers.
\r
183 void mg_send_file(struct mg_connection *conn, const char *path);
\r
186 // Read data from the remote end, return number of bytes read.
\r
187 int mg_read(struct mg_connection *, void *buf, size_t len);
\r
190 // Get the value of particular HTTP header.
\r
192 // This is a helper function. It traverses request_info->http_headers array,
\r
193 // and if the header is present in the array, returns its value. If it is
\r
194 // not present, NULL is returned.
\r
195 const char *mg_get_header(const struct mg_connection *, const char *name);
\r
198 // Get a value of particular form variable.
\r
201 // data: pointer to form-uri-encoded buffer. This could be either POST data,
\r
202 // or request_info.query_string.
\r
203 // data_len: length of the encoded data.
\r
204 // var_name: variable name to decode from the buffer
\r
205 // dst: destination buffer for the decoded variable
\r
206 // dst_len: length of the destination buffer
\r
209 // On success, length of the decoded variable.
\r
211 // -1 (variable not found).
\r
212 // -2 (destination buffer is NULL, zero length or too small to hold the decoded variable).
\r
214 // Destination buffer is guaranteed to be '\0' - terminated if it is not
\r
215 // NULL or zero length.
\r
216 int mg_get_var(const char *data, size_t data_len,
\r
217 const char *var_name, char *dst, size_t dst_len);
\r
219 // Fetch value of certain cookie variable into the destination buffer.
\r
221 // Destination buffer is guaranteed to be '\0' - terminated. In case of
\r
222 // failure, dst[0] == '\0'. Note that RFC allows many occurrences of the same
\r
223 // parameter. This function returns only first occurrence.
\r
226 // On success, value length.
\r
228 // -1 (either "Cookie:" header is not present at all or the requested parameter is not found).
\r
229 // -2 (destination buffer is NULL, zero length or too small to hold the value).
\r
230 int mg_get_cookie(const struct mg_connection *,
\r
231 const char *cookie_name, char *buf, size_t buf_len);
\r
234 // Download data from the remote web server.
\r
235 // host: host name to connect to, e.g. "foo.com", or "10.12.40.1".
\r
236 // port: port number, e.g. 80.
\r
237 // use_ssl: wether to use SSL connection.
\r
238 // error_buffer, error_buffer_size: error message placeholder.
\r
239 // request_fmt,...: HTTP request.
\r
241 // On success, valid pointer to the new connection, suitable for mg_read().
\r
242 // On error, NULL. error_buffer contains error message.
\r
245 // struct mg_connection *conn;
\r
246 // conn = mg_download("google.com", 80, 0, ebuf, sizeof(ebuf),
\r
247 // "%s", "GET / HTTP/1.0\r\nHost: google.com\r\n\r\n");
\r
248 struct mg_connection *mg_download(const char *host, int port, int use_ssl,
\r
249 char *error_buffer, size_t error_buffer_size,
\r
250 PRINTF_FORMAT_STRING(const char *request_fmt),
\r
251 ...) PRINTF_ARGS(6, 7);
\r
254 // Close the connection opened by mg_download().
\r
255 void mg_close_connection(struct mg_connection *conn);
\r
258 // File upload functionality. Each uploaded file gets saved into a temporary
\r
259 // file and MG_UPLOAD event is sent.
\r
260 // Return number of uploaded files.
\r
261 int mg_upload(struct mg_connection *conn, const char *destination_dir);
\r
264 // Convenience function -- create detached thread.
\r
265 // Return: 0 on success, non-0 on error.
\r
266 typedef void * (*mg_thread_func_t)(void *);
\r
267 int mg_start_thread(mg_thread_func_t f, void *p);
\r
270 // Return builtin mime type for the given file name.
\r
271 // For unrecognized extensions, "text/plain" is returned.
\r
272 const char *mg_get_builtin_mime_type(const char *file_name);
\r
275 // Return Mongoose version.
\r
276 const char *mg_version(void);
\r
279 // MD5 hash given strings.
\r
280 // Buffer 'buf' must be 33 bytes long. Varargs is a NULL terminated list of
\r
281 // ASCIIz strings. When function returns, buf will contain human-readable
\r
282 // MD5 hash. Example:
\r
284 // mg_md5(buf, "aa", "bb", NULL);
\r
285 void mg_md5(char buf[33], ...);
\r
290 #endif // __cplusplus
\r
292 #endif // MONGOOSE_HEADER_INCLUDED
\r