OLD | NEW |
| (Empty) |
1 // Copyright (c) 2004-2011 Sergey Lyubka | |
2 // | |
3 // Permission is hereby granted, free of charge, to any person obtaining a copy | |
4 // of this software and associated documentation files (the "Software"), to deal | |
5 // in the Software without restriction, including without limitation the rights | |
6 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | |
7 // copies of the Software, and to permit persons to whom the Software is | |
8 // furnished to do so, subject to the following conditions: | |
9 // | |
10 // The above copyright notice and this permission notice shall be included in | |
11 // all copies or substantial portions of the Software. | |
12 // | |
13 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
14 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
15 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | |
16 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | |
17 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
18 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN | |
19 // THE SOFTWARE. | |
20 | |
21 #ifndef MONGOOSE_HEADER_INCLUDED | |
22 #define MONGOOSE_HEADER_INCLUDED | |
23 | |
24 #include <stddef.h> | |
25 | |
26 #ifdef __cplusplus | |
27 extern "C" { | |
28 #endif // __cplusplus | |
29 | |
30 struct mg_context; // Handle for the HTTP service itself | |
31 struct mg_connection; // Handle for the individual connection | |
32 | |
33 | |
34 // This structure contains information about the HTTP request. | |
35 struct mg_request_info { | |
36 void *user_data; // User-defined pointer passed to mg_start() | |
37 char *request_method; // "GET", "POST", etc | |
38 char *uri; // URL-decoded URI | |
39 char *http_version; // E.g. "1.0", "1.1" | |
40 char *query_string; // \0 - terminated | |
41 char *remote_user; // Authenticated user | |
42 char *log_message; // Mongoose error log message | |
43 long remote_ip; // Client's IP address | |
44 int remote_port; // Client's port | |
45 int status_code; // HTTP reply status code | |
46 int is_ssl; // 1 if SSL-ed, 0 if not | |
47 int num_headers; // Number of headers | |
48 struct mg_header { | |
49 char *name; // HTTP header name | |
50 char *value; // HTTP header value | |
51 } http_headers[64]; // Maximum 64 headers | |
52 }; | |
53 | |
54 // Various events on which user-defined function is called by Mongoose. | |
55 enum mg_event { | |
56 MG_NEW_REQUEST, // New HTTP request has arrived from the client | |
57 MG_HTTP_ERROR, // HTTP error must be returned to the client | |
58 MG_EVENT_LOG, // Mongoose logs an event, request_info.log_message | |
59 MG_INIT_SSL // Mongoose initializes SSL. Instead of mg_connection *, | |
60 // SSL context is passed to the callback function. | |
61 }; | |
62 | |
63 // Prototype for the user-defined function. Mongoose calls this function | |
64 // on every event mentioned above. | |
65 // | |
66 // Parameters: | |
67 // event: which event has been triggered. | |
68 // conn: opaque connection handler. Could be used to read, write data to the | |
69 // client, etc. See functions below that accept "mg_connection *". | |
70 // request_info: Information about HTTP request. | |
71 // | |
72 // Return: | |
73 // If handler returns non-NULL, that means that handler has processed the | |
74 // request by sending appropriate HTTP reply to the client. Mongoose treats | |
75 // the request as served. | |
76 // If callback returns NULL, that means that callback has not processed | |
77 // the request. Handler must not send any data to the client in this case. | |
78 // Mongoose proceeds with request handling as if nothing happened. | |
79 typedef void * (*mg_callback_t)(enum mg_event event, | |
80 struct mg_connection *conn, | |
81 const struct mg_request_info *request_info); | |
82 | |
83 | |
84 // Start web server. | |
85 // | |
86 // Parameters: | |
87 // callback: user defined event handling function or NULL. | |
88 // options: NULL terminated list of option_name, option_value pairs that | |
89 // specify Mongoose configuration parameters. | |
90 // | |
91 // Side-effects: on UNIX, ignores SIGCHLD and SIGPIPE signals. If custom | |
92 // processing is required for these, signal handlers must be set up | |
93 // after calling mg_start(). | |
94 // | |
95 // | |
96 // Example: | |
97 // const char *options[] = { | |
98 // "document_root", "/var/www", | |
99 // "listening_ports", "80,443s", | |
100 // NULL | |
101 // }; | |
102 // struct mg_context *ctx = mg_start(&my_func, NULL, options); | |
103 // | |
104 // Please refer to http://code.google.com/p/mongoose/wiki/MongooseManual | |
105 // for the list of valid option and their possible values. | |
106 // | |
107 // Return: | |
108 // web server context, or NULL on error. | |
109 struct mg_context *mg_start(mg_callback_t callback, void *user_data, | |
110 const char **options); | |
111 | |
112 | |
113 // Stop the web server. | |
114 // | |
115 // Must be called last, when an application wants to stop the web server and | |
116 // release all associated resources. This function blocks until all Mongoose | |
117 // threads are stopped. Context pointer becomes invalid. | |
118 void mg_stop(struct mg_context *); | |
119 | |
120 | |
121 // Get the value of particular configuration parameter. | |
122 // The value returned is read-only. Mongoose does not allow changing | |
123 // configuration at run time. | |
124 // If given parameter name is not valid, NULL is returned. For valid | |
125 // names, return value is guaranteed to be non-NULL. If parameter is not | |
126 // set, zero-length string is returned. | |
127 const char *mg_get_option(const struct mg_context *ctx, const char *name); | |
128 | |
129 | |
130 // Return array of strings that represent valid configuration options. | |
131 // For each option, a short name, long name, and default value is returned. | |
132 // Array is NULL terminated. | |
133 const char **mg_get_valid_option_names(void); | |
134 | |
135 | |
136 // Add, edit or delete the entry in the passwords file. | |
137 // | |
138 // This function allows an application to manipulate .htpasswd files on the | |
139 // fly by adding, deleting and changing user records. This is one of the | |
140 // several ways of implementing authentication on the server side. For another, | |
141 // cookie-based way please refer to the examples/chat.c in the source tree. | |
142 // | |
143 // If password is not NULL, entry is added (or modified if already exists). | |
144 // If password is NULL, entry is deleted. | |
145 // | |
146 // Return: | |
147 // 1 on success, 0 on error. | |
148 int mg_modify_passwords_file(const char *passwords_file_name, | |
149 const char *domain, | |
150 const char *user, | |
151 const char *password); | |
152 | |
153 // Send data to the client. | |
154 int mg_write(struct mg_connection *, const void *buf, size_t len); | |
155 | |
156 | |
157 // Send data to the browser using printf() semantics. | |
158 // | |
159 // Works exactly like mg_write(), but allows to do message formatting. | |
160 // Note that mg_printf() uses internal buffer of size IO_BUF_SIZE | |
161 // (8 Kb by default) as temporary message storage for formatting. Do not | |
162 // print data that is bigger than that, otherwise it will be truncated. | |
163 int mg_printf(struct mg_connection *, const char *fmt, ...); | |
164 | |
165 | |
166 // Send contents of the entire file together with HTTP headers. | |
167 void mg_send_file(struct mg_connection *conn, const char *path); | |
168 | |
169 | |
170 // Read data from the remote end, return number of bytes read. | |
171 int mg_read(struct mg_connection *, void *buf, size_t len); | |
172 | |
173 | |
174 // Get the value of particular HTTP header. | |
175 // | |
176 // This is a helper function. It traverses request_info->http_headers array, | |
177 // and if the header is present in the array, returns its value. If it is | |
178 // not present, NULL is returned. | |
179 const char *mg_get_header(const struct mg_connection *, const char *name); | |
180 | |
181 | |
182 // Get a value of particular form variable. | |
183 // | |
184 // Parameters: | |
185 // data: pointer to form-uri-encoded buffer. This could be either POST data, | |
186 // or request_info.query_string. | |
187 // data_len: length of the encoded data. | |
188 // var_name: variable name to decode from the buffer | |
189 // buf: destination buffer for the decoded variable | |
190 // buf_len: length of the destination buffer | |
191 // | |
192 // Return: | |
193 // On success, length of the decoded variable. | |
194 // On error, -1 (variable not found, or destination buffer is too small). | |
195 // | |
196 // Destination buffer is guaranteed to be '\0' - terminated. In case of | |
197 // failure, dst[0] == '\0'. | |
198 int mg_get_var(const char *data, size_t data_len, | |
199 const char *var_name, char *buf, size_t buf_len); | |
200 | |
201 // Fetch value of certain cookie variable into the destination buffer. | |
202 // | |
203 // Destination buffer is guaranteed to be '\0' - terminated. In case of | |
204 // failure, dst[0] == '\0'. Note that RFC allows many occurrences of the same | |
205 // parameter. This function returns only first occurrence. | |
206 // | |
207 // Return: | |
208 // On success, value length. | |
209 // On error, 0 (either "Cookie:" header is not present at all, or the | |
210 // requested parameter is not found, or destination buffer is too small | |
211 // to hold the value). | |
212 int mg_get_cookie(const struct mg_connection *, | |
213 const char *cookie_name, char *buf, size_t buf_len); | |
214 | |
215 | |
216 // Return Mongoose version. | |
217 const char *mg_version(void); | |
218 | |
219 | |
220 // MD5 hash given strings. | |
221 // Buffer 'buf' must be 33 bytes long. Varargs is a NULL terminated list of | |
222 // asciiz strings. When function returns, buf will contain human-readable | |
223 // MD5 hash. Example: | |
224 // char buf[33]; | |
225 // mg_md5(buf, "aa", "bb", NULL); | |
226 void mg_md5(char *buf, ...); | |
227 | |
228 | |
229 #ifdef __cplusplus | |
230 } | |
231 #endif // __cplusplus | |
232 | |
233 #endif // MONGOOSE_HEADER_INCLUDED | |
OLD | NEW |