diff --git a/docs/coap/client_example.md b/docs/coap/client-example.md similarity index 100% rename from docs/coap/client_example.md rename to docs/coap/client-example.md diff --git a/docs/coap/intro.md b/docs/coap/intro.md deleted file mode 100644 index 5561044f..00000000 --- a/docs/coap/intro.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: CoAP -items: - - { name: server_example.md } - - { name: client_example.md } - - { name: ../c-api/coap.h/ } ---- diff --git a/docs/coap/server_example.md b/docs/coap/server-example.md similarity index 100% rename from docs/coap/server_example.md rename to docs/coap/server-example.md diff --git a/docs/dns/client_example.md b/docs/dns/client_example.md deleted file mode 100644 index 29e94fa7..00000000 --- a/docs/dns/client_example.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: DNS client example ---- - -See https://github.com/cesanta/mongoose/blob/master/mongoose.c and search -for the `mg_resolve_async_eh()` function - that is the core of -built-in Mongoose async DNS resolver. diff --git a/docs/dns/server_example.md b/docs/dns/examples.md similarity index 89% rename from docs/dns/server_example.md rename to docs/dns/examples.md index 2145f735..f4957c48 100644 --- a/docs/dns/server_example.md +++ b/docs/dns/examples.md @@ -1,6 +1,7 @@ ---- -title: DNS server example ---- +# Examples + + +## DNS server example To create a DNS server, follow this pattern: @@ -71,3 +72,10 @@ int main(int argc, char *argv[]) { ``` See full [Captive DNS server example](https://github.com/cesanta/mongoose/tree/master/examples/captive_dns_server). + + +## DNS client example + +See https://github.com/cesanta/mongoose/blob/master/mongoose.c and search +for the `mg_resolve_async_eh()` function - that is the core of +built-in Mongoose async DNS resolver. diff --git a/docs/dns/intro.md b/docs/dns/intro.md deleted file mode 100644 index fb2b7a76..00000000 --- a/docs/dns/intro.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: DNS -items: - - { name: server_example.md } - - { name: client_example.md } - - { name: ../c-api/dns.h/ } - - { name: ../c-api/dns_server.h/ } ---- diff --git a/docs/http/cgi.md b/docs/http/cgi.md index 86b0a4f3..1601254f 100644 --- a/docs/http/cgi.md +++ b/docs/http/cgi.md @@ -1,6 +1,4 @@ ---- -title: CGI ---- +# CGI [CGI](https://en.wikipedia.org/wiki/Common_Gateway_Interface) is a simple mechanism to generate dynamic content. @@ -32,4 +30,4 @@ Example: NOTE: In the CGI handler we don't use explicitly a system call waitpid() for reaping zombie processes. Instead, we set the SIGCHLD handler to SIG_IGN. It will cause zombie processes to be reaped automatically. -CAUTION: not all OSes (e.g. QNX) reap zombies if SIGCHLD is ignored. \ No newline at end of file +CAUTION: not all OSes (e.g. QNX) reap zombies if SIGCHLD is ignored. diff --git a/docs/http/client_example.md b/docs/http/client-example.md similarity index 96% rename from docs/http/client_example.md rename to docs/http/client-example.md index 2b159a65..8d2088b7 100644 --- a/docs/http/client_example.md +++ b/docs/http/client-example.md @@ -1,6 +1,4 @@ ---- -title: HTTP client example ---- +# HTTP client example To create an HTTP client, follow this pattern: diff --git a/docs/http/digest_auth.md b/docs/http/digest-auth.md similarity index 79% rename from docs/http/digest_auth.md rename to docs/http/digest-auth.md index a49c95f9..2c5aef9f 100644 --- a/docs/http/digest_auth.md +++ b/docs/http/digest-auth.md @@ -1,6 +1,4 @@ ---- -title: Digest Authentication ---- +# Digest Authentication Mongoose has a built-in Digest (MD5) authentication support. In order to enable Digest authentication, create a file `.htpasswd` in the directory @@ -8,7 +6,7 @@ you would like to protect. That file should be in the format that Apache's `htdigest` utility. You can use either Apache `htdigest` utility, or -Mongoose pre-build binary (https://www.cesanta.com/products/binary) +Mongoose pre-build binary at https://www.cesanta.com/binary.html to add new users into that file: ``` diff --git a/docs/http/events.md b/docs/http/events.md index 5bd432fc..756e8e65 100644 --- a/docs/http/events.md +++ b/docs/http/events.md @@ -1,6 +1,4 @@ ---- -title: HTTP events ---- +#: HTTP events As discussed in the overview, `mg_set_protocol_http_websocket()` function parses incoming data, treats it as HTTP or WebSocket, and triggers high-level diff --git a/docs/http/files.md b/docs/http/files.md index e59d2519..9700b5c3 100644 --- a/docs/http/files.md +++ b/docs/http/files.md @@ -1,6 +1,4 @@ ---- -title: Serving files ---- +# Serving files API function `mg_serve_http()` makes it easy to serve files from a filesystem. Generally speaking, that function is an implementation of the HTTP server diff --git a/docs/http/intro.md b/docs/http/intro.md deleted file mode 100644 index 52e325c6..00000000 --- a/docs/http/intro.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: HTTP -items: - - { name: server_example.md } - - { name: client_example.md } - - { name: events.md } - - { name: files.md } - - { name: cgi.md } - - { name: ssi.md } - - { name: upload.md } - - { name: ssl.md } - - { name: digest_auth.md } - - { name: ../c-api/http.h/ } - - { name: ../c-api/http_server.h/ } - - { name: ../c-api/http_client.h/ } ---- diff --git a/docs/http/server_example.md b/docs/http/server-example.md similarity index 98% rename from docs/http/server_example.md rename to docs/http/server-example.md index 225beb40..5bb7e66b 100644 --- a/docs/http/server_example.md +++ b/docs/http/server-example.md @@ -1,6 +1,4 @@ ---- -title: HTTP server example ---- +# HTTP server example To create an HTTP server, follow this pattern: diff --git a/docs/http/ssi.md b/docs/http/ssi.md index 23c390e1..3f84f400 100644 --- a/docs/http/ssi.md +++ b/docs/http/ssi.md @@ -1,6 +1,4 @@ ---- -title: SSI ---- +# SSI Server Side Includes (SSI) is a simple interpreted server-side scripting language which is most commonly used to include the contents of a file diff --git a/docs/http/ssl.md b/docs/http/ssl.md index c317e57a..c15fc90c 100644 --- a/docs/http/ssl.md +++ b/docs/http/ssl.md @@ -1,6 +1,4 @@ ---- -title: Enabling HTTPS ---- +# Enabling SSL (HTTPS) To enable SSL on the server side, please follow these steps: diff --git a/docs/http/upload.md b/docs/http/upload.md index 21caf07e..7f40d451 100644 --- a/docs/http/upload.md +++ b/docs/http/upload.md @@ -1,14 +1,12 @@ ---- -title: Handling file uploads ---- +# Handling file uploads In order to handle file uploads, use the following HTML snippet: ```HTML -<form method="POST" action="/upload" enctype="multipart/form-data"> - <input type="file" name="file"> - <input type="submit" value="Upload"> -</form> +
+ + +
``` Uploaded files will be sent to the `/upload` endpoint via the `POST` request. diff --git a/docs/mqtt/client_example.md b/docs/mqtt/client_example.md deleted file mode 100644 index 11f55707..00000000 --- a/docs/mqtt/client_example.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: MQTT client example ---- - -See https://github.com/cesanta/mongoose/tree/master/examples/mqtt_client diff --git a/docs/mqtt/examples.md b/docs/mqtt/examples.md new file mode 100644 index 00000000..1db73d22 --- /dev/null +++ b/docs/mqtt/examples.md @@ -0,0 +1,5 @@ +# Examples + +- [Client example](https://github.com/cesanta/mongoose/tree/master/examples/mqtt_client) +- [Server example](https://github.com/cesanta/mongoose/tree/master/examples/mqtt_broker) + diff --git a/docs/mqtt/intro.md b/docs/mqtt/intro.md deleted file mode 100644 index 9771d02f..00000000 --- a/docs/mqtt/intro.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: MQTT -items: - - { name: server_example.md } - - { name: client_example.md } - - { name: ../c-api/mqtt.h/ } - - { name: ../c-api/mqtt_server.h/ } ---- diff --git a/docs/mqtt/server_example.md b/docs/mqtt/server_example.md deleted file mode 100644 index b1d449ca..00000000 --- a/docs/mqtt/server_example.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: MQTT server example ---- - -See https://github.com/cesanta/mongoose/tree/master/examples/mqtt_broker diff --git a/docs/overview/build-options.md b/docs/overview/build-options.md new file mode 100644 index 00000000..6f7dee3a --- /dev/null +++ b/docs/overview/build-options.md @@ -0,0 +1,59 @@ +# 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 the executable's 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 the `-D ` +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 +``` +## Enabling flags + +- `MG_ENABLE_SSL` Enable [SSL/TLS support](https://docs.cesanta.com/mongoose/master/#/http/ssl.md/) (OpenSSL API) +- `MG_ENABLE_IPV6` Enable IPv6 support +- `MG_ENABLE_MQTT` enable [MQTT client](https://docs.cesanta.com/mongoose/master/#/mqtt/client_example.md/) (on by default, set to 0 to disable) +- `MG_ENABLE_MQTT_BROKER` enable [MQTT broker](https://docs.cesanta.com/mongoose/master/#/mqtt/server_example.md/) +- `MG_ENABLE_DNS_SERVER` enable DNS server +- `MG_ENABLE_COAP` enable CoAP protocol +- `MG_ENABLE_HTTP` Enable HTTP protocol support (on by default, set to 0 to disable) +- `MG_ENABLE_HTTP_CGI` Enable [CGI](https://docs.cesanta.com/mongoose/master/#/http/cgi.md/) support +- `MG_ENABLE_HTTP_SSI` Enable [Server Side Includes](https://docs.cesanta.com/mongoose/master/#/http/ssi.md/) support +- `MG_ENABLE_HTTP_SSI_EXEC` Enable SSI `exec` operator +- `MG_ENABLE_HTTP_WEBDAV` enable WebDAV extensions to HTTP +- `MG_ENABLE_HTTP_WEBSOCKET` enable WebSocket extension to HTTP (on by default, =0 to disable) +- `MG_ENABLE_BROADCAST` enable `mg_broadcast()` API +- `MG_ENABLE_GETADDRINFO` enable `getaddrinfo()` in `mg_resolve2()` +- `MG_ENABLE_THREADS` enable `mg_start_thread()` API + +## Disabling flags + +- `MG_DISABLE_HTTP_DIGEST_AUTH` disable HTTP Digest (MD5) authorisation support +- `CS_DISABLE_SHA1` disable SHA1 support (used by WebSocket) +- `CS_DISABLE_MD5` disable MD5 support (used by HTTP auth) +- `MG_DISABLE_HTTP_KEEP_ALIVE` useful for embedded systems to save resources + +## 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_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. + +## Tunables + +- `MG_MALLOC`, `MG_CALLOC`, `MG_REALLOC`, `MG_FREE` allow you to a 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. +- `MG_USER_FILE_FUNCTIONS` allow you to use custom file operation, by defining you own `mg_stat`, `mg_fopen`, `mg_open`, `mg_fread` and `mg_fwrite` functions + diff --git a/docs/overview/build-options/disabling-flags.md b/docs/overview/build-options/disabling-flags.md deleted file mode 100644 index 767438fe..00000000 --- a/docs/overview/build-options/disabling-flags.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Disabling flags ---- - -- `MG_DISABLE_HTTP_DIGEST_AUTH` disable HTTP Digest (MD5) authorisation support -- `CS_DISABLE_SHA1` disable SHA1 support (used by WebSocket) -- `CS_DISABLE_MD5` disable MD5 support (used by HTTP auth) -- `MG_DISABLE_HTTP_KEEP_ALIVE` useful for embedded systems to save resources diff --git a/docs/overview/build-options/enabling-flags.md b/docs/overview/build-options/enabling-flags.md deleted file mode 100644 index 1159c177..00000000 --- a/docs/overview/build-options/enabling-flags.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Enabling flags ---- - -- `MG_ENABLE_SSL` Enable [SSL/TLS support](https://docs.cesanta.com/mongoose/master/#/http/ssl.md/) (OpenSSL API) -- `MG_ENABLE_IPV6` Enable IPv6 support -- `MG_ENABLE_MQTT` enable [MQTT client](https://docs.cesanta.com/mongoose/master/#/mqtt/client_example.md/) (on by default, set to 0 to disable) -- `MG_ENABLE_MQTT_BROKER` enable [MQTT broker](https://docs.cesanta.com/mongoose/master/#/mqtt/server_example.md/) -- `MG_ENABLE_DNS_SERVER` enable DNS server -- `MG_ENABLE_COAP` enable CoAP protocol -- `MG_ENABLE_HTTP` Enable HTTP protocol support (on by default, set to 0 to disable) -- `MG_ENABLE_HTTP_CGI` Enable [CGI](https://docs.cesanta.com/mongoose/master/#/http/cgi.md/) support -- `MG_ENABLE_HTTP_SSI` Enable [Server Side Includes](https://docs.cesanta.com/mongoose/master/#/http/ssi.md/) support -- `MG_ENABLE_HTTP_SSI_EXEC` Enable SSI `exec` operator -- `MG_ENABLE_HTTP_WEBDAV` enable WebDAV extensions to HTTP -- `MG_ENABLE_HTTP_WEBSOCKET` enable WebSocket extension to HTTP (on by default, =0 to disable) -- `MG_ENABLE_BROADCAST` enable `mg_broadcast()` API -- `MG_ENABLE_GETADDRINFO` enable `getaddrinfo()` in `mg_resolve2()` -- `MG_ENABLE_THREADS` enable `mg_start_thread()` API diff --git a/docs/overview/build-options/intro.md b/docs/overview/build-options/intro.md deleted file mode 100644 index 93e67ef0..00000000 --- a/docs/overview/build-options/intro.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -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 the executable's 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 the `-D ` -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 -``` diff --git a/docs/overview/build-options/platform-spec.md b/docs/overview/build-options/platform-spec.md deleted file mode 100644 index 5a4f1761..00000000 --- a/docs/overview/build-options/platform-spec.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -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_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. diff --git a/docs/overview/build-options/tunables.md b/docs/overview/build-options/tunables.md deleted file mode 100644 index c9944c4c..00000000 --- a/docs/overview/build-options/tunables.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Tunables ---- - -- `MG_MALLOC`, `MG_CALLOC`, `MG_REALLOC`, `MG_FREE` allow you to a 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. -- `MG_USER_FILE_FUNCTIONS` allow you to use custom file operation, by defining you own `mg_stat`, `mg_fopen`, `mg_open`, `mg_fread` and `mg_fwrite` functions \ No newline at end of file diff --git a/docs/overview/concept.md b/docs/overview/concept.md index 034dfb92..52660abb 100644 --- a/docs/overview/concept.md +++ b/docs/overview/concept.md @@ -1,6 +1,4 @@ ---- -title: Design Concept ---- +# Design Concept Mongoose has three basic data structures: diff --git a/docs/overview/conn-flags.md b/docs/overview/conn-flags.md index eca0003a..aeb642ab 100644 --- a/docs/overview/conn-flags.md +++ b/docs/overview/conn-flags.md @@ -1,6 +1,4 @@ ---- -title: Connection flags ---- +# Connection flags Each connection has a `flags` bit field. Some flags are set by Mongoose, for example if a user creates an outbound UDP connection using a `udp://1.2.3.4:5678` diff --git a/docs/overview/event-handler.md b/docs/overview/event-handler.md index 2c2a5f9c..bb14ba19 100644 --- a/docs/overview/event-handler.md +++ b/docs/overview/event-handler.md @@ -1,6 +1,4 @@ ---- -title: Event handler function ---- +# Event handler function Each connection has an event handler function associated with it. That function must be implemented by the user. Event handler is the key element of the Mongoose diff --git a/docs/overview/events.md b/docs/overview/events.md index 9cde686a..152f4405 100644 --- a/docs/overview/events.md +++ b/docs/overview/events.md @@ -1,6 +1,4 @@ ---- -title: Events ---- +# Events Mongoose accepts incoming connections, reads and writes data and calls specified event handlers for each connection when appropriate. A typical event diff --git a/docs/overview/intro.md b/docs/overview/intro.md index 9f8a0809..4f7c3607 100644 --- a/docs/overview/intro.md +++ b/docs/overview/intro.md @@ -1,15 +1,4 @@ ---- -title: Overview -items: -# - { name: usage-example.md } - - { name: concept.md } - - { name: mbufs.md } - - { name: event-handler.md } - - { name: events.md } - - { name: conn-flags.md } - - { name: build-options } - - { name: usage-example.md } ---- +# Introduction Mongoose is a networking library written in C. It is a swiss army knife for embedded network programming. diff --git a/docs/overview/mbufs.md b/docs/overview/mbufs.md index 095cdce3..25d92f0e 100644 --- a/docs/overview/mbufs.md +++ b/docs/overview/mbufs.md @@ -1,6 +1,4 @@ ---- -title: Memory buffers ---- +# Memory buffers Each connection has a send and receive buffer, `struct mg_connection::send_mbuf` and `struct mg_connection::recv_mbuf` respectively. When data arrives, @@ -11,4 +9,4 @@ When Mongoose successfully writes data to the socket, it discards data from `struct mg_connection::send_mbuf` and sends an `MG_EV_SEND` event. When the connection is closed, an `MG_EV_CLOSE` event is sent. -![](media/mbuf.png) +![](/docs/media/mbuf.png) diff --git a/docs/overview/usage-example.md b/docs/overview/usage-example.md index 9c2ce0fd..b19deb4c 100644 --- a/docs/overview/usage-example.md +++ b/docs/overview/usage-example.md @@ -1,6 +1,4 @@ ---- -title: Example - TCP echo server ---- +# Example - TCP echo server - Copy `mongoose.c` and `mongoose.h` to your build tree - Write code that uses the Mongoose API, e.g. in `my_app.c`