1 /* Copyright (c) 2013-2021 the Civetweb developers
2 * Copyright (c) 2004-2013 Sergey Lyubka
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:
11 * The above copyright notice and this permission notice shall be included in
12 * all copies or substantial portions of the Software.
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
23 #ifndef CIVETWEB_HEADER_INCLUDED
24 #define CIVETWEB_HEADER_INCLUDED
26 #define CIVETWEB_VERSION "1.15"
27 #define CIVETWEB_VERSION_MAJOR (1)
28 #define CIVETWEB_VERSION_MINOR (15)
29 #define CIVETWEB_VERSION_PATCH (0)
33 #if defined(CIVETWEB_DLL_EXPORTS)
34 #define CIVETWEB_API __declspec(dllexport)
35 #elif defined(CIVETWEB_DLL_IMPORTS)
36 #define CIVETWEB_API __declspec(dllimport)
41 #define CIVETWEB_API __attribute__((visibility("default")))
52 #endif /* __cplusplus */
57 MG_FEATURES_DEFAULT
= 0x0u
,
59 /* Support files from local directories */
60 /* Will only work, if NO_FILES is not set. */
61 MG_FEATURES_FILES
= 0x1u
,
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. */
66 MG_FEATURES_TLS
= 0x2u
,
67 MG_FEATURES_SSL
= 0x2u
,
69 /* Support common gateway interface (CGI). */
70 /* Will only work, if NO_CGI is not set. */
71 MG_FEATURES_CGI
= 0x4u
,
74 /* Will only work, if USE_IPV6 is set. */
75 MG_FEATURES_IPV6
= 0x8u
,
77 /* Support WebSocket protocol. */
78 /* Will only work, if USE_WEBSOCKET is set. */
79 MG_FEATURES_WEBSOCKET
= 0x10u
,
81 /* Support server side Lua scripting. */
82 /* Will only work, if USE_LUA is set. */
83 MG_FEATURES_LUA
= 0x20u
,
85 /* Support server side JavaScript scripting. */
86 /* Will only work, if USE_DUKTAPE is set. */
87 MG_FEATURES_SSJS
= 0x40u
,
89 /* Provide data required for caching files. */
90 /* Will only work, if NO_CACHING is not set. */
91 MG_FEATURES_CACHE
= 0x80u
,
93 /* Collect server status information. */
94 /* Will only work, if USE_SERVER_STATS is set. */
95 MG_FEATURES_STATS
= 0x100u
,
97 /* Support on-the-fly compression. */
98 /* Will only work, if USE_ZLIB is set. */
99 MG_FEATURES_COMPRESSION
= 0x200u
,
101 /* HTTP/2 support enabled. */
102 MG_FEATURES_HTTP2
= 0x400u
,
104 /* Support unix domain sockets. */
105 MG_FEATURES_X_DOMAIN_SOCKET
= 0x800u
,
107 /* Bit mask for all feature defines. */
108 MG_FEATURES_ALL
= 0xFFFFu
112 /* Initialize this library. This should be called once before any other
113 * function from this library. This function is not guaranteed to be
116 * features: bit mask for features to be initialized.
117 * Note: The TLS libraries (like OpenSSL) is initialized
118 * only if the MG_FEATURES_TLS bit is set.
119 * Currently the other bits do not influence
120 * initialization, but this may change in future
123 * initialized features
126 CIVETWEB_API
unsigned mg_init_library(unsigned features
);
129 /* Un-initialize this library.
133 CIVETWEB_API
unsigned mg_exit_library(void);
136 struct mg_context
; /* Handle for the HTTP service itself */
137 struct mg_connection
; /* Handle for the individual connection */
140 /* Maximum number of headers */
141 #define MG_MAX_HEADERS (64)
144 const char *name
; /* HTTP header name */
145 const char *value
; /* HTTP header value */
149 /* This structure contains information about the HTTP request. */
150 struct mg_request_info
{
151 const char *request_method
; /* "GET", "POST", etc */
152 const char *request_uri
; /* URL-decoded URI (absolute or relative,
153 * as in the request) */
154 const char *local_uri_raw
; /* URL-decoded URI (relative). Can be NULL
155 * if the request_uri does not address a
156 * resource at the server host. */
157 const char *local_uri
; /* Same as local_uri_raw, however, cleaned
159 * allowed_dir/../forbidden_file
160 * is not possible. */
161 const char *http_version
; /* E.g. "1.0", "1.1" */
162 const char *query_string
; /* URL part after '?', not including '?', or
164 const char *remote_user
; /* Authenticated user, or NULL if no auth
166 char remote_addr
[48]; /* Client's IP address as a string. */
168 long long content_length
; /* Length (in bytes) of the request body,
169 can be -1 if no length was given. */
170 int remote_port
; /* Port at client side */
171 int server_port
; /* Port at server side (one of the listening
173 int is_ssl
; /* 1 if HTTPS or WS is used (SSL/TLS used),
175 void *user_data
; /* User data pointer passed to mg_start() */
176 void *conn_data
; /* Connection-specific user data */
178 int num_headers
; /* Number of HTTP headers */
180 http_headers
[MG_MAX_HEADERS
]; /* Allocate maximum headers */
182 struct mg_client_cert
*client_cert
; /* Client certificate information */
184 const char *acceptedWebSocketSubprotocol
; /* websocket subprotocol,
185 * accepted during handshake */
189 /* This structure contains information about the HTTP request. */
190 /* This structure may be extended in future versions. */
191 struct mg_response_info
{
192 int status_code
; /* E.g. 200 */
193 const char *status_text
; /* E.g. "OK" */
194 const char *http_version
; /* E.g. "1.0", "1.1" */
196 long long content_length
; /* Length (in bytes) of the request body,
197 can be -1 if no length was given. */
199 int num_headers
; /* Number of HTTP headers */
201 http_headers
[MG_MAX_HEADERS
]; /* Allocate maximum headers */
205 /* Client certificate information (part of mg_request_info) */
206 struct mg_client_cert
{
215 /* This structure needs to be passed to mg_start(), to let civetweb know
216 which callbacks to invoke. For a detailed description, see
217 https://github.com/civetweb/civetweb/blob/master/docs/UserManual.md */
218 struct mg_callbacks
{
219 /* Called when civetweb has received new HTTP request.
220 If the callback returns one, it must process the request
221 by sending valid HTTP headers and a body. Civetweb will not do
222 any further processing. Otherwise it must return zero.
223 Note that since V1.7 the "begin_request" function is called
224 before an authorization check. If an authorization check is
225 required, use a request_handler instead.
227 0: civetweb will process the request itself. In this case,
228 the callback must not send any data to the client.
229 1-999: callback already processed the request. Civetweb will
230 not send any data after the callback returned. The
231 return code is stored as a HTTP status code for the
233 int (*begin_request
)(struct mg_connection
*);
235 /* Called when civetweb has finished processing request. */
236 void (*end_request
)(const struct mg_connection
*, int reply_status_code
);
238 /* Called when civetweb is about to log a message. If callback returns
239 non-zero, civetweb does not log anything. */
240 int (*log_message
)(const struct mg_connection
*, const char *message
);
242 /* Called when civetweb is about to log access. If callback returns
243 non-zero, civetweb does not log anything. */
244 int (*log_access
)(const struct mg_connection
*, const char *message
);
246 /* Called when civetweb initializes SSL library.
248 ssl_ctx: SSL_CTX pointer.
249 user_data: parameter user_data passed when starting the server.
251 0: civetweb will set up the SSL certificate.
252 1: civetweb assumes the callback already set up the certificate.
253 -1: initializing ssl fails. */
254 int (*init_ssl
)(void *ssl_ctx
, void *user_data
);
256 /* Called when civetweb initializes SSL library for a domain.
258 server_domain: authentication_domain from the domain config.
259 ssl_ctx: SSL_CTX pointer.
260 user_data: parameter user_data passed when starting the server.
262 0: civetweb will set up the SSL certificate.
263 1: civetweb assumes the callback already set up the certificate.
264 -1: initializing ssl fails. */
265 int (*init_ssl_domain
)(const char *server_domain
,
269 /* Called when civetweb is about to create or free a SSL_CTX.
271 ssl_ctx: SSL_CTX pointer. NULL at creation time, Not NULL when
272 mg_context will be freed user_data: parameter user_data passed when starting
273 the server. Return value: 0: civetweb will continue to create the context,
274 just as if the callback would not be present. The value in *ssl_ctx when the
275 function returns is ignored. 1: civetweb will copy the value from *ssl_ctx
276 to the civetweb context and doesn't create its own. -1: initializing ssl
278 int (*external_ssl_ctx
)(void **ssl_ctx
, void *user_data
);
280 /* Called when civetweb is about to create or free a SSL_CTX for a domain.
282 server_domain: authentication_domain from the domain config.
283 ssl_ctx: SSL_CTX pointer. NULL at creation time, Not NULL when
284 mg_context will be freed user_data: parameter user_data passed when starting
285 the server. Return value: 0: civetweb will continue to create the context,
286 just as if the callback would not be present. The value in *ssl_ctx when the
287 function returns is ignored. 1: civetweb will copy the value from *ssl_ctx
288 to the civetweb context and doesn't create its own. -1: initializing ssl
290 int (*external_ssl_ctx_domain
)(const char *server_domain
,
294 #if defined(MG_EXPERIMENTAL_INTERFACES) /* 2019-11-03 */
295 /* Called when data frame has been received from the peer.
297 bits: first byte of the websocket frame, see websocket RFC at
298 http://tools.ietf.org/html/rfc6455, section 5.2
299 data, data_len: payload, with mask (if any) already applied.
301 1: keep this websocket connection open.
302 0: close this websocket connection.
303 This callback is deprecated: Use mg_set_websocket_handler instead. */
304 int (*websocket_data
)(struct mg_connection
*,
308 #endif /* MG_LEGACY_INTERFACE */
310 /* Called when civetweb is closing a connection. The per-context mutex is
311 locked when this is invoked.
314 Before mg_set_websocket_handler has been added, it was primarily useful
315 for noting when a websocket is closing, and used to remove it from any
316 application-maintained list of clients.
317 Using this callback for websocket connections is deprecated: Use
318 mg_set_websocket_handler instead.
320 void (*connection_close
)(const struct mg_connection
*);
322 /* Called after civetweb has closed a connection. The per-context mutex is
323 locked when this is invoked.
325 Connection specific data:
326 If memory has been allocated for the connection specific user data
327 (mg_request_info->conn_data, mg_get_user_connection_data),
328 this is the last chance to free it.
330 void (*connection_closed
)(const struct mg_connection
*);
333 /* init_lua is called when civetweb is about to serve Lua server page.
334 exit_lua is called when the Lua processing is complete.
335 Both will work only if Lua support is enabled.
337 conn: current connection.
338 lua_context: "lua_State *" pointer.
339 context_flags: context type information as bitmask:
340 context_flags & 0x0F: (0-15) Lua environment type
342 void (*init_lua
)(const struct mg_connection
*conn
,
344 unsigned context_flags
);
345 void (*exit_lua
)(const struct mg_connection
*conn
,
347 unsigned context_flags
);
350 /* Called when civetweb is about to send HTTP error to the client.
351 Implementing this callback allows to create custom error pages.
353 conn: current connection.
354 status: HTTP error status code.
355 errmsg: error message text.
357 1: run civetweb error handler.
358 0: callback already handled the error. */
359 int (*http_error
)(struct mg_connection
*conn
,
363 /* Called after civetweb context has been created, before requests
366 ctx: context handle */
367 void (*init_context
)(const struct mg_context
*ctx
);
369 /* Called when civetweb context is deleted.
371 ctx: context handle */
372 void (*exit_context
)(const struct mg_context
*ctx
);
374 /* Called when a new worker thread is initialized.
375 * It is always called from the newly created thread and can be used to
376 * initialize thread local storage data.
378 * ctx: context handle
380 * 0 indicates the master thread
381 * 1 indicates a worker thread handling client connections
382 * 2 indicates an internal helper thread (timer thread)
384 * This function returns a user supplied pointer. The pointer is assigned
385 * to the thread and can be obtained from the mg_connection object using
386 * mg_get_thread_pointer in all server callbacks. Note: A connection and
387 * a thread are not directly related. Threads will serve several different
388 * connections, and data from a single connection may call different
389 * callbacks using different threads. The thread pointer can be obtained
390 * in a callback handler, but should not be stored beyond the scope of
391 * one call to one callback.
393 void *(*init_thread
)(const struct mg_context
*ctx
, int thread_type
);
395 /* Called when a worker exits.
396 * The parameters "ctx" and "thread_type" correspond to the "init_thread"
397 * call. The "thread_pointer" parameter is the value returned by
400 void (*exit_thread
)(const struct mg_context
*ctx
,
402 void *thread_pointer
);
404 /* Called when initializing a new connection object.
405 * Can be used to initialize the connection specific user data
406 * (mg_request_info->conn_data, mg_get_user_connection_data).
407 * When the callback is called, it is not yet known if a
408 * valid HTTP(S) request will be made.
410 * conn: not yet fully initialized connection object
411 * conn_data: output parameter, set to initialize the
412 * connection specific user data
415 * Otherwise, the result is undefined
417 int (*init_connection
)(const struct mg_connection
*conn
, void **conn_data
);
424 callbacks: mg_callbacks structure with user-defined callbacks.
425 options: NULL terminated list of option_name, option_value pairs that
426 specify Civetweb configuration parameters.
428 Side-effects: on UNIX, ignores SIGCHLD and SIGPIPE signals. If custom
429 processing is required for these, signal handlers must be set up
430 after calling mg_start().
434 const char *options[] = {
435 "document_root", "/var/www",
436 "listening_ports", "80,443s",
439 struct mg_context *ctx = mg_start(&my_func, NULL, options);
441 Refer to https://github.com/civetweb/civetweb/blob/master/docs/UserManual.md
442 for the list of valid option and their possible values.
445 web server context, or NULL on error. */
446 CIVETWEB_API
struct mg_context
*mg_start(const struct mg_callbacks
*callbacks
,
448 const char **configuration_options
);
451 /* Stop the web server.
453 Must be called last, when an application wants to stop the web server and
454 release all associated resources. This function blocks until all Civetweb
455 threads are stopped. Context pointer becomes invalid. */
456 CIVETWEB_API
void mg_stop(struct mg_context
*);
459 /* Add an additional domain to an already running web server.
462 * ctx: Context handle of a server started by mg_start.
463 * options: NULL terminated list of option_name, option_value pairs that
464 * specify CivetWeb configuration parameters.
467 * < 0 in case of an error
468 * -1 for a parameter error
470 * -3 initializing SSL failed
471 * -4 mandatory domain option missing
472 * -5 duplicate domain
474 * > 0 index / handle of a new domain
476 CIVETWEB_API
int mg_start_domain(struct mg_context
*ctx
,
477 const char **configuration_options
);
480 /* mg_request_handler
482 Called when a new request comes in. This callback is URI based
483 and configured with mg_set_request_handler().
486 conn: current connection information.
487 cbdata: the callback data configured with mg_set_request_handler().
489 0: the handler could not handle the request, so fall through.
490 1 - 999: the handler processed the request. The return code is
491 stored as a HTTP status code for the access log. */
492 typedef int (*mg_request_handler
)(struct mg_connection
*conn
, void *cbdata
);
495 /* mg_set_request_handler
497 Sets or removes a URI mapping for a request handler.
498 This function waits until a removing/updating handler becomes unused, so
499 do not call from the handler itself.
501 URI's are ordered and prefixed URI's are supported. For example,
502 consider two URIs: /a/b and /a
509 uri: the URI (exact or pattern) for the handler
510 handler: the callback handler to use when the URI is requested.
511 If NULL, an already registered handler for this URI will
513 The URI used to remove a handler must match exactly the
514 one used to register it (not only a pattern match).
515 cbdata: the callback data to give to the handler when it is called. */
516 CIVETWEB_API
void mg_set_request_handler(struct mg_context
*ctx
,
518 mg_request_handler handler
,
522 /* Callback types for websocket handlers in C/C++.
524 mg_websocket_connect_handler
525 Is called when the client intends to establish a websocket connection,
526 before websocket handshake.
528 0: civetweb proceeds with websocket handshake.
529 1: connection is closed immediately.
531 mg_websocket_ready_handler
532 Is called when websocket handshake is successfully completed, and
533 connection is ready for data exchange.
535 mg_websocket_data_handler
536 Is called when a data frame has been received from the client.
538 bits: first byte of the websocket frame, see websocket RFC at
539 http://tools.ietf.org/html/rfc6455, section 5.2
540 data, data_len: payload, with mask (if any) already applied.
542 1: keep this websocket connection open.
543 0: close this websocket connection.
545 mg_connection_close_handler
546 Is called, when the connection is closed.*/
547 typedef int (*mg_websocket_connect_handler
)(const struct mg_connection
*,
549 typedef void (*mg_websocket_ready_handler
)(struct mg_connection
*, void *);
550 typedef int (*mg_websocket_data_handler
)(struct mg_connection
*,
555 typedef void (*mg_websocket_close_handler
)(const struct mg_connection
*,
558 /* struct mg_websocket_subprotocols
560 * List of accepted subprotocols
562 struct mg_websocket_subprotocols
{
564 const char **subprotocols
;
567 /* mg_set_websocket_handler
569 Set or remove handler functions for websocket connections.
570 This function works similar to mg_set_request_handler - see there. */
572 mg_set_websocket_handler(struct mg_context
*ctx
,
574 mg_websocket_connect_handler connect_handler
,
575 mg_websocket_ready_handler ready_handler
,
576 mg_websocket_data_handler data_handler
,
577 mg_websocket_close_handler close_handler
,
580 /* mg_set_websocket_handler
582 Set or remove handler functions for websocket connections.
583 This function works similar to mg_set_request_handler - see there. */
584 CIVETWEB_API
void mg_set_websocket_handler_with_subprotocols(
585 struct mg_context
*ctx
,
587 struct mg_websocket_subprotocols
*subprotocols
,
588 mg_websocket_connect_handler connect_handler
,
589 mg_websocket_ready_handler ready_handler
,
590 mg_websocket_data_handler data_handler
,
591 mg_websocket_close_handler close_handler
,
595 /* mg_authorization_handler
597 Callback function definition for mg_set_auth_handler
600 conn: current connection information.
601 cbdata: the callback data configured with mg_set_request_handler().
606 typedef int (*mg_authorization_handler
)(struct mg_connection
*conn
,
610 /* mg_set_auth_handler
612 Sets or removes a URI mapping for an authorization handler.
613 This function works similar to mg_set_request_handler - see there. */
614 CIVETWEB_API
void mg_set_auth_handler(struct mg_context
*ctx
,
616 mg_authorization_handler handler
,
620 /* Get the value of particular configuration parameter.
621 The value returned is read-only. Civetweb does not allow changing
622 configuration at run time.
623 If given parameter name is not valid, NULL is returned. For valid
624 names, return value is guaranteed to be non-NULL. If parameter is not
625 set, zero-length string is returned. */
626 CIVETWEB_API
const char *mg_get_option(const struct mg_context
*ctx
,
630 /* Get context from connection. */
631 CIVETWEB_API
struct mg_context
*
632 mg_get_context(const struct mg_connection
*conn
);
635 /* Get user data passed to mg_start from context. */
636 CIVETWEB_API
void *mg_get_user_data(const struct mg_context
*ctx
);
639 /* Get user data passed to mg_start from connection. */
640 CIVETWEB_API
void *mg_get_user_context_data(const struct mg_connection
*conn
);
643 /* Get user defined thread pointer for server threads (see init_thread). */
644 CIVETWEB_API
void *mg_get_thread_pointer(const struct mg_connection
*conn
);
647 /* Set user data for the current connection. */
648 /* Note: CivetWeb callbacks use "struct mg_connection *conn" as input
649 when mg_read/mg_write callbacks are allowed in the callback,
650 while "const struct mg_connection *conn" is used as input in case
651 calling mg_read/mg_write is not allowed.
652 Setting the user connection data will modify the connection
653 object represented by mg_connection *, but it will not read from
654 or write to the connection. */
655 /* Note: An alternative is to use the init_connection callback
656 instead to initialize the user connection data pointer. It is
657 reccomended to supply a pointer to some user defined data structure
658 as conn_data initializer in init_connection. In case it is required
659 to change some data after the init_connection call, store another
660 data pointer in the user defined data structure and modify that
661 pointer. In either case, after the init_connection callback, only
662 calls to mg_get_user_connection_data should be required. */
663 CIVETWEB_API
void mg_set_user_connection_data(const struct mg_connection
*conn
,
667 /* Get user data set for the current connection. */
669 mg_get_user_connection_data(const struct mg_connection
*conn
);
672 /* Get a formatted link corresponding to the current request
675 conn: current connection information.
676 buf: string buffer (out)
677 buflen: length of the string buffer
682 mg_get_request_link(const struct mg_connection
*conn
, char *buf
, size_t buflen
);
688 const char *default_value
;
692 /* Configuration types */
694 MG_CONFIG_TYPE_UNKNOWN
= 0x0,
695 MG_CONFIG_TYPE_NUMBER
= 0x1,
696 MG_CONFIG_TYPE_STRING
= 0x2,
697 MG_CONFIG_TYPE_FILE
= 0x3,
698 MG_CONFIG_TYPE_DIRECTORY
= 0x4,
699 MG_CONFIG_TYPE_BOOLEAN
= 0x5,
700 MG_CONFIG_TYPE_EXT_PATTERN
= 0x6,
701 MG_CONFIG_TYPE_STRING_LIST
= 0x7,
702 MG_CONFIG_TYPE_STRING_MULTILINE
= 0x8,
703 MG_CONFIG_TYPE_YES_NO_OPTIONAL
= 0x9
706 /* Return array of struct mg_option, representing all valid configuration
707 options of civetweb.c.
708 The array is terminated by a NULL name option. */
709 CIVETWEB_API
const struct mg_option
*mg_get_valid_options(void);
712 struct mg_server_port
{
713 int protocol
; /* 1 = IPv4, 2 = IPv6, 3 = both */
714 int port
; /* port number */
715 int is_ssl
; /* https port: 0 = no, 1 = yes */
716 int is_redirect
; /* redirect all requests: 0 = no, 1 = yes */
724 #define mg_server_ports mg_server_port
727 /* Get the list of ports that civetweb is listening on.
728 The parameter size is the size of the ports array in elements.
729 The caller is responsibility to allocate the required memory.
730 This function returns the number of struct mg_server_port elements
731 filled in, or <0 in case of an error. */
732 CIVETWEB_API
int mg_get_server_ports(const struct mg_context
*ctx
,
734 struct mg_server_port
*ports
);
737 /* Add, edit or delete the entry in the passwords file.
739 * This function allows an application to manipulate .htpasswd files on the
740 * fly by adding, deleting and changing user records. This is one of the
741 * several ways of implementing authentication on the server side. For another,
742 * cookie-based way please refer to the examples/chat in the source tree.
745 * passwords_file_name: Path and name of a file storing multiple passwords
746 * realm: HTTP authentication realm (authentication domain) name
749 * If password is not NULL, entry modified or added.
750 * If password is NULL, entry is deleted.
753 * 1 on success, 0 on error.
755 CIVETWEB_API
int mg_modify_passwords_file(const char *passwords_file_name
,
758 const char *password
);
761 /* Same as mg_modify_passwords_file, but instead of the plain-text
762 * password, the HA1 hash is specified. The plain-text password is
763 * not made known to civetweb.
765 * The HA1 hash is the MD5 checksum of a "user:realm:password" string
766 * in lower-case hex format. For example, if the user name is "myuser",
767 * the realm is "myrealm", and the password is "secret", then the HA1 is
768 * e67fd3248b58975c3e89ff18ecb75e2f.
770 CIVETWEB_API
int mg_modify_passwords_file_ha1(const char *passwords_file_name
,
776 /* Return information associated with the request.
777 * Use this function to implement a server and get data about a request
778 * from a HTTP/HTTPS client.
779 * Note: Before CivetWeb 1.10, this function could be used to read
780 * a response from a server, when implementing a client, although the
781 * values were never returned in appropriate mg_request_info elements.
782 * It is strongly advised to use mg_get_response_info for clients.
784 CIVETWEB_API
const struct mg_request_info
*
785 mg_get_request_info(const struct mg_connection
*);
788 /* Return information associated with a HTTP/HTTPS response.
789 * Use this function in a client, to check the response from
791 CIVETWEB_API
const struct mg_response_info
*
792 mg_get_response_info(const struct mg_connection
*);
795 /* Send data to the client.
797 0 when the connection has been closed
799 >0 number of bytes written on success */
800 CIVETWEB_API
int mg_write(struct mg_connection
*, const void *buf
, size_t len
);
803 /* Send data to a websocket client wrapped in a websocket frame. Uses
804 mg_lock_connection to ensure that the transmission is not interrupted,
805 i.e., when the application is proactively communicating and responding to
806 a request simultaneously.
808 Send data to a websocket client wrapped in a websocket frame.
809 This function is available when civetweb is compiled with -DUSE_WEBSOCKET
812 0 when the connection has been closed
814 >0 number of bytes written on success */
815 CIVETWEB_API
int mg_websocket_write(struct mg_connection
*conn
,
821 /* Send data to a websocket server wrapped in a masked websocket frame. Uses
822 mg_lock_connection to ensure that the transmission is not interrupted,
823 i.e., when the application is proactively communicating and responding to
824 a request simultaneously.
826 Send data to a websocket server wrapped in a masked websocket frame.
827 This function is available when civetweb is compiled with -DUSE_WEBSOCKET
830 0 when the connection has been closed
832 >0 number of bytes written on success */
833 CIVETWEB_API
int mg_websocket_client_write(struct mg_connection
*conn
,
839 /* Blocks until unique access is obtained to this connection. Intended for use
840 with websockets only.
841 Invoke this before mg_write or mg_printf when communicating with a
842 websocket if your code has server-initiated communication as well as
843 communication in direct response to a message.
844 Do not acquire this lock while holding mg_lock_context(). */
845 CIVETWEB_API
void mg_lock_connection(struct mg_connection
*conn
);
846 CIVETWEB_API
void mg_unlock_connection(struct mg_connection
*conn
);
849 /* Lock server context. This lock may be used to protect resources
850 that are shared between different connection/worker threads.
851 If the given context is not server, these functions do nothing. */
852 CIVETWEB_API
void mg_lock_context(struct mg_context
*ctx
);
853 CIVETWEB_API
void mg_unlock_context(struct mg_context
*ctx
);
856 /* WebSocket OpcCodes, from http://tools.ietf.org/html/rfc6455 */
858 MG_WEBSOCKET_OPCODE_CONTINUATION
= 0x0,
859 MG_WEBSOCKET_OPCODE_TEXT
= 0x1,
860 MG_WEBSOCKET_OPCODE_BINARY
= 0x2,
861 MG_WEBSOCKET_OPCODE_CONNECTION_CLOSE
= 0x8,
862 MG_WEBSOCKET_OPCODE_PING
= 0x9,
863 MG_WEBSOCKET_OPCODE_PONG
= 0xa
867 /* Macros for enabling compiler-specific checks for printf-like arguments. */
868 #undef PRINTF_FORMAT_STRING
869 #if defined(_MSC_VER) && _MSC_VER >= 1400
871 #if defined(_MSC_VER) && _MSC_VER > 1400
872 #define PRINTF_FORMAT_STRING(s) _Printf_format_string_ s
874 #define PRINTF_FORMAT_STRING(s) __format_string s
877 #define PRINTF_FORMAT_STRING(s) s
881 #define PRINTF_ARGS(x, y) __attribute__((format(printf, x, y)))
883 #define PRINTF_ARGS(x, y)
887 /* Send data to the client using printf() semantics.
888 Works exactly like mg_write(), but allows to do message formatting. */
889 CIVETWEB_API
int mg_printf(struct mg_connection
*,
890 PRINTF_FORMAT_STRING(const char *fmt
),
891 ...) PRINTF_ARGS(2, 3);
894 /* Send a part of the message body, if chunked transfer encoding is set.
895 * Only use this function after sending a complete HTTP request or response
896 * header with "Transfer-Encoding: chunked" set. */
897 CIVETWEB_API
int mg_send_chunk(struct mg_connection
*conn
,
899 unsigned int chunk_len
);
902 /* Send contents of the entire file together with HTTP headers.
904 * conn: Current connection information.
905 * path: Full path to the file to send.
906 * This function has been superseded by mg_send_mime_file
908 CIVETWEB_API
void mg_send_file(struct mg_connection
*conn
, const char *path
);
911 /* Send contents of the file without HTTP headers.
912 * The code must send a valid HTTP response header before using this function.
915 * conn: Current connection information.
916 * path: Full path to the file to send.
921 CIVETWEB_API
int mg_send_file_body(struct mg_connection
*conn
,
925 /* Send HTTP error reply. */
926 CIVETWEB_API
int mg_send_http_error(struct mg_connection
*conn
,
928 PRINTF_FORMAT_STRING(const char *fmt
),
929 ...) PRINTF_ARGS(3, 4);
932 /* Send "HTTP 200 OK" response header.
933 * After calling this function, use mg_write or mg_send_chunk to send the
936 * conn: Current connection handle.
937 * mime_type: Set Content-Type for the following content.
938 * content_length: Size of the following content, if content_length >= 0.
939 * Will set transfer-encoding to chunked, if set to -1.
943 CIVETWEB_API
int mg_send_http_ok(struct mg_connection
*conn
,
944 const char *mime_type
,
945 long long content_length
);
948 /* Send "HTTP 30x" redirect response.
949 * The response has content-size zero: do not send any body data after calling
952 * conn: Current connection handle.
953 * target_url: New location.
954 * redirect_code: HTTP redirect type. Could be 301, 302, 303, 307, 308.
956 * < 0 Error (-1 send error, -2 parameter error)
958 CIVETWEB_API
int mg_send_http_redirect(struct mg_connection
*conn
,
959 const char *target_url
,
963 /* Send HTTP digest access authentication request.
964 * Browsers will send a user name and password in their next request, showing
965 * an authentication dialog if the password is not stored.
967 * conn: Current connection handle.
968 * realm: Authentication realm. If NULL is supplied, the sever domain
969 * set in the authentication_domain configuration is used.
974 mg_send_digest_access_authentication_request(struct mg_connection
*conn
,
978 /* Check if the current request has a valid authentication token set.
979 * A file is used to provide a list of valid user names, realms and
980 * password hashes. The file can be created and modified using the
981 * mg_modify_passwords_file API function.
983 * conn: Current connection handle.
984 * realm: Authentication realm. If NULL is supplied, the sever domain
985 * set in the authentication_domain configuration is used.
986 * filename: Path and name of a file storing multiple password hashes.
988 * > 0 Valid authentication
989 * 0 Invalid authentication
990 * < 0 Error (all values < 0 should be considered as invalid
991 * authentication, future error codes will have negative
997 mg_check_digest_access_authentication(struct mg_connection
*conn
,
999 const char *filename
);
1002 /* Send contents of the entire file together with HTTP headers.
1004 * conn: Current connection handle.
1005 * path: Full path to the file to send.
1006 * mime_type: Content-Type for file. NULL will cause the type to be
1007 * looked up by the file extension.
1009 CIVETWEB_API
void mg_send_mime_file(struct mg_connection
*conn
,
1011 const char *mime_type
);
1014 /* Send contents of the entire file together with HTTP headers.
1016 conn: Current connection information.
1017 path: Full path to the file to send.
1018 mime_type: Content-Type for file. NULL will cause the type to be
1019 looked up by the file extension.
1020 additional_headers: Additional custom header fields appended to the header.
1021 Each header should start with an X-, to ensure it is
1023 NULL does not append anything.
1025 CIVETWEB_API
void mg_send_mime_file2(struct mg_connection
*conn
,
1027 const char *mime_type
,
1028 const char *additional_headers
);
1031 /* Store body data into a file. */
1032 CIVETWEB_API
long long mg_store_body(struct mg_connection
*conn
,
1034 /* Read entire request body and store it in a file "path".
1037 >= 0 Number of bytes stored in file "path".
1041 /* Read data from the remote end, return number of bytes read.
1043 0 connection has been closed by peer. No more data could be read.
1044 < 0 read error. No more data could be read from the connection.
1045 > 0 number of bytes read into the buffer. */
1046 CIVETWEB_API
int mg_read(struct mg_connection
*, void *buf
, size_t len
);
1049 /* Get the value of particular HTTP header.
1051 This is a helper function. It traverses request_info->http_headers array,
1052 and if the header is present in the array, returns its value. If it is
1053 not present, NULL is returned. */
1054 CIVETWEB_API
const char *mg_get_header(const struct mg_connection
*,
1058 /* Get a value of particular form variable.
1061 data: pointer to form-uri-encoded buffer. This could be either POST data,
1062 or request_info.query_string.
1063 data_len: length of the encoded data.
1064 var_name: variable name to decode from the buffer
1065 dst: destination buffer for the decoded variable
1066 dst_len: length of the destination buffer
1069 On success, length of the decoded variable.
1071 -1 (variable not found).
1072 -2 (destination buffer is NULL, zero length or too small to hold the
1075 Destination buffer is guaranteed to be '\0' - terminated if it is not
1076 NULL or zero length. */
1077 CIVETWEB_API
int mg_get_var(const char *data
,
1079 const char *var_name
,
1084 /* Get a value of particular form variable.
1087 data: pointer to form-uri-encoded buffer. This could be either POST data,
1088 or request_info.query_string.
1089 data_len: length of the encoded data.
1090 var_name: variable name to decode from the buffer
1091 dst: destination buffer for the decoded variable
1092 dst_len: length of the destination buffer
1093 occurrence: which occurrence of the variable, 0 is the 1st, 1 the 2nd, ...
1094 this makes it possible to parse a query like
1095 b=x&a=y&a=z which will have occurrence values b:0, a:0 and a:1
1098 On success, length of the decoded variable.
1100 -1 (variable not found).
1101 -2 (destination buffer is NULL, zero length or too small to hold the
1104 Destination buffer is guaranteed to be '\0' - terminated if it is not
1105 NULL or zero length. */
1106 CIVETWEB_API
int mg_get_var2(const char *data
,
1108 const char *var_name
,
1114 /* Split form encoded data into a list of key value pairs.
1115 A form encoded input might be a query string, the body of a
1116 x-www-form-urlencoded POST request or any other data with this
1117 structure: "keyName1=value1&keyName2=value2&keyName3=value3".
1118 Values might be percent-encoded - this function will transform
1119 them to the unencoded characters.
1120 The input string is modified by this function: To split the
1121 "query_string" member of struct request_info, create a copy first
1122 (e.g., using strdup).
1123 The function itself does not allocate memory. Thus, it is not
1124 required to free any pointer returned from this function.
1125 The output list of is limited to MG_MAX_FORM_FIELDS name-value-
1126 pairs. The default value is reasonably oversized for typical
1127 applications, however, for special purpose systems it might be
1128 required to increase this value at compile time.
1131 data: form encoded iput string. Will be modified by this function.
1132 form_fields: output list of name/value-pairs. A buffer with a size
1133 specified by num_form_fields must be provided by the
1135 num_form_fields: Size of provided form_fields buffer in number of
1136 "struct mg_header" elements.
1139 On success: number of form_fields filled
1141 -1 (parameter error). */
1142 CIVETWEB_API
int mg_split_form_urlencoded(char *data
,
1143 struct mg_header
*form_fields
,
1144 unsigned num_form_fields
);
1147 /* Fetch value of certain cookie variable into the destination buffer.
1149 Destination buffer is guaranteed to be '\0' - terminated. In case of
1150 failure, dst[0] == '\0'. Note that RFC allows many occurrences of the same
1151 parameter. This function returns only first occurrence.
1154 On success, value length.
1156 -1 (either "Cookie:" header is not present at all or the requested
1157 parameter is not found).
1158 -2 (destination buffer is NULL, zero length or too small to hold the
1160 CIVETWEB_API
int mg_get_cookie(const char *cookie
,
1161 const char *var_name
,
1166 /* Download data from the remote web server.
1167 host: host name to connect to, e.g. "foo.com", or "10.12.40.1".
1168 port: port number, e.g. 80.
1169 use_ssl: whether to use SSL connection.
1170 error_buffer, error_buffer_size: error message placeholder.
1171 request_fmt,...: HTTP request.
1173 On success, valid pointer to the new connection, suitable for mg_read().
1174 On error, NULL. error_buffer contains error message.
1177 struct mg_connection *conn;
1178 conn = mg_download("google.com", 80, 0, ebuf, sizeof(ebuf),
1179 "%s", "GET / HTTP/1.0\r\nHost: google.com\r\n\r\n");
1181 mg_download is equivalent to calling mg_connect_client followed by
1182 mg_printf and mg_get_response. Using these three functions directly may
1183 allow more control as compared to using mg_download.
1185 CIVETWEB_API
struct mg_connection
*
1186 mg_download(const char *host
,
1190 size_t error_buffer_size
,
1191 PRINTF_FORMAT_STRING(const char *request_fmt
),
1192 ...) PRINTF_ARGS(6, 7);
1195 /* Close the connection opened by mg_download(). */
1196 CIVETWEB_API
void mg_close_connection(struct mg_connection
*conn
);
1199 /* This structure contains callback functions for handling form fields.
1200 It is used as an argument to mg_handle_form_request. */
1201 struct mg_form_data_handler
{
1202 /* This callback function is called, if a new field has been found.
1203 * The return value of this callback is used to define how the field
1204 * should be processed.
1207 * key: Name of the field ("name" property of the HTML input field).
1208 * filename: Name of a file to upload, at the client computer.
1209 * Only set for input fields of type "file", otherwise NULL.
1210 * path: Output parameter: File name (incl. path) to store the file
1211 * at the server computer. Only used if FORM_FIELD_STORAGE_STORE
1212 * is returned by this callback. Existing files will be
1214 * pathlen: Length of the buffer for path.
1215 * user_data: Value of the member user_data of mg_form_data_handler
1218 * The callback must return the intended storage for this field
1219 * (See FORM_FIELD_STORAGE_*).
1221 int (*field_found
)(const char *key
,
1222 const char *filename
,
1227 /* If the "field_found" callback returned FORM_FIELD_STORAGE_GET,
1228 * this callback will receive the field data.
1231 * key: Name of the field ("name" property of the HTML input field).
1232 * value: Value of the input field.
1233 * user_data: Value of the member user_data of mg_form_data_handler
1236 * The return code determines how the server should continue processing
1237 * the current request (See MG_FORM_FIELD_HANDLE_*).
1239 int (*field_get
)(const char *key
,
1244 /* If the "field_found" callback returned FORM_FIELD_STORAGE_STORE,
1245 * the data will be stored into a file. If the file has been written
1246 * successfully, this callback will be called. This callback will
1247 * not be called for only partially uploaded files. The
1248 * mg_handle_form_request function will either store the file completely
1249 * and call this callback, or it will remove any partial content and
1250 * not call this callback function.
1253 * path: Path of the file stored at the server.
1254 * file_size: Size of the stored file in bytes.
1255 * user_data: Value of the member user_data of mg_form_data_handler
1258 * The return code determines how the server should continue processing
1259 * the current request (See MG_FORM_FIELD_HANDLE_*).
1261 int (*field_store
)(const char *path
, long long file_size
, void *user_data
);
1263 /* User supplied argument, passed to all callback functions. */
1268 /* Return values definition for the "field_found" callback in
1269 * mg_form_data_handler. */
1271 /* Skip this field (neither get nor store it). Continue with the
1273 MG_FORM_FIELD_STORAGE_SKIP
= 0x0,
1274 /* Get the field value. */
1275 MG_FORM_FIELD_STORAGE_GET
= 0x1,
1276 /* Store the field value into a file. */
1277 MG_FORM_FIELD_STORAGE_STORE
= 0x2,
1278 /* Stop parsing this request. Skip the remaining fields. */
1279 MG_FORM_FIELD_STORAGE_ABORT
= 0x10
1282 /* Return values for "field_get" and "field_store" */
1284 /* Only "field_get": If there is more data in this field, get the next
1285 * chunk. Otherwise: handle the next field. */
1286 MG_FORM_FIELD_HANDLE_GET
= 0x1,
1287 /* Handle the next field */
1288 MG_FORM_FIELD_HANDLE_NEXT
= 0x8,
1289 /* Stop parsing this request */
1290 MG_FORM_FIELD_HANDLE_ABORT
= 0x10
1294 /* Process form data.
1295 * Returns the number of fields handled, or < 0 in case of an error.
1296 * Note: It is possible that several fields are already handled successfully
1297 * (e.g., stored into files), before the request handling is stopped with an
1298 * error. In this case a number < 0 is returned as well.
1299 * In any case, it is the duty of the caller to remove files once they are
1300 * no longer required. */
1301 CIVETWEB_API
int mg_handle_form_request(struct mg_connection
*conn
,
1302 struct mg_form_data_handler
*fdh
);
1305 /* Convenience function -- create detached thread.
1306 Return: 0 on success, non-0 on error. */
1307 typedef void *(*mg_thread_func_t
)(void *);
1308 CIVETWEB_API
int mg_start_thread(mg_thread_func_t f
, void *p
);
1311 /* Return builtin mime type for the given file name.
1312 For unrecognized extensions, "text/plain" is returned. */
1313 CIVETWEB_API
const char *mg_get_builtin_mime_type(const char *file_name
);
1316 /* Get text representation of HTTP status code. */
1317 CIVETWEB_API
const char *
1318 mg_get_response_code_text(const struct mg_connection
*conn
, int response_code
);
1321 /* Return CivetWeb version. */
1322 CIVETWEB_API
const char *mg_version(void);
1325 /* URL-decode input buffer into destination buffer.
1326 0-terminate the destination buffer.
1327 form-url-encoded data differs from URI encoding in a way that it
1328 uses '+' as character for space, see RFC 1866 section 8.2.1
1329 http://ftp.ics.uci.edu/pub/ietf/html/rfc1866.txt
1330 Return: length of the decoded data, or -1 if dst buffer is too small. */
1331 CIVETWEB_API
int mg_url_decode(const char *src
,
1335 int is_form_url_encoded
);
1338 /* URL-encode input buffer into destination buffer.
1339 returns the length of the resulting buffer or -1
1340 is the buffer is too small. */
1341 CIVETWEB_API
int mg_url_encode(const char *src
, char *dst
, size_t dst_len
);
1344 /* MD5 hash given strings.
1345 Buffer 'buf' must be 33 bytes long. Varargs is a NULL terminated list of
1346 ASCIIz strings. When function returns, buf will contain human-readable
1349 mg_md5(buf, "aa", "bb", NULL); */
1350 CIVETWEB_API
char *mg_md5(char buf
[33], ...);
1353 /* Print error message to the opened error log stream.
1354 This utilizes the provided logging configuration.
1355 conn: connection (not used for sending data, but to get perameters)
1356 fmt: format string without the line return
1357 ...: variable argument list
1359 mg_cry(conn,"i like %s", "logging"); */
1360 CIVETWEB_API
void mg_cry(const struct mg_connection
*conn
,
1361 PRINTF_FORMAT_STRING(const char *fmt
),
1362 ...) PRINTF_ARGS(2, 3);
1365 /* utility methods to compare two buffers, case insensitive. */
1366 CIVETWEB_API
int mg_strcasecmp(const char *s1
, const char *s2
);
1367 CIVETWEB_API
int mg_strncasecmp(const char *s1
, const char *s2
, size_t len
);
1370 /* Connect to a websocket as a client
1372 host: host to connect to, i.e. "echo.websocket.org" or "192.168.1.1" or
1375 use_ssl: make a secure connection to server
1376 error_buffer, error_buffer_size: buffer for an error message
1377 path: server path you are trying to connect to, i.e. if connection to
1378 localhost/app, path should be "/app"
1379 origin: value of the Origin HTTP header
1380 data_func: callback that should be used when data is received from the
1382 user_data: user supplied argument
1385 On success, valid mg_connection object.
1386 On error, NULL. Se error_buffer for details.
1388 CIVETWEB_API
struct mg_connection
*
1389 mg_connect_websocket_client(const char *host
,
1393 size_t error_buffer_size
,
1396 mg_websocket_data_handler data_func
,
1397 mg_websocket_close_handler close_func
,
1400 CIVETWEB_API
struct mg_connection
*
1401 mg_connect_websocket_client_extensions(const char *host
,
1405 size_t error_buffer_size
,
1408 const char *extensions
,
1409 mg_websocket_data_handler data_func
,
1410 mg_websocket_close_handler close_func
,
1414 /* Connect to a TCP server as a client (can be used to connect to a HTTP server)
1416 host: host to connect to, i.e. "www.wikipedia.org" or "192.168.1.1" or
1419 use_ssl: make a secure connection to server
1420 error_buffer, error_buffer_size: buffer for an error message
1423 On success, valid mg_connection object.
1424 On error, NULL. Se error_buffer for details.
1426 CIVETWEB_API
struct mg_connection
*mg_connect_client(const char *host
,
1430 size_t error_buffer_size
);
1433 struct mg_client_options
{
1436 const char *client_cert
;
1437 const char *server_cert
;
1438 const char *host_name
;
1439 /* TODO: add more data */
1443 CIVETWEB_API
struct mg_connection
*
1444 mg_connect_client_secure(const struct mg_client_options
*client_options
,
1446 size_t error_buffer_size
);
1449 CIVETWEB_API
struct mg_connection
*mg_connect_websocket_client_secure(
1450 const struct mg_client_options
*client_options
,
1452 size_t error_buffer_size
,
1455 mg_websocket_data_handler data_func
,
1456 mg_websocket_close_handler close_func
,
1459 CIVETWEB_API
struct mg_connection
*
1460 mg_connect_websocket_client_secure_extensions(
1461 const struct mg_client_options
*client_options
,
1463 size_t error_buffer_size
,
1466 const char *extensions
,
1467 mg_websocket_data_handler data_func
,
1468 mg_websocket_close_handler close_func
,
1471 #if defined(MG_LEGACY_INTERFACE) /* 2019-11-02 */
1472 enum { TIMEOUT_INFINITE
= -1 };
1474 enum { MG_TIMEOUT_INFINITE
= -1 };
1477 /* Wait for a response from the server
1480 ebuf, ebuf_len: error message placeholder.
1481 timeout: time to wait for a response in milliseconds (if < 0 then wait
1486 On error/timeout, < 0
1488 CIVETWEB_API
int mg_get_response(struct mg_connection
*conn
,
1494 /* mg_response_header_* functions can be used from server callbacks
1495 * to prepare HTTP server response headers. Using this function will
1496 * allow a callback to work with HTTP/1.x and HTTP/2.
1499 /* Initialize a new HTTP response
1501 * conn: Current connection handle.
1502 * status: HTTP status code (e.g., 200 for "OK").
1505 * -1: parameter error
1506 * -2: invalid connection type
1507 * -3: invalid connection status
1509 CIVETWEB_API
int mg_response_header_start(struct mg_connection
*conn
,
1513 /* Add a new HTTP response header line
1515 * conn: Current connection handle.
1516 * header: Header name.
1517 * value: Header value.
1518 * value_len: Length of header value, excluding the terminating zero.
1519 * Use -1 for "strlen(value)".
1522 * -1: parameter error
1523 * -2: invalid connection type
1524 * -3: invalid connection status
1525 * -4: too many headers
1528 CIVETWEB_API
int mg_response_header_add(struct mg_connection
*conn
,
1534 /* Add a complete header string (key + value).
1535 * This function is less efficient as compared to mg_response_header_add,
1536 * and should only be used to convert complete HTTP/1.x header lines.
1538 * conn: Current connection handle.
1539 * http1_headers: Header line(s) in the form "name: value\r\n".
1541 * >=0: no error, number of header lines added
1542 * -1: parameter error
1543 * -2: invalid connection type
1544 * -3: invalid connection status
1545 * -4: too many headers
1548 CIVETWEB_API
int mg_response_header_add_lines(struct mg_connection
*conn
,
1549 const char *http1_headers
);
1552 /* Send http response
1554 * conn: Current connection handle.
1557 * -1: parameter error
1558 * -2: invalid connection type
1559 * -3: invalid connection status
1561 CIVETWEB_API
int mg_response_header_send(struct mg_connection
*conn
);
1564 /* Check which features where set when the civetweb library has been compiled.
1565 The function explicitly addresses compile time defines used when building
1566 the library - it does not mean, the feature has been initialized using a
1567 mg_init_library call.
1568 mg_check_feature can be called anytime, even before mg_init_library has
1572 feature: specifies which feature should be checked
1573 The value is a bit mask. The individual bits are defined as:
1574 1 serve files (NO_FILES not set)
1575 2 support HTTPS (NO_SSL not set)
1576 4 support CGI (NO_CGI not set)
1577 8 support IPv6 (USE_IPV6 set)
1578 16 support WebSocket (USE_WEBSOCKET set)
1579 32 support Lua scripts and Lua server pages (USE_LUA is set)
1580 64 support server side JavaScript (USE_DUKTAPE is set)
1581 128 support caching (NO_CACHING not set)
1582 256 support server statistics (USE_SERVER_STATS is set)
1583 512 support for on the fly compression (USE_ZLIB is set)
1585 These values are defined as MG_FEATURES_*
1587 The result is undefined, if bits are set that do not represent a
1588 defined feature (currently: feature >= 1024).
1589 The result is undefined, if no bit is set (feature == 0).
1592 If a feature is available, the corresponding bit is set
1593 If a feature is not available, the bit is 0
1595 CIVETWEB_API
unsigned mg_check_feature(unsigned feature
);
1598 /* Get information on the system. Useful for support requests.
1600 buffer: Store system information as string here.
1601 buflen: Length of buffer (including a byte required for a terminating 0).
1603 Available size of system information, exluding a terminating 0.
1604 The information is complete, if the return value is smaller than buflen.
1605 The result is a JSON formatted string, the exact content may vary.
1607 It is possible to determine the required buflen, by first calling this
1608 function with buffer = NULL and buflen = NULL. The required buflen is
1609 one byte more than the returned value.
1611 CIVETWEB_API
int mg_get_system_info(char *buffer
, int buflen
);
1614 /* Get context information. Useful for server diagnosis.
1617 buffer: Store context information here.
1618 buflen: Length of buffer (including a byte required for a terminating 0).
1620 Available size of system information, exluding a terminating 0.
1621 The information is complete, if the return value is smaller than buflen.
1622 The result is a JSON formatted string, the exact content may vary.
1624 It is possible to determine the required buflen, by first calling this
1625 function with buffer = NULL and buflen = NULL. The required buflen is
1626 one byte more than the returned value. However, since the available
1627 context information changes, you should allocate a few bytes more.
1630 mg_get_context_info(const struct mg_context
*ctx
, char *buffer
, int buflen
);
1633 /* Disable HTTP keep-alive on a per-connection basis.
1634 Reference: https://github.com/civetweb/civetweb/issues/727
1636 conn: Current connection handle.
1638 CIVETWEB_API
void mg_disable_connection_keep_alive(struct mg_connection
*conn
);
1641 #if defined(MG_EXPERIMENTAL_INTERFACES)
1642 /* Get connection information. Useful for server diagnosis.
1645 idx: Connection index
1646 buffer: Store context information here.
1647 buflen: Length of buffer (including a byte required for a terminating 0).
1649 Available size of system information, exluding a terminating 0.
1650 The information is complete, if the return value is smaller than buflen.
1651 The result is a JSON formatted string, the exact content may vary.
1653 It is possible to determine the required buflen, by first calling this
1654 function with buffer = NULL and buflen = NULL. The required buflen is
1655 one byte more than the returned value. However, since the available
1656 context information changes, you should allocate a few bytes more.
1658 CIVETWEB_API
int mg_get_connection_info(const struct mg_context
*ctx
,
1665 /* New APIs for enhanced option and error handling.
1666 These mg_*2 API functions have the same purpose as their original versions,
1667 but provide additional options and/or provide improved error diagnostics.
1669 Note: Experimental interfaces may change
1671 struct mg_error_data
{
1672 unsigned *code
; /* error code (number) */
1673 char *text
; /* buffer for error text */
1674 size_t text_buffer_size
; /* size of buffer of "text" */
1677 struct mg_init_data
{
1678 const struct mg_callbacks
*callbacks
; /* callback function pointer */
1679 void *user_data
; /* data */
1680 const char **configuration_options
;
1684 #if defined(MG_EXPERIMENTAL_INTERFACES)
1686 CIVETWEB_API
struct mg_connection
*
1687 mg_connect_client2(const char *host
,
1688 const char *protocol
,
1691 struct mg_init_data
*init
,
1692 struct mg_error_data
*error
);
1694 CIVETWEB_API
int mg_get_response2(struct mg_connection
*conn
,
1695 struct mg_error_data
*error
,
1700 CIVETWEB_API
struct mg_context
*mg_start2(struct mg_init_data
*init
,
1701 struct mg_error_data
*error
);
1703 CIVETWEB_API
int mg_start_domain2(struct mg_context
*ctx
,
1704 const char **configuration_options
,
1705 struct mg_error_data
*error
);
1710 #endif /* __cplusplus */
1712 #endif /* CIVETWEB_HEADER_INCLUDED */