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


jpeg_streamer
Author(s): Ken Tossell
autogenerated on Sat Jun 8 2019 17:54:10