1
/* Copyright (c) 2013-2017 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.11"
27
#define CIVETWEB_VERSION_MAJOR (1)
28
#define CIVETWEB_VERSION_MINOR (11)
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
51
extern "C" {
52
#endif /* __cplusplus */
53

54

55
/* Init Features */
56
enum {
57
	MG_FEATURES_DEFAULT = 0x0u,
58

59
	/* Support files from local directories */
60
	/* Will only work, if NO_FILES is not set. */
61
	MG_FEATURES_FILES = 0x1u,
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. */
66
	MG_FEATURES_TLS = 0x2u,
67
	MG_FEATURES_SSL = 0x2u,
68

69
	/* Support common gateway interface (CGI). */
70
	/* Will only work, if NO_CGI is not set. */
71
	MG_FEATURES_CGI = 0x4u,
72

73
	/* Support IPv6. */
74
	/* Will only work, if USE_IPV6 is set. */
75
	MG_FEATURES_IPV6 = 0x8u,
76

77
	/* Support WebSocket protocol. */
78
	/* Will only work, if USE_WEBSOCKET is set. */
79
	MG_FEATURES_WEBSOCKET = 0x10u,
80

81
	/* Support server side Lua scripting. */
82
	/* Will only work, if USE_LUA is set. */
83
	MG_FEATURES_LUA = 0x20u,
84

85
	/* Support server side JavaScript scripting. */
86
	/* Will only work, if USE_DUKTAPE is set. */
87
	MG_FEATURES_SSJS = 0x40u,
88

89
	/* Provide data required for caching files. */
90
	/* Will only work, if NO_CACHING is not set. */
91
	MG_FEATURES_CACHE = 0x80u,
92

93
	/* Collect server status information. */
94
	/* Will only work, if USE_SERVER_STATS is set. */
95
	MG_FEATURES_STATS = 0x100u,
96

97
	/* Support on-the-fly compression. */
98
	/* Will only work, if USE_ZLIB is set. */
99
	MG_FEATURES_COMPRESSION = 0x200u,
100

101
	/* Collect server status information. */
102
	/* Will only work, if USE_SERVER_STATS is set. */
103
	MG_FEATURES_ALL = 0xFFFFu
104
};
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
 */
121
CIVETWEB_API unsigned mg_init_library(unsigned features);
122

123

124
/* Un-initialize this library.
125
 * Return value:
126
 *   0: error
127
 */
128
CIVETWEB_API unsigned mg_exit_library(void);
129

130

131
struct mg_context;    /* Handle for the HTTP service itself */
132
struct mg_connection; /* Handle for the individual connection */
133

134

135
/* Maximum number of headers */
136
#define MG_MAX_HEADERS (64)
137

