Logo ROOT  
Reference Guide
civetweb.h
Go to the documentation of this file.
1/* Copyright (c) 2013-2018 the Civetweb developers
2 * Copyright (c) 2004-2013 Sergey Lyubka
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a copy
5 * of this software and associated documentation files (the "Software"), to deal
6 * in the Software without restriction, including without limitation the rights
7 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8 * copies of the Software, and to permit persons to whom the Software is
9 * furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included in
12 * all copies or substantial portions of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20 * THE SOFTWARE.
21 */
22
23#ifndef CIVETWEB_HEADER_INCLUDED
24#define CIVETWEB_HEADER_INCLUDED
25
26#define CIVETWEB_VERSION "1.12"
27#define CIVETWEB_VERSION_MAJOR (1)
28#define CIVETWEB_VERSION_MINOR (12)
29#define CIVETWEB_VERSION_PATCH (0)
30
31#ifndef CIVETWEB_API
32#if defined(_WIN32)
33#if defined(CIVETWEB_DLL_EXPORTS)
34#define CIVETWEB_API __declspec(dllexport)
35#elif defined(CIVETWEB_DLL_IMPORTS)
36#define CIVETWEB_API __declspec(dllimport)
37#else
38#define CIVETWEB_API
39#endif
40#elif __GNUC__ >= 4
41#define CIVETWEB_API __attribute__((visibility("default")))
42#else
43#define CIVETWEB_API
44#endif
45#endif
46
47#include <stddef.h>
48#include <stdio.h>
49
50#ifdef __cplusplus
51extern "C" {
52#endif /* __cplusplus */
53
54
55/* Init Features */
56enum {
58
59 /* Support files from local directories */
60 /* Will only work, if NO_FILES is not set. */
62
63 /* Support transport layer security (TLS). */
64 /* SSL is still often used synonymously for TLS. */
65 /* Will only work, if NO_SSL is not set. */
68
69 /* Support common gateway interface (CGI). */
70 /* Will only work, if NO_CGI is not set. */
72
73 /* Support IPv6. */
74 /* Will only work, if USE_IPV6 is set. */
76
77 /* Support WebSocket protocol. */
78 /* Will only work, if USE_WEBSOCKET is set. */
80
81 /* Support server side Lua scripting. */
82 /* Will only work, if USE_LUA is set. */
84
85 /* Support server side JavaScript scripting. */
86 /* Will only work, if USE_DUKTAPE is set. */
88
89 /* Provide data required for caching files. */
90 /* Will only work, if NO_CACHING is not set. */
92
93 /* Collect server status information. */
94 /* Will only work, if USE_SERVER_STATS is set. */
96
97 /* Support on-the-fly compression. */
98 /* Will only work, if USE_ZLIB is set. */
100
101 /* Collect server status information. */
102 /* Will only work, if USE_SERVER_STATS is set. */
103 MG_FEATURES_ALL = 0xFFFFu
105
106
107/* Initialize this library. This should be called once before any other
108 * function from this library. This function is not guaranteed to be
109 * thread safe.
110 * Parameters:
111 * features: bit mask for features to be initialized.
112 * Note: The TLS libraries (like OpenSSL) is initialized
113 * only if the MG_FEATURES_TLS bit is set.
114 * Currently the other bits do not influence
115 * initialization, but this may change in future
116 * versions.
117 * Return value:
118 * initialized features
119 * 0: error
120 */
121CIVETWEB_API unsigned mg_init_library(unsigned features);
122
123
124/* Un-initialize this library.
125 * Return value:
126 * 0: error
127 */
128CIVETWEB_API unsigned mg_exit_library(void);
129
130
131struct mg_context; /* Handle for the HTTP service itself */
132struct mg_connection; /* Handle for the individual connection */
133
134
135/* Maximum number of headers */
136#define MG_MAX_HEADERS (64)
137
138struct mg_header {
139 const char *name; /* HTTP header name */
140 const char *value; /* HTTP header value */
141};
142
143
144/* This structure contains information about the HTTP request. */
146 const char *request_method; /* "GET", "POST", etc */
147 const char *request_uri; /* URL-decoded URI (absolute or relative,
148 * as in the request) */
149 const char *local_uri; /* URL-decoded URI (relative). Can be NULL
150 * if the request_uri does not address a
151 * resource at the server host. */
152#if defined(MG_LEGACY_INTERFACE) /* 2017-02-04, deprecated 2014-09-14 */
153 const char *uri; /* Deprecated: use local_uri instead */
154#endif
155 const char *http_version; /* E.g. "1.0", "1.1" */
156 const char *query_string; /* URL part after '?', not including '?', or
157 NULL */
158 const char *remote_user; /* Authenticated user, or NULL if no auth
159 used */
160 char remote_addr[48]; /* Client's IP address as a string. */
161
162 long long content_length; /* Length (in bytes) of the request body,
163 can be -1 if no length was given. */
164 int remote_port; /* Client's port */
165 int is_ssl; /* 1 if SSL-ed, 0 if not */
166 void *user_data; /* User data pointer passed to mg_start() */
167 void *conn_data; /* Connection-specific user data */
168
169 int num_headers; /* Number of HTTP headers */
170 struct mg_header
171 http_headers[MG_MAX_HEADERS]; /* Allocate maximum headers */
172
173 struct mg_client_cert *client_cert; /* Client certificate information */
174
175 const char *acceptedWebSocketSubprotocol; /* websocket subprotocol,
176 * accepted during handshake */
177};
178
179
180/* This structure contains information about the HTTP request. */
181/* This structure may be extended in future versions. */
183 int status_code; /* E.g. 200 */
184 const char *status_text; /* E.g. "OK" */
185 const char *http_version; /* E.g. "1.0", "1.1" */
186
187 long long content_length; /* Length (in bytes) of the request body,
188 can be -1 if no length was given. */
189
190 int num_headers; /* Number of HTTP headers */
191 struct mg_header
192 http_headers[MG_MAX_HEADERS]; /* Allocate maximum headers */
193};
194
195
196/* Client certificate information (part of mg_request_info) */
197/* New nomenclature. */
200 const char *subject;
201 const char *issuer;
202 const char *serial;
203 const char *finger;
204};
205
206#if defined(MG_LEGACY_INTERFACE) /* 2017-10-05 */
207/* Old nomenclature. */
208struct client_cert {
209 const char *subject;
210 const char *issuer;
211 const char *serial;
212 const char *finger;
213};
214#endif
215
216
217/* This structure needs to be passed to mg_start(), to let civetweb know
218 which callbacks to invoke. For a detailed description, see
219 https://github.com/civetweb/civetweb/blob/master/docs/UserManual.md */
221 /* Called when civetweb has received new HTTP request.
222 If the callback returns one, it must process the request
223 by sending valid HTTP headers and a body. Civetweb will not do
224 any further processing. Otherwise it must return zero.
225 Note that since V1.7 the "begin_request" function is called
226 before an authorization check. If an authorization check is
227 required, use a request_handler instead.
228 Return value:
229 0: civetweb will process the request itself. In this case,
230 the callback must not send any data to the client.
231 1-999: callback already processed the request. Civetweb will
232 not send any data after the callback returned. The
233 return code is stored as a HTTP status code for the
234 access log. */
235 int (*begin_request)(struct mg_connection *);
236
237 /* Called when civetweb has finished processing request. */
238 void (*end_request)(const struct mg_connection *, int reply_status_code);
239
240 /* Called when civetweb is about to log a message. If callback returns
241 non-zero, civetweb does not log anything. */
242 int (*log_message)(const struct mg_connection *, const char *message);
243
244 /* Called when civetweb is about to log access. If callback returns
245 non-zero, civetweb does not log anything. */
246 int (*log_access)(const struct mg_connection *, const char *message);
247
248 /* Called when civetweb initializes SSL library.
249 Parameters:
250 user_data: parameter user_data passed when starting the server.
251 Return value:
252 0: civetweb will set up the SSL certificate.
253 1: civetweb assumes the callback already set up the certificate.
254 -1: initializing ssl fails. */
255 int (*init_ssl)(void *ssl_context, void *user_data);
256
257 /* Called when civetweb is about to create or free a SSL_CTX.
258 Parameters:
259 ssl_ctx: SSL_CTX pointer. NULL at creation time, Not NULL when mg_context
260 will be freed
261 user_data: parameter user_data passed when starting the server.
262 Return value:
263 0: civetweb will continue to create the context, just as if the
264 callback would not be present.
265 The value in *ssl_ctx when the function returns is ignored.
266 1: civetweb will copy the value from *ssl_ctx to the civetweb context
267 and doesn't create its own.
268 -1: initializing ssl fails.*/
269 int (*external_ssl_ctx)(void **ssl_ctx, void *user_data);
270
271#if defined(MG_LEGACY_INTERFACE) /* 2015-08-19 */
272 /* Called when websocket request is received, before websocket handshake.
273 Return value:
274 0: civetweb proceeds with websocket handshake.
275 1: connection is closed immediately.
276 This callback is deprecated: Use mg_set_websocket_handler instead. */
277 int (*websocket_connect)(const struct mg_connection *);
278
279 /* Called when websocket handshake is successfully completed, and
280 connection is ready for data exchange.
281 This callback is deprecated: Use mg_set_websocket_handler instead. */
282 void (*websocket_ready)(struct mg_connection *);
283
284 /* Called when data frame has been received from the client.
285 Parameters:
286 bits: first byte of the websocket frame, see websocket RFC at
287 http://tools.ietf.org/html/rfc6455, section 5.2
288 data, data_len: payload, with mask (if any) already applied.
289 Return value:
290 1: keep this websocket connection open.
291 0: close this websocket connection.
292 This callback is deprecated: Use mg_set_websocket_handler instead. */
293 int (*websocket_data)(struct mg_connection *,
294 int bits,
295 char *data,
296 size_t data_len);
297#endif /* MG_LEGACY_INTERFACE */
298
299 /* Called when civetweb is closing a connection. The per-context mutex is
300 locked when this is invoked.
301
302 Websockets:
303 Before mg_set_websocket_handler has been added, it was primarily useful
304 for noting when a websocket is closing, and used to remove it from any
305 application-maintained list of clients.
306 Using this callback for websocket connections is deprecated: Use
307 mg_set_websocket_handler instead.
308
309 Connection specific data:
310 If memory has been allocated for the connection specific user data
311 (mg_request_info->conn_data, mg_get_user_connection_data),
312 this is the last chance to free it.
313 */
314 void (*connection_close)(const struct mg_connection *);
315
316 /* Called when civetweb is about to serve Lua server page, if
317 Lua support is enabled.
318 Parameters:
319 conn: current connection.
320 lua_context: "lua_State *" pointer. */
321 void (*init_lua)(const struct mg_connection *conn, void *lua_context);
322
323#if defined(MG_LEGACY_INTERFACE) /* 2016-05-14 */
324 /* Called when civetweb has uploaded a file to a temporary directory as a
325 result of mg_upload() call.
326 Note that mg_upload is deprecated. Use mg_handle_form_request instead.
327 Parameters:
328 file_name: full path name to the uploaded file. */
329 void (*upload)(struct mg_connection *, const char *file_name);
330#endif
331
332 /* Called when civetweb is about to send HTTP error to the client.
333 Implementing this callback allows to create custom error pages.
334 Parameters:
335 conn: current connection.
336 status: HTTP error status code.
337 errmsg: error message text.
338 Return value:
339 1: run civetweb error handler.
340 0: callback already handled the error. */
341 int (*http_error)(struct mg_connection *conn,
342 int status,
343 const char *errmsg);
344
345 /* Called after civetweb context has been created, before requests
346 are processed.
347 Parameters:
348 ctx: context handle */
349 void (*init_context)(const struct mg_context *ctx);
350
351 /* Called when a new worker thread is initialized.
352 Parameters:
353 ctx: context handle
354 thread_type:
355 0 indicates the master thread
356 1 indicates a worker thread handling client connections
357 2 indicates an internal helper thread (timer thread)
358 */
359 void (*init_thread)(const struct mg_context *ctx, int thread_type);
360
361 /* Called when civetweb context is deleted.
362 Parameters:
363 ctx: context handle */
364 void (*exit_context)(const struct mg_context *ctx);
365
366 /* Called when initializing a new connection object.
367 * Can be used to initialize the connection specific user data
368 * (mg_request_info->conn_data, mg_get_user_connection_data).
369 * When the callback is called, it is not yet known if a
370 * valid HTTP(S) request will be made.
371 * Parameters:
372 * conn: not yet fully initialized connection object
373 * conn_data: output parameter, set to initialize the
374 * connection specific user data
375 * Return value:
376 * must be 0
377 * Otherwise, the result is undefined
378 */
379 int (*init_connection)(const struct mg_connection *conn, void **conn_data);
380};
381
382
383/* Start web server.
384
385 Parameters:
386 callbacks: mg_callbacks structure with user-defined callbacks.
387 options: NULL terminated list of option_name, option_value pairs that
388 specify Civetweb configuration parameters.
389
390 Side-effects: on UNIX, ignores SIGCHLD and SIGPIPE signals. If custom
391 processing is required for these, signal handlers must be set up
392 after calling mg_start().
393
394
395 Example:
396 const char *options[] = {
397 "document_root", "/var/www",
398 "listening_ports", "80,443s",
399 NULL
400 };
401 struct mg_context *ctx = mg_start(&my_func, NULL, options);
402
403 Refer to https://github.com/civetweb/civetweb/blob/master/docs/UserManual.md
404 for the list of valid option and their possible values.
405
406 Return:
407 web server context, or NULL on error. */
408CIVETWEB_API struct mg_context *mg_start(const struct mg_callbacks *callbacks,
409 void *user_data,
410 const char **configuration_options);
411
412
413/* Stop the web server.
414
415 Must be called last, when an application wants to stop the web server and
416 release all associated resources. This function blocks until all Civetweb
417 threads are stopped. Context pointer becomes invalid. */
418CIVETWEB_API void mg_stop(struct mg_context *);
419
420
421#if defined(MG_EXPERIMENTAL_INTERFACES)
422/* Add an additional domain to an already running web server.
423 *
424 * Parameters:
425 * ctx: Context handle of a server started by mg_start.
426 * options: NULL terminated list of option_name, option_value pairs that
427 * specify CivetWeb configuration parameters.
428 *
429 * Return:
430 * < 0 in case of an error
431 * -1 for a parameter error
432 * -2 invalid options
433 * -3 initializing SSL failed
434 * -4 mandatory domain option missing
435 * -5 duplicate domain
436 * -6 out of memory
437 * > 0 index / handle of a new domain
438 */
439CIVETWEB_API int mg_start_domain(struct mg_context *ctx,
440 const char **configuration_options);
441#endif
442
443
444/* mg_request_handler
445
446 Called when a new request comes in. This callback is URI based
447 and configured with mg_set_request_handler().
448
449 Parameters:
450 conn: current connection information.
451 cbdata: the callback data configured with mg_set_request_handler().
452 Returns:
453 0: the handler could not handle the request, so fall through.
454 1 - 999: the handler processed the request. The return code is
455 stored as a HTTP status code for the access log. */
456typedef int (*mg_request_handler)(struct mg_connection *conn, void *cbdata);
457
458
459/* mg_set_request_handler
460
461 Sets or removes a URI mapping for a request handler.
462 This function uses mg_lock_context internally.
463
464 URI's are ordered and prefixed URI's are supported. For example,
465 consider two URIs: /a/b and /a
466 /a matches /a
467 /a/b matches /a/b
468 /a/c matches /a
469
470 Parameters:
471 ctx: server context
472 uri: the URI (exact or pattern) for the handler
473 handler: the callback handler to use when the URI is requested.
474 If NULL, an already registered handler for this URI will
475 be removed.
476 The URI used to remove a handler must match exactly the
477 one used to register it (not only a pattern match).
478 cbdata: the callback data to give to the handler when it is called. */
479CIVETWEB_API void mg_set_request_handler(struct mg_context *ctx,
480 const char *uri,
481 mg_request_handler handler,
482 void *cbdata);
483
484
485/* Callback types for websocket handlers in C/C++.
486
487 mg_websocket_connect_handler
488 Is called when the client intends to establish a websocket connection,
489 before websocket handshake.
490 Return value:
491 0: civetweb proceeds with websocket handshake.
492 1: connection is closed immediately.
493
494 mg_websocket_ready_handler
495 Is called when websocket handshake is successfully completed, and
496 connection is ready for data exchange.
497
498 mg_websocket_data_handler
499 Is called when a data frame has been received from the client.
500 Parameters:
501 bits: first byte of the websocket frame, see websocket RFC at
502 http://tools.ietf.org/html/rfc6455, section 5.2
503 data, data_len: payload, with mask (if any) already applied.
504 Return value:
505 1: keep this websocket connection open.
506 0: close this websocket connection.
507
508 mg_connection_close_handler
509 Is called, when the connection is closed.*/
510typedef int (*mg_websocket_connect_handler)(const struct mg_connection *,
511 void *);
512typedef void (*mg_websocket_ready_handler)(struct mg_connection *, void *);
513typedef int (*mg_websocket_data_handler)(struct mg_connection *,
514 int,
515 char *,
516 size_t,
517 void *);
518typedef void (*mg_websocket_close_handler)(const struct mg_connection *,
519 void *);
520
521/* struct mg_websocket_subprotocols
522 *
523 * List of accepted subprotocols
524 */
528};
529
530/* mg_set_websocket_handler
531
532 Set or remove handler functions for websocket connections.
533 This function works similar to mg_set_request_handler - see there. */
534CIVETWEB_API void
535mg_set_websocket_handler(struct mg_context *ctx,
536 const char *uri,
537 mg_websocket_connect_handler connect_handler,
538 mg_websocket_ready_handler ready_handler,
539 mg_websocket_data_handler data_handler,
540 mg_websocket_close_handler close_handler,
541 void *cbdata);
542
543/* mg_set_websocket_handler
544
545 Set or remove handler functions for websocket connections.
546 This function works similar to mg_set_request_handler - see there. */
548 struct mg_context *ctx,
549 const char *uri,
550 struct mg_websocket_subprotocols *subprotocols,
551 mg_websocket_connect_handler connect_handler,
552 mg_websocket_ready_handler ready_handler,
553 mg_websocket_data_handler data_handler,
554 mg_websocket_close_handler close_handler,
555 void *cbdata);
556
557
558/* mg_authorization_handler
559
560 Callback function definition for mg_set_auth_handler
561
562 Parameters:
563 conn: current connection information.
564 cbdata: the callback data configured with mg_set_request_handler().
565 Returns:
566 0: access denied
567 1: access granted
568 */
569typedef int (*mg_authorization_handler)(struct mg_connection *conn,
570 void *cbdata);
571
572
573/* mg_set_auth_handler
574
575 Sets or removes a URI mapping for an authorization handler.
576 This function works similar to mg_set_request_handler - see there. */
577CIVETWEB_API void mg_set_auth_handler(struct mg_context *ctx,
578 const char *uri,
580 void *cbdata);
581
582
583/* Get the value of particular configuration parameter.
584 The value returned is read-only. Civetweb does not allow changing
585 configuration at run time.
586 If given parameter name is not valid, NULL is returned. For valid
587 names, return value is guaranteed to be non-NULL. If parameter is not
588 set, zero-length string is returned. */
589CIVETWEB_API const char *mg_get_option(const struct mg_context *ctx,
590 const char *name);
591
592
593/* Get context from connection. */
594CIVETWEB_API struct mg_context *
595mg_get_context(const struct mg_connection *conn);
596
597
598/* Get user data passed to mg_start from context. */
599CIVETWEB_API void *mg_get_user_data(const struct mg_context *ctx);
600
601
602/* Set user data for the current connection. */
603/* Note: This function is deprecated. Use the init_connection callback
604 instead to initialize the user connection data pointer. It is
605 reccomended to supply a pointer to some user defined data structure
606 as conn_data initializer in init_connection. In case it is required
607 to change some data after the init_connection call, store another
608 data pointer in the user defined data structure and modify that
609 pointer. In either case, after the init_connection callback, only
610 calls to mg_get_user_connection_data should be required. */
611CIVETWEB_API void mg_set_user_connection_data(struct mg_connection *conn,
612 void *data);
613
614
615/* Get user data set for the current connection. */
616CIVETWEB_API void *
617mg_get_user_connection_data(const struct mg_connection *conn);
618
619
620/* Get a formatted link corresponding to the current request
621
622 Parameters:
623 conn: current connection information.
624 buf: string buffer (out)
625 buflen: length of the string buffer
626 Returns:
627 <0: error
628 >=0: ok */
629CIVETWEB_API int
630mg_get_request_link(const struct mg_connection *conn, char *buf, size_t buflen);
631
632
633#if defined(MG_LEGACY_INTERFACE) /* 2014-02-21 */
634/* Return array of strings that represent valid configuration options.
635 For each option, option name and default value is returned, i.e. the
636 number of entries in the array equals to number_of_options x 2.
637 Array is NULL terminated. */
638/* Deprecated: Use mg_get_valid_options instead. */
639CIVETWEB_API const char **mg_get_valid_option_names(void);
640#endif
641
642
643struct mg_option {
644 const char *name;
645 int type;
646 const char *default_value;
647};
648
649/* Old nomenclature */
650#if defined(MG_LEGACY_INTERFACE) /* 2017-10-05 */
651enum {
652 CONFIG_TYPE_UNKNOWN = 0x0,
653 CONFIG_TYPE_NUMBER = 0x1,
654 CONFIG_TYPE_STRING = 0x2,
655 CONFIG_TYPE_FILE = 0x3,
656 CONFIG_TYPE_DIRECTORY = 0x4,
657 CONFIG_TYPE_BOOLEAN = 0x5,
658 CONFIG_TYPE_EXT_PATTERN = 0x6,
659 CONFIG_TYPE_STRING_LIST = 0x7,
660 CONFIG_TYPE_STRING_MULTILINE = 0x8
661};
662#endif
663
664/* New nomenclature */
665enum {
677
678/* Return array of struct mg_option, representing all valid configuration
679 options of civetweb.c.
680 The array is terminated by a NULL name option. */
682
683
685 int protocol; /* 1 = IPv4, 2 = IPv6, 3 = both */
686 int port; /* port number */
687 int is_ssl; /* https port: 0 = no, 1 = yes */
688 int is_redirect; /* redirect all requests: 0 = no, 1 = yes */
693};
694
695
696/* Get the list of ports that civetweb is listening on.
697 The parameter size is the size of the ports array in elements.
698 The caller is responsibility to allocate the required memory.
699 This function returns the number of struct mg_server_ports elements
700 filled in, or <0 in case of an error. */
701CIVETWEB_API int mg_get_server_ports(const struct mg_context *ctx,
702 int size,
703 struct mg_server_ports *ports);
704
705
706#if defined(MG_LEGACY_INTERFACE) /* 2017-04-02 */
707/* Deprecated: Use mg_get_server_ports instead. */
708CIVETWEB_API size_t mg_get_ports(const struct mg_context *ctx,
709 size_t size,
710 int *ports,
711 int *ssl);
712#endif
713
714
715/* Add, edit or delete the entry in the passwords file.
716 *
717 * This function allows an application to manipulate .htpasswd files on the
718 * fly by adding, deleting and changing user records. This is one of the
719 * several ways of implementing authentication on the server side. For another,
720 * cookie-based way please refer to the examples/chat in the source tree.
721 *
722 * Parameter:
723 * passwords_file_name: Path and name of a file storing multiple passwords
724 * realm: HTTP authentication realm (authentication domain) name
725 * user: User name
726 * password:
727 * If password is not NULL, entry modified or added.
728 * If password is NULL, entry is deleted.
729 *
730 * Return:
731 * 1 on success, 0 on error.
732 */
733CIVETWEB_API int mg_modify_passwords_file(const char *passwords_file_name,
734 const char *realm,
735 const char *user,
736 const char *password);
737
738
739/* Return information associated with the request.
740 * Use this function to implement a server and get data about a request
741 * from a HTTP/HTTPS client.
742 * Note: Before CivetWeb 1.10, this function could be used to read
743 * a response from a server, when implementing a client, although the
744 * values were never returned in appropriate mg_request_info elements.
745 * It is strongly advised to use mg_get_response_info for clients.
746 */
747CIVETWEB_API const struct mg_request_info *
748mg_get_request_info(const struct mg_connection *);
749
750
751/* Return information associated with a HTTP/HTTPS response.
752 * Use this function in a client, to check the response from
753 * the server. */
754CIVETWEB_API const struct mg_response_info *
755mg_get_response_info(const struct mg_connection *);
756
757
758/* Send data to the client.
759 Return:
760 0 when the connection has been closed
761 -1 on error
762 >0 number of bytes written on success */
763CIVETWEB_API int mg_write(struct mg_connection *, const void *buf, size_t len);
764
765
766/* Send data to a websocket client wrapped in a websocket frame. Uses
767 mg_lock_connection to ensure that the transmission is not interrupted,
768 i.e., when the application is proactively communicating and responding to
769 a request simultaneously.
770
771 Send data to a websocket client wrapped in a websocket frame.
772 This function is available when civetweb is compiled with -DUSE_WEBSOCKET
773
774 Return:
775 0 when the connection has been closed
776 -1 on error
777 >0 number of bytes written on success */
778CIVETWEB_API int mg_websocket_write(struct mg_connection *conn,
779 int opcode,
780 const char *data,
781 size_t data_len);
782
783
784/* Send data to a websocket server wrapped in a masked websocket frame. Uses
785 mg_lock_connection to ensure that the transmission is not interrupted,
786 i.e., when the application is proactively communicating and responding to
787 a request simultaneously.
788
789 Send data to a websocket server wrapped in a masked websocket frame.
790 This function is available when civetweb is compiled with -DUSE_WEBSOCKET
791
792 Return:
793 0 when the connection has been closed
794 -1 on error
795 >0 number of bytes written on success */
796CIVETWEB_API int mg_websocket_client_write(struct mg_connection *conn,
797 int opcode,
798 const char *data,
799 size_t data_len);
800
801
802/* Blocks until unique access is obtained to this connection. Intended for use
803 with websockets only.
804 Invoke this before mg_write or mg_printf when communicating with a
805 websocket if your code has server-initiated communication as well as
806 communication in direct response to a message. */
807CIVETWEB_API void mg_lock_connection(struct mg_connection *conn);
808CIVETWEB_API void mg_unlock_connection(struct mg_connection *conn);
809
810
811#if defined(MG_LEGACY_INTERFACE) /* 2014-06-21 */
812#define mg_lock mg_lock_connection
813#define mg_unlock mg_unlock_connection
814#endif
815
816
817/* Lock server context. This lock may be used to protect resources
818 that are shared between different connection/worker threads. */
819CIVETWEB_API void mg_lock_context(struct mg_context *ctx);
820CIVETWEB_API void mg_unlock_context(struct mg_context *ctx);
821
822
823/* Opcodes, from http://tools.ietf.org/html/rfc6455 */
824#if defined(MG_LEGACY_INTERFACE) /* 2017-10-05 */
825enum {
826 WEBSOCKET_OPCODE_CONTINUATION = 0x0,
827 WEBSOCKET_OPCODE_TEXT = 0x1,
828 WEBSOCKET_OPCODE_BINARY = 0x2,
829 WEBSOCKET_OPCODE_CONNECTION_CLOSE = 0x8,
830 WEBSOCKET_OPCODE_PING = 0x9,
831 WEBSOCKET_OPCODE_PONG = 0xa
832};
833#endif
834
835/* New nomenclature */
836enum {
844
845/* Macros for enabling compiler-specific checks for printf-like arguments. */
846#undef PRINTF_FORMAT_STRING
847#if defined(_MSC_VER) && _MSC_VER >= 1400
848#include <sal.h>
849#if defined(_MSC_VER) && _MSC_VER > 1400
850#define PRINTF_FORMAT_STRING(s) _Printf_format_string_ s
851#else
852#define PRINTF_FORMAT_STRING(s) __format_string s
853#endif
854#else
855#define PRINTF_FORMAT_STRING(s) s
856#endif
857
858#ifdef __GNUC__
859#define PRINTF_ARGS(x, y) __attribute__((format(printf, x, y)))
860#else
861#define PRINTF_ARGS(x, y)
862#endif
863
864
865/* Send data to the client using printf() semantics.
866 Works exactly like mg_write(), but allows to do message formatting. */
867CIVETWEB_API int mg_printf(struct mg_connection *,
868 PRINTF_FORMAT_STRING(const char *fmt),
869 ...) PRINTF_ARGS(2, 3);
870
871
872/* Send a part of the message body, if chunked transfer encoding is set.
873 * Only use this function after sending a complete HTTP request or response
874 * header with "Transfer-Encoding: chunked" set. */
875CIVETWEB_API int mg_send_chunk(struct mg_connection *conn,
876 const char *chunk,
877 unsigned int chunk_len);
878
879
880/* Send contents of the entire file together with HTTP headers.
881 * Parameters:
882 * conn: Current connection information.
883 * path: Full path to the file to send.
884 * This function has been superseded by mg_send_mime_file
885 */
886CIVETWEB_API void mg_send_file(struct mg_connection *conn, const char *path);
887
888
889/* Send contents of the file without HTTP headers.
890 * The code must send a valid HTTP response header before using this function.
891 *
892 * Parameters:
893 * conn: Current connection information.
894 * path: Full path to the file to send.
895 *
896 * Return:
897 * < 0 Error
898 */
899CIVETWEB_API int mg_send_file_body(struct mg_connection *conn,
900 const char *path);
901
902
903/* Send HTTP error reply. */
904CIVETWEB_API int mg_send_http_error(struct mg_connection *conn,
905 int status_code,
906 PRINTF_FORMAT_STRING(const char *fmt),
907 ...) PRINTF_ARGS(3, 4);
908
909
910/* Send "HTTP 200 OK" response header.
911 * After calling this function, use mg_write or mg_send_chunk to send the
912 * response body.
913 * Parameters:
914 * conn: Current connection handle.
915 * mime_type: Set Content-Type for the following content.
916 * content_length: Size of the following content, if content_length >= 0.
917 * Will set transfer-encoding to chunked, if set to -1.
918 * Return:
919 * < 0 Error
920 */
921CIVETWEB_API int mg_send_http_ok(struct mg_connection *conn,
922 const char *mime_type,
923 long long content_length);
924
925
926/* Send "HTTP 30x" redirect response.
927 * The response has content-size zero: do not send any body data after calling
928 * this function.
929 * Parameters:
930 * conn: Current connection handle.
931 * target_url: New location.
932 * redirect_code: HTTP redirect type. Could be 301, 302, 303, 307, 308.
933 * Return:
934 * < 0 Error (-1 send error, -2 parameter error)
935 */
936CIVETWEB_API int mg_send_http_redirect(struct mg_connection *conn,
937 const char *target_url,
938 int redirect_code);
939
940
941/* Send HTTP digest access authentication request.
942 * Browsers will send a user name and password in their next request, showing
943 * an authentication dialog if the password is not stored.
944 * Parameters:
945 * conn: Current connection handle.
946 * realm: Authentication realm. If NULL is supplied, the sever domain
947 * set in the authentication_domain configuration is used.
948 * Return:
949 * < 0 Error
950 */
951CIVETWEB_API int
952mg_send_digest_access_authentication_request(struct mg_connection *conn,
953 const char *realm);
954
955
956/* Check if the current request has a valid authentication token set.
957 * A file is used to provide a list of valid user names, realms and
958 * password hashes. The file can be created and modified using the
959 * mg_modify_passwords_file API function.
960 * Parameters:
961 * conn: Current connection handle.
962 * realm: Authentication realm. If NULL is supplied, the sever domain
963 * set in the authentication_domain configuration is used.
964 * filename: Path and name of a file storing multiple password hashes.
965 * Return:
966 * > 0 Valid authentication
967 * 0 Invalid authentication
968 * < 0 Error (all values < 0 should be considered as invalid
969 * authentication, future error codes will have negative
970 * numbers)
971 * -1 Parameter error
972 * -2 File not found
973 */
974CIVETWEB_API int
975mg_check_digest_access_authentication(struct mg_connection *conn,
976 const char *realm,
977 const char *filename);
978
979
980/* Send contents of the entire file together with HTTP headers.
981 * Parameters:
982 * conn: Current connection handle.
983 * path: Full path to the file to send.
984 * mime_type: Content-Type for file. NULL will cause the type to be
985 * looked up by the file extension.
986 */
987CIVETWEB_API void mg_send_mime_file(struct mg_connection *conn,
988 const char *path,
989 const char *mime_type);
990
991
992/* Send contents of the entire file together with HTTP headers.
993 Parameters:
994 conn: Current connection information.
995 path: Full path to the file to send.
996 mime_type: Content-Type for file. NULL will cause the type to be
997 looked up by the file extension.
998 additional_headers: Additional custom header fields appended to the header.
999 Each header should start with an X-, to ensure it is
1000 not included twice.
1001 NULL does not append anything.
1002*/
1003CIVETWEB_API void mg_send_mime_file2(struct mg_connection *conn,
1004 const char *path,
1005 const char *mime_type,
1006 const char *additional_headers);
1007
1008
1009/* Store body data into a file. */
1010CIVETWEB_API long long mg_store_body(struct mg_connection *conn,
1011 const char *path);
1012/* Read entire request body and store it in a file "path".
1013 Return:
1014 < 0 Error
1015 >= 0 Number of bytes stored in file "path".
1016*/
1017
1018
1019/* Read data from the remote end, return number of bytes read.
1020 Return:
1021 0 connection has been closed by peer. No more data could be read.
1022 < 0 read error. No more data could be read from the connection.
1023 > 0 number of bytes read into the buffer. */
1024CIVETWEB_API int mg_read(struct mg_connection *, void *buf, size_t len);
1025
1026
1027/* Get the value of particular HTTP header.
1028
1029 This is a helper function. It traverses request_info->http_headers array,
1030 and if the header is present in the array, returns its value. If it is
1031 not present, NULL is returned. */
1032CIVETWEB_API const char *mg_get_header(const struct mg_connection *,
1033 const char *name);
1034
1035
1036/* Get a value of particular form variable.
1037
1038 Parameters:
1039 data: pointer to form-uri-encoded buffer. This could be either POST data,
1040 or request_info.query_string.
1041 data_len: length of the encoded data.
1042 var_name: variable name to decode from the buffer
1043 dst: destination buffer for the decoded variable
1044 dst_len: length of the destination buffer
1045
1046 Return:
1047 On success, length of the decoded variable.
1048 On error:
1049 -1 (variable not found).
1050 -2 (destination buffer is NULL, zero length or too small to hold the
1051 decoded variable).
1052
1053 Destination buffer is guaranteed to be '\0' - terminated if it is not
1054 NULL or zero length. */
1055CIVETWEB_API int mg_get_var(const char *data,
1056 size_t data_len,
1057 const char *var_name,
1058 char *dst,
1059 size_t dst_len);
1060
1061
1062/* Get a value of particular form variable.
1063
1064 Parameters:
1065 data: pointer to form-uri-encoded buffer. This could be either POST data,
1066 or request_info.query_string.
1067 data_len: length of the encoded data.
1068 var_name: variable name to decode from the buffer
1069 dst: destination buffer for the decoded variable
1070 dst_len: length of the destination buffer
1071 occurrence: which occurrence of the variable, 0 is the first, 1 the
1072 second...
1073 this makes it possible to parse a query like
1074 b=x&a=y&a=z which will have occurrence values b:0, a:0 and a:1
1075
1076 Return:
1077 On success, length of the decoded variable.
1078 On error:
1079 -1 (variable not found).
1080 -2 (destination buffer is NULL, zero length or too small to hold the
1081 decoded variable).
1082
1083 Destination buffer is guaranteed to be '\0' - terminated if it is not
1084 NULL or zero length. */
1085CIVETWEB_API int mg_get_var2(const char *data,
1086 size_t data_len,
1087 const char *var_name,
1088 char *dst,
1089 size_t dst_len,
1090 size_t occurrence);
1091
1092
1093/* Fetch value of certain cookie variable into the destination buffer.
1094
1095 Destination buffer is guaranteed to be '\0' - terminated. In case of
1096 failure, dst[0] == '\0'. Note that RFC allows many occurrences of the same
1097 parameter. This function returns only first occurrence.
1098
1099 Return:
1100 On success, value length.
1101 On error:
1102 -1 (either "Cookie:" header is not present at all or the requested
1103 parameter is not found).
1104 -2 (destination buffer is NULL, zero length or too small to hold the
1105 value). */
1106CIVETWEB_API int mg_get_cookie(const char *cookie,
1107 const char *var_name,
1108 char *buf,
1109 size_t buf_len);
1110
1111
1112/* Download data from the remote web server.
1113 host: host name to connect to, e.g. "foo.com", or "10.12.40.1".
1114 port: port number, e.g. 80.
1115 use_ssl: whether to use SSL connection.
1116 error_buffer, error_buffer_size: error message placeholder.
1117 request_fmt,...: HTTP request.
1118 Return:
1119 On success, valid pointer to the new connection, suitable for mg_read().
1120 On error, NULL. error_buffer contains error message.
1121 Example:
1122 char ebuf[100];
1123 struct mg_connection *conn;
1124 conn = mg_download("google.com", 80, 0, ebuf, sizeof(ebuf),
1125 "%s", "GET / HTTP/1.0\r\nHost: google.com\r\n\r\n");
1126 */
1127CIVETWEB_API struct mg_connection *
1128mg_download(const char *host,
1129 int port,
1130 int use_ssl,
1131 char *error_buffer,
1132 size_t error_buffer_size,
1133 PRINTF_FORMAT_STRING(const char *request_fmt),
1134 ...) PRINTF_ARGS(6, 7);
1135
1136
1137/* Close the connection opened by mg_download(). */
1138CIVETWEB_API void mg_close_connection(struct mg_connection *conn);
1139
1140
1141#if defined(MG_LEGACY_INTERFACE) /* 2016-05-14 */
1142/* File upload functionality. Each uploaded file gets saved into a temporary
1143 file and MG_UPLOAD event is sent.
1144 Return number of uploaded files.
1145 Deprecated: Use mg_handle_form_request instead. */
1146CIVETWEB_API int mg_upload(struct mg_connection *conn,
1147 const char *destination_dir);
1148#endif
1149
1150
1151/* This structure contains callback functions for handling form fields.
1152 It is used as an argument to mg_handle_form_request. */
1154 /* This callback function is called, if a new field has been found.
1155 * The return value of this callback is used to define how the field
1156 * should be processed.
1157 *
1158 * Parameters:
1159 * key: Name of the field ("name" property of the HTML input field).
1160 * filename: Name of a file to upload, at the client computer.
1161 * Only set for input fields of type "file", otherwise NULL.
1162 * path: Output parameter: File name (incl. path) to store the file
1163 * at the server computer. Only used if FORM_FIELD_STORAGE_STORE
1164 * is returned by this callback. Existing files will be
1165 * overwritten.
1166 * pathlen: Length of the buffer for path.
1167 * user_data: Value of the member user_data of mg_form_data_handler
1168 *
1169 * Return value:
1170 * The callback must return the intended storage for this field
1171 * (See FORM_FIELD_STORAGE_*).
1172 */
1173 int (*field_found)(const char *key,
1174 const char *filename,
1175 char *path,
1176 size_t pathlen,
1177 void *user_data);
1178
1179 /* If the "field_found" callback returned FORM_FIELD_STORAGE_GET,
1180 * this callback will receive the field data.
1181 *
1182 * Parameters:
1183 * key: Name of the field ("name" property of the HTML input field).
1184 * value: Value of the input field.
1185 * user_data: Value of the member user_data of mg_form_data_handler
1186 *
1187 * Return value:
1188 * The return code determines how the server should continue processing
1189 * the current request (See MG_FORM_FIELD_HANDLE_*).
1190 */
1191 int (*field_get)(const char *key,
1192 const char *value,
1193 size_t valuelen,
1194 void *user_data);
1195
1196 /* If the "field_found" callback returned FORM_FIELD_STORAGE_STORE,
1197 * the data will be stored into a file. If the file has been written
1198 * successfully, this callback will be called. This callback will
1199 * not be called for only partially uploaded files. The
1200 * mg_handle_form_request function will either store the file completely
1201 * and call this callback, or it will remove any partial content and
1202 * not call this callback function.
1203 *
1204 * Parameters:
1205 * path: Path of the file stored at the server.
1206 * file_size: Size of the stored file in bytes.
1207 * user_data: Value of the member user_data of mg_form_data_handler
1208 *
1209 * Return value:
1210 * The return code determines how the server should continue processing
1211 * the current request (See MG_FORM_FIELD_HANDLE_*).
1212 */
1213 int (*field_store)(const char *path, long long file_size, void *user_data);
1214
1215 /* User supplied argument, passed to all callback functions. */
1217};
1218
1219
1220/* Return values definition for the "field_found" callback in
1221 * mg_form_data_handler. */
1222#if defined(MG_LEGACY_INTERFACE) /* 2017-10-05 */
1223enum {
1224 /* Skip this field (neither get nor store it). Continue with the
1225 * next field. */
1226 FORM_FIELD_STORAGE_SKIP = 0x0,
1227 /* Get the field value. */
1228 FORM_FIELD_STORAGE_GET = 0x1,
1229 /* Store the field value into a file. */
1230 FORM_FIELD_STORAGE_STORE = 0x2,
1231 /* Stop parsing this request. Skip the remaining fields. */
1232 FORM_FIELD_STORAGE_ABORT = 0x10
1233};
1234#endif
1235/* New nomenclature */
1236enum {
1237 /* Skip this field (neither get nor store it). Continue with the
1238 * next field. */
1240 /* Get the field value. */
1242 /* Store the field value into a file. */
1244 /* Stop parsing this request. Skip the remaining fields. */
1247
1248/* Return values for "field_get" and "field_store" */
1249enum {
1250 /* Only "field_get": If there is more data in this field, get the next
1251 * chunk. Otherwise: handle the next field. */
1253 /* Handle the next field */
1255 /* Stop parsing this request */
1258
1259
1260/* Process form data.
1261 * Returns the number of fields handled, or < 0 in case of an error.
1262 * Note: It is possible that several fields are already handled successfully
1263 * (e.g., stored into files), before the request handling is stopped with an
1264 * error. In this case a number < 0 is returned as well.
1265 * In any case, it is the duty of the caller to remove files once they are
1266 * no longer required. */
1267CIVETWEB_API int mg_handle_form_request(struct mg_connection *conn,
1268 struct mg_form_data_handler *fdh);
1269
1270
1271/* Convenience function -- create detached thread.
1272 Return: 0 on success, non-0 on error. */
1273typedef void *(*mg_thread_func_t)(void *);
1275
1276
1277/* Return builtin mime type for the given file name.
1278 For unrecognized extensions, "text/plain" is returned. */
1279CIVETWEB_API const char *mg_get_builtin_mime_type(const char *file_name);
1280
1281
1282/* Get text representation of HTTP status code. */
1283CIVETWEB_API const char *
1284mg_get_response_code_text(const struct mg_connection *conn, int response_code);
1285
1286
1287/* Return CivetWeb version. */
1288CIVETWEB_API const char *mg_version(void);
1289
1290
1291/* URL-decode input buffer into destination buffer.
1292 0-terminate the destination buffer.
1293 form-url-encoded data differs from URI encoding in a way that it
1294 uses '+' as character for space, see RFC 1866 section 8.2.1
1295 http://ftp.ics.uci.edu/pub/ietf/html/rfc1866.txt
1296 Return: length of the decoded data, or -1 if dst buffer is too small. */
1297CIVETWEB_API int mg_url_decode(const char *src,
1298 int src_len,
1299 char *dst,
1300 int dst_len,
1301 int is_form_url_encoded);
1302
1303
1304/* URL-encode input buffer into destination buffer.
1305 returns the length of the resulting buffer or -1
1306 is the buffer is too small. */
1307CIVETWEB_API int mg_url_encode(const char *src, char *dst, size_t dst_len);
1308
1309
1310/* MD5 hash given strings.
1311 Buffer 'buf' must be 33 bytes long. Varargs is a NULL terminated list of
1312 ASCIIz strings. When function returns, buf will contain human-readable
1313 MD5 hash. Example:
1314 char buf[33];
1315 mg_md5(buf, "aa", "bb", NULL); */
1316CIVETWEB_API char *mg_md5(char buf[33], ...);
1317
1318
1319/* Print error message to the opened error log stream.
1320 This utilizes the provided logging configuration.
1321 conn: connection (not used for sending data, but to get perameters)
1322 fmt: format string without the line return
1323 ...: variable argument list
1324 Example:
1325 mg_cry(conn,"i like %s", "logging"); */
1326CIVETWEB_API void mg_cry(const struct mg_connection *conn,
1327 PRINTF_FORMAT_STRING(const char *fmt),
1328 ...) PRINTF_ARGS(2, 3);
1329
1330
1331/* utility methods to compare two buffers, case insensitive. */
1332CIVETWEB_API int mg_strcasecmp(const char *s1, const char *s2);
1333CIVETWEB_API int mg_strncasecmp(const char *s1, const char *s2, size_t len);
1334
1335
1336/* Connect to a websocket as a client
1337 Parameters:
1338 host: host to connect to, i.e. "echo.websocket.org" or "192.168.1.1" or
1339 "localhost"
1340 port: server port
1341 use_ssl: make a secure connection to server
1342 error_buffer, error_buffer_size: buffer for an error message
1343 path: server path you are trying to connect to, i.e. if connection to
1344 localhost/app, path should be "/app"
1345 origin: value of the Origin HTTP header
1346 data_func: callback that should be used when data is received from the
1347 server
1348 user_data: user supplied argument
1349
1350 Return:
1351 On success, valid mg_connection object.
1352 On error, NULL. Se error_buffer for details.
1353*/
1354CIVETWEB_API struct mg_connection *
1355mg_connect_websocket_client(const char *host,
1356 int port,
1357 int use_ssl,
1358 char *error_buffer,
1359 size_t error_buffer_size,
1360 const char *path,
1361 const char *origin,
1362 mg_websocket_data_handler data_func,
1363 mg_websocket_close_handler close_func,
1364 void *user_data);
1365
1366
1367/* Connect to a TCP server as a client (can be used to connect to a HTTP server)
1368 Parameters:
1369 host: host to connect to, i.e. "www.wikipedia.org" or "192.168.1.1" or
1370 "localhost"
1371 port: server port
1372 use_ssl: make a secure connection to server
1373 error_buffer, error_buffer_size: buffer for an error message
1374
1375 Return:
1376 On success, valid mg_connection object.
1377 On error, NULL. Se error_buffer for details.
1378*/
1379CIVETWEB_API struct mg_connection *mg_connect_client(const char *host,
1380 int port,
1381 int use_ssl,
1382 char *error_buffer,
1383 size_t error_buffer_size);
1384
1385
1387 const char *host;
1388 int port;
1389 const char *client_cert;
1390 const char *server_cert;
1391 const char *host_name;
1392 /* TODO: add more data */
1393};
1394
1395
1396CIVETWEB_API struct mg_connection *
1397mg_connect_client_secure(const struct mg_client_options *client_options,
1398 char *error_buffer,
1399 size_t error_buffer_size);
1400
1401
1402enum { TIMEOUT_INFINITE = -1 };
1404
1405/* Wait for a response from the server
1406 Parameters:
1407 conn: connection
1408 ebuf, ebuf_len: error message placeholder.
1409 timeout: time to wait for a response in milliseconds (if < 0 then wait
1410 forever)
1411
1412 Return:
1413 On success, >= 0
1414 On error/timeout, < 0
1415*/
1416CIVETWEB_API int mg_get_response(struct mg_connection *conn,
1417 char *ebuf,
1418 size_t ebuf_len,
1419 int timeout);
1420
1421
1422/* Check which features where set when the civetweb library has been compiled.
1423 The function explicitly addresses compile time defines used when building
1424 the library - it does not mean, the feature has been initialized using a
1425 mg_init_library call.
1426 mg_check_feature can be called anytime, even before mg_init_library has
1427 been called.
1428
1429 Parameters:
1430 feature: specifies which feature should be checked
1431 The value is a bit mask. The individual bits are defined as:
1432 1 serve files (NO_FILES not set)
1433 2 support HTTPS (NO_SSL not set)
1434 4 support CGI (NO_CGI not set)
1435 8 support IPv6 (USE_IPV6 set)
1436 16 support WebSocket (USE_WEBSOCKET set)
1437 32 support Lua scripts and Lua server pages (USE_LUA is set)
1438 64 support server side JavaScript (USE_DUKTAPE is set)
1439 128 support caching (NO_CACHING not set)
1440 256 support server statistics (USE_SERVER_STATS is set)
1441 The result is undefined, if bits are set that do not represent a
1442 defined feature (currently: feature >= 512).
1443 The result is undefined, if no bit is set (feature == 0).
1444
1445 Return:
1446 If feature is available, the corresponding bit is set
1447 If feature is not available, the bit is 0
1448*/
1449CIVETWEB_API unsigned mg_check_feature(unsigned feature);
1450
1451
1452/* Get information on the system. Useful for support requests.
1453 Parameters:
1454 buffer: Store system information as string here.
1455 buflen: Length of buffer (including a byte required for a terminating 0).
1456 Return:
1457 Available size of system information, exluding a terminating 0.
1458 The information is complete, if the return value is smaller than buflen.
1459 The result is a JSON formatted string, the exact content may vary.
1460 Note:
1461 It is possible to determine the required buflen, by first calling this
1462 function with buffer = NULL and buflen = NULL. The required buflen is
1463 one byte more than the returned value.
1464*/
1465CIVETWEB_API int mg_get_system_info(char *buffer, int buflen);
1466
1467
1468/* Get context information. Useful for server diagnosis.
1469 Parameters:
1470 ctx: Context handle
1471 buffer: Store context information here.
1472 buflen: Length of buffer (including a byte required for a terminating 0).
1473 Return:
1474 Available size of system information, exluding a terminating 0.
1475 The information is complete, if the return value is smaller than buflen.
1476 The result is a JSON formatted string, the exact content may vary.
1477 Note:
1478 It is possible to determine the required buflen, by first calling this
1479 function with buffer = NULL and buflen = NULL. The required buflen is
1480 one byte more than the returned value. However, since the available
1481 context information changes, you should allocate a few bytes more.
1482*/
1483CIVETWEB_API int
1484mg_get_context_info(const struct mg_context *ctx, char *buffer, int buflen);
1485
1486
1487#ifdef MG_EXPERIMENTAL_INTERFACES
1488/* Get connection information. Useful for server diagnosis.
1489 Parameters:
1490 ctx: Context handle
1491 idx: Connection index
1492 buffer: Store context information here.
1493 buflen: Length of buffer (including a byte required for a terminating 0).
1494 Return:
1495 Available size of system information, exluding a terminating 0.
1496 The information is complete, if the return value is smaller than buflen.
1497 The result is a JSON formatted string, the exact content may vary.
1498 Note:
1499 It is possible to determine the required buflen, by first calling this
1500 function with buffer = NULL and buflen = NULL. The required buflen is
1501 one byte more than the returned value. However, since the available
1502 context information changes, you should allocate a few bytes more.
1503*/
1504CIVETWEB_API int mg_get_connection_info(const struct mg_context *ctx,
1505 int idx,
1506 char *buffer,
1507 int buflen);
1508#endif
1509
1510
1511#ifdef __cplusplus
1512}
1513#endif /* __cplusplus */
1514
1515#endif /* CIVETWEB_HEADER_INCLUDED */
#define f(i)
Definition: RSha256.hxx:104
#define s1(x)
Definition: RSha256.hxx:91
char name[80]
Definition: TGX11.cxx:109
typedef void((*Func_t)())
const char * mime_type
Definition: civetweb.c:7795
CIVETWEB_API void mg_lock_context(struct mg_context *ctx)
Definition: civetweb.c:12030
CIVETWEB_API const char * mg_version(void)
Definition: civetweb.c:3738
CIVETWEB_API void mg_set_websocket_handler_with_subprotocols(struct mg_context *ctx, const char *uri, struct mg_websocket_subprotocols *subprotocols, mg_websocket_connect_handler connect_handler, mg_websocket_ready_handler ready_handler, mg_websocket_data_handler data_handler, mg_websocket_close_handler close_handler, void *cbdata)
Definition: civetweb.c:13406
CIVETWEB_API const char * mg_get_response_code_text(const struct mg_connection *conn, int response_code)
Definition: civetweb.c:4312
#define MG_MAX_HEADERS
Definition: civetweb.h:136
@ MG_TIMEOUT_INFINITE
Definition: civetweb.h:1403
CIVETWEB_API const char * mg_get_builtin_mime_type(const char *file_name)
Definition: civetweb.c:7895
CIVETWEB_API int mg_get_cookie(const char *cookie, const char *var_name, char *buf, size_t buf_len)
Definition: civetweb.c:7093
CIVETWEB_API int mg_websocket_write(struct mg_connection *conn, int opcode, const char *data, size_t data_len)
void *(* mg_thread_func_t)(void *)
Definition: civetweb.h:1273
CIVETWEB_API void mg_lock_connection(struct mg_connection *conn)
Definition: civetweb.c:12014
CIVETWEB_API int mg_modify_passwords_file(const char *passwords_file_name, const char *realm, const char *user, const char *password)
Definition: civetweb.c:8580
CIVETWEB_API void * mg_get_user_data(const struct mg_context *ctx)
Definition: civetweb.c:3443
@ TIMEOUT_INFINITE
Definition: civetweb.h:1402
CIVETWEB_API long long mg_store_body(struct mg_connection *conn, const char *path)
Definition: civetweb.c:9953
CIVETWEB_API void mg_send_mime_file(struct mg_connection *conn, const char *path, const char *mime_type)
Definition: civetweb.c:9848
@ MG_FORM_FIELD_STORAGE_GET
Definition: civetweb.h:1241
@ MG_FORM_FIELD_STORAGE_ABORT
Definition: civetweb.h:1245
@ MG_FORM_FIELD_STORAGE_STORE
Definition: civetweb.h:1243
@ MG_FORM_FIELD_STORAGE_SKIP
Definition: civetweb.h:1239
CIVETWEB_API int mg_strncasecmp(const char *s1, const char *s2, size_t len)
Definition: civetweb.c:3267
CIVETWEB_API void mg_unlock_connection(struct mg_connection *conn)
Definition: civetweb.c:12022
CIVETWEB_API void mg_cry(const struct mg_connection *conn, PRINTF_FORMAT_STRING(const char *fmt),...) PRINTF_ARGS(2
#define PRINTF_FORMAT_STRING(s)
Definition: civetweb.h:855
CIVETWEB_API void mg_set_websocket_handler(struct mg_context *ctx, const char *uri, mg_websocket_connect_handler connect_handler, mg_websocket_ready_handler ready_handler, mg_websocket_data_handler data_handler, mg_websocket_close_handler close_handler, void *cbdata)
Definition: civetweb.c:13386
CIVETWEB_API int mg_url_decode(const char *src, int src_len, char *dst, int dst_len, int is_form_url_encoded)
Definition: civetweb.c:6993
int(* mg_authorization_handler)(struct mg_connection *conn, void *cbdata)
Definition: civetweb.h:569
CIVETWEB_API void mg_unlock_context(struct mg_context *ctx)
Definition: civetweb.c:12038
CIVETWEB_API int mg_send_file_body(struct mg_connection *conn, const char *path)
Definition: civetweb.c:9776
CIVETWEB_API int mg_write(struct mg_connection *, const void *buf, size_t len)
Definition: civetweb.c:6755
@ MG_FEATURES_ALL
Definition: civetweb.h:103
@ MG_FEATURES_STATS
Definition: civetweb.h:95
@ MG_FEATURES_CACHE
Definition: civetweb.h:91
@ MG_FEATURES_FILES
Definition: civetweb.h:61
@ MG_FEATURES_CGI
Definition: civetweb.h:71
@ MG_FEATURES_IPV6
Definition: civetweb.h:75
@ MG_FEATURES_DEFAULT
Definition: civetweb.h:57
@ MG_FEATURES_TLS
Definition: civetweb.h:66
@ MG_FEATURES_SSL
Definition: civetweb.h:67
@ MG_FEATURES_LUA
Definition: civetweb.h:83
@ MG_FEATURES_WEBSOCKET
Definition: civetweb.h:79
@ MG_FEATURES_SSJS
Definition: civetweb.h:87
@ MG_FEATURES_COMPRESSION
Definition: civetweb.h:99
CIVETWEB_API int mg_websocket_client_write(struct mg_connection *conn, int opcode, const char *data, size_t data_len)
CIVETWEB_API void mg_set_user_connection_data(struct mg_connection *conn, void *data)
Definition: civetweb.c:3450
CIVETWEB_API const char * mg_get_header(const struct mg_connection *, const char *name)
Definition: civetweb.c:4016
void(* mg_websocket_ready_handler)(struct mg_connection *, void *)
Definition: civetweb.h:512
CIVETWEB_API int mg_start_thread(mg_thread_func_t f, void *p)
Definition: civetweb.c:5841
CIVETWEB_API struct mg_connection * mg_connect_websocket_client(const char *host, int port, int use_ssl, char *error_buffer, size_t error_buffer_size, const char *path, const char *origin, mg_websocket_data_handler data_func, mg_websocket_close_handler close_func, void *user_data)
Definition: civetweb.c:17224
#define CIVETWEB_API
Definition: civetweb.h:43
CIVETWEB_API int mg_send_digest_access_authentication_request(struct mg_connection *conn, const char *realm)
Definition: civetweb.c:8546
CIVETWEB_API struct mg_connection * mg_download(const char *host, int port, int use_ssl, char *error_buffer, size_t error_buffer_size, PRINTF_FORMAT_STRING(const char *request_fmt),...) PRINTF_ARGS(6
CIVETWEB_API int mg_handle_form_request(struct mg_connection *conn, struct mg_form_data_handler *fdh)
CIVETWEB_API void mg_stop(struct mg_context *)
Definition: civetweb.c:18256
CIVETWEB_API int mg_send_http_error(struct mg_connection *conn, int status_code, PRINTF_FORMAT_STRING(const char *fmt),...) PRINTF_ARGS(3
CIVETWEB_API const struct mg_request_info * mg_get_request_info(const struct mg_connection *)
Definition: civetweb.c:3745
CIVETWEB_API int mg_get_response(struct mg_connection *conn, char *ebuf, size_t ebuf_len, int timeout)
Definition: civetweb.c:17052
CIVETWEB_API unsigned mg_exit_library(void)
Definition: civetweb.c:19821
CIVETWEB_API struct mg_context * mg_get_context(const struct mg_connection *conn)
Definition: civetweb.c:3436
CIVETWEB_API int mg_get_context_info(const struct mg_context *ctx, char *buffer, int buflen)
Definition: civetweb.c:19704
CIVETWEB_API int mg_get_var2(const char *data, size_t data_len, const char *var_name, char *dst, size_t dst_len, size_t occurrence)
Definition: civetweb.c:7035
CIVETWEB_API int CIVETWEB_API int mg_send_http_ok(struct mg_connection *conn, const char *mime_type, long long content_length)
Definition: civetweb.c:4701
CIVETWEB_API int mg_get_request_link(const struct mg_connection *conn, char *buf, size_t buflen)
Definition: civetweb.c:3822
CIVETWEB_API int mg_printf(struct mg_connection *, PRINTF_FORMAT_STRING(const char *fmt),...) PRINTF_ARGS(2
CIVETWEB_API const struct mg_response_info * mg_get_response_info(const struct mg_connection *)
Definition: civetweb.c:3782
CIVETWEB_API const struct mg_option * mg_get_valid_options(void)
Definition: civetweb.c:3029
CIVETWEB_API void mg_set_auth_handler(struct mg_context *ctx, const char *uri, mg_authorization_handler handler, void *cbdata)
Definition: civetweb.c:13436
CIVETWEB_API int mg_check_digest_access_authentication(struct mg_connection *conn, const char *realm, const char *filename)
Definition: civetweb.c:8431
CIVETWEB_API void * mg_get_user_connection_data(const struct mg_connection *conn)
Definition: civetweb.c:3459
CIVETWEB_API char * mg_md5(char buf[33],...)
Definition: civetweb.c:7967
CIVETWEB_API const char * mg_get_option(const struct mg_context *ctx, const char *name)
Definition: civetweb.c:3421
CIVETWEB_API struct mg_connection * mg_connect_client_secure(const struct mg_client_options *client_options, char *error_buffer, size_t error_buffer_size)
Definition: civetweb.c:16574
CIVETWEB_API struct mg_connection CIVETWEB_API void mg_close_connection(struct mg_connection *conn)
Definition: civetweb.c:16304
#define PRINTF_ARGS(x, y)
Definition: civetweb.h:861
CIVETWEB_API void CIVETWEB_API int mg_strcasecmp(const char *s1, const char *s2)
Definition: civetweb.c:3282
int(* mg_websocket_data_handler)(struct mg_connection *, int, char *, size_t, void *)
Definition: civetweb.h:513
int(* mg_request_handler)(struct mg_connection *conn, void *cbdata)
Definition: civetweb.h:456
CIVETWEB_API unsigned mg_init_library(unsigned features)
Definition: civetweb.c:19745
CIVETWEB_API void mg_send_mime_file2(struct mg_connection *conn, const char *path, const char *mime_type, const char *additional_headers)
Definition: civetweb.c:9857
CIVETWEB_API int mg_send_http_redirect(struct mg_connection *conn, const char *target_url, int redirect_code)
Definition: civetweb.c:4739
CIVETWEB_API int mg_get_var(const char *data, size_t data_len, const char *var_name, char *dst, size_t dst_len)
Definition: civetweb.c:7024
CIVETWEB_API struct mg_connection * mg_connect_client(const char *host, int port, int use_ssl, char *error_buffer, size_t error_buffer_size)
Definition: civetweb.c:16586
@ MG_WEBSOCKET_OPCODE_CONNECTION_CLOSE
Definition: civetweb.h:840
@ MG_WEBSOCKET_OPCODE_BINARY
Definition: civetweb.h:839
@ MG_WEBSOCKET_OPCODE_PONG
Definition: civetweb.h:842
@ MG_WEBSOCKET_OPCODE_TEXT
Definition: civetweb.h:838
@ MG_WEBSOCKET_OPCODE_CONTINUATION
Definition: civetweb.h:837
@ MG_WEBSOCKET_OPCODE_PING
Definition: civetweb.h:841
CIVETWEB_API unsigned mg_check_feature(unsigned feature)
Definition: civetweb.c:18802
void(* mg_websocket_close_handler)(const struct mg_connection *, void *)
Definition: civetweb.h:518
int(* mg_websocket_connect_handler)(const struct mg_connection *, void *)
Definition: civetweb.h:510
CIVETWEB_API struct mg_context * mg_start(const struct mg_callbacks *callbacks, void *user_data, const char **configuration_options)
Definition: civetweb.c:18342
CIVETWEB_API void mg_set_request_handler(struct mg_context *ctx, const char *uri, mg_request_handler handler, void *cbdata)
Definition: civetweb.c:13364
CIVETWEB_API int CIVETWEB_API int mg_send_chunk(struct mg_connection *conn, const char *chunk, unsigned int chunk_len)
Definition: civetweb.c:6819
@ MG_FORM_FIELD_HANDLE_NEXT
Definition: civetweb.h:1254
@ MG_FORM_FIELD_HANDLE_GET
Definition: civetweb.h:1252
@ MG_FORM_FIELD_HANDLE_ABORT
Definition: civetweb.h:1256
CIVETWEB_API void mg_send_file(struct mg_connection *conn, const char *path)
Definition: civetweb.c:9841
@ MG_CONFIG_TYPE_UNKNOWN
Definition: civetweb.h:666
@ MG_CONFIG_TYPE_FILE
Definition: civetweb.h:669
@ MG_CONFIG_TYPE_STRING
Definition: civetweb.h:668
@ MG_CONFIG_TYPE_DIRECTORY
Definition: civetweb.h:670
@ MG_CONFIG_TYPE_EXT_PATTERN
Definition: civetweb.h:672
@ MG_CONFIG_TYPE_STRING_MULTILINE
Definition: civetweb.h:674
@ MG_CONFIG_TYPE_STRING_LIST
Definition: civetweb.h:673
@ MG_CONFIG_TYPE_YES_NO_OPTIONAL
Definition: civetweb.h:675
@ MG_CONFIG_TYPE_NUMBER
Definition: civetweb.h:667
@ MG_CONFIG_TYPE_BOOLEAN
Definition: civetweb.h:671
CIVETWEB_API int mg_get_system_info(char *buffer, int buflen)
Definition: civetweb.c:19689
CIVETWEB_API int mg_get_server_ports(const struct mg_context *ctx, int size, struct mg_server_ports *ports)
Definition: civetweb.c:3493
CIVETWEB_API int mg_read(struct mg_connection *, void *buf, size_t len)
Definition: civetweb.c:6655
CIVETWEB_API int mg_url_encode(const char *src, char *dst, size_t dst_len)
Definition: civetweb.c:8967
int(* init_ssl)(void *ssl_context, void *user_data)
Definition: civetweb.h:255
int(* log_message)(const struct mg_connection *, const char *message)
Definition: civetweb.h:242
void(* end_request)(const struct mg_connection *, int reply_status_code)
Definition: civetweb.h:238
int(* init_connection)(const struct mg_connection *conn, void **conn_data)
Definition: civetweb.h:379
void(* connection_close)(const struct mg_connection *)
Definition: civetweb.h:314
int(* http_error)(struct mg_connection *conn, int status, const char *errmsg)
Definition: civetweb.h:341
void(* exit_context)(const struct mg_context *ctx)
Definition: civetweb.h:364
void(* init_thread)(const struct mg_context *ctx, int thread_type)
Definition: civetweb.h:359
int(* external_ssl_ctx)(void **ssl_ctx, void *user_data)
Definition: civetweb.h:269
int(* begin_request)(struct mg_connection *)
Definition: civetweb.h:235
int(* log_access)(const struct mg_connection *, const char *message)
Definition: civetweb.h:246
void(* init_context)(const struct mg_context *ctx)
Definition: civetweb.h:349
void(* init_lua)(const struct mg_connection *conn, void *lua_context)
Definition: civetweb.h:321
const char * issuer
Definition: civetweb.h:201
const char * finger
Definition: civetweb.h:203
void * peer_cert
Definition: civetweb.h:199
const char * subject
Definition: civetweb.h:200
const char * serial
Definition: civetweb.h:202
const char * host_name
Definition: civetweb.h:1391
const char * client_cert
Definition: civetweb.h:1389
const char * server_cert
Definition: civetweb.h:1390
const char * host
Definition: civetweb.h:1387
int(* field_get)(const char *key, const char *value, size_t valuelen, void *user_data)
Definition: civetweb.h:1191
int(* field_found)(const char *key, const char *filename, char *path, size_t pathlen, void *user_data)
Definition: civetweb.h:1173
int(* field_store)(const char *path, long long file_size, void *user_data)
Definition: civetweb.h:1213
const char * value
Definition: civetweb.h:140
const char * name
Definition: civetweb.h:139
int type
Definition: civetweb.h:645
const char * default_value
Definition: civetweb.h:646
const char * name
Definition: civetweb.h:644
struct mg_header http_headers[MG_MAX_HEADERS]
Definition: civetweb.h:170
const char * local_uri
Definition: civetweb.h:149
void * user_data
Definition: civetweb.h:166
const char * request_method
Definition: civetweb.h:146
struct mg_client_cert * client_cert
Definition: civetweb.h:173
const char * query_string
Definition: civetweb.h:156
long long content_length
Definition: civetweb.h:162
void * conn_data
Definition: civetweb.h:167
char remote_addr[48]
Definition: civetweb.h:160
const char * http_version
Definition: civetweb.h:155
const char * request_uri
Definition: civetweb.h:147
const char * acceptedWebSocketSubprotocol
Definition: civetweb.h:175
const char * remote_user
Definition: civetweb.h:158
long long content_length
Definition: civetweb.h:187
const char * http_version
Definition: civetweb.h:185
const char * status_text
Definition: civetweb.h:184
struct mg_header http_headers[MG_MAX_HEADERS]
Definition: civetweb.h:191