GraphChi  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Macros
mongoose.h
1 // Copyright (c) 2004-2010 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 #ifdef __cplusplus
25 extern "C" {
26 #endif // __cplusplus
27 
28 struct mg_context; // Handle for the HTTP service itself
29 struct mg_connection; // Handle for the individual connection
30 
31 // Parsed Authorization header
33  const char *user, *uri, *cnonce, *response, *qop, *nc, *nonce; // Fields of the Authorization header
34  // The following members can be set by MG_AUTHENTICATE callback
35  // if non-NULL, will be freed by mongoose
36  char *ha1; // ha1 = md5(username:domain:password), used to compute expected_response
37  char *expected_response; // Compared against response
38 };
39 
40 // This structure contains information about the HTTP request.
42  void *user_data; // User-defined pointer passed to mg_start()
43  char *request_method; // "GET", "POST", etc
44  char *uri; // URL-decoded URI
45  char *http_version; // E.g. "1.0", "1.1"
46  char *query_string; // \0 - terminated
47  char *remote_user; // Authenticated user
48  char *log_message; // Mongoose error log message
49  long remote_ip; // Client's IP address
50  int remote_port; // Client's port
51  int status_code; // HTTP reply status code
52  int is_ssl; // 1 if SSL-ed, 0 if not
53  int num_headers; // Number of headers
54  struct mg_header {
55  char *name; // HTTP header name
56  char *value; // HTTP header value
57  } http_headers[64]; // Maximum 64 headers
58  struct mg_auth_header *ah; // Parsed Authorization header, if present
59 };
60 
61 // Various events on which user-defined function is called by Mongoose.
62 enum mg_event {
63  MG_NEW_REQUEST, // New HTTP request has arrived from the client
64  MG_HTTP_ERROR, // HTTP error must be returned to the client
65  MG_EVENT_LOG, // Mongoose logs an event, request_info.log_message
66  MG_INIT_SSL, // Mongoose initializes SSL. Instead of mg_connection *,
67  // SSL context is passed to the callback function.
68  MG_AUTHENTICATE, // Authenticate a new HTTP request. request_info->ah
69  // is set, if available. Callback should fill in request_info->ha1.
70 };
71 
72 // Prototype for the user-defined function. Mongoose calls this function
73 // on every event mentioned above.
74 //
75 // Parameters:
76 // event: which event has been triggered.
77 // conn: opaque connection handler. Could be used to read, write data to the
78 // client, etc. See functions below that accept "mg_connection *".
79 // request_info: Information about HTTP request.
80 //
81 // Return:
82 // If handler returns non-NULL, that means that handler has processed the
83 // request by sending appropriate HTTP reply to the client. Mongoose treats
84 // the request as served.
85 // If callback returns NULL, that means that callback has not processed
86 // the request. Handler must not send any data to the client in this case.
87 // Mongoose proceeds with request handling as if nothing happened.
88 typedef void * (*mg_callback_t)(enum mg_event event,
89  struct mg_connection *conn,
90  const struct mg_request_info *request_info);
91 
92 
93 // Start web server.
94 //
95 // Parameters:
96 // callback: user defined event handling function or NULL.
97 // options: NULL terminated list of option_name, option_value pairs that
98 // specify Mongoose configuration parameters.
99 //
100 // Example:
101 // const char *options[] = {
102 // "document_root", "/var/www",
103 // "listening_ports", "80,443s",
104 // NULL
105 // };
106 // struct mg_context *ctx = mg_start(&my_func, options);
107 //
108 // Please refer to http://code.google.com/p/mongoose/wiki/MongooseManual
109 // for the list of valid option and their possible values.
110 //
111 // Return:
112 // web server context, or NULL on error.
113 struct mg_context *mg_start(mg_callback_t callback, void *user_data,
114  const char **options);
115 
116 
117 // Stop the web server.
118 //
119 // Must be called last, when an application wants to stop the web server and
120 // release all associated resources. This function blocks until all Mongoose
121 // threads are stopped. Context pointer becomes invalid.
122 void mg_stop(struct mg_context *);
123 
124 
125 // Get the value of particular configuration parameter.
126 // The value returned is read-only. Mongoose does not allow changing
127 // configuration at run time.
128 // If given parameter name is not valid, NULL is returned. For valid
129 // names, return value is guaranteed to be non-NULL. If parameter is not
130 // set, zero-length string is returned.
131 const char *mg_get_option(const struct mg_context *ctx, const char *name);
132 
133 
134 // Return array of strings that represent valid configuration options.
135 // For each option, a short name, long name, and default value is returned.
136 // Array is NULL terminated.
137 const char **mg_get_valid_option_names(void);
138 
139 
140 // Add, edit or delete the entry in the passwords file.
141 //
142 // This function allows an application to manipulate .htpasswd files on the
143 // fly by adding, deleting and changing user records. This is one of the
144 // several ways of implementing authentication on the server side. For another,
145 // cookie-based way please refer to the examples/chat.c in the source tree.
146 //
147 // If password is not NULL, entry is added (or modified if already exists).
148 // If password is NULL, entry is deleted.
149 //
150 // Return:
151 // 1 on success, 0 on error.
152 int mg_modify_passwords_file(struct mg_context *ctx,
153  const char *passwords_file_name, const char *user, const char *password);
154 
155 // Send data to the client.
156 int mg_write(struct mg_connection *, const void *buf, size_t len);
157 
158 
159 // Send data to the browser using printf() semantics.
160 //
161 // Works exactly like mg_write(), but allows to do message formatting.
162 // Note that mg_printf() uses internal buffer of size IO_BUF_SIZE
163 // (8 Kb by default) as temporary message storage for formatting. Do not
164 // print data that is bigger than that, otherwise it will be truncated.
165 int mg_printf(struct mg_connection *, const char *fmt, ...);
166 
167 
168 // Read data from the remote end, return number of bytes read.
169 int mg_read(struct mg_connection *, void *buf, size_t len);
170 
171 // Send a 401 Unauthorized response to the browser.
172 //
173 // This triggers a username/password entry in the browser. The realm
174 // in the request is set to the AUTHENTICATION_DOMAIN option.
175 // If nonce is non-NULL, it is sent as the nonce of the authentication
176 // request, else a nonce is generated.
177 void mg_send_authorization_request(struct mg_connection *conn, const char *nonce);
178 
179 // Get the value of particular HTTP header.
180 //
181 // This is a helper function. It traverses request_info->http_headers array,
182 // and if the header is present in the array, returns its value. If it is
183 // not present, NULL is returned.
184 const char *mg_get_header(const struct mg_connection *, const char *name);
185 
186 
187 // Get a value of particular form variable.
188 //
189 // Parameters:
190 // data: pointer to form-uri-encoded buffer. This could be either POST data,
191 // or request_info.query_string.
192 // data_len: length of the encoded data.
193 // var_name: variable name to decode from the buffer
194 // buf: destination buffer for the decoded variable
195 // buf_len: length of the destination buffer
196 //
197 // Return:
198 // On success, length of the decoded variable.
199 // On error, -1 (variable not found, or destination buffer is too small).
200 //
201 // Destination buffer is guaranteed to be '\0' - terminated. In case of
202 // failure, dst[0] == '\0'.
203 int mg_get_var(const char *data, size_t data_len,
204  const char *var_name, char *buf, size_t buf_len);
205 
206 // Fetch value of certain cookie variable into the destination buffer.
207 //
208 // Destination buffer is guaranteed to be '\0' - terminated. In case of
209 // failure, dst[0] == '\0'. Note that RFC allows many occurrences of the same
210 // parameter. This function returns only first occurrence.
211 //
212 // Return:
213 // On success, value length.
214 // On error, -1 (either "Cookie:" header is not present at all, or the
215 // requested parameter is not found, or destination buffer is too small
216 // to hold the value).
217 int mg_get_cookie(const struct mg_connection *,
218  const char *cookie_name, char *buf, size_t buf_len);
219 
220 
221 // Return Mongoose version.
222 const char *mg_version(void);
223 
224 
225 // MD5 hash given strings.
226 // Buffer 'buf' must be 33 bytes long. Varargs is a NULL terminated list of
227 // asciiz strings. When function returns, buf will contain human-readable
228 // MD5 hash. Example:
229 // char buf[33];
230 // mg_md5(buf, "aa", "bb", NULL);
231 void mg_md5(char *buf, ...);
232 
233 // read user data from connection
234 // required to read user data outside of mongoose.c
235 void *mg_read_user_data(struct mg_connection *conn);
236 
237 #ifdef __cplusplus
238 }
239 #endif // __cplusplus
240 
241 #endif // MONGOOSE_HEADER_INCLUDED