source: rtems/cpukit/mghttpd/mongoose.h @ 121dd881

4.115
Last change on this file since 121dd881 was 5267241, checked in by Christian Mauderer <christian.mauderer@…>, on 06/28/12 at 13:03:39

mghttpd: Clarify comment

  • Property mode set to 100644
File size: 9.1 KB
Line 
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
27extern "C" {
28#endif // __cplusplus
29
30struct mg_context;     // Handle for the HTTP service itself
31struct mg_connection;  // Handle for the individual connection
32
33
34// This structure contains information about the HTTP request.
35struct 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;    // URL part after '?' (not including '?') or NULL
41  char *remote_user;     // Authenticated user, or NULL if no auth used
42  char *log_message;     // Mongoose error log message, MG_EVENT_LOG only
43  long remote_ip;        // Client's IP address
44  int remote_port;       // Client's port
45  int status_code;       // HTTP reply status code, e.g. 200
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.
55enum 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  MG_REQUEST_COMPLETE  // Mongoose has finished handling the request
62};
63
64// Prototype for the user-defined function. Mongoose calls this function
65// on every MG_* event.
66//
67// Parameters:
68//   event: which event has been triggered.
69//   conn: opaque connection handler. Could be used to read, write data to the
70//         client, etc. See functions below that have "mg_connection *" arg.
71//   request_info: Information about HTTP request.
72//
73// Return:
74//   If handler returns non-NULL, that means that handler has processed the
75//   request by sending appropriate HTTP reply to the client. Mongoose treats
76//   the request as served.
77//   If handler returns NULL, that means that handler has not processed
78//   the request. Handler must not send any data to the client in this case.
79//   Mongoose proceeds with request handling as if nothing happened.
80typedef void * (*mg_callback_t)(enum mg_event event,
81                                struct mg_connection *conn,
82                                const struct mg_request_info *request_info);
83
84
85// Start web server.
86//
87// Parameters:
88//   callback: user defined event handling function or NULL.
89//   options: NULL terminated list of option_name, option_value pairs that
90//            specify Mongoose configuration parameters.
91//
92// Side-effects: on UNIX, ignores SIGCHLD and SIGPIPE signals. If custom
93//    processing is required for these, signal handlers must be set up
94//    after calling mg_start().
95//
96//
97// Example:
98//   const char *options[] = {
99//     "document_root", "/var/www",
100//     "listening_ports", "80,443s",
101//     NULL
102//   };
103//   struct mg_context *ctx = mg_start(&my_func, NULL, options);
104//
105// Please refer to http://code.google.com/p/mongoose/wiki/MongooseManual
106// for the list of valid option and their possible values.
107//
108// Return:
109//   web server context, or NULL on error.
110struct mg_context *mg_start(mg_callback_t callback, void *user_data,
111                            const char **options);
112
113
114// Stop the web server.
115//
116// Must be called last, when an application wants to stop the web server and
117// release all associated resources. This function blocks until all Mongoose
118// threads are stopped. Context pointer becomes invalid.
119void mg_stop(struct mg_context *);
120
121
122// Get the value of particular configuration parameter.
123// The value returned is read-only. Mongoose does not allow changing
124// configuration at run time.
125// If given parameter name is not valid, NULL is returned. For valid
126// names, return value is guaranteed to be non-NULL. If parameter is not
127// set, zero-length string is returned.
128const char *mg_get_option(const struct mg_context *ctx, const char *name);
129
130
131// Return array of strings that represent valid configuration options.
132// For each option, a short name, long name, and default value is returned.
133// Array is NULL terminated.
134const char **mg_get_valid_option_names(void);
135
136
137// Add, edit or delete the entry in the passwords file.
138//
139// This function allows an application to manipulate .htpasswd files on the
140// fly by adding, deleting and changing user records. This is one of the
141// several ways of implementing authentication on the server side. For another,
142// cookie-based way please refer to the examples/chat.c in the source tree.
143//
144// If password is not NULL, entry is added (or modified if already exists).
145// If password is NULL, entry is deleted.
146//
147// Return:
148//   1 on success, 0 on error.
149int mg_modify_passwords_file(const char *passwords_file_name,
150                             const char *domain,
151                             const char *user,
152                             const char *password);
153
154// Send data to the client.
155int mg_write(struct mg_connection *, const void *buf, size_t len);
156
157
158// Send data to the browser using printf() semantics.
159//
160// Works exactly like mg_write(), but allows to do message formatting.  Note
161// that mg_printf() uses internal buffer of size BUFSIZ defined in <stdio.h>
162// (8 KiB on most Linux systems) as temporary message storage for formatting.
163// Do not print data that is bigger than that, otherwise it will be truncated.
164int mg_printf(struct mg_connection *, const char *fmt, ...)
165#ifdef __GNUC__
166__attribute__((format(printf, 2, 3)))
167#endif
168;
169
170
171// Send contents of the entire file together with HTTP headers.
172void mg_send_file(struct mg_connection *conn, const char *path);
173
174
175// Read data from the remote end, return number of bytes read.
176int mg_read(struct mg_connection *, void *buf, size_t len);
177
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.
184const 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'.
203int 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, 0 (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).
217int mg_get_cookie(const struct mg_connection *,
218                  const char *cookie_name, char *buf, size_t buf_len);
219
220
221// Return Mongoose version.
222const 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);
231void mg_md5(char *buf, ...);
232
233
234#ifdef __cplusplus
235}
236#endif // __cplusplus
237
238#endif // MONGOOSE_HEADER_INCLUDED
Note: See TracBrowser for help on using the repository browser.