138
struct 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. */
145
struct mg_request_info {
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. */
182
struct mg_response_info {
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. */
198
struct mg_client_cert {
199
	void *peer_cert;
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. */
208
struct 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 */
220
struct mg_callbacks {
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. */
408
CIVETWEB_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. */
418
CIVETWEB_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
 */
439
CIVETWEB_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. */
456
typedef 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. */
479
CIVETWEB_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.*/
510
typedef int (*mg_websocket_connect_handler)(const struct mg_connection *,
511
                                            void *);
512
typedef void (*mg_websocket_ready_handler)(struct mg_connection *, void *);
513
typedef int (*mg_websocket_data_handler)(struct mg_connection *,
514
                                         int,
515
                                         char *,
516
                                         size_t,
517
                                         void *);
518
typedef void (*mg_websocket_close_handler)(const struct mg_connection *,
519
                                           void *);
520

521
/* struct mg_websocket_subprotocols
522
 *
523
 * List of accepted subprotocols
524
 */
525
struct mg_websocket_subprotocols {
526
	int nb_subprotocols;
527
	char **subprotocols;
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. */
534
CIVETWEB_API void
535
mg_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. */
547
CIVETWEB_API void mg_set_websocket_handler_with_subprotocols(
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
 */
569
typedef 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. */
577
CIVETWEB_API void mg_set_auth_handler(struct mg_context *ctx,
578
                                      const char *uri,
579
                                      mg_authorization_handler handler,
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. */
589
CIVETWEB_API const char *mg_get_option(const struct mg_context *ctx,
590
                                       const char *name);
591

592

593
/* Get context from connection. */
594
CIVETWEB_API struct mg_context *
595
mg_get_context(const struct mg_connection *conn);
596

597

598
/* Get user data passed to mg_start from context. */
599
CIVETWEB_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. */
611
CIVETWEB_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. */
616
CIVETWEB_API void *
617
mg_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 */
629
CIVETWEB_API int
630
mg_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. */
639
CIVETWEB_API const char **mg_get_valid_option_names(void);
640
#endif
641

642

643
struct 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 */
651
enum {
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 */
665
enum {
666
	MG_CONFIG_TYPE_UNKNOWN = 0x0,
667
	MG_CONFIG_TYPE_NUMBER = 0x1,
668
	MG_CONFIG_TYPE_STRING = 0x2,
669
	MG_CONFIG_TYPE_FILE = 0x3,
670
	MG_CONFIG_TYPE_DIRECTORY = 0x4,
671
	MG_CONFIG_TYPE_BOOLEAN = 0x5,
672
	MG_CONFIG_TYPE_EXT_PATTERN = 0x6,
673
	MG_CONFIG_TYPE_STRING_LIST = 0x7,
674
	MG_CONFIG_TYPE_STRING_MULTILINE = 0x8,
675
	MG_CONFIG_TYPE_YES_NO_OPTIONAL = 0x9
676
};
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. */
681
CIVETWEB_API const struct mg_option *mg_get_valid_options(void);
682

683

684
struct mg_server_ports {
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 */
689
	int _reserved1;
690
	int _reserved2;
691
	int _reserved3;
692
	int _reserved4;
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. */
701
CIVETWEB_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. */
708
CIVETWEB_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
 */
733
CIVETWEB_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
 */
747
CIVETWEB_API const struct mg_request_info *
748
mg_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. */
754
CIVETWEB_API const struct mg_response_info *
755
mg_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 */
763
CIVETWEB_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 */
778
CIVETWEB_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 */
796
CIVETWEB_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. */
807
CIVETWEB_API void mg_lock_connection(struct mg_connection *conn);
808
CIVETWEB_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. */
819
CIVETWEB_API void mg_lock_context(struct mg_context *ctx);
820
CIVETWEB_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 */
825
enum {
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 */
836
enum {
837
	MG_WEBSOCKET_OPCODE_CONTINUATION = 0x0,
838
	MG_WEBSOCKET_OPCODE_TEXT = 0x1,
839
	MG_WEBSOCKET_OPCODE_BINARY = 0x2,
840
	MG_WEBSOCKET_OPCODE_CONNECTION_CLOSE = 0x8,
841
	MG_WEBSOCKET_OPCODE_PING = 0x9,
842
	MG_WEBSOCKET_OPCODE_PONG = 0xa
843
};
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. */
867
CIVETWEB_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. */
875
CIVETWEB_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
 */
886
CIVETWEB_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
 */
899
CIVETWEB_API int mg_send_file_body(struct mg_connection *conn,
900
                                   const char *path);
901

902

903
/* Send HTTP error reply. */
904
CIVETWEB_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
 */
921
CIVETWEB_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
 */
936
CIVETWEB_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
 */
951
CIVETWEB_API int
952
mg_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
 */
974
CIVETWEB_API int
975
mg_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
 */
987
CIVETWEB_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
*/
1003
CIVETWEB_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. */
1010
CIVETWEB_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. */
1024
CIVETWEB_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. */
1032
CIVETWEB_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. */
1055
CIVETWEB_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. */
1085
CIVETWEB_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). */
1106
CIVETWEB_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
 */
1127
CIVETWEB_API struct mg_connection *
1128
mg_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(). */
1138
CIVETWEB_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. */
1146
CIVETWEB_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. */
1153
struct mg_form_data_handler {
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. */
1216
	void *user_data;
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 */
1223
enum {
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 */
1236
enum {
1237
	/* Skip this field (neither get nor store it). Continue with the
1238
	 * next field. */
1239
	MG_FORM_FIELD_STORAGE_SKIP = 0x0,
1240
	/* Get the field value. */
1241
	MG_FORM_FIELD_STORAGE_GET = 0x1,
1242
	/* Store the field value into a file. */
1243
	MG_FORM_FIELD_STORAGE_STORE = 0x2,
1244
	/* Stop parsing this request. Skip the remaining fields. */
1245
	MG_FORM_FIELD_STORAGE_ABORT = 0x10
1246
};
1247

1248
/* Return values for "field_get" and "field_store" */
1249
enum {
1250
	/* Only "field_get": If there is more data in this field, get the next
1251
	 * chunk. Otherwise: handle the next field. */
1252
	MG_FORM_FIELD_HANDLE_GET = 0x1,
1253
	/* Handle the next field */
1254
	MG_FORM_FIELD_HANDLE_NEXT = 0x8,
1255
	/* Stop parsing this request */
1256
	MG_FORM_FIELD_HANDLE_ABORT = 0x10
1257
};
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. */
1267
CIVETWEB_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. */
1273
typedef void *(*mg_thread_func_t)(void *);
1274
CIVETWEB_API int mg_start_thread(mg_thread_func_t f, void *p);
1275

1276

1277
/* Return builtin mime type for the given file name.
1278
   For unrecognized extensions, "text/plain" is returned. */
1279
CIVETWEB_API const char *mg_get_builtin_mime_type(const char *file_name);
1280

1281

1282
/* Get text representation of HTTP status code. */
1283
CIVETWEB_API const char *
1284
mg_get_response_code_text(const struct mg_connection *conn, int response_code);
1285

1286

1287
/* Return CivetWeb version. */
1288
CIVETWEB_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. */
1297
CIVETWEB_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. */
1307
CIVETWEB_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); */
1316
CIVETWEB_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"); */
1326
CIVETWEB_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. */
1332
CIVETWEB_API int mg_strcasecmp(const char *s1, const char *s2);
1333
CIVETWEB_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
*/
1354
CIVETWEB_API struct mg_connection *
1355
mg_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
*/
1379
CIVETWEB_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

1386
struct mg_client_options {
1387
	const char *host;
1388
	int port;
1389
	const char *client_cert;
1390
	const char *server_cert;
1391
	/* TODO: add more data */
1392
};
1393

1394

1395
CIVETWEB_API struct mg_connection *
1396
mg_connect_client_secure(const struct mg_client_options *client_options,
1397
                         char *error_buffer,
1398
                         size_t error_buffer_size);
1399

1400

1401
enum { TIMEOUT_INFINITE = -1 };
1402
enum { MG_TIMEOUT_INFINITE = -1 };
1403

1404
/* Wait for a response from the server
1405
   Parameters:
1406
     conn: connection
1407
     ebuf, ebuf_len: error message placeholder.
1408
     timeout: time to wait for a response in milliseconds (if < 0 then wait
1409
   forever)
1410

1411
   Return:
1412
     On success, >= 0
1413
     On error/timeout, < 0
1414
*/
1415
CIVETWEB_API int mg_get_response(struct mg_connection *conn,
1416
                                 char *ebuf,
1417
                                 size_t ebuf_len,
1418
                                 int timeout);
1419

1420

1421
/* Check which features where set when the civetweb library has been compiled.
1422
   The function explicitly addresses compile time defines used when building
1423
   the library - it does not mean, the feature has been initialized using a
1424
   mg_init_library call.
1425
   mg_check_feature can be called anytime, even before mg_init_library has
1426
   been called.
1427

1428
   Parameters:
1429
     feature: specifies which feature should be checked
1430
       The value is a bit mask. The individual bits are defined as:
1431
         1  serve files (NO_FILES not set)
1432
         2  support HTTPS (NO_SSL not set)
1433
         4  support CGI (NO_CGI not set)
1434
         8  support IPv6 (USE_IPV6 set)
1435
        16  support WebSocket (USE_WEBSOCKET set)
1436
        32  support Lua scripts and Lua server pages (USE_LUA is set)
1437
        64  support server side JavaScript (USE_DUKTAPE is set)
1438
       128  support caching (NO_CACHING not set)
1439
       256  support server statistics (USE_SERVER_STATS is set)
1440
       The result is undefined, if bits are set that do not represent a
1441
       defined feature (currently: feature >= 512).
1442
       The result is undefined, if no bit is set (feature == 0).
1443

1444
   Return:
1445
     If feature is available, the corresponding bit is set
1446
     If feature is not available, the bit is 0
1447
*/
1448
CIVETWEB_API unsigned mg_check_feature(unsigned feature);
1449

1450

1451
/* Get information on the system. Useful for support requests.
1452
   Parameters:
1453
     buffer: Store system information as string here.
1454
     buflen: Length of buffer (including a byte required for a terminating 0).
1455
   Return:
1456
     Available size of system information, exluding a terminating 0.
1457
     The information is complete, if the return value is smaller than buflen.
1458
     The result is a JSON formatted string, the exact content may vary.
1459
   Note:
1460
     It is possible to determine the required buflen, by first calling this
1461
     function with buffer = NULL and buflen = NULL. The required buflen is
1462
     one byte more than the returned value.
1463
*/
1464
CIVETWEB_API int mg_get_system_info(char *buffer, int buflen);
1465

1466

1467
/* Get context information. Useful for server diagnosis.
1468
   Parameters:
1469
     ctx: Context handle
1470
     buffer: Store context information here.
1471
     buflen: Length of buffer (including a byte required for a terminating 0).
1472
   Return:
1473
     Available size of system information, exluding a terminating 0.
1474
     The information is complete, if the return value is smaller than buflen.
1475
     The result is a JSON formatted string, the exact content may vary.
1476
     Note:
1477
     It is possible to determine the required buflen, by first calling this
1478
     function with buffer = NULL and buflen = NULL. The required buflen is
1479
     one byte more than the returned value. However, since the available
1480
     context information changes, you should allocate a few bytes more.
1481
*/
1482
CIVETWEB_API int
1483
mg_get_context_info(const struct mg_context *ctx, char *buffer, int buflen);
1484

1485

1486
#ifdef MG_EXPERIMENTAL_INTERFACES
1487
/* Get connection information. Useful for server diagnosis.
1488
   Parameters:
1489
     ctx: Context handle
1490
     idx: Connection index
1491
     buffer: Store context information here.
1492
     buflen: Length of buffer (including a byte required for a terminating 0).
1493
   Return:
1494
     Available size of system information, exluding a terminating 0.
1495
     The information is complete, if the return value is smaller than buflen.
1496
     The result is a JSON formatted string, the exact content may vary.
1497
   Note:
1498
     It is possible to determine the required buflen, by first calling this
1499
     function with buffer = NULL and buflen = NULL. The required buflen is
1500
     one byte more than the returned value. However, since the available
1501
     context information changes, you should allocate a few bytes more.
1502
*/
1503
CIVETWEB_API int mg_get_connection_info(const struct mg_context *ctx,
1504
                                        int idx,
1505
                                        char *buffer,
1506
                                        int buflen);
1507
#endif
1508

1509

1510
#ifdef __cplusplus
1511
}
1512
#endif /* __cplusplus */
1513

1514
#endif /* CIVETWEB_HEADER_INCLUDED */
1515

1516