Mongoose 6.5

PUBLISHED_FROM=d151a5a0bf34b135a7a2c879f5a6bd5676af275a

CONTRIBUTING.md

@@ -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.

LICENSE

@@ -1,5 +1,5 @@
 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 software is dual-licensed: you can redistribute it and/or modify

README.md

@@ -1,39 +1,41 @@
-# <img src="http://www.cesanta.com/hubfs/www.cesanta.com/Images/mongoose_library.png" width="64" height="64"> Mongoose - Embedded Web Server
+# Mongoose - Embedded Web Server / Embedded Networking Library
 
 ![](https://img.shields.io/badge/license-GPL_2-green.svg "License")
 
 Mongoose is ideal for embedded environments. It has been designed
-for connecting devices and bringing them online.
-[Mongoose](https://www.cesanta.com/products)
-has been on the market since 2004 and attracted
-over 1 million cumulative downloads.
+for connecting devices and bringing them online. On the market since 2004,
+used by vast number of open source and
+commercial products - it even runs on space stations!
+Mongoose makes embedded network programming fast, robust, and easy.
 
-It 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.
+If you're looking for a pre-compiled Windows or Mac binary,
+- [Download pre-compiled Mongoose web server binary](https://www.cesanta.com/products/binary)
+
+Alternatively,
 
 - [Download Mongoose Source Code here](http://hubs.ly/H01bWvx0)
-- [Ask questions on support forum](http://forum.cesanta.com/index.php?p=/categories/mongoose)
-- [Read User Guide and API reference](https://docs.cesanta.com/mongoose)
-- [Study mongoose example code](https://github.com/cesanta/mongoose/tree/master/examples) 
+- [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)
 
-> Nothing overdone. Nothing less. So unbelievably easy to use.
-> Just how good software should be! -- Pritin Tyagaraj, SAP
+If you are looking for a complete solution with firmware and cloud components, check out [Mongoose IoT Platform](https://github.com/cesanta/mongoose-iot).
 
+# Support
+- [Support Forum - Ask your technical questions here] (http://forum.cesanta.com/index.php?p=/categories/mongoose)
+- [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
 
 * Cross-platform: works on Linux/UNIX, MacOS, QNX, eCos, Windows, Android,
   iPhone, FreeRTOS (TI CC3200, ESP8266), etc
 * Single-threaded, asynchronous, non-blocking core with simple event-based API
-* Native support for [PicoTCP embedded TCP/IP stack](http://www.picotcp.com), 
+* Native support for [PicoTCP embedded TCP/IP stack](http://www.picotcp.com),
   [LWIP embedded TCP/IP stack](https://en.wikipedia.org/wiki/LwIP)
 * Builtin protocols:
    - plain TCP, plain UDP, SSL/TLS (over TCP, one-way or two-way)
    - HTTP client, HTTP server
-   - Websocket client, Websocket server
-   - JSON-RPC client, JSON-RPC server
+   - WebSocket client, WebSocket server
    - MQTT client, MQTT broker
    - CoAP client, CoAP server
    - DNS client, DNS server, async DNS resolver
@@ -43,7 +45,16 @@ and let them concentrate on the logic, saving time and money.
   [mongoose.c](https://raw.githubusercontent.com/cesanta/mongoose/master/mongoose.c) and
   [mongoose.h](https://raw.githubusercontent.com/cesanta/mongoose/master/mongoose.h)
   files to your build tree
-* Extensively tested and production-ready, trusted by many blue chip businesses
+
+# Licensing
+
+Mongoose is released under commercial and [GNU GPL v.2](http://www.gnu.org/licenses/old-licenses/gpl-2.0.html) open source licenses.
+
+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)
+
+Prototyping:
+While your project is still in prototyping stage and not for sale, you can use Mongoose’s open source code without license restrictions.
 
 # Dashboard Example
 
@@ -58,47 +69,8 @@ the functionality:
 
 # Contributions
 
-People who have agreed to the
+To submit contributions, sign
 [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.
+and send GitHub pull request. You retain the copyright on your contributions.
 
-# Licensing
-
-You are using Mongoose under
-[GPLv2](http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
-and until you commercialize your
-application, can continue to use Mongoose free of charge.
-
-Once you commercialize your product, in order to comply with GPLv2
-you need to either open the source code of your product fully or
-alternatively purchase a commercial license.
-We offer [three levels of commercial licensing](https://www.cesanta.com/products):
-
-- Mongoose Lite: cross platform integration, SSL/TLS, HTTP support
-- Mongoose: Mongoose Lite + HTTP CGI, HTTP SSI, HTTP Digest Auth,
-  WebSocket support
-- Mongoose Premium: Mongoose + Plain TCP, UDP, JSON-RPC, MQTT, DNS,
-  CoAP support
-
-
-[Enquire about commercial licensing here](https://www.cesanta.com/contact)
-
-# Mongoose Binary
-
-This is our easy to use web server for web developers (PHP, Ruby, Python, etc)
-and web designers. Available in three editions to suit your needs: free, pro
-(USD 5) and dev edition (from USD 8). To install, simply download, double-click
-to start and run browser - that's all!
-
-[Download Mongoose Binary here](https://www.cesanta.com/products#binary)
-
-# Other products by Cesanta
-
-- [Smart.js](https://github.com/cesanta/smart.js) -
-    Generic, hardware independent, full-stack IoT software platform
-- [V7](https://github.com/cesanta/v7) - Embedded JavaScript engine
-- [Frozen](https://github.com/cesanta/frozen) - JSON parser and generator
-- [SLRE](https://github.com/cesanta/slre) - Super Light Regular Expression
-  library
+[![Analytics](https://ga-beacon.appspot.com/UA-42732794-5/project-page)](https://github.com/cesanta/mongoose)

docs/build-options/disabling-flags.md

@@ -0,0 +1,11 @@
+---
+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_SOCKETPAIR` disable `mg_broadcast()` API
+- `MG_DISABLE_HTTP_KEEP_ALIVE` useful for embedded systems to save resources

docs/build-options/enabling-flags.md

@@ -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()`

docs/build-options/intro.md

@@ -0,0 +1,22 @@
+---
+title: Build Options
+items:
+  - { type: file, name: enabling-flags.md }
+  - { type: file, name: disabling-flags.md }
+  - { type: file, name: platform-spec.md }
+  - { type: file, name: tunables.md }
+---
+
+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 COAP,
+compile the application `my_app.c` like this (assumed UNIX system):
+
+```
+  $ cc my_app.c mongoose.c -D MG_DISABLE_MQTT -D MG_DISABLE_COAP
+```

docs/build-options/platform-spec.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.

docs/build-options/tunables.md

@@ -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.

docs/c-api/coap.h/intro.md

@@ -0,0 +1,26 @@
+---
+title: "CoAP"
+symbol_kind: "intro"
+decl_name: "coap.h"
+items:
+  - { type: file, name: mg_set_protocol_coap.md }
+  - { type: file, name: mg_coap_add_option.md }
+  - { type: file, name: mg_coap_free_options.md }
+  - { type: file, name: mg_coap_send_message.md }
+  - { type: file, name: mg_coap_send_ack.md }
+  - { type: file, name: mg_coap_parse.md }
+  - { type: file, name: mg_coap_compose.md }
+  - { type: file, name: struct_mg_coap_option.md }
+  - { type: file, name: struct_mg_coap_message.md }
+---
+
+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) ...
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
+```
+

docs/c-api/coap.h/mg_coap_add_option.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. 
+

docs/c-api/coap.h/mg_coap_compose.md

@@ -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()` 
+

docs/c-api/coap.h/mg_coap_free_options.md

@@ -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. 
+

docs/c-api/coap.h/mg_coap_parse.md

@@ -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()` 
+

docs/c-api/coap.h/mg_coap_send_ack.md

@@ -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()` 
+

docs/c-api/coap.h/mg_coap_send_message.md

@@ -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)` 
+

docs/c-api/coap.h/mg_set_protocol_coap.md

@@ -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 
+

docs/c-api/coap.h/struct_mg_coap_message.md

@@ -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. 
+

docs/c-api/coap.h/struct_mg_coap_option.md

@@ -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. 
+

docs/c-api/dns-server.h/intro.md

@@ -0,0 +1,12 @@
+---
+title: "DNS server"
+symbol_kind: "intro"
+decl_name: "dns-server.h"
+items:
+  - { type: file, name: mg_dns_create_reply.md }
+  - { type: file, name: mg_dns_reply_record.md }
+  - { type: file, name: mg_dns_send_reply.md }
+---
+
+Disabled by default; enable with `-DMG_ENABLE_DNS_SERVER`.
+

docs/c-api/dns-server.h/mg_dns_create_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);
+``` 
+

docs/c-api/dns-server.h/mg_dns_reply_record.md

@@ -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. 
+

docs/c-api/dns-server.h/mg_dns_send_reply.md

@@ -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. 
+

docs/c-api/dns.h/intro.md

@@ -0,0 +1,19 @@
+---
+title: "DNS"
+symbol_kind: "intro"
+decl_name: "dns.h"
+items:
+  - { type: file, name: mg_dns_parse_record_data.md }
+  - { type: file, name: mg_send_dns_query.md }
+  - { type: file, name: mg_dns_insert_header.md }
+  - { type: file, name: mg_dns_copy_questions.md }
+  - { type: file, name: mg_dns_encode_record.md }
+  - { type: file, name: mg_parse_dns.md }
+  - { type: file, name: mg_dns_uncompress_name.md }
+  - { type: file, name: mg_set_protocol_dns.md }
+  - { type: file, name: struct_mg_dns_resource_record.md }
+  - { type: file, name: struct_mg_dns_message.md }
+---
+
+
+

docs/c-api/dns.h/mg_dns_copy_questions.md

@@ -0,0 +1,15 @@
+---
+title: "mg_dns_copy_questions()"
+decl_name: "mg_dns_copy_questions"
+symbol_kind: "func"
+signature: |
+  int mg_dns_copy_questions(struct mbuf *io, struct mg_dns_message *msg);
+---
+
+Append already encoded questions from an existing message.
+
+This is useful when generating a DNS reply message which includes
+all question records.
+
+Return number of appened bytes. 
+

docs/c-api/dns.h/mg_dns_encode_record.md

@@ -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. 
+

docs/c-api/dns.h/mg_dns_insert_header.md

@@ -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. 
+

docs/c-api/dns.h/mg_dns_parse_record_data.md

@@ -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 
+

docs/c-api/dns.h/mg_dns_uncompress_name.md

@@ -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. 
+

docs/c-api/dns.h/mg_parse_dns.md

@@ -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. 
+

docs/c-api/dns.h/mg_send_dns_query.md

@@ -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. 
+

docs/c-api/dns.h/mg_set_protocol_dns.md

@@ -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. 
+

docs/c-api/dns.h/struct_mg_dns_message.md

@@ -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). 
+

docs/c-api/dns.h/struct_mg_dns_resource_record.md

@@ -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. 
+

docs/c-api/http.h/intro.md

@@ -0,0 +1,40 @@
+---
+title: "HTTP + Websocket"
+symbol_kind: "intro"
+decl_name: "http.h"
+items:
+  - { type: file, name: mg_set_protocol_http_websocket.md }
+  - { type: file, name: mg_send_websocket_handshake.md }
+  - { type: file, name: mg_send_websocket_handshake2.md }
+  - { type: file, name: mg_connect_ws.md }
+  - { type: file, name: mg_connect_ws_opt.md }
+  - { type: file, name: mg_send_websocket_frame.md }
+  - { type: file, name: mg_send_websocket_framev.md }
+  - { type: file, name: mg_printf_websocket_frame.md }
+  - { type: file, name: mg_send_http_chunk.md }
+  - { type: file, name: mg_printf_http_chunk.md }
+  - { type: file, name: mg_send_response_line.md }
+  - { type: file, name: mg_send_head.md }
+  - { type: file, name: mg_printf_html_escape.md }
+  - { type: file, name: mg_parse_http.md }
+  - { type: file, name: mg_get_http_header.md }
+  - { type: file, name: mg_http_parse_header.md }
+  - { type: file, name: mg_parse_multipart.md }
+  - { type: file, name: mg_get_http_var.md }
+  - { type: file, name: mg_url_decode.md }
+  - { type: file, name: mg_http_create_digest_auth_header.md }
+  - { type: file, name: mg_connect_http.md }
+  - { type: file, name: mg_connect_http_opt.md }
+  - { type: file, name: mg_serve_http.md }
+  - { type: file, name: mg_register_http_endpoint.md }
+  - { type: file, name: mg_file_upload_handler.md }
+  - { type: file, name: mg_http_check_digest_auth.md }
+  - { type: file, name: mg_fu_fname_fn.md }
+  - { type: file, name: struct_http_message.md }
+  - { type: file, name: struct_websocket_message.md }
+  - { type: file, name: struct_mg_http_multipart_part.md }
+  - { type: file, name: struct_mg_serve_http_opts.md }
+---
+
+
+

docs/c-api/http.h/mg_connect_http.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");
+``` 
+

docs/c-api/http.h/mg_connect_http_opt.md

@@ -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 
+

docs/c-api/http.h/mg_connect_ws.md

@@ -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);
+``` 
+

docs/c-api/http.h/mg_connect_ws_opt.md

@@ -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 
+

docs/c-api/http.h/mg_file_upload_handler.md

@@ -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;
+  }
+}
+``` 
+

docs/c-api/http.h/mg_fu_fname_fn.md

@@ -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()`. 
+

docs/c-api/http.h/mg_get_http_header.md

@@ -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"); 
+

docs/c-api/http.h/mg_get_http_var.md

@@ -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. 
+

docs/c-api/http.h/mg_http_check_digest_auth.md

@@ -0,0 +1,12 @@
+---
+title: "mg_http_check_digest_auth()"
+decl_name: "mg_http_check_digest_auth"
+symbol_kind: "func"
+signature: |
+  int mg_http_check_digest_auth(struct http_message *hm, const char *auth_domain,
+                                FILE *fp);
+---
+
+Authenticate HTTP request against opened passwords file.
+Returns 1 if authenticated, 0 otherwise. 
+

docs/c-api/http.h/mg_http_create_digest_auth_header.md

@@ -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. 
+

docs/c-api/http.h/mg_http_parse_header.md

@@ -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. 
+

docs/c-api/http.h/mg_parse_http.md

@@ -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. 
+

docs/c-api/http.h/mg_parse_multipart.md

@@ -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;
+``` 
+

docs/c-api/http.h/mg_printf_html_escape.md

@@ -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. 
+

docs/c-api/http.h/mg_printf_http_chunk.md

@@ -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()`. 
+

docs/c-api/http.h/mg_printf_websocket_frame.md

@@ -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. 
+

docs/c-api/http.h/mg_register_http_endpoint.md

@@ -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);
+}
+``` 
+

docs/c-api/http.h/mg_send_head.md

@@ -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. 
+

docs/c-api/http.h/mg_send_http_chunk.md

@@ -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
+``` 
+

docs/c-api/http.h/mg_send_response_line.md

@@ -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 
+

docs/c-api/http.h/mg_send_websocket_frame.md

@@ -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. 
+

docs/c-api/http.h/mg_send_websocket_framev.md

@@ -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. 
+

docs/c-api/http.h/mg_send_websocket_handshake.md

@@ -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` 
+

docs/c-api/http.h/mg_send_websocket_handshake2.md

@@ -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. 
+

docs/c-api/http.h/mg_serve_http.md

@@ -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;
+  }
+}
+``` 
+

docs/c-api/http.h/mg_set_protocol_http_websocket.md

@@ -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 
+

docs/c-api/http.h/mg_url_decode.md

@@ -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`. 
+

docs/c-api/http.h/struct_http_message.md

@@ -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 
+

docs/c-api/http.h/struct_mg_http_multipart_part.md

@@ -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 
+

docs/c-api/http.h/struct_mg_serve_http_opts.md

@@ -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. 
+

docs/c-api/http.h/struct_websocket_message.md

@@ -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 
+

docs/c-api/intro.md

@@ -0,0 +1,12 @@
+---
+items:
+  - { type: dir, name: mbuf.h }
+  - { type: dir, name: net.h }
+  - { type: dir, name: http.h }
+  - { type: dir, name: dns.h }
+  - { type: dir, name: dns-server.h }
+  - { type: dir, name: mqtt.h }
+  - { type: dir, name: mqtt-broker.h }
+  - { type: dir, name: coap.h }
+  - { type: dir, name: util.h }
+---

docs/c-api/mbuf.h/intro.md

@@ -0,0 +1,20 @@
+---
+title: "Memory Buffers"
+symbol_kind: "intro"
+decl_name: "mbuf.h"
+items:
+  - { type: file, name: mbuf_init.md }
+  - { type: file, name: mbuf_free.md }
+  - { type: file, name: mbuf_append.md }
+  - { type: file, name: mbuf_insert.md }
+  - { type: file, name: mbuf_remove.md }
+  - { type: file, name: mbuf_resize.md }
+  - { type: file, name: mbuf_trim.md }
+  - { type: file, name: struct_mbuf.md }
+---
+
+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.
+

docs/c-api/mbuf.h/mbuf_append.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. 
+

docs/c-api/mbuf.h/mbuf_free.md

@@ -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. 
+

docs/c-api/mbuf.h/mbuf_init.md

@@ -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. 
+

docs/c-api/mbuf.h/mbuf_insert.md

@@ -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. 
+

docs/c-api/mbuf.h/mbuf_remove.md

@@ -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. 
+

docs/c-api/mbuf.h/mbuf_resize.md

@@ -0,0 +1,13 @@
+---
+title: "mbuf_resize()"
+decl_name: "mbuf_resize"
+symbol_kind: "func"
+signature: |
+  void mbuf_resize(struct mbuf *, size_t new_size);
+---
+
+Resize an Mbuf.
+
+If `new_size` is smaller than buffer's `len`, the
+resize is not performed. 
+

docs/c-api/mbuf.h/mbuf_trim.md

@@ -0,0 +1,10 @@
+---
+title: "mbuf_trim()"
+decl_name: "mbuf_trim"
+symbol_kind: "func"
+signature: |
+  void mbuf_trim(struct mbuf *);
+---
+
+Shrink an Mbuf by resizing its `size` to `len`. 
+

docs/c-api/mbuf.h/struct_mbuf.md

@@ -0,0 +1,14 @@
+---
+title: "struct mbuf"
+decl_name: "struct mbuf"
+symbol_kind: "struct"
+signature: |
+  struct mbuf {
+    char *buf;   /* Buffer pointer */
+    size_t len;  /* Data length. Data is located between offset 0 and len. */
+    size_t size; /* Buffer size allocated by realloc(1). Must be >= len */
+  };
+---
+
+Memory buffer descriptor 
+

docs/c-api/mqtt-broker.h/intro.md

@@ -0,0 +1,14 @@
+---
+title: "MQTT Broker"
+symbol_kind: "intro"
+decl_name: "mqtt-broker.h"
+items:
+  - { type: file, name: mg_mqtt_broker_init.md }
+  - { type: file, name: mg_mqtt_broker.md }
+  - { type: file, name: mg_mqtt_next.md }
+  - { type: file, name: struct_mg_mqtt_session.md }
+  - { type: file, name: struct_mg_mqtt_broker.md }
+---
+
+
+

docs/c-api/mqtt-broker.h/mg_mqtt_broker.md

@@ -0,0 +1,32 @@
+---
+title: "mg_mqtt_broker()"
+decl_name: "mg_mqtt_broker"
+symbol_kind: "func"
+signature: |
+  void mg_mqtt_broker(struct mg_connection *brk, int ev, void *data);
+---
+
+Process a MQTT broker message.
+
+Listening connection expects a pointer to an initialized `mg_mqtt_broker`
+structure in the `user_data` field.
+
+Basic usage:
+
+```c
+mg_mqtt_broker_init(&brk, NULL);
+
+if ((nc = mg_bind(&mgr, address, mg_mqtt_broker)) == NULL) {
+  // fail;
+}
+nc->user_data = &brk;
+```
+
+New incoming connections will receive a `mg_mqtt_session` structure
+in the connection `user_data`. The original `user_data` will be stored
+in the `user_data` field of the session structure. This allows the user
+handler to store user data before `mg_mqtt_broker` creates the session.
+
+Since only the MG_EV_ACCEPT message is processed by the listening socket,
+for most events the `user_data` will thus point to a `mg_mqtt_session`. 
+

docs/c-api/mqtt-broker.h/mg_mqtt_broker_init.md

@@ -0,0 +1,10 @@
+---
+title: "mg_mqtt_broker_init()"
+decl_name: "mg_mqtt_broker_init"
+symbol_kind: "func"
+signature: |
+  void mg_mqtt_broker_init(struct mg_mqtt_broker *brk, void *user_data);
+---
+
+Initialize a MQTT broker. 
+

docs/c-api/mqtt-broker.h/mg_mqtt_next.md

@@ -0,0 +1,18 @@
+---
+title: "mg_mqtt_next()"
+decl_name: "mg_mqtt_next"
+symbol_kind: "func"
+signature: |
+  struct mg_mqtt_session *mg_mqtt_next(struct mg_mqtt_broker *brk,
+                                       struct mg_mqtt_session *s);
+---
+
+Iterate over all mqtt sessions connections. Example:
+
+```c
+struct mg_mqtt_session *s;
+for (s = mg_mqtt_next(brk, NULL); s != NULL; s = mg_mqtt_next(brk, s)) {
+  // Do something
+}
+``` 
+

docs/c-api/mqtt-broker.h/struct_mg_mqtt_broker.md

@@ -0,0 +1,13 @@
+---
+title: "struct mg_mqtt_broker"
+decl_name: "struct mg_mqtt_broker"
+symbol_kind: "struct"
+signature: |
+  struct mg_mqtt_broker {
+    struct mg_mqtt_session *sessions; /* Session list */
+    void *user_data;                  /* User data */
+  };
+---
+
+MQTT broker. 
+

docs/c-api/mqtt-broker.h/struct_mg_mqtt_session.md

@@ -0,0 +1,17 @@
+---
+title: "struct mg_mqtt_session"
+decl_name: "struct mg_mqtt_session"
+symbol_kind: "struct"
+signature: |
+  struct mg_mqtt_session {
+    struct mg_mqtt_broker *brk;          /* Broker */
+    struct mg_mqtt_session *next, *prev; /* mg_mqtt_broker::sessions linkage */
+    struct mg_connection *nc;            /* Connection with the client */
+    size_t num_subscriptions;            /* Size of `subscriptions` array */
+    struct mg_mqtt_topic_expression *subscriptions;
+    void *user_data; /* User data */
+  };
+---
+
+MQTT session (Broker side). 
+

docs/c-api/mqtt.h/intro.md

@@ -0,0 +1,27 @@
+---
+title: "MQTT"
+symbol_kind: "intro"
+decl_name: "mqtt.h"
+items:
+  - { type: file, name: mg_set_protocol_mqtt.md }
+  - { type: file, name: mg_send_mqtt_handshake.md }
+  - { type: file, name: mg_send_mqtt_handshake_opt.md }
+  - { type: file, name: mg_mqtt_publish.md }
+  - { type: file, name: mg_mqtt_subscribe.md }
+  - { type: file, name: mg_mqtt_unsubscribe.md }
+  - { type: file, name: mg_mqtt_disconnect.md }
+  - { type: file, name: mg_mqtt_connack.md }
+  - { type: file, name: mg_mqtt_puback.md }
+  - { type: file, name: mg_mqtt_pubrec.md }
+  - { type: file, name: mg_mqtt_pubrel.md }
+  - { type: file, name: mg_mqtt_pubcomp.md }
+  - { type: file, name: mg_mqtt_suback.md }
+  - { type: file, name: mg_mqtt_unsuback.md }
+  - { type: file, name: mg_mqtt_ping.md }
+  - { type: file, name: mg_mqtt_pong.md }
+  - { type: file, name: mg_mqtt_next_subscribe_topic.md }
+  - { type: file, name: struct_mg_mqtt_topic_expression.md }
+---
+
+
+

docs/c-api/mqtt.h/mg_mqtt_connack.md

@@ -0,0 +1,10 @@
+---
+title: "mg_mqtt_connack()"
+decl_name: "mg_mqtt_connack"
+symbol_kind: "func"
+signature: |
+  void mg_mqtt_connack(struct mg_connection *nc, uint8_t return_code);
+---
+
+Send a CONNACK command with a given `return_code`. 
+

docs/c-api/mqtt.h/mg_mqtt_disconnect.md

@@ -0,0 +1,10 @@
+---
+title: "mg_mqtt_disconnect()"
+decl_name: "mg_mqtt_disconnect"
+symbol_kind: "func"
+signature: |
+  void mg_mqtt_disconnect(struct mg_connection *nc);
+---
+
+Send a DISCONNECT command. 
+

docs/c-api/mqtt.h/mg_mqtt_next_subscribe_topic.md

@@ -0,0 +1,15 @@
+---
+title: "mg_mqtt_next_subscribe_topic()"
+decl_name: "mg_mqtt_next_subscribe_topic"
+symbol_kind: "func"
+signature: |
+  int mg_mqtt_next_subscribe_topic(struct mg_mqtt_message *msg,
+                                   struct mg_str *topic, uint8_t *qos, int pos);
+---
+
+Extract the next topic expression from a SUBSCRIBE command payload.
+
+Topic expression name will point to a string in the payload buffer.
+Return the pos of the next topic expression or -1 when the list
+of topics is exhausted. 
+

docs/c-api/mqtt.h/mg_mqtt_ping.md

@@ -0,0 +1,10 @@
+---
+title: "mg_mqtt_ping()"
+decl_name: "mg_mqtt_ping"
+symbol_kind: "func"
+signature: |
+  void mg_mqtt_ping(struct mg_connection *nc);
+---
+
+Send a PINGREQ command. 
+

docs/c-api/mqtt.h/mg_mqtt_pong.md

@@ -0,0 +1,10 @@
+---
+title: "mg_mqtt_pong()"
+decl_name: "mg_mqtt_pong"
+symbol_kind: "func"
+signature: |
+  void mg_mqtt_pong(struct mg_connection *nc);
+---
+
+Send a PINGRESP command. 
+

docs/c-api/mqtt.h/mg_mqtt_puback.md

@@ -0,0 +1,10 @@
+---
+title: "mg_mqtt_puback()"
+decl_name: "mg_mqtt_puback"
+symbol_kind: "func"
+signature: |
+  void mg_mqtt_puback(struct mg_connection *nc, uint16_t message_id);
+---
+
+Send a PUBACK command with a given `message_id`. 
+

docs/c-api/mqtt.h/mg_mqtt_pubcomp.md

@@ -0,0 +1,10 @@
+---
+title: "mg_mqtt_pubcomp()"
+decl_name: "mg_mqtt_pubcomp"
+symbol_kind: "func"
+signature: |
+  void mg_mqtt_pubcomp(struct mg_connection *nc, uint16_t message_id);
+---
+
+Send a PUBCOMP command with a given `message_id`. 
+

docs/c-api/mqtt.h/mg_mqtt_publish.md

@@ -0,0 +1,12 @@
+---
+title: "mg_mqtt_publish()"
+decl_name: "mg_mqtt_publish"
+symbol_kind: "func"
+signature: |
+  void mg_mqtt_publish(struct mg_connection *nc, const char *topic,
+                       uint16_t message_id, int flags, const void *data,
+                       size_t len);
+---
+
+Publish a message to a given topic. 
+

docs/c-api/mqtt.h/mg_mqtt_pubrec.md

@@ -0,0 +1,10 @@
+---
+title: "mg_mqtt_pubrec()"
+decl_name: "mg_mqtt_pubrec"
+symbol_kind: "func"
+signature: |
+  void mg_mqtt_pubrec(struct mg_connection *nc, uint16_t message_id);
+---
+
+Send a PUBREC command with a given `message_id`. 
+

docs/c-api/mqtt.h/mg_mqtt_pubrel.md

@@ -0,0 +1,10 @@
+---
+title: "mg_mqtt_pubrel()"
+decl_name: "mg_mqtt_pubrel"
+symbol_kind: "func"
+signature: |
+  void mg_mqtt_pubrel(struct mg_connection *nc, uint16_t message_id);
+---
+
+Send a PUBREL command with a given `message_id`. 
+

docs/c-api/mqtt.h/mg_mqtt_suback.md

@@ -0,0 +1,12 @@
+---
+title: "mg_mqtt_suback()"
+decl_name: "mg_mqtt_suback"
+symbol_kind: "func"
+signature: |
+  void mg_mqtt_suback(struct mg_connection *nc, uint8_t *qoss, size_t qoss_len,
+                      uint16_t message_id);
+---
+
+Send a SUBACK command with a given `message_id`
+and a sequence of granted QoSs. 
+

docs/c-api/mqtt.h/mg_mqtt_subscribe.md

@@ -0,0 +1,12 @@
+---
+title: "mg_mqtt_subscribe()"
+decl_name: "mg_mqtt_subscribe"
+symbol_kind: "func"
+signature: |
+  void mg_mqtt_subscribe(struct mg_connection *nc,
+                         const struct mg_mqtt_topic_expression *topics,
+                         size_t topics_len, uint16_t message_id);
+---
+
+Subscribe to a bunch of topics. 
+

docs/c-api/mqtt.h/mg_mqtt_unsuback.md

@@ -0,0 +1,10 @@
+---
+title: "mg_mqtt_unsuback()"
+decl_name: "mg_mqtt_unsuback"
+symbol_kind: "func"
+signature: |
+  void mg_mqtt_unsuback(struct mg_connection *nc, uint16_t message_id);
+---
+
+Send a UNSUBACK command with a given `message_id`. 
+

docs/c-api/mqtt.h/mg_mqtt_unsubscribe.md

@@ -0,0 +1,11 @@
+---
+title: "mg_mqtt_unsubscribe()"
+decl_name: "mg_mqtt_unsubscribe"
+symbol_kind: "func"
+signature: |
+  void mg_mqtt_unsubscribe(struct mg_connection *nc, char **topics,
+                           size_t topics_len, uint16_t message_id);
+---
+
+Unsubscribe from a bunch of topics. 
+

docs/c-api/mqtt.h/mg_send_mqtt_handshake.md

@@ -0,0 +1,10 @@
+---
+title: "mg_send_mqtt_handshake()"
+decl_name: "mg_send_mqtt_handshake"
+symbol_kind: "func"
+signature: |
+  void mg_send_mqtt_handshake(struct mg_connection *nc, const char *client_id);
+---
+
+Send MQTT handshake. 
+

docs/c-api/mqtt.h/mg_send_mqtt_handshake_opt.md

@@ -0,0 +1,11 @@
+---
+title: "mg_send_mqtt_handshake_opt()"
+decl_name: "mg_send_mqtt_handshake_opt"
+symbol_kind: "func"
+signature: |
+  void mg_send_mqtt_handshake_opt(struct mg_connection *nc, const char *client_id,
+                                  struct mg_send_mqtt_handshake_opts);
+---
+
+Send MQTT handshake with optional parameters. 
+

docs/c-api/mqtt.h/mg_set_protocol_mqtt.md

@@ -0,0 +1,20 @@
+---
+title: "mg_set_protocol_mqtt()"
+decl_name: "mg_set_protocol_mqtt"
+symbol_kind: "func"
+signature: |
+  void mg_set_protocol_mqtt(struct mg_connection *nc);
+---
+
+Attach built-in MQTT event handler to the given connection.
+
+The user-defined event handler will receive following extra events:
+
+- MG_EV_MQTT_CONNACK
+- MG_EV_MQTT_PUBLISH
+- MG_EV_MQTT_PUBACK
+- MG_EV_MQTT_PUBREC
+- MG_EV_MQTT_PUBREL
+- MG_EV_MQTT_PUBCOMP
+- MG_EV_MQTT_SUBACK 
+

docs/c-api/mqtt.h/struct_mg_mqtt_topic_expression.md

@@ -0,0 +1,13 @@
+---
+title: "struct mg_mqtt_topic_expression"
+decl_name: "struct mg_mqtt_topic_expression"
+symbol_kind: "struct"
+signature: |
+  struct mg_mqtt_topic_expression {
+    const char *topic;
+    uint8_t qos;
+  };
+---
+
+puback 
+