Mongoose 6.4

PUBLISHED_FROM=5585ece71e9032b1357ea47fa8de626c52405650
Fix docs link. Better description
2026-10-26 12:14:56 +00:00 · 2016-04-12 14:21:12 +01:00 · 2016-04-12 14:21:08 +01:00 · 2016-04-12 14:21:06 +01:00 · 2016-04-12 14:21:05 +01:00 · 2016-04-12 12:37:05 +01:00
403 changed files with 176193 additions and 9880 deletions
@@ -0,0 +1,8 @@
 People who have agreed to the
 [Cesanta CLA](https://docs.cesanta.com/contributors_la.shtml)
 can make contributions. Note that the CLA isn't a copyright
 _assigment_ but rather a copyright _license_.
 You retain the copyright on your contributions.
 We follow the Google C/C++ style guide: https://google.github.io/styleguide/cppguide.html
 We'd appreciate if your contribution follows the same style guide.
@@ -1,16 +1,16 @@
 Copyright (c) 2004-2013 Sergey Lyubka <valenok@gmail.com>
-Copyright (c) 2013-2015 Cesanta Software Limited
+Copyright (c) 2013-2016 Cesanta Software Limited
 All rights reserved
-This code is dual-licensed: you can redistribute it and/or modify
+This software is dual-licensed: you can redistribute it and/or modify
 it under the terms of the GNU General Public License version 2 as
 published by the Free Software Foundation. For the terms of this
-license, see <http://www.gnu.org/licenses>.
+license, see <http://www.gnu.org/licenses/>.
-You are free to use this code under the terms of the GNU General
+You are free to use this software under the terms of the GNU General
 Public License, but WITHOUT ANY WARRANTY; without even the implied
 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 See the GNU General Public License for more details.
-Alternatively, you can license this code under a commercial
+Alternatively, you can license this software under a commercial
-license, as set out in <http://cesanta.com/>.
+license, as set out in <https://www.cesanta.com/license>.
@@ -1,76 +1,80 @@
-# <img src="http://cesanta.com/images/mongoose_logo.png" width="64" height="64"> Mongoose Web Server
+# <img src="http://www.cesanta.com/hubfs/www.cesanta.com/Images/mongoose_library.png" width="64" height="64"> Mongoose - Embedded Web Server / Embedded Networking Library
-Mongoose is the most easy to use web server on the planet. A web server of choice for Web developers (PHP, Ruby, Python, etc) and Web designers.
+![](https://img.shields.io/badge/license-GPL_2-green.svg "License")
-Mongoose is built on top of Libmongoose embedded library, which can turn
+Mongoose is ideal for embedded environments. It has been designed
-anything into a web server in 5 minutes worth of effort and few lines of code.
+for connecting devices and bringing them online. Mongoose
-Libmongoose is used to serve Web GUI on embedded devices, implement RESTful
+is on the market since 2004, used by vast number of open source and
-services, RPC frameworks (e.g. JSON-RPC), handle telemetry data exchange, and
+commercial products - it even runs on space stations!
 perform many other tasks in various different industries including aerospace,
 manufacturing, finance, research, automotive, gaming, IT.
 Mongoose provides easy to use event-driven interface that allows to implement
 network protocols or scalable network applications  with little effort.
 Mongoose helps developers to manage the complexity of network programming
 and let them concentrate on the logic, saving time and money.
-   * [Mailing list](http://groups.google.com/group/mongoose-users)
+If you're looking for a pre-compiled Windows or Mac binary,
-   * [Downloads](http://cesanta.com/products.shtml)
+- [Download pre-compiled Mongoose web server binary](https://www.cesanta.com/products/binary)
   * [Documentation](http://cesanta.com/docs.shtml)
-Check out Fossa - our [embedded multi-protocol library](https://github.com/cesanta/fossa) with TCP,UDP,HTTP,Websocket,MQTT,DNS support, designed for Internet Of Things!
+Alternatively,
 - [Download Mongoose Source Code here](http://hubs.ly/H01bWvx0)
 - [Check our latest releases] (https://github.com/cesanta/mongoose/releases)
 - [Read User Guide and API reference](https://docs.cesanta.com/mongoose/dev)
 - [Study mongoose example code](https://github.com/cesanta/mongoose/tree/master/examples)
 If you are looking for a complete IoT platform with firmware and cloud compotent,
 - [Check out Smart.js - a full stack IoT platform](https://github.com/cesanta/smart.js)
 # Support
 - [Support Forum - Ask your technical questions here] (http://forum.cesanta.com/index.php?p=/categories/smart-js)
 - [Chat - Visit www.cesanta.com for our live chat] (http://www.cesanta.com)
 - [Commercial one-to-one support - Available to all commercial license holders] (https://www.cesanta.com/services-support)
 # Features
- Works on Windows, Mac, UNIX/Linux, iPhone, Android eCos, QNX
+* Cross-platform: works on Linux/UNIX, MacOS, QNX, eCos, Windows, Android,
-and many other platforms
+  iPhone, FreeRTOS (TI CC3200, ESP8266), etc
- CGI, SSI, SSL, Digest auth, Websocket, WEbDAV, Resumed download,
+* Single-threaded, asynchronous, non-blocking core with simple event-based API
-  URL rewrite, file blacklist
+* Native support for [PicoTCP embedded TCP/IP stack](http://www.picotcp.com),
- Custom error pages, Virtual hosts, IP-based ACL, Windows service,
+  [LWIP embedded TCP/IP stack](https://en.wikipedia.org/wiki/LwIP)
-  HTTP/HTTPS client
+* Builtin protocols:
- Simple and clean
+   - plain TCP, plain UDP, SSL/TLS (over TCP, one-way or two-way)
-  [embedding API](https://github.com/cesanta/mongoose/blob/master/mongoose.h).
+   - HTTP client, HTTP server
-  The source is in single
+   - WebSocket client, WebSocket server
-  [mongoose.c](https://github.com/cesanta/mongoose/blob/master/mongoose.c) file
+   - JSON-RPC client, JSON-RPC server
-  to make embedding easy
+   - MQTT client, MQTT broker
- Extremely lightweight, has a core of under 40kB and tiny runtime footprint
+   - CoAP client, CoAP server
- Asynchronous, non-blocking core supporting single- or multi-threaded usage
+   - DNS client, DNS server, async DNS resolver
- On the market since 2004 with over 1 million cumulative downloads
+* Tiny static and run-time footprint
- Stable, mature and tested, has several man-years invested
+* Source code is both ISO C and ISO C++ compliant
-  in continuous improvement and refinement
+* Very easy to integrate: just copy
-
+  [mongoose.c](https://raw.githubusercontent.com/cesanta/mongoose/master/mongoose.c) and
-# Screenshots
+  [mongoose.h](https://raw.githubusercontent.com/cesanta/mongoose/master/mongoose.h)
-
+  files to your build tree
 Download, double-click to start, run browser -- that's all!
 ![shot1](http://cesanta.com/images/tut_sharing/tut1.png)
 ![shot2](http://cesanta.com/images/tut_sharing/tut2.png)
 ![shot3](http://cesanta.com/images/tut_sharing/tut3.png)
 ![shot4](http://cesanta.com/images/tut_sharing/tut4.png)
 # Contributions
 People who have agreed to the
 [Cesanta CLA](http://cesanta.com/contributors_la.html)
 can make contributions. Note that the CLA isn't a copyright
 _assigment_ but rather a copyright _license_.
 You retain the copyright on your contributions.
 # Licensing
-Mongoose is released under commercial and
+Mongoose is released under commercial and [GNU GPL v.2](http://www.gnu.org/licenses/old-licenses/gpl-2.0.html) open source licenses.
 [GNU GPL v.2](http://www.gnu.org/licenses/old-licenses/gpl-2.0.html) open
 source licenses. The GPLv2 open source License does not generally permit
 incorporating this software into non-open source programs. 
 For those customers who do not wish to comply with the GPLv2 open
 source license requirements,
 [Cesanta](http://cesanta.com) offers a full,
 royalty-free commercial license and professional support
 without any of the GPL restrictions.
-# Other products by Cesanta
+Commercial Projects:
 Once your project becomes commercialised GPLv2 licensing dictates that you need to either open your source fully or purchase a commercial license. Cesanta offer full, royalty-free commercial licenses without any GPL restrictions. If your needs require a custom license, we’d be happy to work on a solution with you. [Contact us for pricing.] (https://www.cesanta.com/contact)
- [Fossa](http://github.com/cesanta/fossa) - Multi-protocol networking library
+Prototyping:
- [SSL Wrapper](https://github.com/cesanta/ssl_wrapper) - application to
+While your project is still in prototyping stage and not for sale, you can use Mongoose’s open source code without license restrictions.
-  secure network communications
+
- [Frozen](https://github.com/cesanta/frozen) - JSON parser and generator
+# Dashboard Example
- [SLRE](https://github.com/cesanta/slre) - Super Light Regular Expression
+
-  library
+Mongoose is often used to implement device dashboards and real-time
- [V7](https://github.com/cesanta/v7) - Embedded JavaScript engine
+data exchange over Websocket. Here is a dashboard example that illustrates
 the functionality:
 ![](http://www.cesanta.com/hubfs/www.cesanta.com/diagrams/dash_mongoose_diagram.png)
 [Developing a new product? Contact us today to discuss how Mongoose can help
 ](https://www.cesanta.com/contact)
 # Contributions
 People who have agreed to the [Cesanta CLA] (https://docs.cesanta.com/contributors_la.shtml) can make contributions. Note that the CLA isn't a copyright assigment but rather a copyright license. You retain the copyright on your contributions.
 [![Analytics](https://ga-beacon.appspot.com/UA-42732794-5/project-page)](https://github.com/cesanta/mongoose)
@@ -1,249 +0,0 @@
 # Mongoose API Reference
    struct mg_server *mg_create_server(void *server_param, mg_handler_t handler);
 Creates web server instance. Returns opaque instance pointer, or NULL if
 there is not enough memory. `server_param`: Could be any pointer, or NULL.
 This pointer will be passed
 to the callback functions as `struct mg_connection::server_param` field.
 A common use case is to pass `this` pointer of the C++ wrapper class
 as `user_param`, to let the callback get the pointer to the C++ object.
 Note that this function doesn't make the
 server instance to serve. Serving is done by `mg_poll_server()` function.
 Mongoose has single-threaded, event-driven, asynchronous, non-blocking core.
 When server instance is created, it contains an information about
 the configuration and the state of each connection.
 Server instance is capable on listening on only one port. After creation,
 `struct mg_server` has a list
 of active connections and configuration parameters.
 Side-effect: on UNIX, `mg_create_server()` ignores SIGPIPE signals. If custom
 processing is required SIGPIPE, signal handler must be set up after
 calling `mg_create_server()`.
 Important: Mongoose does not install `SIGCHLD` handler. If CGI is used,
 `SIGCHLD` handler must be set up to reap CGI zombie processes.
    void mg_destroy_server(struct mg_server **server);
 Deallocates web server instance, closes all pending connections, and makes
 server pointer a NULL pointer.
    const char mg_set_option(struct mg_server *server, const char *name,
                             const char *value);
 Sets a particular server option. Note that at least one option,
 `listening_port`, must be specified. To serve static files, `document_root`
 must be specified too. If `document_root` option is left unset, Mongoose
 will not access filesystem at all. `mg_set_option()` returns NULL if option was
 set successfully, otherwise it returns human-readable error string. It is
 allowed to call `mg_set_option()` by the same thread that does
 `mg_poll_server()` (Mongoose thread) and change server configuration while it
 is serving, in between `mg_poll_server()` calls.
    int mg_poll_server(struct mg_server *server, int milliseconds);
 Performs one iteration of IO loop by iterating over all
 active connections, performing `select()` syscall on all sockets with a timeout
 of `milliseconds`. When `select()` returns, Mongoose
 does an IO for each socket that has data to be sent or received. Application
 code must call `mg_poll_server()` in a loop. It is an error to have more then
 one thread calling `mg_poll_server()`, `mg_set_option()` or any other function
 that take `struct mg_server *` parameter. Mongoose does not
 mutex-protect `struct mg_server *`, therefore only single thread
 (Mongoose thread) should make Mongoose calls.
 `mg_poll_server()` calls user-specified event handler when certain events
 occur. Sequence of events for the accepted connection is this:
   * `MG_AUTH` - Mongoose asks whether this connection is authorized. If event
      handler returns `MG_FALSE`, then Mongoose does not serve the request but
      sends authorization request to the client. If `MG_TRUE` is returned,
      then Mongoose continues on with the request.
   * `MG_REQUEST` - Mongoose asks event handler to serve the request. If
      event handler serves the request by sending a reply,
      it should return `MG_TRUE`. Otherwise,
      it should return `MG_FALSE` which tells Mongoose that request is not
      served and Mongoose should serve it. For example, event handler might
      choose to serve only RESTful API requests with URIs that start with
      certain prefix, and let Mongoose serve all static files.
      If event handler decides to serve the request, but doesn't have
      all the data at the moment, it should return `MG_MORE`. That tells
      Mongoose to keep the connection open after callback returns.
      `mg_connection::connection_param` pointer is a placeholder to keep
      user-specific data. For example, handler could decide to open a DB
      connection and store DB connection handle in `connection_param`.
   * `MG_POLL` is sent to every connection on every iteration of
      `mg_poll_server()`. Event handler should return `MG_FALSE` to ignore
      this event. If event handler returns `MG_TRUE`, then Mongoose assumes
      that event handler has finished sending data, and Mongoose will
      close the connection.
   * `MG_HTTP_ERROR` sent when Mongoose is about to send HTTP error back
      to the client. Event handler can choose to send a reply itself, in which
      case event handler must return `MG_TRUE`. Otherwise, event handler must
      return `MG_FALSE`.
   * `MG_CLOSE` is sent when the connection is closed. This event is used
      to cleanup per-connection state stored in `connection_param`
      if it was allocated. Event handler return value is ignored.
 Sequence of events for the client connection is this:
   * `MG_CONNECT` sent when Mongoose has connected to the remote host.
   This event is sent to the connection initiated by `mg_connect()` call.
   Connection status is held in `mg_connection::status_code`: if zero,
   then connection was successful, otherwise connection was not established.
   User should send a request upon successful connection.
   Event handler should return `MG_TRUE` if connection was successful and
   HTTP request has been sent. Otherwise, it should send `MG_FALSE`.
   * `MG_REPLY` is sent when response has been received from the remote host.
   If event handler sends another request, then it should return `MG_TRUE`.
   Otherwise it should return `MG_FALSE` and Mongoose will close the connection.
   * `MG_CLOSE` same as for the accepted connection.
 When mongoose buffers in HTTP request and successfully parses it, it sends
 `MG_REQUEST` event for GET requests immediately. For POST requests,
 Mongoose delays the call until the whole POST request is buffered in memory.
 POST data is available to the callback as `struct mg_connection::content`,
 and POST data length is in `struct mg_connection::content_len`.
 Note that websocket connections are treated the same way. Mongoose buffers
 websocket frame in memory, and calls event handler when frame is fully
 buffered. Frame data is available `struct mg_connection::content`, and
 data length is in `struct mg_connection::content_len`, i.e. very similar to
 the POST request. `struct mg_connection::is_websocket` flag indicates
 whether the request is websocket or not. Also, for websocket requests,
 there is `struct mg_connection::wsbits` field which contains first byte
 of the websocket frame which URI handler can examine. Note that to
 reply to the websocket client, `mg_websocket_write()` should be used.
 To reply to the plain HTTP client, `mg_write_data()` should be used.
 Return value: number of active connections.
    const char **mg_get_valid_option_names(void);
 Returns a NULL-terminated array of option names and their default values.
 There are two entries per option in an array: an option name followed by a
 default value. A default value could be NULL. A NULL name indicates an end
 of the array.
    const char *mg_get_option(const struct mg_server *server, const char *name);
 Returns the value of particular configuration parameter. If
 given parameter name is not valid, NULL is returned. For valid names, return
 value is guaranteed to be non-NULL. If parameter is not set, zero-length string
 is returned.
    void mg_wakeup_server_ex(struct mg_server *, mg_handler_t func,
                             const char *fmt, ...);
 Sends string message to a server. Function `func` is called for every active
 connection. String message is passed in `struct mg_connection::callback_param`.
 This function is designed to push data to the connected clients, and
 can be called from any thread. There is a limitation on the length of
 the message, currently at 8 kilobytes.
    void mg_send_status(struct mg_connection *, int status_code);
    void mg_send_header(struct mg_connection *, const char *name,
                        const char *value);
    void mg_send_data(struct mg_connection *, const void *data, int data_len);
    void mg_printf_data(struct mg_connection *, const char *format, ...);
 These functions are used to construct a response to the client. HTTP response
 consists of three parts: a status line, zero or more HTTP headers,
 a response body.  Mongoose provides functions for all three parts:
   * `mg_send_status()` is used to create status line. This function can be
      called zero or once. If `mg_send_status()` is not called, then Mongoose
      will send status 200 (success) implicitly.
   * `mg_send_header()` adds HTTP header to the response. This function could
      be called zero or more times.
   * `mg_send_data()` and `mg_printf_data()` are used to send data to the
     client. Note that Mongoose adds `Transfer-Encoding: chunked` header
     implicitly, and sends data in chunks. Therefore, it is not necessary to
     set `Content-Length` header. Note that `mg_send_data()` and
     `mg_printf_data()` do not send data immediately. Instead, they spool
     data in memory, and Mongoose sends that data later after URI handler
     returns. If data to be sent is huge, an URI handler might
     send data in pieces by saving state in
     `struct mg_connection::connection_param` variable and returning `0`. Then
     Mongoose will call a handler repeatedly after each socket write.
 <!-- -->
     void mg_send_file(struct mg_connection *, const char *path);
 Tells Mongoose to serve given file. Mongoose handles file according to
 it's extensions, i.e. Mongoose will invoke CGI script if `path` has CGI
 extension, it'll render SSI file if `path` has SSI extension, etc. If `path`
 points to a directory, Mongoose will show directory listing. If this function
 is used, no calls to `mg_send*` or `mg_printf*` functions must be made, and
 event handler must return `MG_MORE`.
    size_t mg_websocket_write(struct mg_connection* conn, int opcode,
                              const char *data, size_t data_len);
    size_t mg_websocket_printf(struct mg_connection* conn, int opcode,
                               const char *fmt, ...);
 Similar to `mg_write()` and `mg_printf()`, but wraps the data into a
 websocket frame with a given websocket `opcode`.
    const char *mg_get_header(const struct mg_connection *, const char *name);
 Get the value of particular HTTP header. This is a helper function.
 It traverses http_headers array, and if the header is present in the array,
 returns its value. If it is not present, NULL is returned.
    int mg_get_var(const struct mg_connection *conn, const char *var_name,
                   char *buf, size_t buf_len);
 Gets HTTP form variable. Both POST buffer and query string are inspected.
 Form variable is url-decoded and written to the buffer. On success, this
 function returns the length of decoded variable. On error, -1 is returned if
 variable not found, and -2 is returned if destination buffer is too small
 to hold the variable. Destination buffer is guaranteed to be
 '\0' - terminated if it is not NULL or zero length.
    int mg_parse_header(const char *hdr, const char *var_name, char *buf,
                        size_t buf_size);
 This function parses HTTP header and fetches given variable's value in a buffer.
 A header should be like `x=123, y=345, z="other value"`. This function is
 designed to parse Cookie headers, Authorization headers, and similar. Returns
 the length of the fetched value, or 0 if variable not found.
    int mg_modify_passwords_file(const char *passwords_file_name,
                                 const char *domain,
                                 const char *user,
                                 const char *password);
 Add, edit or delete the entry in the passwords file.
 This function allows an application to manipulate .htpasswd files on the
 fly by adding, deleting and changing user records. This is one of the
 several ways of implementing authentication on the server side.
 If password is not NULL, entry is added (or modified if already exists).
 If password is NULL, entry is deleted.
 Return: 1 on success, 0 on error.
    int mg_parse_multipart(const char *buf, int buf_len,
                           char *var_name, int var_name_len,
                           char *file_name, int file_name_len,
                           const char **data, int *data_len);
 Parses a buffer that contains multipart form data. Stores chunk name
 in a `var_name` buffer. If chunk is an uploaded file, then `file_name`
 will have a file name. `data` and `data_len` will point to the chunk data.
 Returns number of bytes to skip to the next chunk.
     struct mg_connection *mg_connect(struct mg_server *server,
                                      const char *host, int port, int use_ssl);
 Create connection to the remote host. Returns `NULL` on error, non-null
 if the connection has been scheduled for connection. Upon a connection,
 Mongoose will send `MG_CONNECT` event to the event handler.
@@ -1,27 +0,0 @@
 # Mongoose Build on Android
 This is a small guide to help you run mongoose on Android. Currently it is
 tested on the HTC Wildfire. If you have managed to run it on other devices
 as well, please comment or drop an email in the mailing list.
 Note : You dont need root access to run mongoose on Android.
 - Clone Mongoose Git repo
 - Download the Android NDK from [http://developer.android.com/tools/sdk/ndk/index.html](http://developer.android.com/tools/sdk/ndk/index.html)
 - Run `/path-to-ndk/ndk-build -C /path/to/mongoose`
  That should generate mongoose/lib/armeabi/mongoose
 - Using the adb tool (you need to have Android SDK installed for that),
  push the generated mongoose binary to `/data/local` folder on device.
 - From adb shell, navigate to `/data/local` and execute `./mongoose`.
 - To test if the server is running fine, visit your web-browser and
  navigate to `http://127.0.0.1:8080` You should see the `Index of /` page.
 ![screenshot](http://cesanta.com/images/android_build.png)
 Notes:
 - `jni` stands for Java Native Interface. Read up on Android NDK if you want
  to know how to interact with the native C functions of mongoose in Android
  Java applications.
 - TODO: A Java application that interacts with the native binary or a
  shared library.
@@ -1,34 +0,0 @@
 How To Create Basic Website With Mongoose
 ===========================================
 ## 1. Create a directory which will contain your website files. For example, on drive `C:\`, create a directory called `my_website`:
 ![screenshot](http://cesanta.com/images/tut_basic/tut1.png)
 ## 2. Inside `my_website` directory, create a new file called "index". This will be the default web page shown when the website is visited.
 ![screenshot](http://cesanta.com/images/tut_basic/tut2.png)
 ## 3. Open index file with your favorite editor (for example, Notepad) and enter some HTML code:
 ![screenshot](http://cesanta.com/images/tut_basic/tut3.png)
 ## 4. Save this file as `index.html`:
 ![screenshot](http://cesanta.com/images/tut_basic/tut4.png)
 ## 5. Download Mongoose executable from http://cesanta.com/mongoose.shtml and copy the executable inside `my_website` directory:
 ![screenshot](http://cesanta.com/images/tut_basic/tut5.png)
 ## 6. Double-click mongoose executable. An icon will appear on a system tray in the bottom right corner of the desktop:
 ![screenshot](http://cesanta.com/images/tut_basic/tut6.png)
 ## 7. Click on the mongoose icon and choose "Go to my address" menu:
 ![screenshot](http://cesanta.com/images/tut_basic/tut7.png)
 ## 8. A browser will popup displaying `index.html` file. Now, you can expand your website by adding more content.
 ![screenshot](http://cesanta.com/images/tut_basic/tut8.png)
@@ -1,173 +0,0 @@
 # Mongoose Embedding Guide
 Embedding Mongoose is done in two steps:
   1. Copy
    [mongoose.c](https://raw.github.com/cesanta/mongoose/master/mongoose.c) and
    [mongoose.h](https://raw.github.com/cesanta/mongoose/master/mongoose.h)
    to your application's source tree and include them in the build.
   2. Somewhere in the application code, call `mg_create_server()` to create
    a server, configure it with `mg_set_option()` and loop with
    `mg_poll_server()` until done. Call `mg_destroy_server()` to cleanup.
 Here's a minimal application `app.c` that embeds mongoose:
    #include "mongoose.h"
    int main(void) {
      struct mg_server *server = mg_create_server(NULL, NULL);
      mg_set_option(server, "document_root", ".");      // Serve current directory
      mg_set_option(server, "listening_port", "8080");  // Open port 8080
      for (;;) {
        mg_poll_server(server, 1000);   // Infinite loop, Ctrl-C to stop
      }
      mg_destroy_server(&server);
      return 0;
    }
 To compile it, put `mongoose.c`, `mongoose.h` and `app.c` into one
 folder, start terminal on UNIX or Visual Studio command line prompt on Windows,
 and run the following command:
    cc app.c mongoose.c -pthread -o app     # on Unix
    cl.exe app.c mongoose.c /TC /MD         # on Windows
 When run, this simple application opens port 8080 and serves static files,
 CGI files and lists directory content in the current working directory.
 It is possible to generate HTML page content. Mongoose can call user-defined
 function when certain events occur.
 That function is called _an event handler_, and it is the second parameter
 to `mg_create_server()` function. Here is the example event handler function:
    int event_handler(struct mg_connection *conn, enum mg_event ev) {
      switch (ev) {
        case MG_AUTH: return MG_TRUE;
        default: return MG_FALSE;
      }
    }
 Event handler is called by Mongoose with `struct mg_connection *`
 pointer and an event number. `struct mg_connection *conn`
 has all information about the request: HTTP headers, POST or websocket
 data buffer, etcetera. `enum mg_event ev` tells which exactly event is sent.
 For each event, an event handler returns a value which tells Mongoose how
 to behave.
 The sequence of events for every connection is this:
   * `MG_AUTH` - Mongoose asks whether this connection is authorized. If event
      handler returns `MG_FALSE`, then Mongoose does not serve the request but
      sends authorization request to the client. If `MG_TRUE` is returned,
      then Mongoose continues on with the request.
   * `MG_REQUEST` - Mongoose asks event handler to serve the request. If
      event handler serves the request by sending a reply,
      it should return `MG_TRUE`. Otherwise,
      it should return `MG_FALSE` which tells Mongoose that request is not
      served and Mongoose should serve it. For example, event handler might
      choose to serve only RESTful API requests with URIs that start with
      certain prefix, and let Mongoose serve all static files.
      If event handler decides to serve the request, but doesn't have
      all the data at the moment, it should return `MG_MORE`. That tells
      Mongoose to keep the connection open after callback returns.
      `mg_connection::connection_param` pointer is a placeholder to keep
      user-specific data. For example, handler could decide to open a DB
      connection and store DB connection handle in `connection_param`.
   * `MG_POLL` is sent to every connection on every iteration of
      `mg_poll_server()`. Event handler should return `MG_FALSE` to ignore
      this event. If event handler returns `MG_TRUE`, then Mongoose assumes
      that event handler has finished sending data, and Mongoose will
      close the connection.
   * `MG_HTTP_ERROR` sent when Mongoose is about to send HTTP error back
      to the client. Event handler can choose to send a reply itself, in which
      case event handler must return `MG_TRUE`. Otherwise, event handler must
      return `MG_FALSE`
   * `MG_CLOSE` is sent when the connection is closed. This event is used
      to cleanup per-connection state stored in `connection_param`
      if it was allocated.
 Let's extend our minimal application example and
 create an URI that will be served by user's C code. The app will handle
 `/hello` URI by showing a hello message. So, when app is run,
 http://127.0.0.1:8080/hello will say hello, and here's the code:
    #include <string.h>
    #include "mongoose.h"
    static int event_handler(struct mg_connection *conn, enum mg_event ev) {
      if (ev == MG_AUTH) {
        return MG_TRUE;   // Authorize all requests
      } else if (ev == MG_REQUEST && !strcmp(conn->uri, "/hello")) {
        mg_printf_data(conn, "%s", "Hello world");
        return MG_TRUE;   // Mark as processed
      } else {
        return MG_FALSE;  // Rest of the events are not processed
      }
    }
    int main(void) {
      struct mg_server *server = mg_create_server(NULL, event_handler);
      mg_set_option(server, "document_root", ".");
      mg_set_option(server, "listening_port", "8080");
      for (;;) {
        mg_poll_server(server, 1000);  // Infinite loop, Ctrl-C to stop
      }
      mg_destroy_server(&server);
      return 0;
    }
 ## Example code
 Mongoose source code contains number of examples, located in the
 [examples](https://github.com/cesanta/mongoose/blob/master/examples/) directory.
 To build any example, go to the respective directory and run `make`.
 ## Compilation flags
 Below is the list of compilation flags that enable or disable certain
 features. By default, some features are enabled, and could be disabled
 by setting appropriate `NO_*` flag. Features that are disabled by default
 could be enabled by setting appropriate `USE_*` flag. Bare bones Mongoose
 is quite small, about 30 kilobytes of compiled x86 code. Each feature adds
 a couple of kilobytes to the executable size, and also has some runtime penalty.
 Note that some flags start with `NS_` prefix. This is because Mongoose uses
 [Net Skeleton](http://github.com/cesanta/net_skeleton) as a low-level
 networking engine. If user code has `#include <net_skeleton.h>`, then
 all Net Skeleton functions will be available too.
    -DMONGOOSE_NO_AUTH          Disable MD5 authorization support
    -DMONGOOSE_NO_CGI           Disable CGI support
    -DMONGOOSE_NO_DAV           Disable WebDAV support
                                (PUT, DELETE, MKCOL, PROPFIND methods)
    -DMONGOOSE_NO_DIRECTORY_LISTING  Disable directory listing
    -DMONGOOSE_NO_FILESYSTEM    Disables all file IO, serving from memory only
    -DMONGOOSE_NO_LOGGING       Disable access/error logging
    -DMONGOOSE_ENABLE_THREADS   Enable mg_start_thread() function
    -DMONGOOSE_NO_WEBSOCKET     Disable WebSocket support
    -DMONGOOSE_NO_USER          No concept of a user on used platform.
                                (Platform does not provide getpwnam, setgid or setuid)
    -DMONGOOSE_USE_IDLE_TIMEOUT_SECONDS=X Idle connection timeout, default is 30
    -DMONGOOSE_USE_LUA          Enable Lua scripting
    -DMONGOOSE_USE_LUA_SQLITE3  Enable sqlite3 binding for Lua
    -DMONGOOSE_USE_POST_SIZE_LIMIT=X      POST requests larger than X will be
                                          rejected, not set by default
    -DMONGOOSE_USE_EXTRA_HTTP_HEADERS=X   Append X to the HTTP headers
                                          for static files, empty by default
    -DNS_ENABLE_DEBUG         Enables debug messages on stdout, very noisy
    -DNS_ENABLE_SSL           Enable SSL
    -DNS_ENABLE_IPV6          Enable IPv6 support
    -DNS_ENABLE_HEXDUMP       Enables hexdump of sent and received traffic
    -DNS_STACK_SIZE=X         Sets stack size to X for  ns_start_thread()
    -DNS_DISABLE_THREADS      Disable threads support
    -DNS_DISABLE_SOCKETPAIR   For systems without loopback interface
    -DMONGOOSE_SEND_NS_EVENTS Send Net Skeleton events to the event handler
                              in addition to the Mongoose events
@@ -1,45 +0,0 @@
 # Mongoose FAQ
 ## My Antivirus Software reports Mongoose as a security threat
 Mongoose doesn't contain any malicious logic. Antivirus reports a
 [false positive](http://en.wikipedia.org/wiki/Type_I_and_type_II_errors#False_positive_error).
 This is when certain byte sequence in Mongoose accidentally matches
 virus signature in the Antivirus database.
 ## Download page doesn't work
 Please make sure Javascript is enabled in your browser, and that the
 antivirus software is not blocking the download.
 ## MacOS message: "Mongoose.app is damaged and can’t be opened. You should move it to the Trash"
 This happens on newer MacOS systems. The reason for the message
 is the fact Mongoose.app is not digitally signed.
 Mongoose download procedure changes the app on the fly by injecting
 user information in the binary, making any prior digital signature void.
 Open "System Preferences" -> "Security"  and set "Allow apps downloaded from"
 to "Anywhere".  Revert the settings once Mongoose is installed.
 ## PHP doesn't work: getting empty page, or 'File not found' error
 The reason for that is wrong paths to the interpreter. Remember that with PHP,
 correct interpreter is `php-cgi.exe` (`php-cgi` on UNIX). Solution: specify
 full path to the PHP interpreter, e.g.:
    mongoose -cgi_interpreter /full/path/to/php-cgi
 ## Mongoose fails to start
 If Mongoose exits immediately when run, this
 usually indicates a syntax error in the configuration file
 (named `mongoose.conf` by default) or the command-line arguments.
 Syntax checking is omitted from Mongoose to keep its size low. However,
 the Manual should be of help. Note: the syntax changes from time to time,
 so updating the config file might be necessary after executable update.
 ### Embedding with OpenSSL on Windows might fail because of calling convention
 To force Mongoose to use `__stdcall` convention, add `/Gz` compilation
 flag to the Visual Studio project settings.
@@ -1,18 +0,0 @@
 How To Share Files With Mongoose
 ===========================================
 ## 1. Download Mongoose executable from http://cesanta.com/mongoose.shtml and copy the executable inside the directory you want to share:
 ![screenshot](http://cesanta.com/images/tut_sharing/tut1.png)
 ## 2. Double-click mongoose executable. A browser will start automatically, an icon will appear on a system tray in the bottom right corner of the desktop:
 ![screenshot](http://cesanta.com/images/tut_sharing/tut2.png)
 ## 3. Click on the mongoose icon
 ![screenshot](http://cesanta.com/images/tut_sharing/tut3.png)
 ## 4. Click on "Go to my address" to launch a browser locally. Or, to access a folder from another machine, launch a browser and type in the URL:
 ![screenshot](http://cesanta.com/images/tut_sharing/tut4.png)
@@ -1,44 +0,0 @@
 # Mongoose Internals
 Mongoose has single-threaded, event-driven, asynchronous, non-blocking core.
 `mg_create_server()` creates a web server instance. An instance is a container
 for the config options and list of active connections. To do the actual
 serving, user must call `mg_poll_server()`, which iterates over all
 active connections, performing `select()` syscall on all sockets with a
 timeout of specified number of milliseconds. When `select()` returns, Mongoose
 does an IO for each socket that has data to be sent or received. Application
 code must call `mg_poll_server()` in a loop.
 Mongoose server instance is designed to be used by a single thread.
 It is an error to have more then
 one thread calling `mg_poll_server()`, `mg_set_option()` or any other function
 that take `struct mg_server *` parameter. Mongoose does not
 mutex-protect `struct mg_server *`, therefore the best practice is
 to call server management functions from the same thread (an IO thread).
 On a multi-core systems, many server instances can be created, sharing the
 same listening socket and managed by separate threads (see [multi_threaded.c](https://github.com/cesanta/mongoose/blob/master/examples/multi_threaded.c))
 example.
 It is an error to pass and store `struct mg_connection *` pointers for
 later use to send data. The reason is that they can be invalidated by the
 next `mg_poll_server()` call. For such a task,
 there is `mg_iterate_over_connections()` API
 exists, which sends a callback function to the IO thread, then IO thread
 calls specified function for all active connection.
 When mongoose buffers in HTTP request and successfully parses it, it calls
 appropriate URI handler immediately for GET requests. For POST requests,
 Mongoose delays the call until the whole POST request is buffered in memory.
 POST data is available to the callback as `struct mg_connection::content`,
 and POST data length is in `struct mg_connection::content_len`.
 Note that websocket connections are treated the same way. Mongoose buffers
 websocket frame in memory, and calls URI handler when frame is fully
 buffered. Frame data is available `struct mg_connection::content`, and
 data length is in `struct mg_connection::content_len`, i.e. very similar to
 the POST request. `struct mg_connection::is_websocket` flag indicates
 whether the request is websocket or not. Also, for websocket requests,
 there is `struct mg_connection::wsbits` field which contains first byte
 of the websocket frame which URI handler can examine. Note that to
 reply to the websocket client, `mg_websocket_write()` should be used.
 To reply to the plain HTTP client, `mg_write()` should be used.
@@ -1,154 +0,0 @@
 # Mongoose Configuration Options
 ### access\_control\_list
 An Access Control List (ACL) allows restrictions to be put on the list of IP
 addresses which have access to the web server. In the case of the Mongoose
 web server, the ACL is a comma separated list of IP subnets, where each
 subnet is prepended by either a `-` or a `+` sign. A plus sign means allow,
 where a minus sign means deny. If a subnet mask is omitted, such as `-1.2.3.4`,
 this means to deny only that single IP address.
 Subnet masks may vary from 0 to 32, inclusive. The default setting is to allow
 all accesses. On each request the full list is traversed, and
 the last match wins. Example: `$ mongoose -access_control_list -0.0.0.0/0,+192.168/16` to deny all acccesses except those from `192.168/16` subnet. Note that if the option is set, then all accesses are forbidden
 by default. Thus in a previous example, `-0.0.0.0` part is not necessary.
 For example, `$mongoose access_control_list +10.0.0.0/8`
 means disallow all, allow subnet 10/8 only.
 To learn more about subnet masks, see the
 [Wikipedia page on Subnetwork](http://en.wikipedia.org/wiki/Subnetwork)
 Default: not set, all accesses are allowed.
 ### access\_log\_file
 Path to a file for access logs. Either full path, or relative to the
 mongoose executable. Default: not set, no query logging is done.
 ### auth_domain
 Authorization realm used in `.htpasswd` authorization. Default: `mydomain.com`
 ### cgi_interpreter
 Path to an executable to be used use as an interpreter for __all__ CGI scripts
 regardless script extension.  Default: not set, Mongoose looks at
 [shebang line](http://en.wikipedia.org/wiki/Shebang_(Unix\).
 For example, if both PHP and perl CGIs are used, then
 `#!/path/to/php-cgi.exe` and `#!/path/to/perl.exe` must be first lines of the
 respective CGI scripts. Note that paths should be either full file paths,
 or file paths relative to the directory where mongoose executable is located.
 If all CGIs use the same interpreter, for example they are all PHP, then
 `cgi_interpreter` option can be set to the path to `php-cgi.exe` executable and
 shebang line in the CGI scripts can be omitted.
 **Note**: PHP scripts must use `php-cgi.exe`, not `php.exe`.
 ### cgi_pattern
 All files that match `cgi_pattern` are treated as CGI files. Default pattern
 allows CGI files be anywhere. To restrict CGIs to a certain directory,
 use `/path/to/cgi-bin/**.cgi` as a pattern. Note that **full file path** is
 matched against the pattern, not the URI.
 When Mongoose starts CGI program, it creates new environment for it (in
 contrast, usually child program inherits the environment from parent). Several
 environment variables however are inherited from Mongoose's environment,
 they are: `PATH`, `TMP`, `TEMP`, `TMPDIR`, `PERLLIB`, `MONGOOSE_CGI`. On UNIX
 it is also `LD_LIBRARY_PATH`. On Windows it is also `COMSPEC`, `SYSTEMROOT`,
 `SystemDrive`, `ProgramFiles`, `ProgramFiles(x86)`, `CommonProgramFiles(x86)`.
 Default: `**.cgi$|**.pl$|**.php$`
 ### dav\_auth\_file
 Authentication file for WebDAV mutation requests: `PUT`, `DELETE`, `MKCOL`.
 The format of that file is the same as for the `.htpasswd` file
 used for digest authentication. It can be created and managed by
 `mongoose -A` command. Default: not set, WebDAV mutations are disallowed.
 ### document_root
 A directory to serve. Default: current working directory.
 ### enable\_directory\_listing
 Enable directory listing, either `yes` or `no`. Default: `yes`.
 ### enable\_proxy
 Enable proxy functionality, either `yes` or `no`. If set to `yes`, then
 browsers can be configured to use Mongoose as a proxy. Default: `no`.
 ### extra\_mime\_types
 Extra mime types to recognize, in form `extension1=type1,extension2=type2,...`.
 Extension must include dot.  Example:
 `mongoose -extra_mime_types .cpp=plain/text,.java=plain/text`. Default: not set.
 ### global\_auth\_file
 Path to a global passwords file, either full path or relative to the mongoose
 executable. If set, per-directory `.htpasswd` files are ignored,
 and all requests are authorised against that file. Use `mongoose -A` to
 manage passwords, or third party utilities like
 [htpasswd-generator](http://www.askapache.com/online-tools/htpasswd-generator).
 Default: not set, per-directory `.htpasswd` files are respected.
 ### hide\_files\_patterns
 A pattern for the files to hide. Files that match the pattern will not
 show up in directory listing and return `404 Not Found` if requested. Pattern
 must be for a file name only, not including directory name, e.g.
 `mongoose -hide_files_patterns secret.txt|even_more_secret.txt`. Default:
 not set.
 ### index_files
 Comma-separated list of files to be treated as directory index
 files. Default: `index.html,index.htm,index.cgi,index.shtml,index.php`
 ### listening_port
 Port to listen on. Port could be prepended by the specific IP address to bind
 to, e.g. `mongoose -listening_port 127.0.0.1:8080`. Otherwise Mongoose
 will bind to all addresses. To enable SSL, build Mongoose with
 `-DNS_ENABLE_SSL` compilation option, and specify `listening_port` as
 `ssl://PORT:SSL_CERTIFICATE.PEM`. Example SSL listener:
 `mongoose -listening_port ssl://8043:ssl_cert.pem`. Note that PEM file should
 be in PEM format, and must have both certificate and private key in it,
 concatenated together. More than one listening port can be specified,
 separated by comma,
 for example `mongoose -listening_port 8080,8000`. Default: 8080.
 ### run\_as\_user
 Switch to given user credentials after startup. UNIX-only. This option is
 required when mongoose needs to bind on privileged port on UNIX, e.g.
    $ sudo mongoose -listening_port 80 -run_as_user nobody
 Default: not set.
 ### url\_rewrites
 Comma-separated list of URL rewrites in the form of
 `uri_pattern=file_or_directory_path`. When Mongoose receives the request,
 it constructs the file name to show by combining `document_root` and the URI.
 However, if the rewrite option is used and `uri_pattern` matches the
 requested URI, then `document_root` is ignored. Instead,
 `file_or_directory_path` is used, which should be a full path name or
 a path relative to the web server's current working directory. Note that
 `uri_pattern`, as all mongoose patterns, is a prefix pattern. If `uri_pattern`
 is a number, then it is treated as HTTP error code, and `file_or_directory_path`
 should be an URI to redirect to. Mongoose will issue `302` temporary redirect
 to the specified URI with following parameters:
 `?code=HTTP_ERROR_CODE&orig_uri=ORIGINAL_URI&query_string=QUERY_STRING`.
 If `uri_pattern` starts with `@` symbol, then Mongoose compares
 it with the `HOST` header of the request. If they are equal, Mongoose sets
 document root to `file_or_directory_path`, implementing virtual hosts support.
 Examples:
    # Redirect all accesses to `.doc` files to a special script
    mongoose -url_rewrites **.doc$=/path/to/cgi-bin/handle_doc.cgi
    # Implement user home directories support
    mongoose -url_rewrites /~joe/=/home/joe/,/~bill=/home/bill/
    # Redirect 404 errors to a specific error page
    mongoose -url_rewrites 404=/cgi-bin/error.cgi
    # Virtual hosts example: serve foo.com domain from different directory
    mongoose -url_rewrites @foo.com=/var/www/foo.com
 Default: not set.
@@ -1,49 +0,0 @@
 How To Create A PHP Website With Mongoose
 ===========================================
 ## 1. Create a directory which will contain your website files. For example, on drive `C:\`, create a directory called `my_website`:
 ![screenshot](http://cesanta.com/images/tut_php/tut1.png)
 ## 2. Inside `my_website` directory, create a new file called "index". This will be the default web page shown when the website is visited.
 ![screenshot](http://cesanta.com/images/tut_php/tut2.png)
 ## 3. Open index file with your favorite editor (for example, Notepad) and enter some HTML / PHP code:
 ![screenshot](http://cesanta.com/images/tut_php/tut3.png)
 ## 4. Save this file as `index.php`:
 ![screenshot](http://cesanta.com/images/tut_php/tut4.png)
 ## 5. Download Mongoose executable from http://cesanta.com/mongoose.shtml and copy the executable inside `my_website` directory:
 ![screenshot](http://cesanta.com/images/tut_php/tut5.png)
 ## 6. Double-click mongoose executable. An icon will appear on a system tray in the bottom right corner of the desktop:
 ![screenshot](http://cesanta.com/images/tut_php/tut6.png)
 ## 7. Download PHP 5.3 zip (do NOT download PHP 5.5 cause you might have missing DLLs problem) from http://windows.php.net/download and extract it to `C:\php5` directory:
 ![screenshot](http://cesanta.com/images/tut_php/tut7.png)
 ## 8. Click on the mongoose icon and choose "Edit Settings" menu.:
 ![screenshot](http://cesanta.com/images/tut_php/tut8.png)
 ## 9. A settings dialog will appear. Click on `cgi_interpreter` button:
 ![screenshot](http://cesanta.com/images/tut_php/tut9.png)
 ## 10. Choose `C:\php5\php-cgi.exe` and click "Save Settings":
 ![screenshot](http://cesanta.com/images/tut_php/tut10.png)
 ## 11. Click on the mongoose icon and choose "Go to my address" menu:
 ![screenshot](http://cesanta.com/images/tut_php/tut11.png)
 ## 12. A browser will popup displaying `index.php`.
 ![screenshot](http://cesanta.com/images/tut_php/tut12.png)
@@ -1,218 +0,0 @@
 # Mongoose Release Notes
 ## Release 5.6, 2015-03-17
 Changes in Libmongoose library:
 - Added `-dav_root` configuration option that gives an ability to mount
  a different root directory (not document_root)
 - Fixes for build under Win23 and MinGW
 - Bugfix: Double dots removal
 - Bugfix: final chunked response double-send
 - Fixed compilation in 64-bit environments
 - Added OS/2 compatibility
 - Added `getaddrinfo()` call and `NS_ENABLE_GETADDRINFO`
 - Various SSL-related fixes
 - Added integer overflow protection in `iobuf_append()` and `deliver_websocket_frame()`
 - Fixed NetBSD build
 - Enabled `NS_ENABLE_IPV6` build for Visual Studio 2008+
 - Enhanced comma detection in `parse_header()`
 - Fixed unchanged memory accesses on ARM
 - Added ability to use custom memory allocator through NS_MALLOC, NS_FREE, NS_REALLOC
 Changes in Mongoose binary:
 - Added `-start_browser` option to disable automatic browser launch
 - Added experimental SSL support. To listen on HTTPS port, use `ssl://PORT:SSL_CERT` format. For example, to listen on HTTP port 8080 and HTTPS port 8043, use `-listening_port 8080,ssl://8043:ssl_cert.pem`
 ## Release 5.5, October 28 2014
 Changes in Libmongoose library:
 - Added new API function: `mg_forward()` for proxying functionality
 - Added new API function: `mg_send_file_data()` for sending file data
 - Added new utility API functions: `mg_mmap() and mg_munmap()`
 - Changed the way SSL settings are handled: removed `ssl_certificate` and
  `ssl_ca_certificate` options, and instead made `listening_port` accept
  `ssl://PORT:SSL_CERT:CA_CERT` notation
 - Added ability to listen on multiple ports, see `listening_port` documentation
 - Added `enable_proxy` option
 - Added [cookie_authentication](https://github.com/cesanta/mongoose/tree/master/examples/cookie_authentication) example
 - Added [websocket\_ssl\_proxy](https://github.com/cesanta/mongoose/tree/master/examples/websocket_ssl_proxy) example
 - Added [http_client](https://github.com/cesanta/mongoose/tree/master/examples/http_client) example
 - Increased default 'idle connection' timeout from 30 to 300 seconds
 - Fixed MinGW build
 - Refactored all examples, put each in it's own directory with dedicated build
 - Many smaller bugfixed, including SSL, CGI, API, proxy, etc
 Changes in pre-compiled binaries:
 - Support for multiple listening ports
 - Fixed CGI handling for scripts that specify interpreter in the hashbang line
 ## Release 5.4, July 28 2014
 Changes in Libmongoose library:
 - Added `hexdump_file` option for low-level request/reply debugging
 - Added `mg_template()` API function for generating HTML pages from
    templates with expansions
 - Fixed `struct mg_connection::local_ip` handling, `mg_set_option()`
    behavior with NULL values
 - Added `mg_send_file()` call to send arbitrary file to the client
 - Added `mg_terminate_ssl()` for SSL termination functionality
 - Added HTTP proxy support, `enable_proxy` config option
 - Added `mg_next()` for iterating over existing active connections
 - Added client-side SSL auth, `ssl_ca_certificate` option
 - Added `mg_wakeup_server_ex()` for pushing messages to existing connections
 - Added `MG_WS_HANDSHAKE` and `MG_WS_CONNECT` events that are sent on
     Websocket handshake is connection establishment, respectively
 - Removed server-side Lua support
 - Filesystem access, reading from socket/SSL performance improvements
 - DAV PROPFIND memory leak fixed
 - Added `big_upload.c` and enhanced `upload.c` example
 - Added `proxy.c` example that demonstrates proxy functionality and SSE pushes
 - Added `websocket2.c` example that shows simple web chat implementation
    over websockets
 - Various minor fixes
 Changes in pre-compiled binaries:
 - Created HTML administration console
 - When server is started, browser is started automatically
 - Fixed directory listing bug when directory contains `#` character
 - Removed built-in Lua Server Pages in the binary, and instead
  added Mongoose + Lua developer bundle which has Lua Server Pages support.
  That also solves external Lua modules loading problem.
 ## Release 5.3, March 10 2014
 Changes in Libmongoose library:
   * Moved to the evented API. Updated API documentation is at
       http://cesanta.com/docs/Embed.shtml
       http://cesanta.com/docs/API.shtml
   *  Added `MG_LUA` event for exporting custom variables to the Lua environment
   *  Added virtual hosts capability, see `url_rewrites` option description at
       http://cesanta.com/docs/Options.shtml
   *  Added mjpg serving example
   *  Cleaned up and documented HTTP client API, with unit tests
   *  Added `mg_wakeup_server()` to awaken `mg_poll_server()`
      from another thread
   *  Moved Mongoose IO core to [https://github.com/cesanta/net_skeleton](Net Skeleton)
   *  Added connection hexdump functionality for developers
   *  Bug fixes
 Changes in pre-compiled binaries:
   *  New awesome Mongoose logos by our designer Katrin - thanks Katrin!
        Check them out at http://cesanta.com/products.shtml
   *  Added Lua Server Pages support to the free version, quick intro is at
        http://cesanta.com/docs/Lua.shtml
   *  Added quick "Set shared directory" menu item to set `document_root`
   *  Added SSI support to the Pro version
   *  Removed SSL support from the Pro version
 ## Release 5.2, Feb 1 2014
   *  Windows binary made fully UNICODE aware. In previous versions,
      the presence of non-ASCII chars in document root, CGI script name,
      or directory name might have broken Mongoose as stand-alone
      or as Windows service. Now Mongoose works with non-ASCII paths properly.
      Internally, Mongoose uses UTF8 encoding. When making WinAPI calls,
      mongoose converts UTF8 strings to wide chars and calls UNICODE API.
   *  Enhanced authorization API by providing `mg_set_auth_handler()` and
      `mg_authorize_digest()`
   *  Removed `mg_add_uri_handler()`, added `mg_set_request_handler()`.
      There is only oneURI handler that handles all requests, just like in 4.x.
      The reason for this change is to provide an ability to catch all URIs,
      and at the same time signal Mongoose to continue handling specific URIs.
  *  Added `mg_parse_multipart()` API for file uploads.
      Note that the restriction on uploading huge files still exists,
      and will be eliminated in the next release.
  *  Allowing mongoose to bind to port 0, in which case it'll bind to any
      random unused port.
  *  Moved `idle_timeout_ms` run-time option to compile-time flag
  *  Added asynchronous HTTP client, not documented yet. Documentation and
      examples are coming in the next couple of weeks. Async Websocket client
      is scheduled for the next release. See usage examples at `unit_test.c`
  *  Windows and MacOS pre-built binaries are now split to free and paid ones,
    paid binaries include CGI, SSL, Lua, Sqlite, support and updates.
    Linux pre-built binary includes all functionality and is free, and will
    continue to be free.  Source code for Windows and MacOS GUI is closed.
    Disclaimer: source code for the command line stand-alone server,
    as well as Mongoose library itself, will never be closed.
  *  Multiple bug fixes and minor enhancements
 ## Release 5.1, Jan 10 2014
   *  CGI-related bugs where fixed, primarily for Windows platform
   *  Bugs on Windows related to UNICODE support were fixed
   *  Added a feature to support "error pages" through redirect.
      Done using `-url_redirects` option, details are on
      http://cesanta.com/docs/Options.shtml
 ## Release 5.0, Jan 6 2014
   *  Internal core has been changed from blocking, thread-per-connection to
      non-blocking, asynchronous, one thread for all.
   *  API modification for server creation and response creation. That allowed
     keep-alive support for dynamic requests, boosting the embedded performance
     to 100+ thousands requests per second on a single core
     (as measured on my development MacBook laptop)
   * Unified handling of POST requests and Websocket requests by putting a
    payload into `conn->content`, `conn->content_len` attributes.
    That simplified user code and eliminated the need of `mg_read()`,
    since mongoose buffers all data prior to calling the callback
   * keep-alive support is the default
   * Dropped SSI support and throttling support
   *  Several configuraition parameters are gone:
    *  `cgi_environment` (replaced with MONGOOSE_CGI),
    *  `protect_uri` (not useful)
    *  `ssi_pattern` (SSI support is gone)
    *  `throttle` (throttling support is gone)
    *  `error_log_file` (not used)
    *   `enable_keep_alive` (enabled by default)
    *   `listening_ports` (renamed to listening_port)
    *   `num_threads` (core has changed to single thread)
    *   `put_delete_auth_file` (renamed to dav_auth_file)
    *   `authentication_domain` (renamed to auth_domain)
   * Due to the async, non-blocking nature of the core, few restrictions
      are now in place:
    * user callbacks must not block
    * POST and Websocket data are now buffered, and cannot be huge
   * mongoose is now capable on listening on only one port
 ## Release 4.1, Oct 2013
 ## Release 4.0, Oct 2013
 ## Release 3.8, Sep 2013
 ## Release 3.7, Feb 2 2013
  *  Added "redirect to SSL port" functionality, e.g. if you specify
      `-listening_ports 8080r,8043s`
      then all requests to HTTP port 8080 will be redirected to HTTPS port 8043
  *  Added `mg_download()` API, an HTTP client interface!
  *  Lua server pages now must output HTTP headers -- full control for Lua
  *  Added pre-built binary for MacOS, with initial GUI support
  *  API change: got rid of events, moved to struct `mg_callbacks`
  *  Bugfixes, thanks to contributors
 ## Release 3.7, Jan 18 2013
  *  Fixed source code archive (main.c was missing)
  *  Extended Windows GUI functionality:
   * Added "Start browser" systray popup menu item
   *  Enhanced configuration editor
  *  Renamed config options:
   * `put_delete_passwords_file` -> `put_delete_auth_file`
   * `global_passwords_file` -> `global_auth_file`
  *  `select()` changed to `poll()`, to avoid big file descriptor
  `FD_SET` problem on UNIX
  *  Couple of bugfixes, thanks to contributors
 Eearlier release notes could be found by searching
 [Mongoose mailing list](https://groups.google.com/forum/#!forum/mongoose-users)
@@ -1,70 +0,0 @@
 # Mongoose SSL guide
 SSL is a protocol that makes web communication secure. To enable SSL
 in mongoose, 2 steps are required:
   1. Create valid SSL certificate file
   2. Append SSL certificate file path to the `listening_ports` option
 Below is the `mongoose.conf` file snippet for typical SSL setup:
    document_root     www_root         # Serve files in www_root directory
    listening_ports   80,443:cert.pem  # Listen on ports 80 and 443
 ## How to create SSL certificate file
 SSL certificate file is a text file that must contain at least two
 sections:
   1. A private key
   2. A certificate
 Both sections should be chunks of text in PEM format. When PEM file is
 opened in a text editor, it looks like this:
    -----BEGIN RSA PRIVATE KEY-----
    MIIEogIBAAKCAQEAwONaLOP7EdegqjRuQKSDXzvHmFMZfBufjhELhNjo5KsL4ieH
    hYN0Zii2yTb63jGxKY6gH1R/r9dL8kXaJmcZrfSa3AgywnteJWg=
    -----END RSA PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIIDBjCCAe4CCQCX05m0b053QzANBgkqhkiG9w0BAQQFADBFMQswCQYDVQQGEwJB
    SEGI4JSxV56lYg==
    -----END CERTIFICATE-----
 Two aforementioned sections are clearly seen. Typically, those section
 are bigger then in the example shown. The text between the `BEGIN` and
 `END` is the text representation of binary data, a private key and a
 certificate. Therefore, in order to create a certificate file,
   * private key must be converted to PEM format
   * certificate must be converted to PEM format
   * those two should be concatenated into a single file
 If the certificate chain in used, a chain file also needs to be
 converted into PEM format and appended to the certificate file.
 ## How SSL works
 SSL is a protocol that can encrypt communication between two parties. If third
 party observes all messages passed by, it would be very
 hard for the third party (though not impossible) to decrypt the communication.
 The idea is based on so-called public key encryption. Communicating parties
 have two keys: a public key and a private key. A public key is advertised
 to everybody, and it is contained in a certificate. A private key is kept
 secret. Security algorithm works in a way that anybody can encrypt
 a message using public key, and only private key can decrypt it.
 This is why web server needs both private key and certificate: private key
 is used to decrypt incoming messages, and certificate is used to tell the
 public key to the other party. When communication starts, parties exchange
 their public keys, and keep private keys to themselves. Man-in-the-middle
 who observes the communication is unable to decrypt the messages cause
 private keys are required for decryption.
 Encryption algorithms are built on top of hard mathematical problem, which
 makes it very expensive for man-in-the-middle to compute private keys.
 For example, RSA algorithm is based on a mathematical problem of factorization.
 It is easy to generate two very large prime numbers `P` and `Q` and make
 a product `P * Q`. But given a product, it is very hard to recover these
 two prime numbers - this is called factorization.
@@ -1,86 +0,0 @@
 # Mongoose User Guide
 Mongoose is small and easy to use web server built on top of
 mongoose library. It is designed with maximum simplicity in mind. For example,
 to share any directory, just drop mongoose executable in that directory,
 double-click it (on UNIX, run it from shell) and launch a browser at
 [http://localhost:8080](http://localhost:8080) Note that 'localhost' should
 be changed to a machine's name if a folder is accessed from other computer.
 On Windows and Mac, Mongoose iconifies itself to the system tray when started.
 Right-click on the icon to pop up a menu, where it is possible to stop
 mongoose, or configure it.
 On UNIX, `mongoose` is a command line utility. Running `mongoose` in
 terminal, optionally followed by configuration parameters
 (`mongoose [OPTIONS]`) or configuration file name
 (`mongoose [config_file_name]`) starts the
 web server:
    $ mongoose -document_root /var/www  # Running mongoose with cmdline options
    $ mongoose /etc/my_config.txt       # Running mongoose with config file
    $ mongoose                          # Running with no parameters. This will
                                        # serve current directory on port 8080
 Mongoose does not detach from terminal. Pressing `Ctrl-C` keys
 stops the server.
 When started, mongoose first searches for the configuration file.
 If configuration file is specified explicitly in the command line, then
 specified configuration file is used.
 Otherwise, mongoose would search for file `mongoose.conf` in the same directory
 where binary is located, and use it. Configuration file can be absent.
 Configuration file is a sequence of lines, each line containing
 command line argument name and it's value. Empty lines and lines beginning
 with `#` are ignored. Here is the example of `mongoose.conf` file:
    # This is a comment
    document_root C:\www
    listening_port 80
    ssl_certificate C:\mongoose\ssl_cert.pem
 Command line arguments are highest priority and can override
 configuration file settings. For example, if `mongoose.conf` has line
 `document_root /var/www`, and mongoose has been started as
 `mongoose -document_root /etc`, then `/etc` directory will be used as
 document root.
 Note that configuration options on the command line must start with `-`,
 and their names are the same as in the config file. Exampli gratia,
 the following two setups are equivalent:
    $ mongoose -listening_port 1234 -document_root /var/www
    $ cat > mongoose.conf
    listening_ports 1234
    document_root /var/www
    ^D
    $ mongoose
 Mongoose can also be used to modify `.htpasswd` passwords file:
    $ mongoose -A .htpasswd mydomain.com user_name user_password
 Unlike other web servers, mongoose does not require CGI scripts be located in
 a special directory. CGI scripts can be anywhere. CGI (and SSI) files are
 recognized by the file name pattern. Mongoose uses shell-like glob
 patterns. Pattern match starts at the beginning of the string, so essentially
 patterns are prefix patterns. Syntax is as follows:
     **         Matches everything
     *          Matches everything but slash character, '/'
     ?          Matches any character
     $          Matches the end of the string
     |          Matches if pattern on the left side or the right side matches.
 All other characters in the pattern match themselves. Examples:
    # Pattern   Meaning
    **.cgi$     Any string that ends with .cgi
    /foo        Any string that begins with /foo
    **a$|**b$   Any string that ends with a or b
 To restrict CGI files only to `/cgi-bin/` directory, use this setting:
    $ mongoose -cgi_pattern /cgi-bin/*.cgi # Emulate /cgi-bin/ restriction
@@ -0,0 +1,12 @@
 ---
 title: Disabling flags
 ---
 - `MG_DISABLE_HTTP_WEBSOCKET` disable HTTP + Websocket protocol support
 - `MG_DISABLE_HTTP_DIGEST_AUTH` disable HTTP Digest (MD5) authorization support
 - `MG_DISABLE_MQTT` disable MQTT support
 - `MG_DISABLE_SHA1` disable SHA1 support (used by Websocket)
 - `MG_DISABLE_MD5` disable MD5 support (used by HTTP auth)
 - `MG_DISABLE_JSON_RPC` disable JSON-RPC support
 - `MG_DISABLE_SOCKETPAIR` disable `mg_broadcast()` API
 - `MG_DISABLE_HTTP_KEEP_ALIVE` useful for embedded systems to save resources
@@ -0,0 +1,11 @@
 ---
 title: Enabling flags
 ---
 - `MG_ENABLE_SSL` Enable OpenSSL support
 - `MG_ENABLE_IPV6` Enable IPV6 support
 - `MG_ENABLE_THREADS` enable `mg_start_thread()` API
 - `MG_ENABLE_MQTT_BROKER` enable MQTT broker
 - `MG_ENABLE_DNS_SERVER` enable DNS server
 - `MG_ENABLE_COAP` enable CoAP protocol
 - `MG_ENABLE_GETADDRINFO` enable `getaddrinfo()` in `mg_resolve2()`
@@ -0,0 +1,17 @@
 ---
 title: Build Options
 ---
 Mongoose source code ships in a single .c file that contains functionality
 for all supported protocols (modules). Modules can be disabled at compile
 time which reduces executable size. That can be done by setting preprocessor
 flags. Also, some preprocessor flags can be used to tune internal Mongoose
 parameters.
 To set a preprocessor flag during compile time, use `-D <PREPROCESSOR_FLAG>`
 compiler option. For example, to disable both MQTT and JSON-RPC,
 compile the application `my_app.c` like this (assumed UNIX system):
 ```
  $ cc my_app.c mongoose.c -D MG_DISABLE_MQTT -D MG_DISABLE_JSON_RPC
 ```
@@ -0,0 +1,9 @@
 {
  "items": [
    { "type": "markdown", "name": "intro.md" },
    { "type": "markdown", "name": "enabling-flags.md" },
    { "type": "markdown", "name": "disabling-flags.md" },
    { "type": "markdown", "name": "platform-spec.md" },
    { "type": "markdown", "name": "tunables.md" }
  ]
 }
@@ -0,0 +1,10 @@
 ---
 title: Platform specific
 ---
 Mongoose tries to detect the target platform whenever possible, but in some cases you have
 to explicitly declare some peculiarities of your target, such as:
 - `MG_LWIP`: use LWIP networking stack
 - `MG_CC3200`: enable workarounds for the TI CC3200 target.
 - `MG_ESP8266`: enable workarounds for the ESP8266 target, add `RTOS_SDK` to specify the RTOS SDK flavour.
@@ -0,0 +1,11 @@
 ---
 title: Tunables
 ---
 - `MG_MALLOC`, `MG_CALLOC`, `MG_REALLOC`, `MG_FREE` allow to use custom
  memory allocator, e.g. `-DMG_MALLOC=my_malloc`
 - `MG_USE_READ_WRITE` when set replaces calls to `recv` with `read` and `send` with `write`,
  thus enabling to add any kind of file descriptor (files, serial devices) to an event manager.
 - `MG_SSL_CRYPTO_MODERN`, `MG_SSL_CRYPTO_OLD` - choose either "Modern" or "Old" ciphers
  instead of the default "Intermediate" setting.
  See [this article](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_configurations) for details.
@@ -0,0 +1,16 @@
 ---
 title: "CoAP"
 symbol_kind: "intro"
 decl_name: "coap.h"
 ---
 CoAP message format:
 ```
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
 |Ver| T | TKL | Code | Message ID | Token (if any, TKL bytes) ...
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
 | Options (if any) ...            |1 1 1 1 1 1 1 1| Payload (if any) ...
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
 ```
@@ -0,0 +1,44 @@
 {
    "items": [
        {
            "type": "markdown",
            "name": "intro.md"
        },
        {
            "type": "markdown",
            "name": "mg_set_protocol_coap.md"
        },
        {
            "type": "markdown",
            "name": "mg_coap_add_option.md"
        },
        {
            "type": "markdown",
            "name": "mg_coap_free_options.md"
        },
        {
            "type": "markdown",
            "name": "mg_coap_send_message.md"
        },
        {
            "type": "markdown",
            "name": "mg_coap_send_ack.md"
        },
        {
            "type": "markdown",
            "name": "mg_coap_parse.md"
        },
        {
            "type": "markdown",
            "name": "mg_coap_compose.md"
        },
        {
            "type": "markdown",
            "name": "struct_mg_coap_option.md"
        },
        {
            "type": "markdown",
            "name": "struct_mg_coap_message.md"
        }
    ]
 }
@@ -0,0 +1,13 @@
 ---
 title: "mg_coap_add_option()"
 decl_name: "mg_coap_add_option"
 symbol_kind: "func"
 signature: |
  struct mg_coap_option *mg_coap_add_option(struct mg_coap_message *cm,
                                            uint32_t number, char *value,
                                            size_t len);
 ---
 Add new option to mg_coap_message structure.
 Returns pointer to the newly created option. 
@@ -0,0 +1,12 @@
 ---
 title: "mg_coap_compose()"
 decl_name: "mg_coap_compose"
 symbol_kind: "func"
 signature: |
  uint32_t mg_coap_compose(struct mg_coap_message *cm, struct mbuf *io);
 ---
 Composes CoAP message from mg_coap_message structure.
 This is a helper function.
 Return value: see `mg_coap_send_message()` 
@@ -0,0 +1,11 @@
 ---
 title: "mg_coap_free_options()"
 decl_name: "mg_coap_free_options"
 symbol_kind: "func"
 signature: |
  void mg_coap_free_options(struct mg_coap_message *cm);
 ---
 Free the memory allocated for options,
 if cm paramater doesn't contain any option does nothing. 
@@ -0,0 +1,22 @@
 ---
 title: "mg_coap_parse()"
 decl_name: "mg_coap_parse"
 symbol_kind: "func"
 signature: |
  uint32_t mg_coap_parse(struct mbuf *io, struct mg_coap_message *cm);
 ---
 Parse COAP message and fills mg_coap_message and returns cm->flags.
 This is a helper function.
 NOTE: usually CoAP work over UDP, so lack of data means format error,
 but in theory it is possible to use CoAP over TCP (according to RFC)
 The caller have to check results and treat COAP_NOT_ENOUGH_DATA according to
 underlying protocol:
 - in case of UDP COAP_NOT_ENOUGH_DATA means COAP_FORMAT_ERROR,
 - in case of TCP client can try to receive more data
 Return value: see `mg_coap_send_message()` 
@@ -0,0 +1,12 @@
 ---
 title: "mg_coap_send_ack()"
 decl_name: "mg_coap_send_ack"
 symbol_kind: "func"
 signature: |
  uint32_t mg_coap_send_ack(struct mg_connection *nc, uint16_t msg_id);
 ---
 Compose CoAP acknowledgement from `mg_coap_message`
 and send it into `nc` connection.
 Return value: see `mg_coap_send_message()` 
@@ -0,0 +1,19 @@
 ---
 title: "mg_coap_send_message()"
 decl_name: "mg_coap_send_message"
 symbol_kind: "func"
 signature: |
  uint32_t mg_coap_send_message(struct mg_connection *nc,
                                struct mg_coap_message *cm);
 ---
 Compose CoAP message from `mg_coap_message`
 and send it into `nc` connection.
 Return 0 on success. On error, it is a bitmask:
 - `#define MG_COAP_ERROR 0x10000`
 - `#define MG_COAP_FORMAT_ERROR (MG_COAP_ERROR | 0x20000)`
 - `#define MG_COAP_IGNORE (MG_COAP_ERROR | 0x40000)`
 - `#define MG_COAP_NOT_ENOUGH_DATA (MG_COAP_ERROR | 0x80000)`
 - `#define MG_COAP_NETWORK_ERROR (MG_COAP_ERROR | 0x100000)` 
@@ -0,0 +1,10 @@
 ---
 title: "mg_set_protocol_coap()"
 decl_name: "mg_set_protocol_coap"
 symbol_kind: "func"
 signature: |
  int mg_set_protocol_coap(struct mg_connection *nc);
 ---
 Set CoAP protocol handler - trigger CoAP specific events 
@@ -0,0 +1,20 @@
 ---
 title: "struct mg_coap_message"
 decl_name: "struct mg_coap_message"
 symbol_kind: "struct"
 signature: |
  struct mg_coap_message {
    uint32_t flags;
    uint8_t msg_type;
    uint8_t code_class;
    uint8_t code_detail;
    uint16_t msg_id;
    struct mg_str token;
    struct mg_coap_option *options;
    struct mg_str payload;
    struct mg_coap_option *optiomg_tail;
  };
 ---
 CoAP message. See RFC 7252 for details. 
@@ -0,0 +1,16 @@
 ---
 title: "struct mg_coap_option"
 decl_name: "struct mg_coap_option"
 symbol_kind: "struct"
 signature: |
  struct mg_coap_option {
    struct mg_coap_option *next;
    uint32_t number;
    struct mg_str value;
  };
 ---
 CoAP options.
 Use mg_coap_add_option and mg_coap_free_options
 for creation and destruction. 
@@ -0,0 +1,8 @@
 ---
 title: "DNS server"
 symbol_kind: "intro"
 decl_name: "dns-server.h"
 ---
 Disabled by default; enable with `-DMG_ENABLE_DNS_SERVER`.
@@ -0,0 +1,20 @@
 {
    "items": [
        {
            "type": "markdown",
            "name": "intro.md"
        },
        {
            "type": "markdown",
            "name": "mg_dns_create_reply.md"
        },
        {
            "type": "markdown",
            "name": "mg_dns_reply_record.md"
        },
        {
            "type": "markdown",
            "name": "mg_dns_send_reply.md"
        }
    ]
 }
@@ -0,0 +1,36 @@
 ---
 title: "mg_dns_create_reply()"
 decl_name: "mg_dns_create_reply"
 symbol_kind: "func"
 signature: |
  struct mg_dns_reply mg_dns_create_reply(struct mbuf *io,
                                          struct mg_dns_message *msg);
 ---
 Create a DNS reply.
 The reply will be based on an existing query message `msg`.
 The query body will be appended to the output buffer.
 "reply + recursion allowed" will be added to the message flags and
 message's num_answers will be set to 0.
 Answer records can be appended with `mg_dns_send_reply` or by lower
 level function defined in the DNS API.
 In order to send the reply use `mg_dns_send_reply`.
 It's possible to use a connection's send buffer as reply buffers,
 and it will work for both UDP and TCP connections.
 Example:
 ```c
 reply = mg_dns_create_reply(&nc->send_mbuf, msg);
 for (i = 0; i < msg->num_questions; i++) {
  rr = &msg->questions[i];
  if (rr->rtype == MG_DNS_A_RECORD) {
    mg_dns_reply_record(&reply, rr, 3600, &dummy_ip_addr, 4);
  }
 }
 mg_dns_send_reply(nc, &reply);
 ``` 
@@ -0,0 +1,18 @@
 ---
 title: "mg_dns_reply_record()"
 decl_name: "mg_dns_reply_record"
 symbol_kind: "func"
 signature: |
  int mg_dns_reply_record(struct mg_dns_reply *reply,
                          struct mg_dns_resource_record *question,
                          const char *name, int rtype, int ttl, const void *rdata,
                          size_t rdata_len);
 ---
 Append a DNS reply record to the IO buffer and to the DNS message.
 The message num_answers field will be incremented. It's caller's duty
 to ensure num_answers is propertly initialized.
 Returns -1 on error. 
@@ -0,0 +1,19 @@
 ---
 title: "mg_dns_send_reply()"
 decl_name: "mg_dns_send_reply"
 symbol_kind: "func"
 signature: |
  void mg_dns_send_reply(struct mg_connection *nc, struct mg_dns_reply *r);
 ---
 Send a DNS reply through a connection.
 The DNS data is stored in an IO buffer pointed by reply structure in `r`.
 This function mutates the content of that buffer in order to ensure that
 the DNS header reflects size and flags of the mssage, that might have been
 updated either with `mg_dns_reply_record` or by direct manipulation of
 `r->message`.
 Once sent, the IO buffer will be trimmed unless the reply IO buffer
 is the connection's send buffer and the connection is not in UDP mode. 
@@ -0,0 +1,8 @@
 ---
 title: "DNS"
 symbol_kind: "intro"
 decl_name: "dns.h"
 ---
@@ -0,0 +1,48 @@
 {
    "items": [
        {
            "type": "markdown",
            "name": "intro.md"
        },
        {
            "type": "markdown",
            "name": "mg_dns_parse_record_data.md"
        },
        {
            "type": "markdown",
            "name": "mg_send_dns_query.md"
        },
        {
            "type": "markdown",
            "name": "mg_dns_insert_header.md"
        },
        {
            "type": "markdown",
            "name": "mg_dns_copy_body.md"
        },
        {
            "type": "markdown",
            "name": "mg_dns_encode_record.md"
        },
        {
            "type": "markdown",
            "name": "mg_parse_dns.md"
        },
        {
            "type": "markdown",
            "name": "mg_dns_uncompress_name.md"
        },
        {
            "type": "markdown",
            "name": "mg_set_protocol_dns.md"
        },
        {
            "type": "markdown",
            "name": "struct_mg_dns_resource_record.md"
        },
        {
            "type": "markdown",
            "name": "struct_mg_dns_message.md"
        }
    ]
 }
@@ -0,0 +1,15 @@
 ---
 title: "mg_dns_copy_body()"
 decl_name: "mg_dns_copy_body"
 symbol_kind: "func"
 signature: |
  int mg_dns_copy_body(struct mbuf *io, struct mg_dns_message *msg);
 ---
 Append already encoded body from an existing message.
 This is useful when generating a DNS reply message which includes
 all question records.
 Return number of appened bytes. 
@@ -0,0 +1,25 @@
 ---
 title: "mg_dns_encode_record()"
 decl_name: "mg_dns_encode_record"
 symbol_kind: "func"
 signature: |
  int mg_dns_encode_record(struct mbuf *io, struct mg_dns_resource_record *rr,
                           const char *name, size_t nlen, const void *rdata,
                           size_t rlen);
 ---
 Encode and append a DNS resource record to an IO buffer.
 The record metadata is taken from the `rr` parameter, while the name and data
 are taken from the parameters, encoded in the appropriate format depending on
 record type, and stored in the IO buffer. The encoded values might contain
 offsets within the IO buffer. It's thus important that the IO buffer doesn't
 get trimmed while a sequence of records are encoded while preparing a DNS
 *reply.
 This function doesn't update the `name` and `rdata` pointers in the `rr`
 *struct
 because they might be invalidated as soon as the IO buffer grows again.
 Return the number of bytes appened or -1 in case of error. 
@@ -0,0 +1,13 @@
 ---
 title: "mg_dns_insert_header()"
 decl_name: "mg_dns_insert_header"
 symbol_kind: "func"
 signature: |
  int mg_dns_insert_header(struct mbuf *io, size_t pos,
                           struct mg_dns_message *msg);
 ---
 Insert a DNS header to an IO buffer.
 Return number of bytes inserted. 
@@ -0,0 +1,20 @@
 ---
 title: "mg_dns_parse_record_data()"
 decl_name: "mg_dns_parse_record_data"
 symbol_kind: "func"
 signature: |
  int mg_dns_parse_record_data(struct mg_dns_message *msg,
                               struct mg_dns_resource_record *rr, void *data,
                               size_t data_len);
 ---
 Parse the record data from a DNS resource record.
 - A:     struct in_addr *ina
 - AAAA:  struct in6_addr *ina
 - CNAME: char buffer
 Returns -1 on error.
 TODO(mkm): MX 
@@ -0,0 +1,21 @@
 ---
 title: "mg_dns_uncompress_name()"
 decl_name: "mg_dns_uncompress_name"
 symbol_kind: "func"
 signature: |
  size_t mg_dns_uncompress_name(struct mg_dns_message *msg, struct mg_str *name,
                                char *dst, int dst_len);
 ---
 Uncompress a DNS compressed name.
 The containing dns message is required because the compressed encoding
 and reference suffixes present elsewhere in the packet.
 If name is less than `dst_len` characters long, the remainder
 of `dst` is terminated with `\0' characters. Otherwise, `dst` is not
 *terminated.
 If `dst_len` is 0 `dst` can be NULL.
 Return the uncompressed name length. 
@@ -0,0 +1,10 @@
 ---
 title: "mg_parse_dns()"
 decl_name: "mg_parse_dns"
 symbol_kind: "func"
 signature: |
  int mg_parse_dns(const char *buf, int len, struct mg_dns_message *msg);
 ---
 Low-level: parses a DNS response. 
@@ -0,0 +1,11 @@
 ---
 title: "mg_send_dns_query()"
 decl_name: "mg_send_dns_query"
 symbol_kind: "func"
 signature: |
  void mg_send_dns_query(struct mg_connection *nc, const char *name,
                         int query_type);
 ---
 Send a DNS query to the remote end. 
@@ -0,0 +1,19 @@
 ---
 title: "mg_set_protocol_dns()"
 decl_name: "mg_set_protocol_dns"
 symbol_kind: "func"
 signature: |
  void mg_set_protocol_dns(struct mg_connection *nc);
 ---
 Attach built-in DNS event handler to the given listening connection.
 DNS event handler parses incoming UDP packets, treating them as DNS
 requests. If incoming packet gets successfully parsed by the DNS event
 handler, a user event handler will receive `MG_DNS_REQUEST` event, with
 `ev_data` pointing to the parsed `struct mg_dns_message`.
 See
 [captive_dns_server](https://github.com/cesanta/mongoose/tree/master/examples/captive_dns_server)
 example on how to handle DNS request and send DNS reply. 
@@ -0,0 +1,18 @@
 ---
 title: "struct mg_dns_message"
 decl_name: "struct mg_dns_message"
 symbol_kind: "struct"
 signature: |
  struct mg_dns_message {
    struct mg_str pkt; /* packet body */
    uint16_t flags;
    uint16_t transaction_id;
    int num_questions;
    int num_answers;
    struct mg_dns_resource_record questions[MG_MAX_DNS_QUESTIONS];
    struct mg_dns_resource_record answers[MG_MAX_DNS_ANSWERS];
  };
 ---
 DNS message (request and response). 
@@ -0,0 +1,17 @@
 ---
 title: "struct mg_dns_resource_record"
 decl_name: "struct mg_dns_resource_record"
 symbol_kind: "struct"
 signature: |
  struct mg_dns_resource_record {
    struct mg_str name; /* buffer with compressed name */
    int rtype;
    int rclass;
    int ttl;
    enum mg_dns_resource_record_kind kind;
    struct mg_str rdata; /* protocol data (can be a compressed name) */
  };
 ---
 DNS resource record. 
@@ -0,0 +1,8 @@
 ---
 title: "HTTP + Websocket"
 symbol_kind: "intro"
 decl_name: "http.h"
 ---
@@ -0,0 +1,128 @@
 {
    "items": [
        {
            "type": "markdown",
            "name": "intro.md"
        },
        {
            "type": "markdown",
            "name": "mg_set_protocol_http_websocket.md"
        },
        {
            "type": "markdown",
            "name": "mg_send_websocket_handshake.md"
        },
        {
            "type": "markdown",
            "name": "mg_send_websocket_handshake2.md"
        },
        {
            "type": "markdown",
            "name": "mg_connect_ws.md"
        },
        {
            "type": "markdown",
            "name": "mg_connect_ws_opt.md"
        },
        {
            "type": "markdown",
            "name": "mg_send_websocket_frame.md"
        },
        {
            "type": "markdown",
            "name": "mg_send_websocket_framev.md"
        },
        {
            "type": "markdown",
            "name": "mg_printf_websocket_frame.md"
        },
        {
            "type": "markdown",
            "name": "mg_send_http_chunk.md"
        },
        {
            "type": "markdown",
            "name": "mg_printf_http_chunk.md"
        },
        {
            "type": "markdown",
            "name": "mg_send_response_line.md"
        },
        {
            "type": "markdown",
            "name": "mg_send_head.md"
        },
        {
            "type": "markdown",
            "name": "mg_printf_html_escape.md"
        },
        {
            "type": "markdown",
            "name": "mg_parse_http.md"
        },
        {
            "type": "markdown",
            "name": "mg_get_http_header.md"
        },
        {
            "type": "markdown",
            "name": "mg_http_parse_header.md"
        },
        {
            "type": "markdown",
            "name": "mg_parse_multipart.md"
        },
        {
            "type": "markdown",
            "name": "mg_get_http_var.md"
        },
        {
            "type": "markdown",
            "name": "mg_url_decode.md"
        },
        {
            "type": "markdown",
            "name": "mg_http_create_digest_auth_header.md"
        },
        {
            "type": "markdown",
            "name": "mg_connect_http.md"
        },
        {
            "type": "markdown",
            "name": "mg_connect_http_opt.md"
        },
        {
            "type": "markdown",
            "name": "mg_serve_http.md"
        },
        {
            "type": "markdown",
            "name": "mg_register_http_endpoint.md"
        },
        {
            "type": "markdown",
            "name": "mg_file_upload_handler.md"
        },
        {
            "type": "markdown",
            "name": "mg_fu_fname_fn.md"
        },
        {
            "type": "markdown",
            "name": "struct_http_message.md"
        },
        {
            "type": "markdown",
            "name": "struct_websocket_message.md"
        },
        {
            "type": "markdown",
            "name": "struct_mg_http_multipart_part.md"
        },
        {
            "type": "markdown",
            "name": "struct_mg_serve_http_opts.md"
        }
    ]
 }
@@ -0,0 +1,35 @@
 ---
 title: "mg_connect_http()"
 decl_name: "mg_connect_http"
 symbol_kind: "func"
 signature: |
  struct mg_connection *mg_connect_http(struct mg_mgr *mgr,
                                        mg_event_handler_t event_handler,
                                        const char *url,
                                        const char *extra_headers,
                                        const char *post_data);
 ---
 Helper function that creates outbound HTTP connection.
 `url` is a URL to fetch. It must be properly URL-encoded, e.g. have
 no spaces, etc. By default, `mg_connect_http()` sends Connection and
 Host headers. `extra_headers` is an extra HTTP headers to send, e.g.
 `"User-Agent: my-app\r\n"`.
 If `post_data` is NULL, then GET request is created. Otherwise, POST request
 is created with the specified POST data. Note that if the data being posted
 is a form submission, the `Content-Type` header should be set accordingly
 (see example below).
 Examples:
 ```c
  nc1 = mg_connect_http(mgr, ev_handler_1, "http://www.google.com", NULL,
                        NULL);
  nc2 = mg_connect_http(mgr, ev_handler_1, "https://github.com", NULL, NULL);
  nc3 = mg_connect_http(
      mgr, ev_handler_1, "my_server:8000/form_submit/",
      "Content-Type: application/x-www-form-urlencoded\r\n",
      "var_1=value_1&var_2=value_2");
 ``` 
@@ -0,0 +1,18 @@
 ---
 title: "mg_connect_http_opt()"
 decl_name: "mg_connect_http_opt"
 symbol_kind: "func"
 signature: |
  struct mg_connection *mg_connect_http_opt(struct mg_mgr *mgr,
                                            mg_event_handler_t ev_handler,
                                            struct mg_connect_opts opts,
                                            const char *url,
                                            const char *extra_headers,
                                            const char *post_data);
 ---
 Helper function that creates outbound HTTP connection.
 Mostly identical to mg_connect_http, but allows to provide extra parameters
 (for example, SSL parameters 
@@ -0,0 +1,30 @@
 ---
 title: "mg_connect_ws()"
 decl_name: "mg_connect_ws"
 symbol_kind: "func"
 signature: |
  struct mg_connection *mg_connect_ws(struct mg_mgr *mgr,
                                      mg_event_handler_t event_handler,
                                      const char *url, const char *protocol,
                                      const char *extra_headers);
 ---
 Helper function that creates an outbound WebSocket connection.
 `url` is a URL to connect to. It must be properly URL-encoded, e.g. have
 no spaces, etc. By default, `mg_connect_ws()` sends Connection and
 Host headers. `extra_headers` is an extra HTTP headers to send, e.g.
 `"User-Agent: my-app\r\n"`.
 If `protocol` is not NULL, then a `Sec-WebSocket-Protocol` header is sent.
 Examples:
 ```c
  nc1 = mg_connect_ws(mgr, ev_handler_1, "ws://echo.websocket.org", NULL,
                      NULL);
  nc2 = mg_connect_ws(mgr, ev_handler_1, "wss://echo.websocket.org", NULL,
                      NULL);
  nc3 = mg_connect_ws(mgr, ev_handler_1, "ws://api.cesanta.com",
                      "clubby.cesanta.com", NULL);
 ``` 
@@ -0,0 +1,17 @@
 ---
 title: "mg_connect_ws_opt()"
 decl_name: "mg_connect_ws_opt"
 symbol_kind: "func"
 signature: |
  struct mg_connection *mg_connect_ws_opt(struct mg_mgr *mgr,
                                          mg_event_handler_t ev_handler,
                                          struct mg_connect_opts opts,
                                          const char *url, const char *protocol,
                                          const char *extra_headers);
 ---
 Helper function that creates an outbound WebSocket connection
 Mostly identical to mg_connect_ws, but allows to provide extra parameters
 (for example, SSL parameters 
@@ -0,0 +1,39 @@
 ---
 title: "mg_file_upload_handler()"
 decl_name: "mg_file_upload_handler"
 symbol_kind: "func"
 signature: |
  void mg_file_upload_handler(struct mg_connection *nc, int ev, void *ev_data,
                              mg_fu_fname_fn local_name_fn);
 ---
 File upload handler.
 This handler can be used to implement file uploads with minimum code.
 This handler will process MG_EV_HTTP_PART_* events and store file data into
 a local file.
 `local_name_fn` will be invoked with whatever name was provided by the client
 and will expect the name of the local file to open. Return value of NULL will
 abort file upload (client will get a "403 Forbidden" response). If non-null,
 the returned string must be heap-allocated and will be freed by the caller.
 Exception: it is ok to return the same string verbatim.
 Example:
 ```c
 struct mg_str upload_fname(struct mg_connection *nc, struct mg_str fname) {
  // Just return the same filename. Do not actually do this except in test!
  // fname is user-controlled and needs to be sanitized.
  return fname;
 }
 void ev_handler(struct mg_connection *nc, int ev, void *ev_data) {
  switch (ev) {
    ...
    case MG_EV_HTTP_PART_BEGIN:
    case MG_EV_HTTP_PART_DATA:
    case MG_EV_HTTP_PART_END:
      mg_file_upload_handler(nc, ev, ev_data, upload_fname);
      break;
  }
 }
 ``` 
@@ -0,0 +1,11 @@
 ---
 title: "mg_fu_fname_fn"
 decl_name: "mg_fu_fname_fn"
 symbol_kind: "typedef"
 signature: |
  typedef struct mg_str (*mg_fu_fname_fn)(struct mg_connection *nc,
                                          struct mg_str fname);
 ---
 Callback prototype for `mg_file_upload_handler()`. 
@@ -0,0 +1,13 @@
 ---
 title: "mg_get_http_header()"
 decl_name: "mg_get_http_header"
 symbol_kind: "func"
 signature: |
  struct mg_str *mg_get_http_header(struct http_message *hm, const char *name);
 ---
 Search and return header `name` in parsed HTTP message `hm`.
 If header is not found, NULL is returned. Example:
    struct mg_str *host_hdr = mg_get_http_header(hm, "Host"); 
@@ -0,0 +1,16 @@
 ---
 title: "mg_get_http_var()"
 decl_name: "mg_get_http_var"
 symbol_kind: "func"
 signature: |
  int mg_get_http_var(const struct mg_str *buf, const char *name, char *dst,
                      size_t dst_len);
 ---
 Fetch an HTTP form variable.
 Fetch a variable `name` from a `buf` into a buffer specified by
 `dst`, `dst_len`. Destination is always zero-terminated. Return length
 of a fetched variable. If not found, 0 is returned. `buf` must be
 valid url-encoded buffer. If destination is too small, `-1` is returned. 
@@ -0,0 +1,13 @@
 ---
 title: "mg_http_create_digest_auth_header()"
 decl_name: "mg_http_create_digest_auth_header"
 symbol_kind: "func"
 signature: |
  int mg_http_create_digest_auth_header(char *buf, size_t buf_len,
                                        const char *method, const char *uri,
                                        const char *auth_domain, const char *user,
                                        const char *passwd);
 ---
 Create Digest authentication header for client request. 
@@ -0,0 +1,23 @@
 ---
 title: "mg_http_parse_header()"
 decl_name: "mg_http_parse_header"
 symbol_kind: "func"
 signature: |
  int mg_http_parse_header(struct mg_str *hdr, const char *var_name, char *buf,
                           size_t buf_size);
 ---
 Parse HTTP header `hdr`. Find variable `var_name` and store it's value
 in the buffer `buf`, `buf_size`. Return 0 if variable not found, non-zero
 otherwise.
 This function is supposed to parse
 cookies, authentication headers, etcetera. Example (error handling omitted):
    char user[20];
    struct mg_str *hdr = mg_get_http_header(hm, "Authorization");
    mg_http_parse_header(hdr, "username", user, sizeof(user));
 Return length of the variable's value. If buffer is not large enough,
 or variable not found, 0 is returned. 
@@ -0,0 +1,15 @@
 ---
 title: "mg_parse_http()"
 decl_name: "mg_parse_http"
 symbol_kind: "func"
 signature: |
  int mg_parse_http(const char *s, int n, struct http_message *hm, int is_req);
 ---
 Parse a HTTP message.
 `is_req` should be set to 1 if parsing request, 0 if reply.
 Return number of bytes parsed. If HTTP message is
 incomplete, `0` is returned. On parse error, negative number is returned. 
@@ -0,0 +1,46 @@
 ---
 title: "mg_parse_multipart()"
 decl_name: "mg_parse_multipart"
 symbol_kind: "func"
 signature: |
  size_t mg_parse_multipart(const char *buf, size_t buf_len, char *var_name,
                            size_t var_name_len, char *file_name,
                            size_t file_name_len, const char **chunk,
                            size_t *chunk_len);
 ---
 Parse buffer `buf`, `buf_len` that contains multipart form data chunks.
 Store chunk name in a `var_name`, `var_name_len` buffer.
 If a chunk is an uploaded file, then `file_name`, `file_name_len` is
 filled with an uploaded file name. `chunk`, `chunk_len`
 points to the chunk data.
 Return: number of bytes to skip to the next chunk, or 0 if there are
        no more chunks.
 Usage example:
 ```c
   static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) {
     switch(ev) {
       case MG_EV_HTTP_REQUEST: {
         struct http_message *hm = (struct http_message *) ev_data;
         char var_name[100], file_name[100];
         const char *chunk;
         size_t chunk_len, n1, n2;
         n1 = n2 = 0;
         while ((n2 = mg_parse_multipart(hm->body.p + n1,
                                         hm->body.len - n1,
                                         var_name, sizeof(var_name),
                                         file_name, sizeof(file_name),
                                         &chunk, &chunk_len)) > 0) {
           printf("var: %s, file_name: %s, size: %d, chunk: [%.*s]\n",
                  var_name, file_name, (int) chunk_len,
                  (int) chunk_len, chunk);
           n1 += n2;
         }
       }
       break;
 ``` 
@@ -0,0 +1,10 @@
 ---
 title: "mg_printf_html_escape()"
 decl_name: "mg_printf_html_escape"
 symbol_kind: "func"
 signature: |
  void mg_printf_html_escape(struct mg_connection *nc, const char *fmt, ...);
 ---
 Send printf-formatted HTTP chunk, escaping HTML tags. 
@@ -0,0 +1,11 @@
 ---
 title: "mg_printf_http_chunk()"
 decl_name: "mg_printf_http_chunk"
 symbol_kind: "func"
 signature: |
  void mg_printf_http_chunk(struct mg_connection *nc, const char *fmt, ...);
 ---
 Send printf-formatted HTTP chunk.
 Functionality is similar to `mg_send_http_chunk()`. 
@@ -0,0 +1,14 @@
 ---
 title: "mg_printf_websocket_frame()"
 decl_name: "mg_printf_websocket_frame"
 symbol_kind: "func"
 signature: |
  void mg_printf_websocket_frame(struct mg_connection *nc, int op_and_flags,
                                 const char *fmt, ...);
 ---
 Send websocket frame to the remote end.
 Like `mg_send_websocket_frame()`, but allows to create formatted message
 with `printf()`-like semantics. 
@@ -0,0 +1,35 @@
 ---
 title: "mg_register_http_endpoint()"
 decl_name: "mg_register_http_endpoint"
 symbol_kind: "func"
 signature: |
  void mg_register_http_endpoint(struct mg_connection *nc, const char *uri_path,
                                 mg_event_handler_t handler);
 ---
 Register callback for specified http endpoint
 Note: if callback is registered it is called instead of
 callback provided in mg_bind
 Example code snippet:
 ```c
 static void handle_hello1(struct mg_connection *nc, int ev, void *ev_data) {
  (void) ev; (void) ev_data;
  mg_printf(nc, "HTTP/1.0 200 OK\r\n\r\n[I am Hello1]");
 nc->flags |= MG_F_SEND_AND_CLOSE;
 }
 static void handle_hello1(struct mg_connection *nc, int ev, void *ev_data) {
 (void) ev; (void) ev_data;
  mg_printf(nc, "HTTP/1.0 200 OK\r\n\r\n[I am Hello2]");
 nc->flags |= MG_F_SEND_AND_CLOSE;
 }
 void init() {
  nc = mg_bind(&mgr, local_addr, cb1);
  mg_register_http_endpoint(nc, "/hello1", handle_hello1);
  mg_register_http_endpoint(nc, "/hello1/hello2", handle_hello2);
 }
 ``` 
@@ -0,0 +1,21 @@
 ---
 title: "mg_send_head()"
 decl_name: "mg_send_head"
 symbol_kind: "func"
 signature: |
  void mg_send_head(struct mg_connection *n, int status_code,
                    int64_t content_length, const char *extra_headers);
 ---
 Send response line and headers.
 This function sends response line with the `status_code`, and automatically
 sends one header: either "Content-Length", or "Transfer-Encoding".
 If `content_length` is negative, then "Transfer-Encoding: chunked" header
 is sent, otherwise, "Content-Length" header is sent.
 NOTE: If `Transfer-Encoding` is `chunked`, then message body must be sent
 using `mg_send_http_chunk()` or `mg_printf_http_chunk()` functions.
 Otherwise, `mg_send()` or `mg_printf()` must be used.
 Extra headers could be set through `extra_headers` - and note `extra_headers`
 must NOT be terminated by a new line. 
@@ -0,0 +1,25 @@
 ---
 title: "mg_send_http_chunk()"
 decl_name: "mg_send_http_chunk"
 symbol_kind: "func"
 signature: |
  void mg_send_http_chunk(struct mg_connection *nc, const char *buf, size_t len);
 ---
 Send buffer `buf` of size `len` to the client using chunked HTTP encoding.
 This function first sends buffer size as hex number + newline, then
 buffer itself, then newline. For example,
  `mg_send_http_chunk(nc, "foo", 3)` whill append `3\r\nfoo\r\n` string to
 the `nc->send_mbuf` output IO buffer.
 NOTE: HTTP header "Transfer-Encoding: chunked" should be sent prior to
 using this function.
 NOTE: do not forget to send empty chunk at the end of the response,
 to tell the client that everything was sent. Example:
 ```
  mg_printf_http_chunk(nc, "%s", "my response!");
  mg_send_http_chunk(nc, "", 0); // Tell the client we're finished
 ``` 
@@ -0,0 +1,21 @@
 ---
 title: "mg_send_response_line()"
 decl_name: "mg_send_response_line"
 symbol_kind: "func"
 signature: |
  void mg_send_response_line(struct mg_connection *c, int status_code,
                             const char *extra_headers);
 ---
 Send response status line.
 If `extra_headers` is not NULL, then `extra_headers` are also sent
 after the reponse line. `extra_headers` must NOT end end with new line.
 Example:
     mg_send_response_line(nc, 200, "Access-Control-Allow-Origin: *");
 Will result in:
     HTTP/1.1 200 OK\r\n
     Access-Control-Allow-Origin: *\r\n 
@@ -0,0 +1,26 @@
 ---
 title: "mg_send_websocket_frame()"
 decl_name: "mg_send_websocket_frame"
 symbol_kind: "func"
 signature: |
  void mg_send_websocket_frame(struct mg_connection *nc, int op_and_flags,
                               const void *data, size_t data_len);
 ---
 Send websocket frame to the remote end.
 `op_and_flags` specifies frame's type, one of:
 - WEBSOCKET_OP_CONTINUE
 - WEBSOCKET_OP_TEXT
 - WEBSOCKET_OP_BINARY
 - WEBSOCKET_OP_CLOSE
 - WEBSOCKET_OP_PING
 - WEBSOCKET_OP_PONG
 Orred with one of the flags:
 - WEBSOCKET_DONT_FIN: Don't set the FIN flag on the frame to be sent.
 `data` and `data_len` contain frame data. 
@@ -0,0 +1,13 @@
 ---
 title: "mg_send_websocket_framev()"
 decl_name: "mg_send_websocket_framev"
 symbol_kind: "func"
 signature: |
  void mg_send_websocket_framev(struct mg_connection *nc, int op_and_flags,
                                const struct mg_str *strings, int num_strings);
 ---
 Send multiple websocket frames.
 Like `mg_send_websocket_frame()`, but composes a frame from multiple buffers. 
@@ -0,0 +1,22 @@
 ---
 title: "mg_send_websocket_handshake()"
 decl_name: "mg_send_websocket_handshake"
 symbol_kind: "func"
 signature: |
  void mg_send_websocket_handshake(struct mg_connection *nc, const char *uri,
                                   const char *extra_headers);
 ---
 Send websocket handshake to the server.
 `nc` must be a valid connection, connected to a server. `uri` is an URI
 to fetch, extra_headers` is extra HTTP headers to send or `NULL`.
 This function is intended to be used by websocket client.
 Note that the Host header is mandatory in HTTP/1.1 and must be
 included in `extra_headers`. `mg_send_websocket_handshake2` offers
 a better API for that.
 Deprecated in favour of `mg_send_websocket_handshake2` 
@@ -0,0 +1,19 @@
 ---
 title: "mg_send_websocket_handshake2()"
 decl_name: "mg_send_websocket_handshake2"
 symbol_kind: "func"
 signature: |
  void mg_send_websocket_handshake2(struct mg_connection *nc, const char *path,
                                    const char *host, const char *protocol,
                                    const char *extra_headers);
 ---
 Send websocket handshake to the server.
 `nc` must be a valid connection, connected to a server. `uri` is an URI
 to fetch, `host` goes into the `Host` header, `protocol` goes into the
 `Sec-WebSocket-Proto` header (NULL to omit), extra_headers` is extra HTTP
 headers to send or `NULL`.
 This function is intended to be used by websocket client. 
@@ -0,0 +1,28 @@
 ---
 title: "mg_serve_http()"
 decl_name: "mg_serve_http"
 symbol_kind: "func"
 signature: |
  void mg_serve_http(struct mg_connection *nc, struct http_message *hm,
                     struct mg_serve_http_opts opts);
 ---
 Serve given HTTP request according to the `options`.
 Example code snippet:
 ```c
 static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) {
  struct http_message *hm = (struct http_message *) ev_data;
  struct mg_serve_http_opts opts = { .document_root = "/var/www" };  // C99
  switch (ev) {
    case MG_EV_HTTP_REQUEST:
      mg_serve_http(nc, hm, opts);
      break;
    default:
      break;
  }
 }
 ``` 
@@ -0,0 +1,50 @@
 ---
 title: "mg_set_protocol_http_websocket()"
 decl_name: "mg_set_protocol_http_websocket"
 symbol_kind: "func"
 signature: |
  void mg_set_protocol_http_websocket(struct mg_connection *nc);
 ---
 Attach built-in HTTP event handler to the given connection.
 User-defined event handler will receive following extra events:
 - MG_EV_HTTP_REQUEST: HTTP request has arrived. Parsed HTTP request
 is passed as
  `struct http_message` through the handler's `void *ev_data` pointer.
 - MG_EV_HTTP_MULTIPART_REQUEST: A multipart POST request has received.
  This event is sent before body is parsed. After this user
  should expect a sequence of MG_EV_HTTP_PART_BEGIN/DATA/END requests.
  This is also the last time when headers and other request fields are
  accessible.
 - MG_EV_HTTP_REPLY: HTTP reply has arrived. Parsed HTTP reply is passed as
  `struct http_message` through the handler's `void *ev_data` pointer.
 - MG_EV_HTTP_CHUNK: HTTP chunked-encoding chunk has arrived.
  Parsed HTTP reply is passed as `struct http_message` through the
  handler's `void *ev_data` pointer. `http_message::body` would contain
  incomplete, reassembled HTTP body.
  It will grow with every new chunk arrived, and
  potentially can consume a lot of memory. An event handler may process
  the body as chunks are coming, and signal Mongoose to delete processed
  body by setting `MG_F_DELETE_CHUNK` in `mg_connection::flags`. When
  the last zero chunk is received,
  Mongoose sends `MG_EV_HTTP_REPLY` event with
  full reassembled body (if handler did not signal to delete chunks) or
  with empty body (if handler did signal to delete chunks).
 - MG_EV_WEBSOCKET_HANDSHAKE_REQUEST: server has received websocket handshake
  request. `ev_data` contains parsed HTTP request.
 - MG_EV_WEBSOCKET_HANDSHAKE_DONE: server has completed Websocket handshake.
  `ev_data` is `NULL`.
 - MG_EV_WEBSOCKET_FRAME: new websocket frame has arrived. `ev_data` is
  `struct websocket_message *`
 - MG_EV_HTTP_PART_BEGIN: new part of multipart message is started,
  extra parameters are passed in mg_http_multipart_part
 - MG_EV_HTTP_PART_DATA: new portion of data from multiparted message
  no additional headers are available, only data and data size
 - MG_EV_HTTP_PART_END: final boundary received, analogue to maybe used to
  find the end of packet
  Note: Mongoose should be compiled with MG_ENABLE_HTTP_STREAMING_MULTIPART
  to enable MG_EV_HTTP_MULTIPART_REQUEST, MG_EV_HTTP_REQUEST_END,
  MG_EV_HTTP_REQUEST_CANCEL, MG_EV_HTTP_PART_BEGIN, MG_EV_HTTP_PART_DATA,
  MG_EV_HTTP_PART_END constants 
@@ -0,0 +1,18 @@
 ---
 title: "mg_url_decode()"
 decl_name: "mg_url_decode"
 symbol_kind: "func"
 signature: |
  int mg_url_decode(const char *src, int src_len, char *dst, int dst_len,
                    int is_form_url_encoded);
 ---
 Decode URL-encoded string.
 Source string is specified by (`src`, `src_len`), and destination is
 (`dst`, `dst_len`). If `is_form_url_encoded` is non-zero, then
 `+` character is decoded as a blank space character. This function
 guarantees to `\0`-terminate the destination. If destination is too small,
 then source string is partially decoded and `-1` is returned. Otherwise,
 a length of decoded string is returned, not counting final `\0`. 
@@ -0,0 +1,38 @@
 ---
 title: "struct http_message"
 decl_name: "struct http_message"
 symbol_kind: "struct"
 signature: |
  struct http_message {
    struct mg_str message; /* Whole message: request line + headers + body */
    /* HTTP Request line (or HTTP response line) */
    struct mg_str method; /* "GET" */
    struct mg_str uri;    /* "/my_file.html" */
    struct mg_str proto;  /* "HTTP/1.1" -- for both request and response */
    /* For responses, code and response status message are set */
    int resp_code;
    struct mg_str resp_status_msg;
    /*
     * Query-string part of the URI. For example, for HTTP request
     *    GET /foo/bar?param1=val1&param2=val2
     *    |    uri    |     query_string     |
     *
     * Note that question mark character doesn't belong neither to the uri,
     * nor to the query_string
     */
    struct mg_str query_string;
    /* Headers */
    struct mg_str header_names[MG_MAX_HTTP_HEADERS];
    struct mg_str header_values[MG_MAX_HTTP_HEADERS];
    /* Message body */
    struct mg_str body; /* Zero-length for requests with no body */
  };
 ---
 HTTP message 
@@ -0,0 +1,16 @@
 ---
 title: "struct mg_http_multipart_part"
 decl_name: "struct mg_http_multipart_part"
 symbol_kind: "struct"
 signature: |
  struct mg_http_multipart_part {
    const char *file_name;
    const char *var_name;
    struct mg_str data;
    int status; /* <0 on error */
    void *user_data;
  };
 ---
 HTTP multipart part 
@@ -0,0 +1,104 @@
 ---
 title: "struct mg_serve_http_opts"
 decl_name: "struct mg_serve_http_opts"
 symbol_kind: "struct"
 signature: |
  struct mg_serve_http_opts {
    /* Path to web root directory */
    const char *document_root;
    /* List of index files. Default is "" */
    const char *index_files;
    /*
     * Leave as NULL to disable authentication.
     * To enable directory protection with authentication, set this to ".htpasswd"
     * Then, creating ".htpasswd" file in any directory automatically protects
     * it with digest authentication.
     * Use `mongoose` web server binary, or `htdigest` Apache utility to
     * create/manipulate passwords file.
     * Make sure `auth_domain` is set to a valid domain name.
     */
    const char *per_directory_auth_file;
    /* Authorization domain (domain name of this web server) */
    const char *auth_domain;
    /*
     * Leave as NULL to disable authentication.
     * Normally, only selected directories in the document root are protected.
     * If absolutely every access to the web server needs to be authenticated,
     * regardless of the URI, set this option to the path to the passwords file.
     * Format of that file is the same as ".htpasswd" file. Make sure that file
     * is located outside document root to prevent people fetching it.
     */
    const char *global_auth_file;
    /* Set to "no" to disable directory listing. Enabled by default. */
    const char *enable_directory_listing;
    /* SSI files pattern. If not set, "**.shtml$|**.shtm$" is used. */
    const char *ssi_pattern;
    /* IP ACL. By default, NULL, meaning all IPs are allowed to connect */
    const char *ip_acl;
    /* URL rewrites.
     *
     * Comma-separated list of `uri_pattern=file_or_directory_path` rewrites.
     * When HTTP request is received, Mongoose constructs a file name from the
     * requested URI by combining `document_root` and the URI. However, if the
     * rewrite option is used and `uri_pattern` matches requested URI, then
     * `document_root` is ignored. Instead, `file_or_directory_path` is used,
     * which should be a full path name or a path relative to the web server's
     * current working directory. Note that `uri_pattern`, as all Mongoose
     * patterns, is a prefix pattern.
     *
     * If uri_pattern starts with `@` symbol, then Mongoose compares it with the
     * HOST header of the request. If they are equal, Mongoose sets document root
     * to `file_or_directory_path`, implementing virtual hosts support.
     * Example: `@foo.com=/document/root/for/foo.com`
     *
     * If `uri_pattern` starts with `%` symbol, then Mongoose compares it with
     * the listening port. If they match, then Mongoose issues a 301 redirect.
     * For example, to redirect all HTTP requests to the
     * HTTPS port, do `%80=https://my.site.com`. Note that the request URI is
     * automatically appended to the redirect location.
     */
    const char *url_rewrites;
    /* DAV document root. If NULL, DAV requests are going to fail. */
    const char *dav_document_root;
    /*
     * DAV passwords file. If NULL, DAV requests are going to fail.
     * If passwords file is set to "-", then DAV auth is disabled.
     */
    const char *dav_auth_file;
    /* Glob pattern for the files to hide. */
    const char *hidden_file_pattern;
    /* Set to non-NULL to enable CGI, e.g. **.cgi$|**.php$" */
    const char *cgi_file_pattern;
    /* If not NULL, ignore CGI script hashbang and use this interpreter */
    const char *cgi_interpreter;
    /*
     * Comma-separated list of Content-Type overrides for path suffixes, e.g.
     * ".txt=text/plain; charset=utf-8,.c=text/plain"
     */
    const char *custom_mime_types;
    /*
     * Extra HTTP headers to add to each server response.
     * Example: to enable CORS, set this to "Access-Control-Allow-Origin: *".
     */
    const char *extra_headers;
  };
 ---
 This structure defines how `mg_serve_http()` works.
 Best practice is to set only required settings, and leave the rest as NULL. 
@@ -0,0 +1,14 @@
 ---
 title: "struct websocket_message"
 decl_name: "struct websocket_message"
 symbol_kind: "struct"
 signature: |
  struct websocket_message {
    unsigned char *data;
    size_t size;
    unsigned char flags;
  };
 ---
 WebSocket message 
@@ -0,0 +1,44 @@
 {
    "items": [
        {
            "type": "section",
            "name": "mbuf.h"
        },
        {
            "type": "section",
            "name": "net.h"
        },
        {
            "type": "section",
            "name": "http.h"
        },
        {
            "type": "section",
            "name": "json-rpc.h"
        },
        {
            "type": "section",
            "name": "dns.h"
        },
        {
            "type": "section",
            "name": "dns-server.h"
        },
        {
            "type": "section",
            "name": "mqtt.h"
        },
        {
            "type": "section",
            "name": "mqtt-broker.h"
        },
        {
            "type": "section",
            "name": "coap.h"
        },
        {
            "type": "section",
            "name": "util.h"
        }
    ]
 }
@@ -0,0 +1,8 @@
 ---
 title: "JSON-RPC"
 symbol_kind: "intro"
 decl_name: "json-rpc.h"
 ---
@@ -0,0 +1,44 @@
 {
    "items": [
        {
            "type": "markdown",
            "name": "intro.md"
        },
        {
            "type": "markdown",
            "name": "mg_rpc_parse_reply.md"
        },
        {
            "type": "markdown",
            "name": "mg_rpc_create_request.md"
        },
        {
            "type": "markdown",
            "name": "mg_rpc_create_reply.md"
        },
        {
            "type": "markdown",
            "name": "mg_rpc_create_error.md"
        },
        {
            "type": "markdown",
            "name": "mg_rpc_create_std_error.md"
        },
        {
            "type": "markdown",
            "name": "mg_rpc_dispatch.md"
        },
        {
            "type": "markdown",
            "name": "struct_mg_rpc_request.md"
        },
        {
            "type": "markdown",
            "name": "struct_mg_rpc_reply.md"
        },
        {
            "type": "markdown",
            "name": "struct_mg_rpc_error.md"
        }
    ]
 }
@@ -0,0 +1,16 @@
 ---
 title: "mg_rpc_create_error()"
 decl_name: "mg_rpc_create_error"
 symbol_kind: "func"
 signature: |
  int mg_rpc_create_error(char *buf, int len, struct mg_rpc_request *req,
                          int code, const char *message, const char *fmt, ...);
 ---
 Create JSON-RPC error reply in a given buffer.
 Return length of the error, which
 can be larger then `len` that indicates an overflow.
 `fmt` format string should conform to `json_emit()` API,
 see https://github.com/cesanta/frozen 
@@ -0,0 +1,16 @@
 ---
 title: "mg_rpc_create_reply()"
 decl_name: "mg_rpc_create_reply"
 symbol_kind: "func"
 signature: |
  int mg_rpc_create_reply(char *buf, int len, const struct mg_rpc_request *req,
                          const char *result_fmt, ...);
 ---
 Create JSON-RPC reply in a given buffer.
 Return length of the reply, which
 can be larger then `len` that indicates an overflow.
 `result_fmt` format string should conform to `json_emit()` API,
 see https://github.com/cesanta/frozen 
@@ -0,0 +1,16 @@
 ---
 title: "mg_rpc_create_request()"
 decl_name: "mg_rpc_create_request"
 symbol_kind: "func"
 signature: |
  int mg_rpc_create_request(char *buf, int len, const char *method,
                            const char *id, const char *params_fmt, ...);
 ---
 Create JSON-RPC request in a given buffer.
 Return length of the request, which
 can be larger then `len` that indicates an overflow.
 `params_fmt` format string should conform to `json_emit()` API,
 see https://github.com/cesanta/frozen 
@@ -0,0 +1,22 @@
 ---
 title: "mg_rpc_create_std_error()"
 decl_name: "mg_rpc_create_std_error"
 symbol_kind: "func"
 signature: |
  int mg_rpc_create_std_error(char *buf, int len, struct mg_rpc_request *req,
                              int code);
 ---
 Create JSON-RPC error in a given buffer.
 Return length of the error, which
 can be larger then `len` that indicates an overflow. See
 JSON_RPC_*_ERROR definitions for standard error values:
 - `#define JSON_RPC_PARSE_ERROR (-32700)`
 - `#define JSON_RPC_INVALID_REQUEST_ERROR (-32600)`
 - `#define JSON_RPC_METHOD_NOT_FOUND_ERROR (-32601)`
 - `#define JSON_RPC_INVALID_PARAMS_ERROR (-32602)`
 - `#define JSON_RPC_INTERNAL_ERROR (-32603)`
 - `#define JSON_RPC_SERVER_ERROR (-32000)` 
@@ -0,0 +1,20 @@
 ---
 title: "mg_rpc_dispatch()"
 decl_name: "mg_rpc_dispatch"
 symbol_kind: "func"
 signature: |
  int mg_rpc_dispatch(const char *buf, int, char *dst, int dst_len,
                      const char **methods, mg_rpc_handler_t *handlers);
 ---
 Dispatches a JSON-RPC request.
 Parses JSON-RPC request contained in `buf`, `len`.
 Then, dispatches the request to the correct handler method.
 Valid method names should be specified in NULL
 terminated array `methods`, and corresponding handlers in `handlers`.
 Result is put in `dst`, `dst_len`. Return: length of the result, which
 can be larger then `dst_len` that indicates an overflow.
 Overflown bytes are not written to the buffer.
 If method is not found, an error is automatically generated. 
@@ -0,0 +1,24 @@
 ---
 title: "mg_rpc_parse_reply()"
 decl_name: "mg_rpc_parse_reply"
 symbol_kind: "func"
 signature: |
  int mg_rpc_parse_reply(const char *buf, int len, struct json_token *toks,
                         int max_toks, struct mg_rpc_reply *,
                         struct mg_rpc_error *);
 ---
 Parse JSON-RPC reply contained in `buf`, `len` into JSON tokens array
 `toks`, `max_toks`. If buffer contains valid reply, `reply` structure is
 populated. The result of RPC call is located in `reply.result`. On error,
 `error` structure is populated. Returns: the result of calling
 `parse_json(buf, len, toks, max_toks)`:
 On success, an offset inside `json_string` is returned
 where parsing has finished. On failure, a negative number is
 returned, one of:
 - `#define JSON_STRING_INVALID           -1`
 - `#define JSON_STRING_INCOMPLETE        -2`
 - `#define JSON_TOKEN_ARRAY_TOO_SMALL    -3` 
@@ -0,0 +1,16 @@
 ---
 title: "struct mg_rpc_error"
 decl_name: "struct mg_rpc_error"
 symbol_kind: "struct"
 signature: |
  struct mg_rpc_error {
    struct json_token *message;       /* Whole RPC message */
    struct json_token *id;            /* Message ID */
    struct json_token *error_code;    /* error.code */
    struct json_token *error_message; /* error.message */
    struct json_token *error_data;    /* error.data, can be NULL */
  };
 ---
 JSON-RPC error 
@@ -0,0 +1,14 @@
 ---
 title: "struct mg_rpc_reply"
 decl_name: "struct mg_rpc_reply"
 symbol_kind: "struct"
 signature: |
  struct mg_rpc_reply {
    struct json_token *message; /* Whole RPC message */
    struct json_token *id;      /* Message ID */
    struct json_token *result;  /* Remote call result */
  };
 ---
 JSON-RPC response 
@@ -0,0 +1,15 @@
 ---
 title: "struct mg_rpc_request"
 decl_name: "struct mg_rpc_request"
 symbol_kind: "struct"
 signature: |
  struct mg_rpc_request {
    struct json_token *message; /* Whole RPC message */
    struct json_token *id;      /* Message ID */
    struct json_token *method;  /* Method name */
    struct json_token *params;  /* Method params */
  };
 ---
 JSON-RPC request 
@@ -0,0 +1,11 @@
 ---
 title: "Memory Buffers"
 symbol_kind: "intro"
 decl_name: "mbuf.h"
 ---
 Mbufs are mutable/growing memory buffers, like C++ strings.
 Mbuf can append data to the end of a buffer, or insert data into arbitrary
 position in the middle of a buffer. The buffer grows automatically when
 needed.
@@ -0,0 +1,40 @@
 {
    "items": [
        {
            "type": "markdown",
            "name": "intro.md"
        },
        {
            "type": "markdown",
            "name": "mbuf_init.md"
        },
        {
            "type": "markdown",
            "name": "mbuf_free.md"
        },
        {
            "type": "markdown",
            "name": "mbuf_append.md"
        },
        {
            "type": "markdown",
            "name": "mbuf_insert.md"
        },
        {
            "type": "markdown",
            "name": "mbuf_remove.md"
        },
        {
            "type": "markdown",
            "name": "mbuf_resize.md"
        },
        {
            "type": "markdown",
            "name": "mbuf_trim.md"
        },
        {
            "type": "markdown",
            "name": "struct_mbuf.md"
        }
    ]
 }
@@ -0,0 +1,12 @@
 ---
 title: "mbuf_append()"
 decl_name: "mbuf_append"
 symbol_kind: "func"
 signature: |
  size_t mbuf_append(struct mbuf *, const void *data, size_t data_size);
 ---
 Appends data to the Mbuf.
 Return the number of bytes appended, or 0 if out of memory. 
@@ -0,0 +1,10 @@
 ---
 title: "mbuf_free()"
 decl_name: "mbuf_free"
 symbol_kind: "func"
 signature: |
  void mbuf_free(struct mbuf *);
 ---
 Free the space allocated for the mbuffer and resets the mbuf structure. 
@@ -0,0 +1,11 @@
 ---
 title: "mbuf_init()"
 decl_name: "mbuf_init"
 symbol_kind: "func"
 signature: |
  void mbuf_init(struct mbuf *, size_t initial_capacity);
 ---
 Initialize an Mbuf.
 `initial_capacity` specifies the initial capacity of the mbuf. 
@@ -0,0 +1,14 @@
 ---
 title: "mbuf_insert()"
 decl_name: "mbuf_insert"
 symbol_kind: "func"
 signature: |
  size_t mbuf_insert(struct mbuf *, size_t, const void *, size_t);
 ---
 Insert data at a specified offset in the Mbuf.
 Existing data will be shifted forwards and the buffer will
 be grown if necessary.
 Return the number of bytes inserted. 
@@ -0,0 +1,10 @@
 ---
 title: "mbuf_remove()"
 decl_name: "mbuf_remove"
 symbol_kind: "func"
 signature: |
  void mbuf_remove(struct mbuf *, size_t data_size);
 ---
 Remove `data_size` bytes from the beginning of the buffer.