Logo ROOT   6.12/07
Reference Guide
civetweb.h
Go to the documentation of this file.
1 /* Copyright (c) 2013-2016 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.8"
27 
28 #ifndef CIVETWEB_API
29 #if defined(_WIN32)
30 #if defined(CIVETWEB_DLL_EXPORTS)
31 #define CIVETWEB_API __declspec(dllexport)
32 #elif defined(CIVETWEB_DLL_IMPORTS)
33 #define CIVETWEB_API __declspec(dllimport)
34 #else
35 #define CIVETWEB_API
36 #endif
37 #elif __GNUC__ >= 4
38 #define CIVETWEB_API __attribute__((visibility("default")))
39 #else
40 #define CIVETWEB_API
41 #endif
42 #endif
43 
44 #include <stdio.h>
45 #include <stddef.h>
46 
47 #ifdef __cplusplus
48 extern "C" {
49 #endif /* __cplusplus */
50 
51 
52 struct mg_context; /* Handle for the HTTP service itself */
53 struct mg_connection; /* Handle for the individual connection */
54 
55 
56 /* This structure contains information about the HTTP request. */
58  const char *request_method; /* "GET", "POST", etc */
59  const char *request_uri; /* URL-decoded URI (absolute or relative,
60  * as in the request) */
61  const char *local_uri; /* URL-decoded URI (relative). Can be NULL
62  * if the request_uri does not address a
63  * resource at the server host. */
64  const char *uri; /* Deprecated: use local_uri instead */
65  const char *http_version; /* E.g. "1.0", "1.1" */
66  const char *query_string; /* URL part after '?', not including '?', or
67  NULL */
68  const char *remote_user; /* Authenticated user, or NULL if no auth
69  used */
70  char remote_addr[48]; /* Client's IP address as a string. */
71 
72 #if defined(MG_LEGACY_INTERFACE)
73  long remote_ip; /* Client's IP address. Deprecated: use remote_addr instead
74  */
75 #endif
76 
77  long long content_length; /* Length (in bytes) of the request body,
78  can be -1 if no length was given. */
79  int remote_port; /* Client's port */
80  int is_ssl; /* 1 if SSL-ed, 0 if not */
81  void *user_data; /* User data pointer passed to mg_start() */
82  void *conn_data; /* Connection-specific user data */
83 
84  int num_headers; /* Number of HTTP headers */
85  struct mg_header {
86  const char *name; /* HTTP header name */
87  const char *value; /* HTTP header value */
88  } http_headers[64]; /* Maximum 64 headers */
89 };
90 
91 
92 /* This structure needs to be passed to mg_start(), to let civetweb know
93  which callbacks to invoke. For a detailed description, see
94  https://github.com/civetweb/civetweb/blob/master/docs/UserManual.md */
95 struct mg_callbacks {
96  /* Called when civetweb has received new HTTP request.
97  If the callback returns one, it must process the request
98  by sending valid HTTP headers and a body. Civetweb will not do
99  any further processing. Otherwise it must return zero.
100  Note that since V1.7 the "begin_request" function is called
101  before an authorization check. If an authorization check is
102  required, use a request_handler instead.
103  Return value:
104  0: civetweb will process the request itself. In this case,
105  the callback must not send any data to the client.
106  1-999: callback already processed the request. Civetweb will
107  not send any data after the callback returned. The
108  return code is stored as a HTTP status code for the
109  access log. */
110  int (*begin_request)(struct mg_connection *);
111 
112  /* Called when civetweb has finished processing request. */
113  void (*end_request)(const struct mg_connection *, int reply_status_code);
114 
115  /* Called when civetweb is about to log a message. If callback returns
116  non-zero, civetweb does not log anything. */
117  int (*log_message)(const struct mg_connection *, const char *message);
118 
119  /* Called when civetweb is about to log access. If callback returns
120  non-zero, civetweb does not log anything. */
121  int (*log_access)(const struct mg_connection *, const char *message);
122 
123  /* Called when civetweb initializes SSL library.
124  Parameters:
125  user_data: parameter user_data passed when starting the server.
126  Return value:
127  0: civetweb will set up the SSL certificate.
128  1: civetweb assumes the callback already set up the certificate.
129  -1: initializing ssl fails. */
130  int (*init_ssl)(void *ssl_context, void *user_data);
131 
132 #if defined(MG_LEGACY_INTERFACE)
133  /* Called when websocket request is received, before websocket handshake.
134  Return value:
135  0: civetweb proceeds with websocket handshake.
136  1: connection is closed immediately.
137  This callback is deprecated: Use mg_set_websocket_handler instead. */
138  int (*websocket_connect)(const struct mg_connection *);
139 
140  /* Called when websocket handshake is successfully completed, and
141  connection is ready for data exchange.
142  This callback is deprecated: Use mg_set_websocket_handler instead. */
143  void (*websocket_ready)(struct mg_connection *);
144 
145  /* Called when data frame has been received from the client.
146  Parameters:
147  bits: first byte of the websocket frame, see websocket RFC at
148  http://tools.ietf.org/html/rfc6455, section 5.2
149  data, data_len: payload, with mask (if any) already applied.
150  Return value:
151  1: keep this websocket connection open.
152  0: close this websocket connection.
153  This callback is deprecated: Use mg_set_websocket_handler instead. */
154  int (*websocket_data)(struct mg_connection *,
155  int bits,
156  char *data,
157  size_t data_len);
158 #endif /* MG_LEGACY_INTERFACE */
159 
160  /* Called when civetweb is closing a connection. The per-context mutex is
161  locked when this is invoked. This is primarily useful for noting when
162  a websocket is closing and removing it from any application-maintained
163  list of clients.
164  Using this callback for websocket connections is deprecated: Use
165  mg_set_websocket_handler instead. */
166  void (*connection_close)(const struct mg_connection *);
167 
168  /* Called when civetweb tries to open a file. Used to intercept file open
169  calls, and serve file data from memory instead.
170  Parameters:
171  path: Full path to the file to open.
172  data_len: Placeholder for the file size, if file is served from
173  memory.
174  Return value:
175  NULL: do not serve file from memory, proceed with normal file open.
176  non-NULL: pointer to the file contents in memory. data_len must be
177  initilized with the size of the memory block. */
178  const char *(*open_file)(const struct mg_connection *,
179  const char *path,
180  size_t *data_len);
181 
182  /* Called when civetweb is about to serve Lua server page, if
183  Lua support is enabled.
184  Parameters:
185  lua_context: "lua_State *" pointer. */
186  void (*init_lua)(const struct mg_connection *, void *lua_context);
187 
188 #if defined(MG_LEGACY_INTERFACE)
189  /* Called when civetweb has uploaded a file to a temporary directory as a
190  result of mg_upload() call.
191  Note that mg_upload is deprecated. Use mg_handle_form_request instead.
192  Parameters:
193  file_name: full path name to the uploaded file. */
194  void (*upload)(struct mg_connection *, const char *file_name);
195 #endif
196 
197  /* Called when civetweb is about to send HTTP error to the client.
198  Implementing this callback allows to create custom error pages.
199  Parameters:
200  status: HTTP error status code.
201  Return value:
202  1: run civetweb error handler.
203  0: callback already handled the error. */
204  int (*http_error)(struct mg_connection *, int status);
205 
206  /* Called after civetweb context has been created, before requests
207  are processed.
208  Parameters:
209  ctx: context handle */
210  void (*init_context)(const struct mg_context *ctx);
211 
212  /* Called when a new worker thread is initialized.
213  Parameters:
214  ctx: context handle
215  thread_type:
216  0 indicates the master thread
217  1 indicates a worker thread handling client connections
218  2 indicates an internal helper thread (timer thread)
219  */
220  void (*init_thread)(const struct mg_context *ctx, int thread_type);
221 
222  /* Called when civetweb context is deleted.
223  Parameters:
224  ctx: context handle */
225  void (*exit_context)(const struct mg_context *ctx);
226 };
227 
228 
229 /* Start web server.
230 
231  Parameters:
232  callbacks: mg_callbacks structure with user-defined callbacks.
233  options: NULL terminated list of option_name, option_value pairs that
234  specify Civetweb configuration parameters.
235 
236  Side-effects: on UNIX, ignores SIGCHLD and SIGPIPE signals. If custom
237  processing is required for these, signal handlers must be set up
238  after calling mg_start().
239 
240 
241  Example:
242  const char *options[] = {
243  "document_root", "/var/www",
244  "listening_ports", "80,443s",
245  NULL
246  };
247  struct mg_context *ctx = mg_start(&my_func, NULL, options);
248 
249  Refer to https://github.com/civetweb/civetweb/blob/master/docs/UserManual.md
250  for the list of valid option and their possible values.
251 
252  Return:
253  web server context, or NULL on error. */
254 CIVETWEB_API struct mg_context *mg_start(const struct mg_callbacks *callbacks,
255  void *user_data,
256  const char **configuration_options);
257 
258 
259 /* Stop the web server.
260 
261  Must be called last, when an application wants to stop the web server and
262  release all associated resources. This function blocks until all Civetweb
263  threads are stopped. Context pointer becomes invalid. */
264 CIVETWEB_API void mg_stop(struct mg_context *);
265 
266 
267 /* mg_request_handler
268 
269  Called when a new request comes in. This callback is URI based
270  and configured with mg_set_request_handler().
271 
272  Parameters:
273  conn: current connection information.
274  cbdata: the callback data configured with mg_set_request_handler().
275  Returns:
276  0: the handler could not handle the request, so fall through.
277  1 - 999: the handler processed the request. The return code is
278  stored as a HTTP status code for the access log. */
279 typedef int (*mg_request_handler)(struct mg_connection *conn, void *cbdata);
280 
281 
282 /* mg_set_request_handler
283 
284  Sets or removes a URI mapping for a request handler.
285  This function uses mg_lock_context internally.
286 
287  URI's are ordered and prefixed URI's are supported. For example,
288  consider two URIs: /a/b and /a
289  /a matches /a
290  /a/b matches /a/b
291  /a/c matches /a
292 
293  Parameters:
294  ctx: server context
295  uri: the URI (exact or pattern) for the handler
296  handler: the callback handler to use when the URI is requested.
297  If NULL, an already registered handler for this URI will be
298  removed.
299  The URI used to remove a handler must match exactly the one used
300  to
301  register it (not only a pattern match).
302  cbdata: the callback data to give to the handler when it is called. */
303 CIVETWEB_API void mg_set_request_handler(struct mg_context *ctx,
304  const char *uri,
305  mg_request_handler handler,
306  void *cbdata);
307 
308 
309 /* Callback types for websocket handlers in C/C++.
310 
311  mg_websocket_connect_handler
312  Is called when the client intends to establish a websocket connection,
313  before websocket handshake.
314  Return value:
315  0: civetweb proceeds with websocket handshake.
316  1: connection is closed immediately.
317 
318  mg_websocket_ready_handler
319  Is called when websocket handshake is successfully completed, and
320  connection is ready for data exchange.
321 
322  mg_websocket_data_handler
323  Is called when a data frame has been received from the client.
324  Parameters:
325  bits: first byte of the websocket frame, see websocket RFC at
326  http://tools.ietf.org/html/rfc6455, section 5.2
327  data, data_len: payload, with mask (if any) already applied.
328  Return value:
329  1: keep this websocket connection open.
330  0: close this websocket connection.
331 
332  mg_connection_close_handler
333  Is called, when the connection is closed.*/
334 typedef int (*mg_websocket_connect_handler)(const struct mg_connection *,
335  void *);
336 typedef void (*mg_websocket_ready_handler)(struct mg_connection *, void *);
337 typedef int (*mg_websocket_data_handler)(struct mg_connection *,
338  int,
339  char *,
340  size_t,
341  void *);
342 typedef void (*mg_websocket_close_handler)(const struct mg_connection *,
343  void *);
344 
345 
346 /* mg_set_websocket_handler
347 
348  Set or remove handler functions for websocket connections.
349  This function works similar to mg_set_request_handler - see there. */
350 CIVETWEB_API void
351 mg_set_websocket_handler(struct mg_context *ctx,
352  const char *uri,
353  mg_websocket_connect_handler connect_handler,
354  mg_websocket_ready_handler ready_handler,
355  mg_websocket_data_handler data_handler,
356  mg_websocket_close_handler close_handler,
357  void *cbdata);
358 
359 
360 /* mg_authorization_handler
361 
362  Some description here
363 
364  Parameters:
365  conn: current connection information.
366  cbdata: the callback data configured with mg_set_request_handler().
367  Returns:
368  0: access denied
369  1: access granted
370  */
371 typedef int (*mg_authorization_handler)(struct mg_connection *conn,
372  void *cbdata);
373 
374 
375 /* mg_set_auth_handler
376 
377  Sets or removes a URI mapping for an authorization handler.
378  This function works similar to mg_set_request_handler - see there. */
379 CIVETWEB_API void mg_set_auth_handler(struct mg_context *ctx,
380  const char *uri,
381  mg_authorization_handler handler,
382  void *cbdata);
383 
384 
385 /* Get the value of particular configuration parameter.
386  The value returned is read-only. Civetweb does not allow changing
387  configuration at run time.
388  If given parameter name is not valid, NULL is returned. For valid
389  names, return value is guaranteed to be non-NULL. If parameter is not
390  set, zero-length string is returned. */
391 CIVETWEB_API const char *mg_get_option(const struct mg_context *ctx,
392  const char *name);
393 
394 
395 /* Get context from connection. */
396 CIVETWEB_API struct mg_context *
397 mg_get_context(const struct mg_connection *conn);
398 
399 
400 /* Get user data passed to mg_start from context. */
401 CIVETWEB_API void *mg_get_user_data(const struct mg_context *ctx);
402 
403 
404 /* Set user data for the current connection. */
405 CIVETWEB_API void mg_set_user_connection_data(struct mg_connection *conn,
406  void *data);
407 
408 
409 /* Get user data set for the current connection. */
410 CIVETWEB_API void *
411 mg_get_user_connection_data(const struct mg_connection *conn);
412 
413 
414 #if defined(MG_LEGACY_INTERFACE)
415 /* Return array of strings that represent valid configuration options.
416  For each option, option name and default value is returned, i.e. the
417  number of entries in the array equals to number_of_options x 2.
418  Array is NULL terminated. */
419 /* Deprecated: Use mg_get_valid_options instead. */
420 CIVETWEB_API const char **mg_get_valid_option_names(void);
421 #endif
422 
423 
424 struct mg_option {
425  const char *name;
426  int type;
427  const char *default_value;
428 };
429 
430 
431 enum {
439 };
440 
441 
442 /* Return array of struct mg_option, representing all valid configuration
443  options of civetweb.c.
444  The array is terminated by a NULL name option. */
445 CIVETWEB_API const struct mg_option *mg_get_valid_options(void);
446 
447 
449  int protocol; /* 1 = IPv4, 2 = IPv6, 3 = both */
450  int port; /* port number */
451  int is_ssl; /* https port: 0 = no, 1 = yes */
452  int is_redirect; /* redirect all requests: 0 = no, 1 = yes */
457 };
458 
459 
460 /* Get the list of ports that civetweb is listening on.
461  The parameter size is the size of the ports array in elements.
462  The caller is responsibility to allocate the required memory.
463  This function returns the number of struct mg_server_ports elements
464  filled in, or <0 in case of an error. */
465 CIVETWEB_API int mg_get_server_ports(const struct mg_context *ctx,
466  int size,
467  struct mg_server_ports *ports);
468 
469 
470 /* Deprecated: Use mg_get_server_ports instead. */
471 CIVETWEB_API size_t
472 mg_get_ports(const struct mg_context *ctx, size_t size, int *ports, int *ssl);
473 
474 
475 /* Add, edit or delete the entry in the passwords file.
476 
477  This function allows an application to manipulate .htpasswd files on the
478  fly by adding, deleting and changing user records. This is one of the
479  several ways of implementing authentication on the server side. For another,
480  cookie-based way please refer to the examples/chat in the source tree.
481 
482  If password is not NULL, entry is added (or modified if already exists).
483  If password is NULL, entry is deleted.
484 
485  Return:
486  1 on success, 0 on error. */
487 CIVETWEB_API int mg_modify_passwords_file(const char *passwords_file_name,
488  const char *domain,
489  const char *user,
490  const char *password);
491 
492 
493 /* Return information associated with the request. */
494 CIVETWEB_API const struct mg_request_info *
495 mg_get_request_info(const struct mg_connection *);
496 
497 
498 /* Send data to the client.
499  Return:
500  0 when the connection has been closed
501  -1 on error
502  >0 number of bytes written on success */
503 CIVETWEB_API int mg_write(struct mg_connection *, const void *buf, size_t len);
504 
505 
506 /* Send data to a websocket client wrapped in a websocket frame. Uses
507  mg_lock_connection to ensure that the transmission is not interrupted,
508  i.e., when the application is proactively communicating and responding to
509  a request simultaneously.
510 
511  Send data to a websocket client wrapped in a websocket frame.
512  This function is available when civetweb is compiled with -DUSE_WEBSOCKET
513 
514  Return:
515  0 when the connection has been closed
516  -1 on error
517  >0 number of bytes written on success */
518 CIVETWEB_API int mg_websocket_write(struct mg_connection *conn,
519  int opcode,
520  const char *data,
521  size_t data_len);
522 
523 
524 /* Send data to a websocket server wrapped in a masked websocket frame. Uses
525  mg_lock_connection to ensure that the transmission is not interrupted,
526  i.e., when the application is proactively communicating and responding to
527  a request simultaneously.
528 
529  Send data to a websocket server wrapped in a masked websocket frame.
530  This function is available when civetweb is compiled with -DUSE_WEBSOCKET
531 
532  Return:
533  0 when the connection has been closed
534  -1 on error
535  >0 number of bytes written on success */
536 CIVETWEB_API int mg_websocket_client_write(struct mg_connection *conn,
537  int opcode,
538  const char *data,
539  size_t data_len);
540 
541 
542 /* Blocks until unique access is obtained to this connection. Intended for use
543  with websockets only.
544  Invoke this before mg_write or mg_printf when communicating with a
545  websocket if your code has server-initiated communication as well as
546  communication in direct response to a message. */
547 CIVETWEB_API void mg_lock_connection(struct mg_connection *conn);
548 CIVETWEB_API void mg_unlock_connection(struct mg_connection *conn);
549 
550 
551 #if defined(MG_LEGACY_INTERFACE)
552 #define mg_lock mg_lock_connection
553 #define mg_unlock mg_unlock_connection
554 #endif
555 
556 
557 /* Lock server context. This lock may be used to protect resources
558  that are shared between different connection/worker threads. */
559 CIVETWEB_API void mg_lock_context(struct mg_context *ctx);
560 CIVETWEB_API void mg_unlock_context(struct mg_context *ctx);
561 
562 
563 /* Opcodes, from http://tools.ietf.org/html/rfc6455 */
564 enum {
571 };
572 
573 
574 /* Macros for enabling compiler-specific checks for printf-like arguments. */
575 #undef PRINTF_FORMAT_STRING
576 #if defined(_MSC_VER) && _MSC_VER >= 1400
577 #include <sal.h>
578 #if defined(_MSC_VER) && _MSC_VER > 1400
579 #define PRINTF_FORMAT_STRING(s) _Printf_format_string_ s
580 #else
581 #define PRINTF_FORMAT_STRING(s) __format_string s
582 #endif
583 #else
584 #define PRINTF_FORMAT_STRING(s) s
585 #endif
586 
587 #ifdef __GNUC__
588 #define PRINTF_ARGS(x, y) __attribute__((format(printf, x, y)))
589 #else
590 #define PRINTF_ARGS(x, y)
591 #endif
592 
593 
594 /* Send data to the client using printf() semantics.
595  Works exactly like mg_write(), but allows to do message formatting. */
596 CIVETWEB_API int mg_printf(struct mg_connection *,
597  PRINTF_FORMAT_STRING(const char *fmt),
598  ...) PRINTF_ARGS(2, 3);
599 
600 
601 /* Send contents of the entire file together with HTTP headers. */
602 CIVETWEB_API void mg_send_file(struct mg_connection *conn, const char *path);
603 
604 /* Send contents of the entire file together with HTTP headers.
605  Parameters:
606  conn: Current connection information.
607  path: Full path to the file to send.
608  mime_type: Content-Type for file. NULL will cause the type to be
609  looked up by the file extension.
610 */
611 CIVETWEB_API void mg_send_mime_file(struct mg_connection *conn,
612  const char *path,
613  const char *mime_type);
614 
615 /* Store body data into a file. */
616 CIVETWEB_API long long mg_store_body(struct mg_connection *conn,
617  const char *path);
618 /* Read entire request body and stor it in a file "path".
619  Return:
620  < 0 Error
621  >= 0 Number of bytes stored in file "path".
622 */
623 
624 
625 /* Read data from the remote end, return number of bytes read.
626  Return:
627  0 connection has been closed by peer. No more data could be read.
628  < 0 read error. No more data could be read from the connection.
629  > 0 number of bytes read into the buffer. */
630 CIVETWEB_API int mg_read(struct mg_connection *, void *buf, size_t len);
631 
632 
633 /* Get the value of particular HTTP header.
634 
635  This is a helper function. It traverses request_info->http_headers array,
636  and if the header is present in the array, returns its value. If it is
637  not present, NULL is returned. */
638 CIVETWEB_API const char *mg_get_header(const struct mg_connection *,
639  const char *name);
640 
641 
642 /* Get a value of particular form variable.
643 
644  Parameters:
645  data: pointer to form-uri-encoded buffer. This could be either POST data,
646  or request_info.query_string.
647  data_len: length of the encoded data.
648  var_name: variable name to decode from the buffer
649  dst: destination buffer for the decoded variable
650  dst_len: length of the destination buffer
651 
652  Return:
653  On success, length of the decoded variable.
654  On error:
655  -1 (variable not found).
656  -2 (destination buffer is NULL, zero length or too small to hold the
657  decoded variable).
658 
659  Destination buffer is guaranteed to be '\0' - terminated if it is not
660  NULL or zero length. */
661 CIVETWEB_API int mg_get_var(const char *data,
662  size_t data_len,
663  const char *var_name,
664  char *dst,
665  size_t dst_len);
666 
667 
668 /* Get a value of particular form variable.
669 
670  Parameters:
671  data: pointer to form-uri-encoded buffer. This could be either POST data,
672  or request_info.query_string.
673  data_len: length of the encoded data.
674  var_name: variable name to decode from the buffer
675  dst: destination buffer for the decoded variable
676  dst_len: length of the destination buffer
677  occurrence: which occurrence of the variable, 0 is the first, 1 the
678  second...
679  this makes it possible to parse a query like
680  b=x&a=y&a=z which will have occurrence values b:0, a:0 and a:1
681 
682  Return:
683  On success, length of the decoded variable.
684  On error:
685  -1 (variable not found).
686  -2 (destination buffer is NULL, zero length or too small to hold the
687  decoded variable).
688 
689  Destination buffer is guaranteed to be '\0' - terminated if it is not
690  NULL or zero length. */
691 CIVETWEB_API int mg_get_var2(const char *data,
692  size_t data_len,
693  const char *var_name,
694  char *dst,
695  size_t dst_len,
696  size_t occurrence);
697 
698 
699 /* Fetch value of certain cookie variable into the destination buffer.
700 
701  Destination buffer is guaranteed to be '\0' - terminated. In case of
702  failure, dst[0] == '\0'. Note that RFC allows many occurrences of the same
703  parameter. This function returns only first occurrence.
704 
705  Return:
706  On success, value length.
707  On error:
708  -1 (either "Cookie:" header is not present at all or the requested
709  parameter is not found).
710  -2 (destination buffer is NULL, zero length or too small to hold the
711  value). */
712 CIVETWEB_API int mg_get_cookie(const char *cookie,
713  const char *var_name,
714  char *buf,
715  size_t buf_len);
716 
717 
718 /* Download data from the remote web server.
719  host: host name to connect to, e.g. "foo.com", or "10.12.40.1".
720  port: port number, e.g. 80.
721  use_ssl: wether to use SSL connection.
722  error_buffer, error_buffer_size: error message placeholder.
723  request_fmt,...: HTTP request.
724  Return:
725  On success, valid pointer to the new connection, suitable for mg_read().
726  On error, NULL. error_buffer contains error message.
727  Example:
728  char ebuf[100];
729  struct mg_connection *conn;
730  conn = mg_download("google.com", 80, 0, ebuf, sizeof(ebuf),
731  "%s", "GET / HTTP/1.0\r\nHost: google.com\r\n\r\n");
732  */
733 CIVETWEB_API struct mg_connection *
734 mg_download(const char *host,
735  int port,
736  int use_ssl,
737  char *error_buffer,
738  size_t error_buffer_size,
739  PRINTF_FORMAT_STRING(const char *request_fmt),
740  ...) PRINTF_ARGS(6, 7);
741 
742 
743 /* Close the connection opened by mg_download(). */
744 CIVETWEB_API void mg_close_connection(struct mg_connection *conn);
745 
746 
747 #if defined(MG_LEGACY_INTERFACE)
748 /* File upload functionality. Each uploaded file gets saved into a temporary
749  file and MG_UPLOAD event is sent.
750  Return number of uploaded files.
751  Deprecated: Use mg_handle_form_request instead. */
752 CIVETWEB_API int mg_upload(struct mg_connection *conn,
753  const char *destination_dir);
754 #endif
755 
756 
757 /* This structure contains callback functions for handling form fields.
758  It is used as an argument to mg_handle_form_request. */
760  /* This callback function is called, if a new field has been found.
761  * The return value of this callback is used to define how the field
762  * should be processed.
763  *
764  * Parameters:
765  * key: Name of the field ("name" property of the HTML input field).
766  * filename: Name of a file to upload, at the client computer.
767  * Only set for input fields of type "file", otherwise NULL.
768  * path: Output parameter: File name (incl. path) to store the file
769  * at the server computer. Only used if FORM_FIELD_STORAGE_STORE
770  * is returned by this callback. Existing files will be
771  * overwritten.
772  * pathlen: Length of the buffer for path.
773  * user_data: Value of the member user_data of mg_form_data_handler
774  *
775  * Return value:
776  * The callback must return the intended storage for this field
777  * (See FORM_FIELD_STORAGE_*).
778  */
779  int (*field_found)(const char *key,
780  const char *filename,
781  char *path,
782  size_t pathlen,
783  void *user_data);
784 
785  /* If the "field_found" callback returned FORM_FIELD_STORAGE_GET,
786  * this callback will receive the field data.
787  *
788  * Parameters:
789  * key: Name of the field ("name" property of the HTML input field).
790  * value: Value of the input field.
791  * user_data: Value of the member user_data of mg_form_data_handler
792  *
793  * Return value:
794  * TODO: Needs to be defined.
795  */
796  int (*field_get)(const char *key,
797  const char *value,
798  size_t valuelen,
799  void *user_data);
800 
801  /* If the "field_found" callback returned FORM_FIELD_STORAGE_STORE,
802  * the data will be stored into a file. If the file has been written
803  * successfully, this callback will be called. This callback will
804  * not be called for only partially uploaded files. The
805  * mg_handle_form_request function will either store the file completely
806  * and call this callback, or it will remove any partial content and
807  * not call this callback function.
808  *
809  * Parameters:
810  * path: Path of the file stored at the server.
811  * file_size: Size of the stored file in bytes.
812  * user_data: Value of the member user_data of mg_form_data_handler
813  *
814  * Return value:
815  * TODO: Needs to be defined.
816  */
817  int (*field_store)(const char *path, long long file_size, void *user_data);
818 
819  /* User supplied argument, passed to all callback functions. */
820  void *user_data;
821 };
822 
823 
824 /* Return values definition for the "field_found" callback in
825  * mg_form_data_handler. */
826 enum {
827  /* Skip this field (neither get nor store it). Continue with the
828  * next field. */
830  /* Get the field value. */
832  /* Store the field value into a file. */
834  /* Stop parsing this request. Skip the remaining fields. */
836 };
837 
838 
839 /* Process form data.
840  * Returns the number of fields handled, or < 0 in case of an error.
841  * Note: It is possible that several fields are already handled successfully
842  * (e.g., stored into files), before the request handling is stopped with an
843  * error. In this case a number < 0 is returned as well.
844  * In any case, it is the duty of the caller to remove files once they are
845  * no longer required. */
846 CIVETWEB_API int mg_handle_form_request(struct mg_connection *conn,
847  struct mg_form_data_handler *fdh);
848 
849 
850 /* Convenience function -- create detached thread.
851  Return: 0 on success, non-0 on error. */
852 typedef void *(*mg_thread_func_t)(void *);
854 
855 
856 /* Return builtin mime type for the given file name.
857  For unrecognized extensions, "text/plain" is returned. */
858 CIVETWEB_API const char *mg_get_builtin_mime_type(const char *file_name);
859 
860 
861 /* Get text representation of HTTP status code. */
862 CIVETWEB_API const char *mg_get_response_code_text(struct mg_connection *conn,
863  int response_code);
864 
865 
866 /* Return CivetWeb version. */
867 CIVETWEB_API const char *mg_version(void);
868 
869 
870 /* URL-decode input buffer into destination buffer.
871  0-terminate the destination buffer.
872  form-url-encoded data differs from URI encoding in a way that it
873  uses '+' as character for space, see RFC 1866 section 8.2.1
874  http://ftp.ics.uci.edu/pub/ietf/html/rfc1866.txt
875  Return: length of the decoded data, or -1 if dst buffer is too small. */
876 CIVETWEB_API int mg_url_decode(const char *src,
877  int src_len,
878  char *dst,
879  int dst_len,
880  int is_form_url_encoded);
881 
882 
883 /* URL-encode input buffer into destination buffer.
884  returns the length of the resulting buffer or -1
885  is the buffer is too small. */
886 CIVETWEB_API int mg_url_encode(const char *src, char *dst, size_t dst_len);
887 
888 
889 /* MD5 hash given strings.
890  Buffer 'buf' must be 33 bytes long. Varargs is a NULL terminated list of
891  ASCIIz strings. When function returns, buf will contain human-readable
892  MD5 hash. Example:
893  char buf[33];
894  mg_md5(buf, "aa", "bb", NULL); */
895 CIVETWEB_API char *mg_md5(char buf[33], ...);
896 
897 
898 /* Print error message to the opened error log stream.
899  This utilizes the provided logging configuration.
900  conn: connection
901  fmt: format string without the line return
902  ...: variable argument list
903  Example:
904  mg_cry(conn,"i like %s", "logging"); */
905 CIVETWEB_API void mg_cry(const struct mg_connection *conn,
906  PRINTF_FORMAT_STRING(const char *fmt),
907  ...) PRINTF_ARGS(2, 3);
908 
909 
910 /* utility methods to compare two buffers, case incensitive. */
911 CIVETWEB_API int mg_strcasecmp(const char *s1, const char *s2);
912 CIVETWEB_API int mg_strncasecmp(const char *s1, const char *s2, size_t len);
913 
914 
915 /* Connect to a websocket as a client
916  Parameters:
917  host: host to connect to, i.e. "echo.websocket.org" or "192.168.1.1" or
918  "localhost"
919  port: server port
920  use_ssl: make a secure connection to server
921  error_buffer, error_buffer_size: buffer for an error message
922  path: server path you are trying to connect to, i.e. if connection to
923  localhost/app, path should be "/app"
924  origin: value of the Origin HTTP header
925  data_func: callback that should be used when data is received from the
926  server
927  user_data: user supplied argument
928 
929  Return:
930  On success, valid mg_connection object.
931  On error, NULL. Se error_buffer for details.
932 */
933 CIVETWEB_API struct mg_connection *
934 mg_connect_websocket_client(const char *host,
935  int port,
936  int use_ssl,
937  char *error_buffer,
938  size_t error_buffer_size,
939  const char *path,
940  const char *origin,
941  mg_websocket_data_handler data_func,
942  mg_websocket_close_handler close_func,
943  void *user_data);
944 
945 
946 /* Connect to a TCP server as a client (can be used to connect to a HTTP server)
947  Parameters:
948  host: host to connect to, i.e. "www.wikipedia.org" or "192.168.1.1" or
949  "localhost"
950  port: server port
951  use_ssl: make a secure connection to server
952  error_buffer, error_buffer_size: buffer for an error message
953 
954  Return:
955  On success, valid mg_connection object.
956  On error, NULL. Se error_buffer for details.
957 */
958 CIVETWEB_API struct mg_connection *mg_connect_client(const char *host,
959  int port,
960  int use_ssl,
961  char *error_buffer,
962  size_t error_buffer_size);
963 
964 
966  const char *host;
967  int port;
968  const char *client_cert;
969  const char *server_cert;
970  /* TODO: add more data */
971 };
972 
973 
974 CIVETWEB_API struct mg_connection *
975 mg_connect_client_secure(const struct mg_client_options *client_options,
976  char *error_buffer,
977  size_t error_buffer_size);
978 
979 
980 enum { TIMEOUT_INFINITE = -1 };
981 
982 
983 /* Wait for a response from the server
984  Parameters:
985  conn: connection
986  ebuf, ebuf_len: error message placeholder.
987  timeout: time to wait for a response in milliseconds (if < 0 then wait
988  forever)
989 
990  Return:
991  On success, >= 0
992  On error/timeout, < 0
993 */
994 CIVETWEB_API int mg_get_response(struct mg_connection *conn,
995  char *ebuf,
996  size_t ebuf_len,
997  int timeout);
998 
999 
1000 /* Check which features where set when civetweb has been compiled.
1001  Parameters:
1002  feature: specifies which feature should be checked
1003  1 serve files (NO_FILES not set)
1004  2 support HTTPS (NO_SSL not set)
1005  4 support CGI (NO_CGI not set)
1006  8 support IPv6 (USE_IPV6 set)
1007  16 support WebSocket (USE_WEBSOCKET set)
1008  32 support Lua scripts and Lua server pages (USE_LUA is set)
1009  64 support server side JavaScript (USE_DUKTAPE is set)
1010  128 support caching (NO_CACHING not set)
1011  The result is undefined for all other feature values.
1012 
1013  Return:
1014  If feature is available > 0
1015  If feature is not available = 0
1016 */
1017 CIVETWEB_API unsigned mg_check_feature(unsigned feature);
1018 
1019 
1020 #ifdef __cplusplus
1021 }
1022 #endif /* __cplusplus */
1023 
1024 #endif /* CIVETWEB_HEADER_INCLUDED */
CIVETWEB_API struct mg_context * mg_start(const struct mg_callbacks *callbacks, void *user_data, const char **configuration_options)
Definition: civetweb.c:12875
const char * remote_user
Definition: civetweb.h:68
CIVETWEB_API const char * mg_get_response_code_text(struct mg_connection *conn, int response_code)
Definition: civetweb.c:2286
CIVETWEB_API int mg_strncasecmp(const char *s1, const char *s2, size_t len)
Definition: civetweb.c:1591
const char * local_uri
Definition: civetweb.h:61
const char * uri
Definition: civetweb.h:64
const char * mime_type
Definition: civetweb.c:5007
#define PRINTF_ARGS(x, y)
Definition: civetweb.h:590
const char * host
Definition: civetweb.h:966
CIVETWEB_API void mg_unlock_connection(struct mg_connection *conn)
Definition: civetweb.c:8392
CIVETWEB_API void mg_set_user_connection_data(struct mg_connection *conn, void *data)
Definition: civetweb.c:1762
const char * server_cert
Definition: civetweb.h:969
CIVETWEB_API void * mg_get_user_data(const struct mg_context *ctx)
Definition: civetweb.c:1755
CIVETWEB_API size_t mg_get_ports(const struct mg_context *ctx, size_t size, int *ports, int *ssl)
Definition: civetweb.c:1781
CIVETWEB_API struct mg_connection * mg_connect_client(const char *host, int port, int use_ssl, char *error_buffer, size_t error_buffer_size)
Definition: civetweb.c:11634
CIVETWEB_API void mg_set_websocket_handler(struct mg_context *ctx, const char *uri, mg_websocket_connect_handler connect_handler, mg_websocket_ready_handler ready_handler, mg_websocket_data_handler data_handler, mg_websocket_close_handler close_handler, void *cbdata)
Definition: civetweb.c:9586
CIVETWEB_API struct mg_connection * mg_download(const char *host, int port, int use_ssl, char *error_buffer, size_t error_buffer_size, PRINTF_FORMAT_STRING(const char *request_fmt),...) PRINTF_ARGS(6
CIVETWEB_API struct mg_connection * mg_connect_websocket_client(const char *host, int port, int use_ssl, char *error_buffer, size_t error_buffer_size, const char *path, const char *origin, mg_websocket_data_handler data_func, mg_websocket_close_handler close_func, void *user_data)
Definition: civetweb.c:12058
CIVETWEB_API int mg_printf(struct mg_connection *, PRINTF_FORMAT_STRING(const char *fmt),...) PRINTF_ARGS(2
CIVETWEB_API struct mg_connection CIVETWEB_API void mg_close_connection(struct mg_connection *conn)
Definition: civetweb.c:11458
CIVETWEB_API const char * mg_get_option(const struct mg_context *ctx, const char *name)
Definition: civetweb.c:1734
CIVETWEB_API void mg_lock_context(struct mg_context *ctx)
Definition: civetweb.c:8400
struct mg_request_info::mg_header http_headers[64]
CIVETWEB_API struct mg_connection * mg_connect_client_secure(const struct mg_client_options *client_options, char *error_buffer, size_t error_buffer_size)
Definition: civetweb.c:11622
char remote_addr[48]
Definition: civetweb.h:70
CIVETWEB_API void mg_unlock_context(struct mg_context *ctx)
Definition: civetweb.c:8408
CIVETWEB_API int CIVETWEB_API void mg_send_file(struct mg_connection *conn, const char *path)
Definition: civetweb.c:6674
CIVETWEB_API const char * mg_get_header(const struct mg_connection *, const char *name)
Definition: civetweb.c:2063
int(* mg_authorization_handler)(struct mg_connection *conn, void *cbdata)
Definition: civetweb.h:371
CIVETWEB_API long long mg_store_body(struct mg_connection *conn, const char *path)
Definition: civetweb.c:6763
CIVETWEB_API void mg_send_mime_file(struct mg_connection *conn, const char *path, const char *mime_type)
Definition: civetweb.c:6681
const char * default_value
Definition: civetweb.h:427
#define PRINTF_FORMAT_STRING(s)
Definition: civetweb.h:584
const char * request_method
Definition: civetweb.h:58
CIVETWEB_API unsigned mg_check_feature(unsigned feature)
Definition: civetweb.c:13099
CIVETWEB_API const char * mg_get_builtin_mime_type(const char *file_name)
Definition: civetweb.c:5106
int(* mg_websocket_data_handler)(struct mg_connection *, int, char *, size_t, void *)
Definition: civetweb.h:337
void(* mg_websocket_close_handler)(const struct mg_connection *, void *)
Definition: civetweb.h:342
CIVETWEB_API void mg_cry(const struct mg_connection *conn, PRINTF_FORMAT_STRING(const char *fmt),...) PRINTF_ARGS(2
CIVETWEB_API void CIVETWEB_API int mg_strcasecmp(const char *s1, const char *s2)
Definition: civetweb.c:1606
CIVETWEB_API void mg_set_request_handler(struct mg_context *ctx, const char *uri, mg_request_handler handler, void *cbdata)
Definition: civetweb.c:9566
CIVETWEB_API void mg_lock_connection(struct mg_connection *conn)
Definition: civetweb.c:8384
CIVETWEB_API int mg_get_cookie(const char *cookie, const char *var_name, char *buf, size_t buf_len)
Definition: civetweb.c:4513
CIVETWEB_API int mg_write(struct mg_connection *, const void *buf, size_t len)
Definition: civetweb.c:4235
CIVETWEB_API int mg_url_encode(const char *src, char *dst, size_t dst_len)
Definition: civetweb.c:5973
CIVETWEB_API int mg_get_server_ports(const struct mg_context *ctx, int size, struct mg_server_ports *ports)
Definition: civetweb.c:1796
const char * http_version
Definition: civetweb.h:65
CIVETWEB_API int mg_get_response(struct mg_connection *conn, char *ebuf, size_t ebuf_len, int timeout)
Definition: civetweb.c:11924
const char * name
Definition: civetweb.h:425
long long content_length
Definition: civetweb.h:77
int(* mg_request_handler)(struct mg_connection *conn, void *cbdata)
Definition: civetweb.h:279
CIVETWEB_API const struct mg_request_info * mg_get_request_info(const struct mg_connection *)
Definition: civetweb.c:1972
CIVETWEB_API int mg_start_thread(mg_thread_func_t f, void *p)
Definition: civetweb.c:3550
CIVETWEB_API int mg_websocket_write(struct mg_connection *conn, int opcode, const char *data, size_t data_len)
int(* mg_websocket_connect_handler)(const struct mg_connection *, void *)
Definition: civetweb.h:334
CIVETWEB_API int mg_url_decode(const char *src, int src_len, char *dst, int dst_len, int is_form_url_encoded)
Definition: civetweb.c:4414
CIVETWEB_API void * mg_get_user_connection_data(const struct mg_connection *conn)
Definition: civetweb.c:1771
CIVETWEB_API int mg_get_var2(const char *data, size_t data_len, const char *var_name, char *dst, size_t dst_len, size_t occurrence)
Definition: civetweb.c:4456
CIVETWEB_API char * mg_md5(char buf[33],...)
Definition: civetweb.c:5174
CIVETWEB_API struct mg_context * mg_get_context(const struct mg_connection *conn)
Definition: civetweb.c:1748
CIVETWEB_API int mg_read(struct mg_connection *, void *buf, size_t len)
Definition: civetweb.c:4146
void * user_data
Definition: civetweb.h:81
typedef void((*Func_t)())
CIVETWEB_API int mg_modify_passwords_file(const char *passwords_file_name, const char *domain, const char *user, const char *password)
Definition: civetweb.c:5684
int type
Definition: civetweb.h:426
void(* mg_websocket_ready_handler)(struct mg_connection *, void *)
Definition: civetweb.h:336
void *(* mg_thread_func_t)(void *)
Definition: civetweb.h:852
CIVETWEB_API int mg_handle_form_request(struct mg_connection *conn, struct mg_form_data_handler *fdh)
CIVETWEB_API int mg_get_var(const char *data, size_t data_len, const char *var_name, char *dst, size_t dst_len)
Definition: civetweb.c:4445
CIVETWEB_API int mg_websocket_client_write(struct mg_connection *conn, int opcode, const char *data, size_t data_len)
const char * query_string
Definition: civetweb.h:66
CIVETWEB_API void mg_set_auth_handler(struct mg_context *ctx, const char *uri, mg_authorization_handler handler, void *cbdata)
Definition: civetweb.c:9612
void * conn_data
Definition: civetweb.h:82
const char * client_cert
Definition: civetweb.h:968
CIVETWEB_API const char * mg_version(void)
Definition: civetweb.c:1965
CIVETWEB_API const struct mg_option * mg_get_valid_options(void)
Definition: civetweb.c:1482
static void log_access(const struct mg_connection *conn)
Definition: civetweb.c:10537
CIVETWEB_API void mg_stop(struct mg_context *)
Definition: civetweb.c:12800
const char * request_uri
Definition: civetweb.h:59
#define CIVETWEB_API
Definition: civetweb.h:40