diff --git a/docs/build-options/disabling-flags.md b/docs/build-options/disabling-flags.md deleted file mode 100644 index c88e25b8..00000000 --- a/docs/build-options/disabling-flags.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -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 diff --git a/docs/build-options/enabling-flags.md b/docs/build-options/enabling-flags.md deleted file mode 100644 index 5dfd6459..00000000 --- a/docs/build-options/enabling-flags.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -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()` diff --git a/docs/build-options/intro.md b/docs/build-options/intro.md deleted file mode 100644 index f418a963..00000000 --- a/docs/build-options/intro.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -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 ` -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 -``` diff --git a/docs/build-options/items.json b/docs/build-options/items.json deleted file mode 100644 index 2d8c57bd..00000000 --- a/docs/build-options/items.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "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" } - ] -} diff --git a/docs/build-options/platform-spec.md b/docs/build-options/platform-spec.md deleted file mode 100644 index 408045a8..00000000 --- a/docs/build-options/platform-spec.md +++ /dev/null @@ -1,10 +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_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. diff --git a/docs/build-options/tunables.md b/docs/build-options/tunables.md deleted file mode 100644 index 1eeefe42..00000000 --- a/docs/build-options/tunables.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -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. diff --git a/docs/build_opts.adoc b/docs/build_opts.adoc new file mode 100644 index 00000000..ee6d44a5 --- /dev/null +++ b/docs/build_opts.adoc @@ -0,0 +1,54 @@ + +== 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 ` +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 +``` + +=== 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()` + +=== 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 + +=== 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. + +=== 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. diff --git a/docs/c-api/coap.h/intro.md b/docs/c-api/coap.h/intro.md deleted file mode 100644 index 764f0777..00000000 --- a/docs/c-api/coap.h/intro.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -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) ... -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- -``` - diff --git a/docs/c-api/coap.h/items.json b/docs/c-api/coap.h/items.json deleted file mode 100644 index de1889c4..00000000 --- a/docs/c-api/coap.h/items.json +++ /dev/null @@ -1,44 +0,0 @@ -{ - "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" - } - ] -} diff --git a/docs/c-api/coap.h/mg_coap_add_option.md b/docs/c-api/coap.h/mg_coap_add_option.md deleted file mode 100644 index f56887e5..00000000 --- a/docs/c-api/coap.h/mg_coap_add_option.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -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. - diff --git a/docs/c-api/coap.h/mg_coap_compose.md b/docs/c-api/coap.h/mg_coap_compose.md deleted file mode 100644 index 844c1b61..00000000 --- a/docs/c-api/coap.h/mg_coap_compose.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -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()` - diff --git a/docs/c-api/coap.h/mg_coap_free_options.md b/docs/c-api/coap.h/mg_coap_free_options.md deleted file mode 100644 index 39d07d44..00000000 --- a/docs/c-api/coap.h/mg_coap_free_options.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -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. - diff --git a/docs/c-api/coap.h/mg_coap_parse.md b/docs/c-api/coap.h/mg_coap_parse.md deleted file mode 100644 index 2f3bc0c6..00000000 --- a/docs/c-api/coap.h/mg_coap_parse.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -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()` - diff --git a/docs/c-api/coap.h/mg_coap_send_ack.md b/docs/c-api/coap.h/mg_coap_send_ack.md deleted file mode 100644 index 5cdd0c1d..00000000 --- a/docs/c-api/coap.h/mg_coap_send_ack.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -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()` - diff --git a/docs/c-api/coap.h/mg_coap_send_message.md b/docs/c-api/coap.h/mg_coap_send_message.md deleted file mode 100644 index 34bf3c87..00000000 --- a/docs/c-api/coap.h/mg_coap_send_message.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -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)` - diff --git a/docs/c-api/coap.h/mg_set_protocol_coap.md b/docs/c-api/coap.h/mg_set_protocol_coap.md deleted file mode 100644 index 60981fb6..00000000 --- a/docs/c-api/coap.h/mg_set_protocol_coap.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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 - diff --git a/docs/c-api/coap.h/struct_mg_coap_message.md b/docs/c-api/coap.h/struct_mg_coap_message.md deleted file mode 100644 index 0ea618a9..00000000 --- a/docs/c-api/coap.h/struct_mg_coap_message.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -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. - diff --git a/docs/c-api/coap.h/struct_mg_coap_option.md b/docs/c-api/coap.h/struct_mg_coap_option.md deleted file mode 100644 index b5eeb15f..00000000 --- a/docs/c-api/coap.h/struct_mg_coap_option.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -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. - diff --git a/docs/c-api/dns-server.h/intro.md b/docs/c-api/dns-server.h/intro.md deleted file mode 100644 index 8ac224dd..00000000 --- a/docs/c-api/dns-server.h/intro.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "DNS server" -symbol_kind: "intro" -decl_name: "dns-server.h" ---- - -Disabled by default; enable with `-DMG_ENABLE_DNS_SERVER`. - diff --git a/docs/c-api/dns-server.h/items.json b/docs/c-api/dns-server.h/items.json deleted file mode 100644 index feea0c96..00000000 --- a/docs/c-api/dns-server.h/items.json +++ /dev/null @@ -1,20 +0,0 @@ -{ - "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" - } - ] -} diff --git a/docs/c-api/dns-server.h/mg_dns_create_reply.md b/docs/c-api/dns-server.h/mg_dns_create_reply.md deleted file mode 100644 index b616c925..00000000 --- a/docs/c-api/dns-server.h/mg_dns_create_reply.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -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); -``` - diff --git a/docs/c-api/dns-server.h/mg_dns_reply_record.md b/docs/c-api/dns-server.h/mg_dns_reply_record.md deleted file mode 100644 index a247c8ec..00000000 --- a/docs/c-api/dns-server.h/mg_dns_reply_record.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -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. - diff --git a/docs/c-api/dns-server.h/mg_dns_send_reply.md b/docs/c-api/dns-server.h/mg_dns_send_reply.md deleted file mode 100644 index d5b15de4..00000000 --- a/docs/c-api/dns-server.h/mg_dns_send_reply.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -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. - diff --git a/docs/c-api/dns.h/intro.md b/docs/c-api/dns.h/intro.md deleted file mode 100644 index d9522b18..00000000 --- a/docs/c-api/dns.h/intro.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "DNS" -symbol_kind: "intro" -decl_name: "dns.h" ---- - - - diff --git a/docs/c-api/dns.h/items.json b/docs/c-api/dns.h/items.json deleted file mode 100644 index 8d21dd80..00000000 --- a/docs/c-api/dns.h/items.json +++ /dev/null @@ -1,48 +0,0 @@ -{ - "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_questions.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" - } - ] -} diff --git a/docs/c-api/dns.h/mg_dns_copy_questions.md b/docs/c-api/dns.h/mg_dns_copy_questions.md deleted file mode 100644 index 9fc2091f..00000000 --- a/docs/c-api/dns.h/mg_dns_copy_questions.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -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. - diff --git a/docs/c-api/dns.h/mg_dns_encode_record.md b/docs/c-api/dns.h/mg_dns_encode_record.md deleted file mode 100644 index 4b8a9850..00000000 --- a/docs/c-api/dns.h/mg_dns_encode_record.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -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. - diff --git a/docs/c-api/dns.h/mg_dns_insert_header.md b/docs/c-api/dns.h/mg_dns_insert_header.md deleted file mode 100644 index 0a9d7dae..00000000 --- a/docs/c-api/dns.h/mg_dns_insert_header.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -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. - diff --git a/docs/c-api/dns.h/mg_dns_parse_record_data.md b/docs/c-api/dns.h/mg_dns_parse_record_data.md deleted file mode 100644 index d8239bef..00000000 --- a/docs/c-api/dns.h/mg_dns_parse_record_data.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -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 - diff --git a/docs/c-api/dns.h/mg_dns_uncompress_name.md b/docs/c-api/dns.h/mg_dns_uncompress_name.md deleted file mode 100644 index 3db03df8..00000000 --- a/docs/c-api/dns.h/mg_dns_uncompress_name.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -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. - diff --git a/docs/c-api/dns.h/mg_parse_dns.md b/docs/c-api/dns.h/mg_parse_dns.md deleted file mode 100644 index 3e28efee..00000000 --- a/docs/c-api/dns.h/mg_parse_dns.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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. - diff --git a/docs/c-api/dns.h/mg_send_dns_query.md b/docs/c-api/dns.h/mg_send_dns_query.md deleted file mode 100644 index 5dd22c36..00000000 --- a/docs/c-api/dns.h/mg_send_dns_query.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -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. - diff --git a/docs/c-api/dns.h/mg_set_protocol_dns.md b/docs/c-api/dns.h/mg_set_protocol_dns.md deleted file mode 100644 index 7d7d0dc4..00000000 --- a/docs/c-api/dns.h/mg_set_protocol_dns.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -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. - diff --git a/docs/c-api/dns.h/struct_mg_dns_message.md b/docs/c-api/dns.h/struct_mg_dns_message.md deleted file mode 100644 index 9838bec9..00000000 --- a/docs/c-api/dns.h/struct_mg_dns_message.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -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). - diff --git a/docs/c-api/dns.h/struct_mg_dns_resource_record.md b/docs/c-api/dns.h/struct_mg_dns_resource_record.md deleted file mode 100644 index 8ff7af40..00000000 --- a/docs/c-api/dns.h/struct_mg_dns_resource_record.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -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. - diff --git a/docs/c-api/http.h/intro.md b/docs/c-api/http.h/intro.md deleted file mode 100644 index 73020471..00000000 --- a/docs/c-api/http.h/intro.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "HTTP + Websocket" -symbol_kind: "intro" -decl_name: "http.h" ---- - - - diff --git a/docs/c-api/http.h/items.json b/docs/c-api/http.h/items.json deleted file mode 100644 index a8bd24e0..00000000 --- a/docs/c-api/http.h/items.json +++ /dev/null @@ -1,128 +0,0 @@ -{ - "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" - } - ] -} diff --git a/docs/c-api/http.h/mg_connect_http.md b/docs/c-api/http.h/mg_connect_http.md deleted file mode 100644 index b897be0c..00000000 --- a/docs/c-api/http.h/mg_connect_http.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -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"); -``` - diff --git a/docs/c-api/http.h/mg_connect_http_opt.md b/docs/c-api/http.h/mg_connect_http_opt.md deleted file mode 100644 index be68a67f..00000000 --- a/docs/c-api/http.h/mg_connect_http_opt.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -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 - diff --git a/docs/c-api/http.h/mg_connect_ws.md b/docs/c-api/http.h/mg_connect_ws.md deleted file mode 100644 index 417279c8..00000000 --- a/docs/c-api/http.h/mg_connect_ws.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -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); -``` - diff --git a/docs/c-api/http.h/mg_connect_ws_opt.md b/docs/c-api/http.h/mg_connect_ws_opt.md deleted file mode 100644 index 3ab91083..00000000 --- a/docs/c-api/http.h/mg_connect_ws_opt.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -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 - diff --git a/docs/c-api/http.h/mg_file_upload_handler.md b/docs/c-api/http.h/mg_file_upload_handler.md deleted file mode 100644 index b0459676..00000000 --- a/docs/c-api/http.h/mg_file_upload_handler.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -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; - } -} -``` - diff --git a/docs/c-api/http.h/mg_fu_fname_fn.md b/docs/c-api/http.h/mg_fu_fname_fn.md deleted file mode 100644 index 78aa7c8b..00000000 --- a/docs/c-api/http.h/mg_fu_fname_fn.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -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()`. - diff --git a/docs/c-api/http.h/mg_get_http_header.md b/docs/c-api/http.h/mg_get_http_header.md deleted file mode 100644 index 5c6d85ba..00000000 --- a/docs/c-api/http.h/mg_get_http_header.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -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"); - diff --git a/docs/c-api/http.h/mg_get_http_var.md b/docs/c-api/http.h/mg_get_http_var.md deleted file mode 100644 index cc54c2eb..00000000 --- a/docs/c-api/http.h/mg_get_http_var.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -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. - diff --git a/docs/c-api/http.h/mg_http_create_digest_auth_header.md b/docs/c-api/http.h/mg_http_create_digest_auth_header.md deleted file mode 100644 index dd98fdc1..00000000 --- a/docs/c-api/http.h/mg_http_create_digest_auth_header.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -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. - diff --git a/docs/c-api/http.h/mg_http_parse_header.md b/docs/c-api/http.h/mg_http_parse_header.md deleted file mode 100644 index cd7beb6e..00000000 --- a/docs/c-api/http.h/mg_http_parse_header.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -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. - diff --git a/docs/c-api/http.h/mg_parse_http.md b/docs/c-api/http.h/mg_parse_http.md deleted file mode 100644 index 068ddc16..00000000 --- a/docs/c-api/http.h/mg_parse_http.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -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. - diff --git a/docs/c-api/http.h/mg_parse_multipart.md b/docs/c-api/http.h/mg_parse_multipart.md deleted file mode 100644 index 3eb82cdb..00000000 --- a/docs/c-api/http.h/mg_parse_multipart.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -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; -``` - diff --git a/docs/c-api/http.h/mg_printf_html_escape.md b/docs/c-api/http.h/mg_printf_html_escape.md deleted file mode 100644 index fd1ff3e0..00000000 --- a/docs/c-api/http.h/mg_printf_html_escape.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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. - diff --git a/docs/c-api/http.h/mg_printf_http_chunk.md b/docs/c-api/http.h/mg_printf_http_chunk.md deleted file mode 100644 index a8e6d142..00000000 --- a/docs/c-api/http.h/mg_printf_http_chunk.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -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()`. - diff --git a/docs/c-api/http.h/mg_printf_websocket_frame.md b/docs/c-api/http.h/mg_printf_websocket_frame.md deleted file mode 100644 index a6561299..00000000 --- a/docs/c-api/http.h/mg_printf_websocket_frame.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -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. - diff --git a/docs/c-api/http.h/mg_register_http_endpoint.md b/docs/c-api/http.h/mg_register_http_endpoint.md deleted file mode 100644 index eefbe99e..00000000 --- a/docs/c-api/http.h/mg_register_http_endpoint.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -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); -} -``` - diff --git a/docs/c-api/http.h/mg_send_head.md b/docs/c-api/http.h/mg_send_head.md deleted file mode 100644 index cd18d36c..00000000 --- a/docs/c-api/http.h/mg_send_head.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -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. - diff --git a/docs/c-api/http.h/mg_send_http_chunk.md b/docs/c-api/http.h/mg_send_http_chunk.md deleted file mode 100644 index 6d017fbb..00000000 --- a/docs/c-api/http.h/mg_send_http_chunk.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -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 -``` - diff --git a/docs/c-api/http.h/mg_send_response_line.md b/docs/c-api/http.h/mg_send_response_line.md deleted file mode 100644 index 8f62d717..00000000 --- a/docs/c-api/http.h/mg_send_response_line.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -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 - diff --git a/docs/c-api/http.h/mg_send_websocket_frame.md b/docs/c-api/http.h/mg_send_websocket_frame.md deleted file mode 100644 index bcc5d0c5..00000000 --- a/docs/c-api/http.h/mg_send_websocket_frame.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -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. - diff --git a/docs/c-api/http.h/mg_send_websocket_framev.md b/docs/c-api/http.h/mg_send_websocket_framev.md deleted file mode 100644 index 4eb3709f..00000000 --- a/docs/c-api/http.h/mg_send_websocket_framev.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -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. - diff --git a/docs/c-api/http.h/mg_send_websocket_handshake.md b/docs/c-api/http.h/mg_send_websocket_handshake.md deleted file mode 100644 index 20ee7017..00000000 --- a/docs/c-api/http.h/mg_send_websocket_handshake.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -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` - diff --git a/docs/c-api/http.h/mg_send_websocket_handshake2.md b/docs/c-api/http.h/mg_send_websocket_handshake2.md deleted file mode 100644 index 27c5c3b8..00000000 --- a/docs/c-api/http.h/mg_send_websocket_handshake2.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -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. - diff --git a/docs/c-api/http.h/mg_serve_http.md b/docs/c-api/http.h/mg_serve_http.md deleted file mode 100644 index 22b32688..00000000 --- a/docs/c-api/http.h/mg_serve_http.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -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; - } -} -``` - diff --git a/docs/c-api/http.h/mg_set_protocol_http_websocket.md b/docs/c-api/http.h/mg_set_protocol_http_websocket.md deleted file mode 100644 index 9dcefcba..00000000 --- a/docs/c-api/http.h/mg_set_protocol_http_websocket.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -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 - diff --git a/docs/c-api/http.h/mg_url_decode.md b/docs/c-api/http.h/mg_url_decode.md deleted file mode 100644 index 9e2f7e78..00000000 --- a/docs/c-api/http.h/mg_url_decode.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -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`. - diff --git a/docs/c-api/http.h/struct_http_message.md b/docs/c-api/http.h/struct_http_message.md deleted file mode 100644 index 60eae685..00000000 --- a/docs/c-api/http.h/struct_http_message.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -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¶m2=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 - diff --git a/docs/c-api/http.h/struct_mg_http_multipart_part.md b/docs/c-api/http.h/struct_mg_http_multipart_part.md deleted file mode 100644 index cd2d0c2e..00000000 --- a/docs/c-api/http.h/struct_mg_http_multipart_part.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -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 - diff --git a/docs/c-api/http.h/struct_mg_serve_http_opts.md b/docs/c-api/http.h/struct_mg_serve_http_opts.md deleted file mode 100644 index c0fafeed..00000000 --- a/docs/c-api/http.h/struct_mg_serve_http_opts.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -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. - diff --git a/docs/c-api/http.h/struct_websocket_message.md b/docs/c-api/http.h/struct_websocket_message.md deleted file mode 100644 index 37b7912a..00000000 --- a/docs/c-api/http.h/struct_websocket_message.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -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 - diff --git a/docs/c-api/items.json b/docs/c-api/items.json deleted file mode 100644 index 1133954a..00000000 --- a/docs/c-api/items.json +++ /dev/null @@ -1,44 +0,0 @@ -{ - "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" - } - ] -} diff --git a/docs/c-api/json-rpc.h/intro.md b/docs/c-api/json-rpc.h/intro.md deleted file mode 100644 index 8d04b623..00000000 --- a/docs/c-api/json-rpc.h/intro.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "JSON-RPC" -symbol_kind: "intro" -decl_name: "json-rpc.h" ---- - - - diff --git a/docs/c-api/json-rpc.h/items.json b/docs/c-api/json-rpc.h/items.json deleted file mode 100644 index 6fc30176..00000000 --- a/docs/c-api/json-rpc.h/items.json +++ /dev/null @@ -1,44 +0,0 @@ -{ - "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" - } - ] -} diff --git a/docs/c-api/json-rpc.h/mg_rpc_create_error.md b/docs/c-api/json-rpc.h/mg_rpc_create_error.md deleted file mode 100644 index b6910e02..00000000 --- a/docs/c-api/json-rpc.h/mg_rpc_create_error.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -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 - diff --git a/docs/c-api/json-rpc.h/mg_rpc_create_reply.md b/docs/c-api/json-rpc.h/mg_rpc_create_reply.md deleted file mode 100644 index 58a37365..00000000 --- a/docs/c-api/json-rpc.h/mg_rpc_create_reply.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -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 - diff --git a/docs/c-api/json-rpc.h/mg_rpc_create_request.md b/docs/c-api/json-rpc.h/mg_rpc_create_request.md deleted file mode 100644 index 28c83e40..00000000 --- a/docs/c-api/json-rpc.h/mg_rpc_create_request.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -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 - diff --git a/docs/c-api/json-rpc.h/mg_rpc_create_std_error.md b/docs/c-api/json-rpc.h/mg_rpc_create_std_error.md deleted file mode 100644 index b682431c..00000000 --- a/docs/c-api/json-rpc.h/mg_rpc_create_std_error.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -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)` - diff --git a/docs/c-api/json-rpc.h/mg_rpc_dispatch.md b/docs/c-api/json-rpc.h/mg_rpc_dispatch.md deleted file mode 100644 index d58f5026..00000000 --- a/docs/c-api/json-rpc.h/mg_rpc_dispatch.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -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. - diff --git a/docs/c-api/json-rpc.h/mg_rpc_parse_reply.md b/docs/c-api/json-rpc.h/mg_rpc_parse_reply.md deleted file mode 100644 index 36fad920..00000000 --- a/docs/c-api/json-rpc.h/mg_rpc_parse_reply.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -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` - diff --git a/docs/c-api/json-rpc.h/struct_mg_rpc_error.md b/docs/c-api/json-rpc.h/struct_mg_rpc_error.md deleted file mode 100644 index b2bff13b..00000000 --- a/docs/c-api/json-rpc.h/struct_mg_rpc_error.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -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 - diff --git a/docs/c-api/json-rpc.h/struct_mg_rpc_reply.md b/docs/c-api/json-rpc.h/struct_mg_rpc_reply.md deleted file mode 100644 index fd606026..00000000 --- a/docs/c-api/json-rpc.h/struct_mg_rpc_reply.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -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 - diff --git a/docs/c-api/json-rpc.h/struct_mg_rpc_request.md b/docs/c-api/json-rpc.h/struct_mg_rpc_request.md deleted file mode 100644 index fc0bb8ae..00000000 --- a/docs/c-api/json-rpc.h/struct_mg_rpc_request.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -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 - diff --git a/docs/c-api/mbuf.h/intro.md b/docs/c-api/mbuf.h/intro.md deleted file mode 100644 index 49c6b7fc..00000000 --- a/docs/c-api/mbuf.h/intro.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mbuf.h/items.json b/docs/c-api/mbuf.h/items.json deleted file mode 100644 index 9f5f2123..00000000 --- a/docs/c-api/mbuf.h/items.json +++ /dev/null @@ -1,40 +0,0 @@ -{ - "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" - } - ] -} diff --git a/docs/c-api/mbuf.h/mbuf_append.md b/docs/c-api/mbuf.h/mbuf_append.md deleted file mode 100644 index ea803926..00000000 --- a/docs/c-api/mbuf.h/mbuf_append.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mbuf.h/mbuf_free.md b/docs/c-api/mbuf.h/mbuf_free.md deleted file mode 100644 index 273d24b9..00000000 --- a/docs/c-api/mbuf.h/mbuf_free.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mbuf.h/mbuf_init.md b/docs/c-api/mbuf.h/mbuf_init.md deleted file mode 100644 index 960f92b8..00000000 --- a/docs/c-api/mbuf.h/mbuf_init.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mbuf.h/mbuf_insert.md b/docs/c-api/mbuf.h/mbuf_insert.md deleted file mode 100644 index b9e84a71..00000000 --- a/docs/c-api/mbuf.h/mbuf_insert.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mbuf.h/mbuf_remove.md b/docs/c-api/mbuf.h/mbuf_remove.md deleted file mode 100644 index b4ce18c9..00000000 --- a/docs/c-api/mbuf.h/mbuf_remove.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mbuf.h/mbuf_resize.md b/docs/c-api/mbuf.h/mbuf_resize.md deleted file mode 100644 index 92f8b302..00000000 --- a/docs/c-api/mbuf.h/mbuf_resize.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mbuf.h/mbuf_trim.md b/docs/c-api/mbuf.h/mbuf_trim.md deleted file mode 100644 index d1878b03..00000000 --- a/docs/c-api/mbuf.h/mbuf_trim.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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`. - diff --git a/docs/c-api/mbuf.h/struct_mbuf.md b/docs/c-api/mbuf.h/struct_mbuf.md deleted file mode 100644 index 98dcdc33..00000000 --- a/docs/c-api/mbuf.h/struct_mbuf.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -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 - diff --git a/docs/c-api/mqtt-broker.h/intro.md b/docs/c-api/mqtt-broker.h/intro.md deleted file mode 100644 index 592ccbc4..00000000 --- a/docs/c-api/mqtt-broker.h/intro.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "MQTT Broker" -symbol_kind: "intro" -decl_name: "mqtt-broker.h" ---- - - - diff --git a/docs/c-api/mqtt-broker.h/items.json b/docs/c-api/mqtt-broker.h/items.json deleted file mode 100644 index 2908ffbb..00000000 --- a/docs/c-api/mqtt-broker.h/items.json +++ /dev/null @@ -1,28 +0,0 @@ -{ - "items": [ - { - "type": "markdown", - "name": "intro.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_broker_init.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_broker.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_next.md" - }, - { - "type": "markdown", - "name": "struct_mg_mqtt_session.md" - }, - { - "type": "markdown", - "name": "struct_mg_mqtt_broker.md" - } - ] -} diff --git a/docs/c-api/mqtt-broker.h/mg_mqtt_broker.md b/docs/c-api/mqtt-broker.h/mg_mqtt_broker.md deleted file mode 100644 index 2532bc6f..00000000 --- a/docs/c-api/mqtt-broker.h/mg_mqtt_broker.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -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`. - diff --git a/docs/c-api/mqtt-broker.h/mg_mqtt_broker_init.md b/docs/c-api/mqtt-broker.h/mg_mqtt_broker_init.md deleted file mode 100644 index 74b7e5db..00000000 --- a/docs/c-api/mqtt-broker.h/mg_mqtt_broker_init.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mqtt-broker.h/mg_mqtt_next.md b/docs/c-api/mqtt-broker.h/mg_mqtt_next.md deleted file mode 100644 index 5c4eab9d..00000000 --- a/docs/c-api/mqtt-broker.h/mg_mqtt_next.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -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 -} -``` - diff --git a/docs/c-api/mqtt-broker.h/struct_mg_mqtt_broker.md b/docs/c-api/mqtt-broker.h/struct_mg_mqtt_broker.md deleted file mode 100644 index d78e620e..00000000 --- a/docs/c-api/mqtt-broker.h/struct_mg_mqtt_broker.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mqtt-broker.h/struct_mg_mqtt_session.md b/docs/c-api/mqtt-broker.h/struct_mg_mqtt_session.md deleted file mode 100644 index 4ce85014..00000000 --- a/docs/c-api/mqtt-broker.h/struct_mg_mqtt_session.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -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). - diff --git a/docs/c-api/mqtt.h/intro.md b/docs/c-api/mqtt.h/intro.md deleted file mode 100644 index 55117eee..00000000 --- a/docs/c-api/mqtt.h/intro.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "MQTT" -symbol_kind: "intro" -decl_name: "mqtt.h" ---- - - - diff --git a/docs/c-api/mqtt.h/items.json b/docs/c-api/mqtt.h/items.json deleted file mode 100644 index b77926f7..00000000 --- a/docs/c-api/mqtt.h/items.json +++ /dev/null @@ -1,80 +0,0 @@ -{ - "items": [ - { - "type": "markdown", - "name": "intro.md" - }, - { - "type": "markdown", - "name": "mg_set_protocol_mqtt.md" - }, - { - "type": "markdown", - "name": "mg_send_mqtt_handshake.md" - }, - { - "type": "markdown", - "name": "mg_send_mqtt_handshake_opt.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_publish.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_subscribe.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_unsubscribe.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_disconnect.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_connack.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_puback.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_pubrec.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_pubrel.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_pubcomp.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_suback.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_unsuback.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_ping.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_pong.md" - }, - { - "type": "markdown", - "name": "mg_mqtt_next_subscribe_topic.md" - }, - { - "type": "markdown", - "name": "struct_mg_mqtt_topic_expression.md" - } - ] -} diff --git a/docs/c-api/mqtt.h/mg_mqtt_connack.md b/docs/c-api/mqtt.h/mg_mqtt_connack.md deleted file mode 100644 index 3b22d0a0..00000000 --- a/docs/c-api/mqtt.h/mg_mqtt_connack.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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`. - diff --git a/docs/c-api/mqtt.h/mg_mqtt_disconnect.md b/docs/c-api/mqtt.h/mg_mqtt_disconnect.md deleted file mode 100644 index 2437c21d..00000000 --- a/docs/c-api/mqtt.h/mg_mqtt_disconnect.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mqtt.h/mg_mqtt_next_subscribe_topic.md b/docs/c-api/mqtt.h/mg_mqtt_next_subscribe_topic.md deleted file mode 100644 index 3e7eeab5..00000000 --- a/docs/c-api/mqtt.h/mg_mqtt_next_subscribe_topic.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mqtt.h/mg_mqtt_ping.md b/docs/c-api/mqtt.h/mg_mqtt_ping.md deleted file mode 100644 index acaa11ac..00000000 --- a/docs/c-api/mqtt.h/mg_mqtt_ping.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mqtt.h/mg_mqtt_pong.md b/docs/c-api/mqtt.h/mg_mqtt_pong.md deleted file mode 100644 index da353b57..00000000 --- a/docs/c-api/mqtt.h/mg_mqtt_pong.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mqtt.h/mg_mqtt_puback.md b/docs/c-api/mqtt.h/mg_mqtt_puback.md deleted file mode 100644 index aad96f66..00000000 --- a/docs/c-api/mqtt.h/mg_mqtt_puback.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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`. - diff --git a/docs/c-api/mqtt.h/mg_mqtt_pubcomp.md b/docs/c-api/mqtt.h/mg_mqtt_pubcomp.md deleted file mode 100644 index aab320f6..00000000 --- a/docs/c-api/mqtt.h/mg_mqtt_pubcomp.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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`. - diff --git a/docs/c-api/mqtt.h/mg_mqtt_publish.md b/docs/c-api/mqtt.h/mg_mqtt_publish.md deleted file mode 100644 index 8b28c57b..00000000 --- a/docs/c-api/mqtt.h/mg_mqtt_publish.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mqtt.h/mg_mqtt_pubrec.md b/docs/c-api/mqtt.h/mg_mqtt_pubrec.md deleted file mode 100644 index e5173f77..00000000 --- a/docs/c-api/mqtt.h/mg_mqtt_pubrec.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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`. - diff --git a/docs/c-api/mqtt.h/mg_mqtt_pubrel.md b/docs/c-api/mqtt.h/mg_mqtt_pubrel.md deleted file mode 100644 index 899e8b9d..00000000 --- a/docs/c-api/mqtt.h/mg_mqtt_pubrel.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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`. - diff --git a/docs/c-api/mqtt.h/mg_mqtt_suback.md b/docs/c-api/mqtt.h/mg_mqtt_suback.md deleted file mode 100644 index 943fd65e..00000000 --- a/docs/c-api/mqtt.h/mg_mqtt_suback.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mqtt.h/mg_mqtt_subscribe.md b/docs/c-api/mqtt.h/mg_mqtt_subscribe.md deleted file mode 100644 index 0978b071..00000000 --- a/docs/c-api/mqtt.h/mg_mqtt_subscribe.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mqtt.h/mg_mqtt_unsuback.md b/docs/c-api/mqtt.h/mg_mqtt_unsuback.md deleted file mode 100644 index e3f6e6ea..00000000 --- a/docs/c-api/mqtt.h/mg_mqtt_unsuback.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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`. - diff --git a/docs/c-api/mqtt.h/mg_mqtt_unsubscribe.md b/docs/c-api/mqtt.h/mg_mqtt_unsubscribe.md deleted file mode 100644 index 73a283e3..00000000 --- a/docs/c-api/mqtt.h/mg_mqtt_unsubscribe.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mqtt.h/mg_send_mqtt_handshake.md b/docs/c-api/mqtt.h/mg_send_mqtt_handshake.md deleted file mode 100644 index 1e903f90..00000000 --- a/docs/c-api/mqtt.h/mg_send_mqtt_handshake.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mqtt.h/mg_send_mqtt_handshake_opt.md b/docs/c-api/mqtt.h/mg_send_mqtt_handshake_opt.md deleted file mode 100644 index c1d3fd4c..00000000 --- a/docs/c-api/mqtt.h/mg_send_mqtt_handshake_opt.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -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. - diff --git a/docs/c-api/mqtt.h/mg_set_protocol_mqtt.md b/docs/c-api/mqtt.h/mg_set_protocol_mqtt.md deleted file mode 100644 index a559eae8..00000000 --- a/docs/c-api/mqtt.h/mg_set_protocol_mqtt.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -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 - diff --git a/docs/c-api/mqtt.h/struct_mg_mqtt_topic_expression.md b/docs/c-api/mqtt.h/struct_mg_mqtt_topic_expression.md deleted file mode 100644 index 8ae14b2d..00000000 --- a/docs/c-api/mqtt.h/struct_mg_mqtt_topic_expression.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -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 - diff --git a/docs/c-api/net.h/intro.md b/docs/c-api/net.h/intro.md deleted file mode 100644 index bb03bacc..00000000 --- a/docs/c-api/net.h/intro.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Core: TCP/UDP/SSL" -symbol_kind: "intro" -decl_name: "net.h" ---- - -NOTE: Mongoose manager is single threaded. It does not protect -its data structures by mutexes, therefore all functions that are dealing -with particular event manager should be called from the same thread, -with exception of `mg_broadcast()` function. It is fine to have different -event managers handled by different threads. - diff --git a/docs/c-api/net.h/items.json b/docs/c-api/net.h/items.json deleted file mode 100644 index 8a8e5468..00000000 --- a/docs/c-api/net.h/items.json +++ /dev/null @@ -1,120 +0,0 @@ -{ - "items": [ - { - "type": "markdown", - "name": "intro.md" - }, - { - "type": "markdown", - "name": "mg_mgr_init.md" - }, - { - "type": "markdown", - "name": "mg_mgr_free.md" - }, - { - "type": "markdown", - "name": "mg_mgr_poll.md" - }, - { - "type": "markdown", - "name": "mg_broadcast.md" - }, - { - "type": "markdown", - "name": "mg_next.md" - }, - { - "type": "markdown", - "name": "mg_add_sock.md" - }, - { - "type": "markdown", - "name": "mg_add_sock_opt.md" - }, - { - "type": "markdown", - "name": "mg_bind.md" - }, - { - "type": "markdown", - "name": "mg_bind_opt.md" - }, - { - "type": "markdown", - "name": "mg_connect.md" - }, - { - "type": "markdown", - "name": "mg_connect_opt.md" - }, - { - "type": "markdown", - "name": "mg_set_ssl.md" - }, - { - "type": "markdown", - "name": "mg_send.md" - }, - { - "type": "markdown", - "name": "mg_printf.md" - }, - { - "type": "markdown", - "name": "mg_vprintf.md" - }, - { - "type": "markdown", - "name": "mg_socketpair.md" - }, - { - "type": "markdown", - "name": "mg_check_ip_acl.md" - }, - { - "type": "markdown", - "name": "mg_enable_multithreading.md" - }, - { - "type": "markdown", - "name": "mg_enable_javascript.md" - }, - { - "type": "markdown", - "name": "mg_set_timer.md" - }, - { - "type": "markdown", - "name": "mg_time.md" - }, - { - "type": "markdown", - "name": "mg_event_handler_t.md" - }, - { - "type": "markdown", - "name": "struct_mg_str.md" - }, - { - "type": "markdown", - "name": "struct_mg_mgr.md" - }, - { - "type": "markdown", - "name": "struct_mg_connection.md" - }, - { - "type": "markdown", - "name": "struct_mg_add_sock_opts.md" - }, - { - "type": "markdown", - "name": "struct_mg_bind_opts.md" - }, - { - "type": "markdown", - "name": "struct_mg_connect_opts.md" - } - ] -} diff --git a/docs/c-api/net.h/mg_add_sock.md b/docs/c-api/net.h/mg_add_sock.md deleted file mode 100644 index 268dc334..00000000 --- a/docs/c-api/net.h/mg_add_sock.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "mg_add_sock()" -decl_name: "mg_add_sock" -symbol_kind: "func" -signature: | - struct mg_connection *mg_add_sock(struct mg_mgr *, sock_t, mg_event_handler_t); ---- - -Create a connection, associate it with the given socket and event handler, -and add it to the manager. - -For more options see the `mg_add_sock_opt` variant. - diff --git a/docs/c-api/net.h/mg_add_sock_opt.md b/docs/c-api/net.h/mg_add_sock_opt.md deleted file mode 100644 index 9a94aee7..00000000 --- a/docs/c-api/net.h/mg_add_sock_opt.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "mg_add_sock_opt()" -decl_name: "mg_add_sock_opt" -symbol_kind: "func" -signature: | - struct mg_connection *mg_add_sock_opt(struct mg_mgr *, sock_t, - mg_event_handler_t, - struct mg_add_sock_opts); ---- - -Create a connection, associate it with the given socket and event handler, -and add to the manager. - -See the `mg_add_sock_opts` structure for a description of the options. - diff --git a/docs/c-api/net.h/mg_bind.md b/docs/c-api/net.h/mg_bind.md deleted file mode 100644 index b6106219..00000000 --- a/docs/c-api/net.h/mg_bind.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "mg_bind()" -decl_name: "mg_bind" -symbol_kind: "func" -signature: | - struct mg_connection *mg_bind(struct mg_mgr *, const char *, - mg_event_handler_t); ---- - -Create listening connection. - -See `mg_bind_opt` for full documentation. - diff --git a/docs/c-api/net.h/mg_bind_opt.md b/docs/c-api/net.h/mg_bind_opt.md deleted file mode 100644 index 4fb514bf..00000000 --- a/docs/c-api/net.h/mg_bind_opt.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: "mg_bind_opt()" -decl_name: "mg_bind_opt" -symbol_kind: "func" -signature: | - struct mg_connection *mg_bind_opt(struct mg_mgr *mgr, const char *address, - mg_event_handler_t handler, - struct mg_bind_opts opts); ---- - -Create listening connection. - -`address` parameter tells which address to bind to. It's format is the same -as for the `mg_connect()` call, where `HOST` part is optional. `address` -can be just a port number, e.g. `:8000`. To bind to a specific interface, -an IP address can be specified, e.g. `1.2.3.4:8000`. By default, a TCP -connection is created. To create UDP connection, prepend `udp://` prefix, -e.g. `udp://:8000`. To summarize, `address` paramer has following format: -`[PROTO://][IP_ADDRESS]:PORT`, where `PROTO` could be `tcp` or `udp`. - -See the `mg_bind_opts` structure for a description of the optional -parameters. - -Return a new listening connection, or `NULL` on error. -NOTE: Connection remains owned by the manager, do not free(). - diff --git a/docs/c-api/net.h/mg_broadcast.md b/docs/c-api/net.h/mg_broadcast.md deleted file mode 100644 index 94fceb8f..00000000 --- a/docs/c-api/net.h/mg_broadcast.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: "mg_broadcast()" -decl_name: "mg_broadcast" -symbol_kind: "func" -signature: | - void mg_broadcast(struct mg_mgr *, mg_event_handler_t func, void *, size_t); ---- - -Pass a message of a given length to all connections. - -Must be called from a thread that does NOT call `mg_mgr_poll()`. -Note that `mg_broadcast()` is the only function -that can be, and must be, called from a different (non-IO) thread. - -`func` callback function will be called by the IO thread for each -connection. When called, event would be `MG_EV_POLL`, and message will -be passed as `ev_data` pointer. Maximum message size is capped -by `MG_CTL_MSG_MESSAGE_SIZE` which is set to 8192 bytes. - diff --git a/docs/c-api/net.h/mg_check_ip_acl.md b/docs/c-api/net.h/mg_check_ip_acl.md deleted file mode 100644 index 957a684f..00000000 --- a/docs/c-api/net.h/mg_check_ip_acl.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: "mg_check_ip_acl()" -decl_name: "mg_check_ip_acl" -symbol_kind: "func" -signature: | - int mg_check_ip_acl(const char *acl, uint32_t remote_ip); ---- - -Verify given IP address against the ACL. - -`remote_ip` - an IPv4 address to check, in host byte order -`acl` - a comma separated list of IP subnets: `x.x.x.x/x` or `x.x.x.x`. -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: - -`-0.0.0.0/0,+192.168/16` - deny all acccesses, only allow 192.168/16 subnet - -To learn more about subnet masks, see the -link:https://en.wikipedia.org/wiki/Subnetwork[Wikipedia page on Subnetwork] - -Return -1 if ACL is malformed, 0 if address is disallowed, 1 if allowed. - diff --git a/docs/c-api/net.h/mg_connect.md b/docs/c-api/net.h/mg_connect.md deleted file mode 100644 index 388196e3..00000000 --- a/docs/c-api/net.h/mg_connect.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "mg_connect()" -decl_name: "mg_connect" -symbol_kind: "func" -signature: | - struct mg_connection *mg_connect(struct mg_mgr *mgr, const char *address, - mg_event_handler_t handler); ---- - -Connect to a remote host. - -See `mg_connect_opt()` for full documentation. - diff --git a/docs/c-api/net.h/mg_connect_opt.md b/docs/c-api/net.h/mg_connect_opt.md deleted file mode 100644 index d169ded1..00000000 --- a/docs/c-api/net.h/mg_connect_opt.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "mg_connect_opt()" -decl_name: "mg_connect_opt" -symbol_kind: "func" -signature: | - struct mg_connection *mg_connect_opt(struct mg_mgr *mgr, const char *address, - mg_event_handler_t handler, - struct mg_connect_opts opts); ---- - -Connect to a remote host. - -`address` format is `[PROTO://]HOST:PORT`. `PROTO` could be `tcp` or `udp`. -`HOST` could be an IP address, -IPv6 address (if Mongoose is compiled with `-DMG_ENABLE_IPV6`), or a host -name. If `HOST` is a name, Mongoose will resolve it asynchronously. Examples -of valid addresses: `google.com:80`, `udp://1.2.3.4:53`, `10.0.0.1:443`, -`[::1]:80` - -See the `mg_connect_opts` structure for a description of the optional -parameters. - -Returns a new outbound connection, or `NULL` on error. - -NOTE: Connection remains owned by the manager, do not free(). - -NOTE: To enable IPv6 addresses, `-DMG_ENABLE_IPV6` should be specified -in the compilation flags. - -NOTE: New connection will receive `MG_EV_CONNECT` as it's first event -which will report connect success status. -If asynchronous resolution fail, or `connect()` syscall fail for whatever -reason (e.g. with `ECONNREFUSED` or `ENETUNREACH`), then `MG_EV_CONNECT` -event report failure. Code example below: - -```c -static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) { - int connect_status; - - switch (ev) { - case MG_EV_CONNECT: - connect_status = * (int *) ev_data; - if (connect_status == 0) { - // Success - } else { - // Error - printf("connect() error: %s\n", strerror(connect_status)); - } - break; - ... - } -} - - ... - mg_connect(mgr, "my_site.com:80", ev_handler); -``` - diff --git a/docs/c-api/net.h/mg_enable_javascript.md b/docs/c-api/net.h/mg_enable_javascript.md deleted file mode 100644 index cb275386..00000000 --- a/docs/c-api/net.h/mg_enable_javascript.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "mg_enable_javascript()" -decl_name: "mg_enable_javascript" -symbol_kind: "func" -signature: | - enum v7_err mg_enable_javascript(struct mg_mgr *m, struct v7 *v7, - const char *init_js_file_name); ---- - -Enable server-side JavaScript scripting. -Requires `-DMG_ENABLE_JAVASCRIPT` compilation flag, and V7 engine sources. -v7 instance must not be destroyed during manager's lifetime. -Return V7 error. - diff --git a/docs/c-api/net.h/mg_enable_multithreading.md b/docs/c-api/net.h/mg_enable_multithreading.md deleted file mode 100644 index 3498e4de..00000000 --- a/docs/c-api/net.h/mg_enable_multithreading.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "mg_enable_multithreading()" -decl_name: "mg_enable_multithreading" -symbol_kind: "func" -signature: | - void mg_enable_multithreading(struct mg_connection *nc); ---- - -Enable multi-threaded handling for the given listening connection `nc`. -For each accepted connection, Mongoose will create a separate thread -and run event handler in that thread. Thus, if an event hanler is doing -a blocking call or some long computation, that will not slow down -other connections. - diff --git a/docs/c-api/net.h/mg_event_handler_t.md b/docs/c-api/net.h/mg_event_handler_t.md deleted file mode 100644 index 79a5ffd9..00000000 --- a/docs/c-api/net.h/mg_event_handler_t.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "mg_event_handler_t" -decl_name: "mg_event_handler_t" -symbol_kind: "typedef" -signature: | - typedef void (*mg_event_handler_t)(struct mg_connection *, int ev, void *); ---- - -Callback function (event handler) prototype, must be defined by user. -Mongoose calls event handler, passing events defined below. - diff --git a/docs/c-api/net.h/mg_mgr_free.md b/docs/c-api/net.h/mg_mgr_free.md deleted file mode 100644 index 07ca25d3..00000000 --- a/docs/c-api/net.h/mg_mgr_free.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "mg_mgr_free()" -decl_name: "mg_mgr_free" -symbol_kind: "func" -signature: | - void mg_mgr_free(struct mg_mgr *); ---- - -De-initializes Mongoose manager. - -Close and deallocate all active connections. - diff --git a/docs/c-api/net.h/mg_mgr_init.md b/docs/c-api/net.h/mg_mgr_init.md deleted file mode 100644 index b59506bd..00000000 --- a/docs/c-api/net.h/mg_mgr_init.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "mg_mgr_init()" -decl_name: "mg_mgr_init" -symbol_kind: "func" -signature: | - void mg_mgr_init(struct mg_mgr *mgr, void *user_data); ---- - -Initialize Mongoose manager. Side effect: ignores SIGPIPE signal. -`mgr->user_data` field will be initialized with `user_data` parameter. -That is an arbitrary pointer, where user code can associate some data -with the particular Mongoose manager. For example, a C++ wrapper class -could be written, in which case `user_data` can hold a pointer to the -class instance. - diff --git a/docs/c-api/net.h/mg_mgr_poll.md b/docs/c-api/net.h/mg_mgr_poll.md deleted file mode 100644 index f25c7595..00000000 --- a/docs/c-api/net.h/mg_mgr_poll.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "mg_mgr_poll()" -decl_name: "mg_mgr_poll" -symbol_kind: "func" -signature: | - time_t mg_mgr_poll(struct mg_mgr *, int milli); ---- - -This function performs the actual IO, and must be called in a loop -(an event loop). Returns the current timestamp. -`milli` is the maximum number of milliseconds to sleep. -`mg_mgr_poll()` checks all connection for IO readiness. If at least one -of the connections is IO-ready, `mg_mgr_poll()` triggers respective -event handlers and returns. - diff --git a/docs/c-api/net.h/mg_next.md b/docs/c-api/net.h/mg_next.md deleted file mode 100644 index fc817262..00000000 --- a/docs/c-api/net.h/mg_next.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: "mg_next()" -decl_name: "mg_next" -symbol_kind: "func" -signature: | - struct mg_connection *mg_next(struct mg_mgr *, struct mg_connection *); ---- - -Iterate over all active connections. - -Returns next connection from the list -of active connections, or `NULL` if there is no more connections. Below -is the iteration idiom: - -```c -for (c = mg_next(srv, NULL); c != NULL; c = mg_next(srv, c)) { - // Do something with connection `c` -} -``` - diff --git a/docs/c-api/net.h/mg_printf.md b/docs/c-api/net.h/mg_printf.md deleted file mode 100644 index 281fb4fd..00000000 --- a/docs/c-api/net.h/mg_printf.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "mg_printf()" -decl_name: "mg_printf" -symbol_kind: "func" -signature: | - int mg_printf(struct mg_connection *, const char *fmt, ...); ---- - -Send `printf`-style formatted data to the connection. - -See `mg_send` for more details on send semantics. - diff --git a/docs/c-api/net.h/mg_send.md b/docs/c-api/net.h/mg_send.md deleted file mode 100644 index e1aed3e0..00000000 --- a/docs/c-api/net.h/mg_send.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "mg_send()" -decl_name: "mg_send" -symbol_kind: "func" -signature: | - void mg_send(struct mg_connection *, const void *buf, int len); ---- - -Send data to the connection. - -Note that sending functions do not actually push data to the socket. -They just append data to the output buffer. MG_EV_SEND will be delivered when -the data has actually been pushed out. - diff --git a/docs/c-api/net.h/mg_set_ssl.md b/docs/c-api/net.h/mg_set_ssl.md deleted file mode 100644 index c2212b87..00000000 --- a/docs/c-api/net.h/mg_set_ssl.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: "mg_set_ssl()" -decl_name: "mg_set_ssl" -symbol_kind: "func" -signature: | - const char *mg_set_ssl(struct mg_connection *nc, const char *cert, - const char *ca_cert); ---- - -Enable SSL for a given connection. -`cert` is a server certificate file name for a listening connection, -or a client certificate file name for an outgoing connection. -Certificate files must be in PEM format. Server certificate file -must contain a certificate, concatenated with a private key, optionally -concatenated with parameters. -`ca_cert` is a CA certificate, or NULL if peer verification is not -required. -Return: NULL on success, or error message on error. - diff --git a/docs/c-api/net.h/mg_set_timer.md b/docs/c-api/net.h/mg_set_timer.md deleted file mode 100644 index e559c26b..00000000 --- a/docs/c-api/net.h/mg_set_timer.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "mg_set_timer()" -decl_name: "mg_set_timer" -symbol_kind: "func" -signature: | - double mg_set_timer(struct mg_connection *c, double timestamp); ---- - -Schedule MG_EV_TIMER event to be delivered at `timestamp` time. -`timestamp` is a UNIX time (a number of seconds since Epoch). It is -`double` instead of `time_t` to allow for sub-second precision. -Return the old timer value. - -Example: set connect timeout to 1.5 seconds: - -``` - c = mg_connect(&mgr, "cesanta.com", ev_handler); - mg_set_timer(c, mg_time() + 1.5); - ... - - void ev_handler(struct mg_connection *c, int ev, void *ev_data) { - switch (ev) { - case MG_EV_CONNECT: - mg_set_timer(c, 0); // Clear connect timer - break; - case MG_EV_TIMER: - log("Connect timeout"); - c->flags |= MG_F_CLOSE_IMMEDIATELY; - break; -``` - diff --git a/docs/c-api/net.h/mg_socketpair.md b/docs/c-api/net.h/mg_socketpair.md deleted file mode 100644 index 1509c0f3..00000000 --- a/docs/c-api/net.h/mg_socketpair.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "mg_socketpair()" -decl_name: "mg_socketpair" -symbol_kind: "func" -signature: | - int mg_socketpair(sock_t[2], int sock_type); ---- - -Create a socket pair. -`sock_type` can be either `SOCK_STREAM` or `SOCK_DGRAM`. -Return 0 on failure, 1 on success. - diff --git a/docs/c-api/net.h/mg_time.md b/docs/c-api/net.h/mg_time.md deleted file mode 100644 index 73b5e387..00000000 --- a/docs/c-api/net.h/mg_time.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "mg_time()" -decl_name: "mg_time" -symbol_kind: "func" -signature: | - double mg_time(); ---- - -A sub-second precision version of time(). - diff --git a/docs/c-api/net.h/mg_vprintf.md b/docs/c-api/net.h/mg_vprintf.md deleted file mode 100644 index ff66e264..00000000 --- a/docs/c-api/net.h/mg_vprintf.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "mg_vprintf()" -decl_name: "mg_vprintf" -symbol_kind: "func" -signature: | - int mg_vprintf(struct mg_connection *, const char *fmt, va_list ap); ---- - -Same as `mg_printf()`, but takes `va_list ap` as an argument. - diff --git a/docs/c-api/net.h/struct_mg_add_sock_opts.md b/docs/c-api/net.h/struct_mg_add_sock_opts.md deleted file mode 100644 index 1f399874..00000000 --- a/docs/c-api/net.h/struct_mg_add_sock_opts.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "struct mg_add_sock_opts" -decl_name: "struct mg_add_sock_opts" -symbol_kind: "struct" -signature: | - struct mg_add_sock_opts { - void *user_data; /* Initial value for connection's user_data */ - unsigned int flags; /* Initial connection flags */ - const char **error_string; /* Placeholder for the error string */ - }; ---- - -Optional parameters to `mg_add_sock_opt()`. - -`flags` is an initial `struct mg_connection::flags` bitmask to set, -see `MG_F_*` flags definitions. - diff --git a/docs/c-api/net.h/struct_mg_bind_opts.md b/docs/c-api/net.h/struct_mg_bind_opts.md deleted file mode 100644 index a72e7a16..00000000 --- a/docs/c-api/net.h/struct_mg_bind_opts.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: "struct mg_bind_opts" -decl_name: "struct mg_bind_opts" -symbol_kind: "struct" -signature: | - struct mg_bind_opts { - void *user_data; /* Initial value for connection's user_data */ - unsigned int flags; /* Extra connection flags */ - const char **error_string; /* Placeholder for the error string */ - #ifdef MG_ENABLE_SSL - /* SSL settings. */ - const char *ssl_cert; /* Server certificate to present to clients */ - const char *ssl_ca_cert; /* Verify client certificates with this CA bundle */ - #endif - }; ---- - -Optional parameters to `mg_bind_opt()`. - -`flags` is an initial `struct mg_connection::flags` bitmask to set, -see `MG_F_*` flags definitions. - diff --git a/docs/c-api/net.h/struct_mg_connect_opts.md b/docs/c-api/net.h/struct_mg_connect_opts.md deleted file mode 100644 index 167035c2..00000000 --- a/docs/c-api/net.h/struct_mg_connect_opts.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: "struct mg_connect_opts" -decl_name: "struct mg_connect_opts" -symbol_kind: "struct" -signature: | - struct mg_connect_opts { - void *user_data; /* Initial value for connection's user_data */ - unsigned int flags; /* Extra connection flags */ - const char **error_string; /* Placeholder for the error string */ - #ifdef MG_ENABLE_SSL - /* SSL settings. */ - const char *ssl_cert; /* Client certificate to present to the server */ - const char *ssl_ca_cert; /* Verify server certificate using this CA bundle */ - - /* - * Server name verification. If ssl_ca_cert is set and the certificate has - * passed verification, its subject will be verified against this string. - * By default (if ssl_server_name is NULL) hostname part of the address will - * be used. Wildcard matching is supported. A special value of "*" disables - * name verification. - */ - const char *ssl_server_name; - #endif - }; ---- - -Optional parameters to `mg_connect_opt()` - diff --git a/docs/c-api/net.h/struct_mg_connection.md b/docs/c-api/net.h/struct_mg_connection.md deleted file mode 100644 index fb72db9b..00000000 --- a/docs/c-api/net.h/struct_mg_connection.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "struct mg_connection" -decl_name: "struct mg_connection" -symbol_kind: "struct" -signature: | - struct mg_connection { - struct mg_connection *next, *prev; /* mg_mgr::active_connections linkage */ - struct mg_connection *listener; /* Set only for accept()-ed connections */ - struct mg_mgr *mgr; /* Pointer to containing manager */ - - sock_t sock; /* Socket to the remote peer */ - int err; - union socket_address sa; /* Remote peer address */ - size_t recv_mbuf_limit; /* Max size of recv buffer */ - struct mbuf recv_mbuf; /* Received data */ - struct mbuf send_mbuf; /* Data scheduled for sending */ - SSL *ssl; - SSL_CTX *ssl_ctx; - time_t last_io_time; /* Timestamp of the last socket IO */ - double ev_timer_time; /* Timestamp of the future MG_EV_TIMER */ - mg_event_handler_t proto_handler; /* Protocol-specific event handler */ - void *proto_data; /* Protocol-specific data */ - void (*proto_data_destructor)(void *proto_data); - mg_event_handler_t handler; /* Event handler function */ - void *user_data; /* User-specific data */ - union { - void *v; - /* - * the C standard is fussy about fitting function pointers into - * void pointers, since some archs might have fat pointers for functions. - */ - mg_event_handler_t f; - } priv_1; /* Used by mg_enable_multithreading() */ - void *priv_2; /* Used by mg_enable_multithreading() */ - void *mgr_data; /* Implementation-specific event manager's data. */ - unsigned long flags; - /* Flags set by Mongoose */ - #define MG_F_LISTENING (1 << 0) /* This connection is listening */ - #define MG_F_UDP (1 << 1) /* This connection is UDP */ - #define MG_F_RESOLVING (1 << 2) /* Waiting for async resolver */ - #define MG_F_CONNECTING (1 << 3) /* connect() call in progress */ - #define MG_F_SSL_HANDSHAKE_DONE (1 << 4) /* SSL specific */ - #define MG_F_WANT_READ (1 << 5) /* SSL specific */ - #define MG_F_WANT_WRITE (1 << 6) /* SSL specific */ - #define MG_F_IS_WEBSOCKET (1 << 7) /* Websocket specific */ - - /* Flags that are settable by user */ - #define MG_F_SEND_AND_CLOSE (1 << 10) /* Push remaining data and close */ - #define MG_F_CLOSE_IMMEDIATELY (1 << 11) /* Disconnect */ - #define MG_F_WEBSOCKET_NO_DEFRAG (1 << 12) /* Websocket specific */ - #define MG_F_DELETE_CHUNK (1 << 13) /* HTTP specific */ - - #define MG_F_USER_1 (1 << 20) /* Flags left for application */ - #define MG_F_USER_2 (1 << 21) - #define MG_F_USER_3 (1 << 22) - #define MG_F_USER_4 (1 << 23) - #define MG_F_USER_5 (1 << 24) - #define MG_F_USER_6 (1 << 25) - }; ---- - -Mongoose connection. - diff --git a/docs/c-api/net.h/struct_mg_mgr.md b/docs/c-api/net.h/struct_mg_mgr.md deleted file mode 100644 index f510e1b0..00000000 --- a/docs/c-api/net.h/struct_mg_mgr.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: "struct mg_mgr" -decl_name: "struct mg_mgr" -symbol_kind: "struct" -signature: | - struct mg_mgr { - struct mg_connection *active_connections; - const char *hexdump_file; /* Debug hexdump file path */ - #ifndef MG_DISABLE_SOCKETPAIR - sock_t ctl[2]; /* Socketpair for mg_wakeup() */ - #endif - void *user_data; /* User data */ - void *mgr_data; /* Implementation-specific event manager's data. */ - #ifdef MG_ENABLE_JAVASCRIPT - struct v7 *v7; - #endif - }; ---- - -Mongoose event manager. - diff --git a/docs/c-api/net.h/struct_mg_str.md b/docs/c-api/net.h/struct_mg_str.md deleted file mode 100644 index 6c0ad613..00000000 --- a/docs/c-api/net.h/struct_mg_str.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "struct mg_str" -decl_name: "struct mg_str" -symbol_kind: "struct" -signature: | - struct mg_str { - const char *p; /* Memory chunk pointer */ - size_t len; /* Memory chunk length */ - }; ---- - -Describes chunk of memory - diff --git a/docs/c-api/util.h/MG_MK_STR.md b/docs/c-api/util.h/MG_MK_STR.md deleted file mode 100644 index 4862e862..00000000 --- a/docs/c-api/util.h/MG_MK_STR.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "MG_MK_STR()" -decl_name: "MG_MK_STR" -symbol_kind: "func" -signature: | - #define MG_MK_STR(str_literal); ---- - -Macro for initializing mg_str. - diff --git a/docs/c-api/util.h/intro.md b/docs/c-api/util.h/intro.md deleted file mode 100644 index 3b516c8a..00000000 --- a/docs/c-api/util.h/intro.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "Utilities" -symbol_kind: "intro" -decl_name: "util.h" ---- - - - diff --git a/docs/c-api/util.h/items.json b/docs/c-api/util.h/items.json deleted file mode 100644 index 4b5b52e0..00000000 --- a/docs/c-api/util.h/items.json +++ /dev/null @@ -1,96 +0,0 @@ -{ - "items": [ - { - "type": "markdown", - "name": "intro.md" - }, - { - "type": "markdown", - "name": "mg_skip.md" - }, - { - "type": "markdown", - "name": "mg_ncasecmp.md" - }, - { - "type": "markdown", - "name": "mg_casecmp.md" - }, - { - "type": "markdown", - "name": "mg_vcmp.md" - }, - { - "type": "markdown", - "name": "mg_vcasecmp.md" - }, - { - "type": "markdown", - "name": "mg_base64_decode.md" - }, - { - "type": "markdown", - "name": "mg_base64_encode.md" - }, - { - "type": "markdown", - "name": "mg_stat.md" - }, - { - "type": "markdown", - "name": "mg_fopen.md" - }, - { - "type": "markdown", - "name": "mg_open.md" - }, - { - "type": "markdown", - "name": "mg_start_thread.md" - }, - { - "type": "markdown", - "name": "mg_conn_addr_to_str.md" - }, - { - "type": "markdown", - "name": "mg_sock_to_str.md" - }, - { - "type": "markdown", - "name": "mg_sock_addr_to_str.md" - }, - { - "type": "markdown", - "name": "mg_hexdump.md" - }, - { - "type": "markdown", - "name": "mg_hexdump_connection.md" - }, - { - "type": "markdown", - "name": "mg_avprintf.md" - }, - { - "type": "markdown", - "name": "mg_is_big_endian.md" - }, - { - "type": "markdown", - "name": "mg_next_comma_list_entry.md" - }, - { - "type": "markdown", - "name": "mg_match_prefix.md" - }, - { - "type": "markdown", - "name": "mg_mk_str.md" - }, - { - "type": "markdown", - "name": "MG_MK_STR.md" - } - ] -} diff --git a/docs/c-api/util.h/mg_avprintf.md b/docs/c-api/util.h/mg_avprintf.md deleted file mode 100644 index efc424d0..00000000 --- a/docs/c-api/util.h/mg_avprintf.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: "mg_avprintf()" -decl_name: "mg_avprintf" -symbol_kind: "func" -signature: | - int mg_avprintf(char **buf, size_t size, const char *fmt, va_list ap); ---- - -Print message to buffer. If buffer is large enough to hold the message, -return buffer. If buffer is to small, allocate large enough buffer on heap, -and return allocated buffer. -This is a supposed use case: - - char buf[5], *p = buf; - p = mg_avprintf(&p, sizeof(buf), "%s", "hi there"); - use_p_somehow(p); - if (p != buf) { - free(p); - } - -The purpose of this is to avoid malloc-ing if generated strings are small. - diff --git a/docs/c-api/util.h/mg_base64_decode.md b/docs/c-api/util.h/mg_base64_decode.md deleted file mode 100644 index 3fa77428..00000000 --- a/docs/c-api/util.h/mg_base64_decode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: "mg_base64_decode()" -decl_name: "mg_base64_decode" -symbol_kind: "func" -signature: | - int mg_base64_decode(const unsigned char *s, int len, char *dst); ---- - -Decode base64-encoded string `s`, `len` into the destination `dst`. -Destination has to have enough space to hold decoded buffer. -Decoding stops either when all string has been decoded, or invalid -character appeared. -Destination is '\0'-terminated. -Return number of decoded characters. On success, that should be equal to -`len`. On error (invalid character) the return value is smaller then `len`. - diff --git a/docs/c-api/util.h/mg_base64_encode.md b/docs/c-api/util.h/mg_base64_encode.md deleted file mode 100644 index c3b5c05e..00000000 --- a/docs/c-api/util.h/mg_base64_encode.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "mg_base64_encode()" -decl_name: "mg_base64_encode" -symbol_kind: "func" -signature: | - void mg_base64_encode(const unsigned char *src, int src_len, char *dst); ---- - -Base64-encode chunk of memory `src`, `src_len` into the destination `dst`. -Destination has to have enough space to hold encoded buffer. -Destination is '\0'-terminated. - diff --git a/docs/c-api/util.h/mg_casecmp.md b/docs/c-api/util.h/mg_casecmp.md deleted file mode 100644 index 8d23dbf6..00000000 --- a/docs/c-api/util.h/mg_casecmp.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "mg_casecmp()" -decl_name: "mg_casecmp" -symbol_kind: "func" -signature: | - int mg_casecmp(const char *s1, const char *s2); ---- - -Cross-platform version of `strcasecmp()`. - diff --git a/docs/c-api/util.h/mg_conn_addr_to_str.md b/docs/c-api/util.h/mg_conn_addr_to_str.md deleted file mode 100644 index f17bfb70..00000000 --- a/docs/c-api/util.h/mg_conn_addr_to_str.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: "mg_conn_addr_to_str()" -decl_name: "mg_conn_addr_to_str" -symbol_kind: "func" -signature: | - void mg_conn_addr_to_str(struct mg_connection *nc, char *buf, size_t len, - int flags); ---- - -Convert connection's local or remote address into string. - -The `flags` parameter is a bit mask that controls the behavior, -see `MG_SOCK_STRINGIFY_*` definitions. - -- MG_SOCK_STRINGIFY_IP - print IP address -- MG_SOCK_STRINGIFY_PORT - print port number -- MG_SOCK_STRINGIFY_REMOTE - print remote peer's IP/port, not local address - -If both port number and IP address are printed, they are separated by `:`. -If compiled with `-DMG_ENABLE_IPV6`, IPv6 addresses are supported. - diff --git a/docs/c-api/util.h/mg_fopen.md b/docs/c-api/util.h/mg_fopen.md deleted file mode 100644 index 3446670c..00000000 --- a/docs/c-api/util.h/mg_fopen.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "mg_fopen()" -decl_name: "mg_fopen" -symbol_kind: "func" -signature: | - FILE *mg_fopen(const char *path, const char *mode); ---- - -Open the given file and return a file stream. - -`path` and `mode` should be UTF8 encoded. - -Return value is the same as for the `fopen()` call. - diff --git a/docs/c-api/util.h/mg_hexdump.md b/docs/c-api/util.h/mg_hexdump.md deleted file mode 100644 index ed02068a..00000000 --- a/docs/c-api/util.h/mg_hexdump.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "mg_hexdump()" -decl_name: "mg_hexdump" -symbol_kind: "func" -signature: | - int mg_hexdump(const void *buf, int len, char *dst, int dst_len); ---- - -Generates human-readable hexdump of memory chunk. - -Takes a memory buffer `buf` of length `len` and creates a hex dump of that -buffer in `dst`. Generated output is a-la hexdump(1). -Return length of generated string, excluding terminating `\0`. If returned -length is bigger than `dst_len`, overflow bytes are discarded. - diff --git a/docs/c-api/util.h/mg_hexdump_connection.md b/docs/c-api/util.h/mg_hexdump_connection.md deleted file mode 100644 index 2e6d520d..00000000 --- a/docs/c-api/util.h/mg_hexdump_connection.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "mg_hexdump_connection()" -decl_name: "mg_hexdump_connection" -symbol_kind: "func" -signature: | - void mg_hexdump_connection(struct mg_connection *nc, const char *path, - const void *buf, int num_bytes, int ev); ---- - -Generates human-readable hexdump of the data sent or received by connection. -`path` is a file name where hexdump should be written. `num_bytes` is -a number of bytes sent/received. `ev` is one of the `MG_*` events sent to -an event handler. This function is supposed to be called from the -event handler. - diff --git a/docs/c-api/util.h/mg_is_big_endian.md b/docs/c-api/util.h/mg_is_big_endian.md deleted file mode 100644 index ba33f4d7..00000000 --- a/docs/c-api/util.h/mg_is_big_endian.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "mg_is_big_endian()" -decl_name: "mg_is_big_endian" -symbol_kind: "func" -signature: | - int mg_is_big_endian(void); ---- - -Return true if target platform is big endian. - diff --git a/docs/c-api/util.h/mg_match_prefix.md b/docs/c-api/util.h/mg_match_prefix.md deleted file mode 100644 index 17da2ea7..00000000 --- a/docs/c-api/util.h/mg_match_prefix.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "mg_match_prefix()" -decl_name: "mg_match_prefix" -symbol_kind: "func" -signature: | - int mg_match_prefix(const char *pattern, int pattern_len, const char *str); ---- - -Match 0-terminated string (mg_match_prefix) or string with given length -mg_match_prefix_n against a glob pattern. -Match is case-insensitive. Return number of bytes matched, or -1 if no match. - diff --git a/docs/c-api/util.h/mg_mk_str.md b/docs/c-api/util.h/mg_mk_str.md deleted file mode 100644 index 4862e862..00000000 --- a/docs/c-api/util.h/mg_mk_str.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "MG_MK_STR()" -decl_name: "MG_MK_STR" -symbol_kind: "func" -signature: | - #define MG_MK_STR(str_literal); ---- - -Macro for initializing mg_str. - diff --git a/docs/c-api/util.h/mg_ncasecmp.md b/docs/c-api/util.h/mg_ncasecmp.md deleted file mode 100644 index 3e113810..00000000 --- a/docs/c-api/util.h/mg_ncasecmp.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "mg_ncasecmp()" -decl_name: "mg_ncasecmp" -symbol_kind: "func" -signature: | - int mg_ncasecmp(const char *s1, const char *s2, size_t len); ---- - -Cross-platform version of `strncasecmp()`. - diff --git a/docs/c-api/util.h/mg_next_comma_list_entry.md b/docs/c-api/util.h/mg_next_comma_list_entry.md deleted file mode 100644 index e82d0609..00000000 --- a/docs/c-api/util.h/mg_next_comma_list_entry.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: "mg_next_comma_list_entry()" -decl_name: "mg_next_comma_list_entry" -symbol_kind: "func" -signature: | - const char *mg_next_comma_list_entry(const char *list, struct mg_str *val, - struct mg_str *eq_val); ---- - -A helper function for traversing a comma separated list of values. -It returns a list pointer shifted to the next value, or NULL if the end -of the list found. -Value is stored in val vector. If value has form "x=y", then eq_val -vector is initialized to point to the "y" part, and val vector length -is adjusted to point only to "x". -If list is just a comma separated list of entries, like "aa,bb,cc" then -`eq_val` will contain zero-length string. - -The purpose of this function is to parse comma separated string without -any copying/memory allocation. - diff --git a/docs/c-api/util.h/mg_open.md b/docs/c-api/util.h/mg_open.md deleted file mode 100644 index 38544670..00000000 --- a/docs/c-api/util.h/mg_open.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "mg_open()" -decl_name: "mg_open" -symbol_kind: "func" -signature: | - int mg_open(const char *path, int flag, int mode); ---- - -Open the given file and return a file stream. - -`path` should be UTF8 encoded. - -Return value is the same as for the `open()` syscall. - diff --git a/docs/c-api/util.h/mg_skip.md b/docs/c-api/util.h/mg_skip.md deleted file mode 100644 index 858dc1d7..00000000 --- a/docs/c-api/util.h/mg_skip.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "mg_skip()" -decl_name: "mg_skip" -symbol_kind: "func" -signature: | - const char *mg_skip(const char *s, const char *end_string, - const char *delimiters, struct mg_str *v); ---- - -Fetch substring from input string `s`, `end` into `v`. -Skips initial delimiter characters. Records first non-delimiter character -as the beginning of substring `v`. Then scans the rest of the string -until a delimiter character or end-of-string is found. -`delimiters` is a 0-terminated string containing delimiter characters. -Either one of `delimiters` or `end_string` terminates the search. -Return an `s` pointer, advanced forward where parsing stopped. - diff --git a/docs/c-api/util.h/mg_sock_addr_to_str.md b/docs/c-api/util.h/mg_sock_addr_to_str.md deleted file mode 100644 index 0563630b..00000000 --- a/docs/c-api/util.h/mg_sock_addr_to_str.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "mg_sock_addr_to_str()" -decl_name: "mg_sock_addr_to_str" -symbol_kind: "func" -signature: | - void mg_sock_addr_to_str(const union socket_address *sa, char *buf, size_t len, - int flags); ---- - -Convert socket's address into string. - -`flags` is MG_SOCK_STRINGIFY_IP and/or MG_SOCK_STRINGIFY_PORT. - diff --git a/docs/c-api/util.h/mg_sock_to_str.md b/docs/c-api/util.h/mg_sock_to_str.md deleted file mode 100644 index fb233b56..00000000 --- a/docs/c-api/util.h/mg_sock_to_str.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "mg_sock_to_str()" -decl_name: "mg_sock_to_str" -symbol_kind: "func" -signature: | - void mg_sock_to_str(sock_t sock, char *buf, size_t len, int flags); ---- - -Legacy interface. - diff --git a/docs/c-api/util.h/mg_start_thread.md b/docs/c-api/util.h/mg_start_thread.md deleted file mode 100644 index 11b66d30..00000000 --- a/docs/c-api/util.h/mg_start_thread.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "mg_start_thread()" -decl_name: "mg_start_thread" -symbol_kind: "func" -signature: | - void *mg_start_thread(void *(*thread_func); ---- - -Start a new detached thread. -Arguments and semantic is the same as pthead's `pthread_create()`. -`thread_func` is a thread function, `thread_func_param` is a parameter -that is passed to the thread function. - diff --git a/docs/c-api/util.h/mg_stat.md b/docs/c-api/util.h/mg_stat.md deleted file mode 100644 index 66c3d75f..00000000 --- a/docs/c-api/util.h/mg_stat.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "mg_stat()" -decl_name: "mg_stat" -symbol_kind: "func" -signature: | - int mg_stat(const char *path, cs_stat_t *st); ---- - -Perform a 64-bit `stat()` call against given file. - -`path` should be UTF8 encoded. - -Return value is the same as for `stat()` syscall. - diff --git a/docs/c-api/util.h/mg_vcasecmp.md b/docs/c-api/util.h/mg_vcasecmp.md deleted file mode 100644 index 54cb1ab0..00000000 --- a/docs/c-api/util.h/mg_vcasecmp.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "mg_vcasecmp()" -decl_name: "mg_vcasecmp" -symbol_kind: "func" -signature: | - int mg_vcasecmp(const struct mg_str *str2, const char *str1); ---- - -Cross-platform version of `strncasecmp()` where first string is -specified by `struct mg_str`. - diff --git a/docs/c-api/util.h/mg_vcmp.md b/docs/c-api/util.h/mg_vcmp.md deleted file mode 100644 index 74c29d12..00000000 --- a/docs/c-api/util.h/mg_vcmp.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "mg_vcmp()" -decl_name: "mg_vcmp" -symbol_kind: "func" -signature: | - int mg_vcmp(const struct mg_str *str2, const char *str1); ---- - -Cross-platform version of `strcmp()` where where first string is -specified by `struct mg_str`. - diff --git a/docs/coap.adoc b/docs/coap.adoc new file mode 100644 index 00000000..4881cae0 --- /dev/null +++ b/docs/coap.adoc @@ -0,0 +1,129 @@ +=== CoAP + +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) ... ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- +``` + +==== struct mg_coap_option + +[source,c] +---- +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. + +==== struct mg_coap_message + +[source,c] +---- +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. + +==== mg_set_protocol_coap() + +[source,c] +---- +int mg_set_protocol_coap(struct mg_connection *nc); +---- +Set CoAP protocol handler - trigger CoAP specific events + +==== mg_coap_add_option() + +[source,c] +---- +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. + +==== mg_coap_free_options() + +[source,c] +---- +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. + +==== mg_coap_send_message() + +[source,c] +---- +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)` + +==== mg_coap_send_ack() + +[source,c] +---- +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()` + +==== mg_coap_parse() + +[source,c] +---- +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()` + +==== mg_coap_compose() + +[source,c] +---- +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()` + diff --git a/docs/common.adoc b/docs/common.adoc new file mode 100644 index 00000000..160a79b5 --- /dev/null +++ b/docs/common.adoc @@ -0,0 +1,2 @@ +Local tweaks, applied before any of Mongoose's own headers. + diff --git a/docs/concept.adoc b/docs/concept.adoc new file mode 100644 index 00000000..d6edebb6 --- /dev/null +++ b/docs/concept.adoc @@ -0,0 +1,167 @@ + +== Design Concept + +Mongoose is a multi-protocol networking library that implements non-blocking, +asyncronous IO and provides event-based API. It has three basic data structures: + +- link:#_struct_mg_mgr[`struct mg_mgr`] is an event manager + that holds all active connections +- link:#_struct_mg_connection[`struct mg_connection`] describes a connection +- link:#_struct_mbuf[`struct mbuf`] describes data buffer + (received or sent data) + +Connections could be either *listening*, *outbound* or *inbound*. +Outbound connections are created by link:#_mg_connect[`mg_connect()`] call. +Listening connections are created by link:#_mg_bind[`mg_bind()`] call. +Inbound connections are those accepted by a listening connection. +Each connection is described by +link:#_struct_mg_connection[`struct mg_connection`] structure, which has +a number of fields like socket, event handler function, send/receive buffer, +flags, et cetera. + +Mongoose usage pattern is to declare and initialize event manager, create +connections and create an event loop by calling +link:#_mg_mgr_poll[`mg_mgr_poll()`] in a loop. +link:#_mg_mgr_poll[`mg_mgr_poll()`] iterates over all sockets, +accepts new connections, sends and receives data, closes connections, +and calls event handler functions for the respective events. + +=== Memory buffers + +Each connection has send and receive buffer, +link:#_struct_mg_connection[`struct mg_connection::send_mbuf`] +and +link:#_struct_mg_connection[`struct mg_connection::recv_mbuf`] respectively. +When data arrives, +Mongoose appends received data to the `recv_mbuf` and +triggers `MG_EV_RECV` event. User may send data back by calling one of the +output functions, like link:#_mg_send[`mg_send()`] or +link:#_mg_printf[`mg_printf()`]. Output functions append data to the +`send_mbuf`. When Mongoose +successfully writes data to the socket, it discards data from +link:#_struct_mg_connection[`mg_connection::send_mbuf`] and +sends `MG_EV_SEND` event. When connection is closed, `MG_EV_CLOSE` event is sent. + +image::mongoose/mbuf.png[width="600",align="center"] + +=== Event handler function + +Each connection has an event handler function associated with it. That +function must be implemented by user. Event handler is the key element of +the Mongoose application, since it defines application's behavior. This is how +an event handler function looks like: + +[source,c] +---- +static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) { + switch (ev) { + /* Event handler code that defines behavior of the connection */ + ... + } +} +---- + +struct mg_connection *nc:: + Connection that has received an event. + +int ev:: + Event number, defined in `mongoose.h`. For example, when data arrives + on inbound connection `ev` would be `MG_EV_RECV`. + +void *ev_data:: + This pointer points to the event-specific data, and it has different + meaning for different events. For example, for `MG_EV_RECV` event, + `ev_data` is an `int *` pointer, pointing to the number of bytes received + from the remote peer and saved into the receive IO buffer. Exact meaning + of `ev_data` is described for each event. Protocol-specific events usually + have `ev_data` pointing to structures that hold protocol-specific information. + +NOTE: link:#_struct_mg_connection[`struct mg_connection`] has `void *user_data` +which is a placeholder for a application-specific data. Mongoose does not use +that pointer. Event handler can store any kind of information there. + +=== Events + +Mongoose accepts incoming connections, reads and writes data, and +calls specified event handler for each connection when appropriate. Typical +event sequence is this: + +- For outbound connection: `MG_EV_CONNECT` -> (`MG_EV_RECV`, `MG_EV_SEND`, `MG_EV_POLL` ...) -> `MG_EV_CLOSE` +- For inbound connection: `MG_EV_ACCEPT` -> (`MG_EV_RECV`, `MG_EV_SEND`, `MG_EV_POLL` ...) -> `MG_EV_CLOSE` + + +Below is a list +of core events triggered by Mongoose (note that each protocol triggers +protocol-specific events in addition to the core ones): + +MG_EV_ACCEPT:: sent when new server connection is accepted by a +listening connection. `void *ev_data` is `union socket_address` +of the remote peer. +MG_EV_CONNECT:: sent when a new outbound connection created by +link:#_mg_connect[`mg_connect()`] +either failed or succeeded. `void *ev_data` is `int *success`. +If `success` is 0, then connection has been established, +otherwise it contains error code. See +link:#_mg_connect_opt[`mg_connect_opt()`] function for code example. + +MG_EV_RECV:: New data is received and appended to the end of `recv_mbuf`. +`void *ev_data` is `int *num_received_bytes`. Typically, event handler +should check received data in `nc->recv_mbuf`, +discard processed data by calling link:#_mbuf_remove[`mbuf_remove()`], +set connection flags `nc->flags` if necessary +(see link:#_struct_mg_connection[`struct mg_connection`]), and write +data the remote peer by output functions like link:#_mg_send[`mg_send()`]. + +WARNING: Mongoose uses `realloc()` to expand receive buffer. +It is user's responsibility to discard processed +data from the beginning of receive buffer, note the `mbuf_remove()` +call in the example above. + +MG_EV_SEND:: Mongoose has written data to the remote peer and discarded +written data from the +link:#_struct_mg_connection[`mg_connection::send_mbuf`]. `void *ev_data` +is `int *num_sent_bytes`. + +NOTE: Mongoose output functions only append +data to the `mg_connection::send_mbuf`, they do not do any socket writes. +An actual IO is done by link:#_mg_mgr_poll[`mg_mgr_poll()`]. `MG_EV_SEND` event +is just a notification about an IO has been done. + +MG_EV_POLL:: Sent to all connections on each invocation of +link:#_mg_mgr_poll[`mg_mgr_poll()`]. +This event could be used to do any housekeeping, for example check whether +certain timeout has expired and close the connection, or send heartbeet +message, et cetera. + +MG_EV_TIMER:: Sent to the connection if +link:#_mg_set_timer[`mg_set_timer()`] was called. + +=== 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 `udp://1.2.3.4:5678` +address, Mongoose is going to set `MG_F_UDP` flag for that connection. Other flags +are meant to be set only by user event handler to tell Mongoose how to behave. +Below is a list of connection flags that are meant to be set by event handlers: + +* `MG_F_FINISHED_SENDING_DATA` tells Mongoose that all data has been + appended to the `send_mbuf`. As soon as Mongoose sends it to the + socket, the connection will be closed. +* `MG_F_BUFFER_BUT_DONT_SEND` tells Mongoose to append data to the + `send_mbuf` but hold on sending it, because the data will be modified + later and then will be sent by clearing `MG_F_BUFFER_BUT_DONT_SEND` flag. +* `MG_F_CLOSE_IMMEDIATELY` tells Mongoose to close the connection + immediately, usually after some error +* `MG_F_USER_1`, `MG_F_USER_2`, `MG_F_USER_3`, `MG_F_USER_4` could be + used by a developer to store application-specific state + +Flags below are set by Mongoose: + +* `MG_F_SSL_HANDSHAKE_DONE` SSL only, set when SSL handshake is done. +* `MG_F_CONNECTING` set when connection is in connecting state after + `mg_connect()` call but connect did not finish yet. +* `MG_F_LISTENING` set for all listening connections +* `MG_F_UDP` set if connection is UDP +* `MG_F_IS_WEBSOCKET` set if connection is a Websocket connection +* `MG_F_WEBSOCKET_NO_DEFRAG` should be set by a user if user wants to switch + off automatic Websocket frame defragmentation diff --git a/docs/design-concept/conn-flags.md b/docs/design-concept/conn-flags.md deleted file mode 100644 index e7533deb..00000000 --- a/docs/design-concept/conn-flags.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: 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 `udp://1.2.3.4:5678` -address, Mongoose is going to set `MG_F_UDP` flag for that connection. Other -flags are meant to be set only by user event handler to tell Mongoose how to -behave. Below is a list of connection flags that are meant to be set by event -handlers: - -* `MG_F_FINISHED_SENDING_DATA` tells Mongoose that all data has been appended - to the `send_mbuf`. As soon as Mongoose sends it to the socket, the - connection will be closed. -* `MG_F_BUFFER_BUT_DONT_SEND` tells Mongoose to append data to the `send_mbuf` - but hold on sending it, because the data will be modified later and then will - be sent by clearing `MG_F_BUFFER_BUT_DONT_SEND` flag. -* `MG_F_CLOSE_IMMEDIATELY` tells Mongoose to close the connection immediately, - usually after some error -* `MG_F_USER_1`, `MG_F_USER_2`, `MG_F_USER_3`, `MG_F_USER_4` could be used by a - developer to store application-specific state - -Flags below are set by Mongoose: - -* `MG_F_SSL_HANDSHAKE_DONE` SSL only, set when SSL handshake is done. -* `MG_F_CONNECTING` set when connection is in connecting state after - `mg_connect()` call but connect did not finish yet. -* `MG_F_LISTENING` set for all listening connections -* `MG_F_UDP` set if connection is UDP -* `MG_F_IS_WEBSOCKET` set if connection is a Websocket connection -* `MG_F_WEBSOCKET_NO_DEFRAG` should be set by a user if user wants to switch - off automatic Websocket frame defragmentation diff --git a/docs/design-concept/event-handler.md b/docs/design-concept/event-handler.md deleted file mode 100644 index 264647cd..00000000 --- a/docs/design-concept/event-handler.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Event handler function ---- - -Each connection has an event handler function associated with it. That function -must be implemented by user. Event handler is the key element of the Mongoose -application, since it defines application's behavior. This is how an event -handler function looks like: - -```c -static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) { - switch (ev) { - /* Event handler code that defines behavior of the connection */ - ... - } -} -``` - -- `struct mg_connection *nc`: Connection that has received an event. -- `int ev`: Event number, defined in `mongoose.h`. For example, when data - arrives on inbound connection `ev` would be `MG_EV_RECV`. -- `void *ev_data`: This pointer points to the event-specific data, and it has - different meaning for different events. For example, for `MG_EV_RECV` event, - `ev_data` is an `int *` pointer, pointing to the number of bytes received - from the remote peer and saved into the receive IO buffer. Exact meaning of - `ev_data` is described for each event. Protocol-specific events usually have - `ev_data` pointing to structures that hold protocol-specific information. - -NOTE: `struct mg_connection` has `void *user_data` which is a placeholder for -an application-specific data. Mongoose does not use that pointer. Event handler -can store any kind of information there. diff --git a/docs/design-concept/events.md b/docs/design-concept/events.md deleted file mode 100644 index d8d632c1..00000000 --- a/docs/design-concept/events.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Events ---- - -Mongoose accepts incoming connections, reads and writes data, and calls -specified event handler for each connection when appropriate. Typical event -sequence is this: - -- For outbound connection: `MG_EV_CONNECT` -> (`MG_EV_RECV`, `MG_EV_SEND`, - `MG_EV_POLL` ...) -> `MG_EV_CLOSE` -- For inbound connection: `MG_EV_ACCEPT` -> (`MG_EV_RECV`, `MG_EV_SEND`, - `MG_EV_POLL` ...) -> `MG_EV_CLOSE` - - -Below is a list of core events triggered by Mongoose (note that each protocol -triggers protocol-specific events in addition to the core ones): - -- `MG_EV_ACCEPT`: sent when new server connection is accepted by a listening - connection. `void *ev_data` is `union socket_address` of the remote peer. - -- `MG_EV_CONNECT`: sent when a new outbound connection created by `mg_connect()` - either failed or succeeded. `void *ev_data` is `int *success`. If `success` - is 0, then connection has been established, otherwise it contains error code. - See `mg_connect_opt()` function for code example. - -- `MG_EV_RECV`: New data is received and appended to the end of `recv_mbuf`. - `void *ev_data` is `int *num_received_bytes`. Typically, event handler should - check received data in `nc->recv_mbuf`, discard processed data by calling - `mbuf_remove()`, set connection flags `nc->flags` if necessary (see `struct - mg_connection`), and write data the remote peer by output functions like - `mg_send()`. - - **WARNING**: Mongoose uses `realloc()` to expand receive buffer. It is - user's responsibility to discard processed data from the beginning of receive - buffer, note the `mbuf_remove()` call in the example above. - -- `MG_EV_SEND`: Mongoose has written data to the remote peer and discarded - written data from the `mg_connection::send_mbuf`. `void *ev_data` is `int - *num_sent_bytes`. - - **NOTE**: Mongoose output functions only append data to the - `mg_connection::send_mbuf`, they do not do any socket writes. An actual IO - is done by `mg_mgr_poll()`. `MG_EV_SEND` event is just a notification about - an IO has been done. - -- `MG_EV_POLL`: Sent to all connections on each invocation of `mg_mgr_poll()`. - This event could be used to do any housekeeping, for example check whether - certain timeout has expired and close the connection, or send heartbeet - message, et cetera. - -- `MG_EV_TIMER`: Sent to the connection if `mg_set_timer()` was called. - diff --git a/docs/design-concept/intro.md b/docs/design-concept/intro.md deleted file mode 100644 index 2142b62f..00000000 --- a/docs/design-concept/intro.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Design Concept ---- - -Mongoose is a multi-protocol networking library that implements non-blocking, -asyncronous IO and provides event-based API. It has three basic data -structures: - -- `struct mg_mgr` is an event manager that holds all active connections -- `struct mg_connection` describes a connection -- `struct mbuf` describes data buffer (received or sent data) - -Connections could be either *listening*, *outbound* or *inbound*. Outbound -connections are created by `mg_connect()` call. Listening connections are -created by `mg_bind()` call. Inbound connections are those accepted by a -listening connection. Each connection is described by `struct mg_connection` -structure, which has a number of fields like socket, event handler function, -send/receive buffer, flags, et cetera. - -Mongoose usage pattern is to declare and initialize event manager, create -connections and create an event loop by calling `mg_mgr_poll()` in a loop. -`mg_mgr_poll()` iterates over all sockets, accepts new connections, sends and -receives data, closes connections, and calls event handler functions for the -respective events. diff --git a/docs/design-concept/items.json b/docs/design-concept/items.json deleted file mode 100644 index c939cbe9..00000000 --- a/docs/design-concept/items.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "items": [ - { "type": "markdown", "name": "intro.md" }, - { "type": "markdown", "name": "memory-buffers.md" }, - { "type": "markdown", "name": "event-handler.md" }, - { "type": "markdown", "name": "events.md" }, - { "type": "markdown", "name": "conn-flags.md" } - ] -} diff --git a/docs/design-concept/memory-buffers.md b/docs/design-concept/memory-buffers.md deleted file mode 100644 index 9f1ffb24..00000000 --- a/docs/design-concept/memory-buffers.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Memory buffers ---- - -Each connection has send and receive buffer, `struct mg_connection::send_mbuf` -and `struct mg_connection::recv_mbuf` respectively. When data arrives, -Mongoose appends received data to the `recv_mbuf` and triggers `MG_EV_RECV` -event. User may send data back by calling one of the output functions, like -`mg_send()` or `mg_printf()`. Output functions append data to the `send_mbuf`. -When Mongoose successfully writes data to the socket, it discards data from -`struct mg_connection::send_mbuf` and sends `MG_EV_SEND` event. When connection -is closed, `MG_EV_CLOSE` event is sent. - -![](mbuf.png) - diff --git a/docs/dns-server.adoc b/docs/dns-server.adoc new file mode 100644 index 00000000..5a5ceea6 --- /dev/null +++ b/docs/dns-server.adoc @@ -0,0 +1,71 @@ +=== DNS server + +Disabled by default; enable with `-DMG_ENABLE_DNS_SERVER`. + +==== mg_dns_create_reply() + +[source,c] +---- +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); +``` + +==== mg_dns_reply_record() + +[source,c] +---- +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. + +==== mg_dns_send_reply() + +[source,c] +---- +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. + diff --git a/docs/dns.adoc b/docs/dns.adoc new file mode 100644 index 00000000..9868a0b7 --- /dev/null +++ b/docs/dns.adoc @@ -0,0 +1,151 @@ +=== DNS + +==== struct mg_dns_resource_record + +[source,c] +---- +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. + +==== struct mg_dns_message + +[source,c] +---- +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). + +==== mg_dns_parse_record_data() + +[source,c] +---- +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 + +==== mg_send_dns_query() + +[source,c] +---- +void mg_send_dns_query(struct mg_connection *nc, const char *name, + int query_type); +---- +Send a DNS query to the remote end. + +==== mg_dns_insert_header() + +[source,c] +---- +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. + +==== mg_dns_copy_questions() + +[source,c] +---- +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. + +==== mg_dns_encode_record() + +[source,c] +---- +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. + +==== mg_parse_dns() + +[source,c] +---- +int mg_parse_dns(const char *buf, int len, struct mg_dns_message *msg); +---- +Low-level: parses a DNS response. + +==== mg_dns_uncompress_name() + +[source,c] +---- +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. + +==== mg_set_protocol_dns() + +[source,c] +---- +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. + diff --git a/docs/http.adoc b/docs/http.adoc new file mode 100644 index 00000000..8317a445 --- /dev/null +++ b/docs/http.adoc @@ -0,0 +1,694 @@ +=== HTTP + Websocket + +==== struct http_message + +[source,c] +---- +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¶m2=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 + +==== struct websocket_message + +[source,c] +---- +struct websocket_message { + unsigned char *data; + size_t size; + unsigned char flags; +}; +---- +WebSocket message + +==== struct mg_http_multipart_part + +[source,c] +---- +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 + +==== struct mg_serve_http_opts + +[source,c] +---- +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. + +==== mg_set_protocol_http_websocket() + +[source,c] +---- +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 + +==== mg_send_websocket_handshake() + +[source,c] +---- +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` + +==== mg_send_websocket_handshake2() + +[source,c] +---- +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. + +==== mg_connect_ws() + +[source,c] +---- +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); +``` + +==== mg_connect_ws_opt() + +[source,c] +---- +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 + +==== mg_send_websocket_frame() + +[source,c] +---- +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. + +==== mg_send_websocket_framev() + +[source,c] +---- +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. + +==== mg_printf_websocket_frame() + +[source,c] +---- +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. + +==== mg_send_http_chunk() + +[source,c] +---- +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 +``` + +==== mg_printf_http_chunk() + +[source,c] +---- +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()`. + +==== mg_send_response_line() + +[source,c] +---- +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 + +==== mg_send_head() + +[source,c] +---- +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. + +==== mg_printf_html_escape() + +[source,c] +---- +void mg_printf_html_escape(struct mg_connection *nc, const char *fmt, ...); +---- +Send printf-formatted HTTP chunk, escaping HTML tags. + +==== mg_parse_http() + +[source,c] +---- +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. + +==== mg_get_http_header() + +[source,c] +---- +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"); + +==== mg_http_parse_header() + +[source,c] +---- +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. + +==== mg_parse_multipart() + +[source,c] +---- +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; +``` + +==== mg_get_http_var() + +[source,c] +---- +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. + +==== mg_url_decode() + +[source,c] +---- +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`. + +==== mg_http_create_digest_auth_header() + +[source,c] +---- +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. + +==== mg_connect_http() + +[source,c] +---- +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"); +``` + +==== mg_connect_http_opt() + +[source,c] +---- +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 + +==== mg_serve_http() + +[source,c] +---- +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; + } +} +``` + +==== mg_register_http_endpoint() + +[source,c] +---- +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); +} +``` + +==== mg_file_upload_handler() + +[source,c] +---- +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; + } +} +``` + diff --git a/docs/img/mbuf.png b/docs/img/mbuf.png deleted file mode 100644 index a162abc3..00000000 Binary files a/docs/img/mbuf.png and /dev/null differ diff --git a/docs/index-docinfo.html b/docs/index-docinfo.html new file mode 100644 index 00000000..ad5a8e74 --- /dev/null +++ b/docs/index-docinfo.html @@ -0,0 +1,10396 @@ + diff --git a/docs/index.adoc b/docs/index.adoc new file mode 100644 index 00000000..e29d1bf9 --- /dev/null +++ b/docs/index.adoc @@ -0,0 +1,23 @@ +:toc2: +:toclevels: 2 +:source-highlighter: pygments +:pygments-style: xcode +:docinfo: + += Multi-Protocol Networking Library + +include::tutorial.adoc[] +include::concept.adoc[] +include::build_opts.adoc[] + +== API Reference +include::mbuf.adoc[] +include::net.adoc[] +include::http.adoc[] +include::json-rpc.adoc[] +include::dns.adoc[] +include::dns-server.adoc[] +include::mqtt.adoc[] +include::mqtt-broker.adoc[] +include::coap.adoc[] +include::util.adoc[] diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 00000000..15a947c6 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,14093 @@ + + + + + + + +Multi-Protocol Networking Library + + + + + + +
+
+

Usage Example

+
+
+
    +
  1. +

    Copy mongoose.c and mongoose.h to your build tree

    +
    2. +
  2. +

    Write code that uses Mongoose API, e.g. in my_app.c

    +
    3. +
  3. +

    Compile application: $ cc my_app.c mongoose.c

    +
    4. +
+
+
+
my_app.c
+
+
#include "mongoose.h"  1
+
+static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) { 2
+  struct mbuf *io = &nc->recv_mbuf;
+
+  switch (ev) {
+    case MG_EV_RECV:
+      // This event handler implements simple TCP echo server
+      mg_send(nc, io->buf, io->len);  // Echo received data back
+      mbuf_remove(io, io->len);      // Discard data from recv buffer
+      break;
+    default:
+      break;
+  }
+}
+
+int main(void) {
+  struct mg_mgr mgr;
+
+  mg_mgr_init(&mgr, NULL);  3
+
+  // Note that many connections can be added to a single event manager
+  // Connections can be created at any point, e.g. in event handler function
+  mg_bind(&mgr, "1234", ev_handler);  4
+
+  for (;;) {  5
+    mg_mgr_poll(&mgr, 1000);
+  }
+
+  mg_mgr_free(&mgr);
+  return 0;
+}
+
+
+
+ + + + + + + + + + + + + + + + + + + + + +
1Include Mongoose API definitions
2Define an event handler function
3Initialize event manager object
4Create listening connection and add it to the event manager
5Start infinite event loop
+
+
+
+
+

Design Concept

+
+
+

Mongoose is a multi-protocol networking library that implements non-blocking, +asyncronous IO and provides event-based API. It has three basic data structures:

+
+
+ +
+
+

Connections could be either listening, outbound or inbound. +Outbound connections are created by mg_connect() call. +Listening connections are created by mg_bind() call. +Inbound connections are those accepted by a listening connection. +Each connection is described by +struct mg_connection structure, which has +a number of fields like socket, event handler function, send/receive buffer, +flags, et cetera.

+
+
+

Mongoose usage pattern is to declare and initialize event manager, create +connections and create an event loop by calling +mg_mgr_poll() in a loop. +mg_mgr_poll() iterates over all sockets, +accepts new connections, sends and receives data, closes connections, +and calls event handler functions for the respective events.

+
+
+

Memory buffers

+
+

Each connection has send and receive buffer, +struct mg_connection::send_mbuf +and +struct mg_connection::recv_mbuf respectively. +When data arrives, +Mongoose appends received data to the recv_mbuf and +triggers MG_EV_RECV event. User may send data back by calling one of the +output functions, like mg_send() or +mg_printf(). Output functions append data to the +send_mbuf. When Mongoose +successfully writes data to the socket, it discards data from +mg_connection::send_mbuf and +sends MG_EV_SEND event. When connection is closed, MG_EV_CLOSE event is sent.

+
+
+
+mbuf +
+
+
+
+

Event handler function

+
+

Each connection has an event handler function associated with it. That +function must be implemented by user. Event handler is the key element of +the Mongoose application, since it defines application’s behavior. This is how +an event handler function looks like:

+
+
+
+
static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) {
+  switch (ev) {
+    /* Event handler code that defines behavior of the connection */
+    ...
+  }
+}
+
+
+
+
+
struct mg_connection *nc
+
+

Connection that has received an event.

+
+
int ev
+
+

Event number, defined in mongoose.h. For example, when data arrives +on inbound connection ev would be MG_EV_RECV.

+
+
void *ev_data
+
+

This pointer points to the event-specific data, and it has different +meaning for different events. For example, for MG_EV_RECV event, +ev_data is an int * pointer, pointing to the number of bytes received +from the remote peer and saved into the receive IO buffer. Exact meaning +of ev_data is described for each event. Protocol-specific events usually +have ev_data pointing to structures that hold protocol-specific information.

+
+
+
+
+ + + + + +
+Note + +struct mg_connection has void *user_data +which is a placeholder for a application-specific data. Mongoose does not use +that pointer. Event handler can store any kind of information there. +
+
+
+
+

Events

+
+

Mongoose accepts incoming connections, reads and writes data, and +calls specified event handler for each connection when appropriate. Typical +event sequence is this:

+
+
+
    +
  • +

    For outbound connection: MG_EV_CONNECT → (MG_EV_RECV, MG_EV_SEND, MG_EV_POLL …​) → MG_EV_CLOSE

    +
    • +
  • +

    For inbound connection: MG_EV_ACCEPT → (MG_EV_RECV, MG_EV_SEND, MG_EV_POLL …​) → MG_EV_CLOSE

    +
    • +
+
+
+

Below is a list +of core events triggered by Mongoose (note that each protocol triggers +protocol-specific events in addition to the core ones):

+
+
+
+
MG_EV_ACCEPT
+
+

sent when new server connection is accepted by a +listening connection. void *ev_data is union socket_address +of the remote peer.

+
+
MG_EV_CONNECT
+
+

sent when a new outbound connection created by +mg_connect() +either failed or succeeded. void *ev_data is int *success. +If success is 0, then connection has been established, +otherwise it contains error code. See +mg_connect_opt() function for code example.

+
+
MG_EV_RECV
+
+

New data is received and appended to the end of recv_mbuf. +void *ev_data is int *num_received_bytes. Typically, event handler +should check received data in nc→recv_mbuf, +discard processed data by calling mbuf_remove(), +set connection flags nc→flags if necessary +(see struct mg_connection), and write +data the remote peer by output functions like mg_send().

+
+
+
+
+ + + + + +
+Warning + +Mongoose uses realloc() to expand receive buffer. +It is user’s responsibility to discard processed +data from the beginning of receive buffer, note the mbuf_remove() +call in the example above. +
+
+
+
+
MG_EV_SEND
+
+

Mongoose has written data to the remote peer and discarded +written data from the +mg_connection::send_mbuf. void *ev_data +is int *num_sent_bytes.

+
+
+
+
+ + + + + +
+Note + +Mongoose output functions only append +data to the mg_connection::send_mbuf, they do not do any socket writes. +An actual IO is done by mg_mgr_poll(). MG_EV_SEND event +is just a notification about an IO has been done. +
+
+
+
+
MG_EV_POLL
+
+

Sent to all connections on each invocation of +mg_mgr_poll(). +This event could be used to do any housekeeping, for example check whether +certain timeout has expired and close the connection, or send heartbeet +message, et cetera.

+
+
MG_EV_TIMER
+
+

Sent to the connection if +mg_set_timer() was called.

+
+
+
+
+
+

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 udp://1.2.3.4:5678 +address, Mongoose is going to set MG_F_UDP flag for that connection. Other flags +are meant to be set only by user event handler to tell Mongoose how to behave. +Below is a list of connection flags that are meant to be set by event handlers:

+
+
+
    +
  • +

    MG_F_FINISHED_SENDING_DATA tells Mongoose that all data has been +appended to the send_mbuf. As soon as Mongoose sends it to the +socket, the connection will be closed.

    +
    • +
  • +

    MG_F_BUFFER_BUT_DONT_SEND tells Mongoose to append data to the +send_mbuf but hold on sending it, because the data will be modified +later and then will be sent by clearing MG_F_BUFFER_BUT_DONT_SEND flag.

    +
    • +
  • +

    MG_F_CLOSE_IMMEDIATELY tells Mongoose to close the connection +immediately, usually after some error

    +
    • +
  • +

    MG_F_USER_1, MG_F_USER_2, MG_F_USER_3, MG_F_USER_4 could be +used by a developer to store application-specific state

    +
    • +
+
+
+

Flags below are set by Mongoose:

+
+
+
    +
  • +

    MG_F_SSL_HANDSHAKE_DONE SSL only, set when SSL handshake is done.

    +
    • +
  • +

    MG_F_CONNECTING set when connection is in connecting state after +mg_connect() call but connect did not finish yet.

    +
    • +
  • +

    MG_F_LISTENING set for all listening connections

    +
    • +
  • +

    MG_F_UDP set if connection is UDP

    +
    • +
  • +

    MG_F_IS_WEBSOCKET set if connection is a Websocket connection

    +
    • +
  • +

    MG_F_WEBSOCKET_NO_DEFRAG should be set by a user if user wants to switch +off automatic Websocket frame defragmentation

    +
    • +
+
+
+
+
+
+

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

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

    +
    • +
+
+
+
+

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

    +
    • +
+
+
+
+

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.

    +
    • +
+
+
+
+

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.

    +
    • +
+
+
+
+
+
+

API Reference

+
+
+

Memory Buffers

+
+

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.

+
+
+

struct mbuf

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

+
+
+
+

mbuf_init()

+
+
+
void mbuf_init(struct mbuf *, size_t initial_capacity);
+
+
+
+

Initialize an Mbuf. +initial_capacity specifies the initial capacity of the mbuf.

+
+
+
+

mbuf_free()

+
+
+
void mbuf_free(struct mbuf *);
+
+
+
+

Free the space allocated for the mbuffer and resets the mbuf structure.

+
+
+
+

mbuf_append()

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

+
+
+
+

mbuf_insert()

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

+
+
+
+

mbuf_remove()

+
+
+
void mbuf_remove(struct mbuf *, size_t data_size);
+
+
+
+

Remove data_size bytes from the beginning of the buffer.

+
+
+
+

mbuf_resize()

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

+
+
+
+

mbuf_trim()

+
+
+
void mbuf_trim(struct mbuf *);
+
+
+
+

Shrink an Mbuf by resizing its size to len.

+
+
+
+
+

Core: TCP/UDP/SSL

+
+ + + + + +
+Note + +Mongoose manager is single threaded. It does not protect +its data structures by mutexes, therefore all functions that are dealing +with particular event manager should be called from the same thread, +with exception of mg_broadcast() function. It is fine to have different +event managers handled by different threads. +
+
+
+

struct mg_str

+
+
+
struct mg_str {
+  const char *p; /* Memory chunk pointer */
+  size_t len;    /* Memory chunk length */
+};
+
+
+
+

Describes chunk of memory

+
+
+
+

struct mg_mgr

+
+
+
struct mg_mgr {
+  struct mg_connection *active_connections;
+  const char *hexdump_file; /* Debug hexdump file path */
+#ifndef MG_DISABLE_SOCKETPAIR
+  sock_t ctl[2]; /* Socketpair for mg_wakeup() */
+#endif
+  void *user_data; /* User data */
+  void *mgr_data;  /* Implementation-specific event manager's data. */
+#ifdef MG_ENABLE_JAVASCRIPT
+  struct v7 *v7;
+#endif
+};
+
+
+
+

Mongoose event manager.

+
+
+
+

struct mg_connection

+
+
+
struct mg_connection {
+  struct mg_connection *next, *prev; /* mg_mgr::active_connections linkage */
+  struct mg_connection *listener;    /* Set only for accept()-ed connections */
+  struct mg_mgr *mgr;                /* Pointer to containing manager */
+
+  sock_t sock; /* Socket to the remote peer */
+  int err;
+  union socket_address sa; /* Remote peer address */
+  size_t recv_mbuf_limit;  /* Max size of recv buffer */
+  struct mbuf recv_mbuf;   /* Received data */
+  struct mbuf send_mbuf;   /* Data scheduled for sending */
+  SSL *ssl;
+  SSL_CTX *ssl_ctx;
+  time_t last_io_time;              /* Timestamp of the last socket IO */
+  double ev_timer_time;             /* Timestamp of the future MG_EV_TIMER */
+  mg_event_handler_t proto_handler; /* Protocol-specific event handler */
+  void *proto_data;                 /* Protocol-specific data */
+  void (*proto_data_destructor)(void *proto_data);
+  mg_event_handler_t handler; /* Event handler function */
+  void *user_data;            /* User-specific data */
+  union {
+    void *v;
+    /*
+     * the C standard is fussy about fitting function pointers into
+     * void pointers, since some archs might have fat pointers for functions.
+     */
+    mg_event_handler_t f;
+  } priv_1;       /* Used by mg_enable_multithreading() */
+  void *priv_2;   /* Used by mg_enable_multithreading() */
+  void *mgr_data; /* Implementation-specific event manager's data. */
+  unsigned long flags;
+/* Flags set by Mongoose */
+#define MG_F_LISTENING (1 << 0)          /* This connection is listening */
+#define MG_F_UDP (1 << 1)                /* This connection is UDP */
+#define MG_F_RESOLVING (1 << 2)          /* Waiting for async resolver */
+#define MG_F_CONNECTING (1 << 3)         /* connect() call in progress */
+#define MG_F_SSL_HANDSHAKE_DONE (1 << 4) /* SSL specific */
+#define MG_F_WANT_READ (1 << 5)          /* SSL specific */
+#define MG_F_WANT_WRITE (1 << 6)         /* SSL specific */
+#define MG_F_IS_WEBSOCKET (1 << 7)       /* Websocket specific */
+
+/* Flags that are settable by user */
+#define MG_F_SEND_AND_CLOSE (1 << 10)      /* Push remaining data and close  */
+#define MG_F_CLOSE_IMMEDIATELY (1 << 11)   /* Disconnect */
+#define MG_F_WEBSOCKET_NO_DEFRAG (1 << 12) /* Websocket specific */
+#define MG_F_DELETE_CHUNK (1 << 13)        /* HTTP specific */
+
+#define MG_F_USER_1 (1 << 20) /* Flags left for application */
+#define MG_F_USER_2 (1 << 21)
+#define MG_F_USER_3 (1 << 22)
+#define MG_F_USER_4 (1 << 23)
+#define MG_F_USER_5 (1 << 24)
+#define MG_F_USER_6 (1 << 25)
+};
+
+
+
+

Mongoose connection.

+
+
+
+

struct mg_add_sock_opts

+
+
+
struct mg_add_sock_opts {
+  void *user_data;           /* Initial value for connection's user_data */
+  unsigned int flags;        /* Initial connection flags */
+  const char **error_string; /* Placeholder for the error string */
+};
+
+
+
+

Optional parameters to mg_add_sock_opt().

+
+
+

flags is an initial struct mg_connection::flags bitmask to set, +see MG_F_* flags definitions.

+
+
+
+

struct mg_bind_opts

+
+
+
struct mg_bind_opts {
+  void *user_data;           /* Initial value for connection's user_data */
+  unsigned int flags;        /* Extra connection flags */
+  const char **error_string; /* Placeholder for the error string */
+#ifdef MG_ENABLE_SSL
+  /* SSL settings. */
+  const char *ssl_cert;    /* Server certificate to present to clients */
+  const char *ssl_ca_cert; /* Verify client certificates with this CA bundle */
+#endif
+};
+
+
+
+

Optional parameters to mg_bind_opt().

+
+
+

flags is an initial struct mg_connection::flags bitmask to set, +see MG_F_* flags definitions.

+
+
+
+

struct mg_connect_opts

+
+
+
struct mg_connect_opts {
+  void *user_data;           /* Initial value for connection's user_data */
+  unsigned int flags;        /* Extra connection flags */
+  const char **error_string; /* Placeholder for the error string */
+#ifdef MG_ENABLE_SSL
+  /* SSL settings. */
+  const char *ssl_cert;    /* Client certificate to present to the server */
+  const char *ssl_ca_cert; /* Verify server certificate using this CA bundle */
+
+  /*
+   * Server name verification. If ssl_ca_cert is set and the certificate has
+   * passed verification, its subject will be verified against this string.
+   * By default (if ssl_server_name is NULL) hostname part of the address will
+   * be used. Wildcard matching is supported. A special value of "*" disables
+   * name verification.
+   */
+  const char *ssl_server_name;
+#endif
+};
+
+
+
+

Optional parameters to mg_connect_opt()

+
+
+
+

mg_mgr_init()

+
+
+
void mg_mgr_init(struct mg_mgr *mgr, void *user_data);
+
+
+
+

Initialize Mongoose manager. Side effect: ignores SIGPIPE signal. +mgr→user_data field will be initialized with user_data parameter. +That is an arbitrary pointer, where user code can associate some data +with the particular Mongoose manager. For example, a C++ wrapper class +could be written, in which case user_data can hold a pointer to the +class instance.

+
+
+
+

mg_mgr_free()

+
+
+
void mg_mgr_free(struct mg_mgr *);
+
+
+
+

De-initializes Mongoose manager.

+
+
+

Close and deallocate all active connections.

+
+
+
+

mg_mgr_poll()

+
+
+
time_t mg_mgr_poll(struct mg_mgr *, int milli);
+
+
+
+

This function performs the actual IO, and must be called in a loop +(an event loop). Returns the current timestamp. +milli is the maximum number of milliseconds to sleep. +mg_mgr_poll() checks all connection for IO readiness. If at least one +of the connections is IO-ready, mg_mgr_poll() triggers respective +event handlers and returns.

+
+
+
+

mg_broadcast()

+
+
+
void mg_broadcast(struct mg_mgr *, mg_event_handler_t func, void *, size_t);
+
+
+
+

Pass a message of a given length to all connections.

+
+
+

Must be called from a thread that does NOT call mg_mgr_poll(). +Note that mg_broadcast() is the only function +that can be, and must be, called from a different (non-IO) thread.

+
+
+

func callback function will be called by the IO thread for each +connection. When called, event would be MG_EV_POLL, and message will +be passed as ev_data pointer. Maximum message size is capped +by MG_CTL_MSG_MESSAGE_SIZE which is set to 8192 bytes.

+
+
+
+

mg_next()

+
+
+
struct mg_connection *mg_next(struct mg_mgr *, struct mg_connection *);
+
+
+
+

Iterate over all active connections.

+
+
+

Returns next connection from the list +of active connections, or NULL if there is no more connections. Below +is the iteration idiom:

+
+
+
+
for (c = mg_next(srv, NULL); c != NULL; c = mg_next(srv, c)) {
+  // Do something with connection `c`
+}
+
+
+
+
+

mg_add_sock()

+
+
+
struct mg_connection *mg_add_sock(struct mg_mgr *, sock_t, mg_event_handler_t);
+
+
+
+

Create a connection, associate it with the given socket and event handler, +and add it to the manager.

+
+
+

For more options see the mg_add_sock_opt variant.

+
+
+
+

mg_add_sock_opt()

+
+
+
struct mg_connection *mg_add_sock_opt(struct mg_mgr *, sock_t,
+                                      mg_event_handler_t,
+                                      struct mg_add_sock_opts);
+
+
+
+

Create a connection, associate it with the given socket and event handler, +and add to the manager.

+
+
+

See the mg_add_sock_opts structure for a description of the options.

+
+
+
+

mg_bind()

+
+
+
struct mg_connection *mg_bind(struct mg_mgr *, const char *,
+                              mg_event_handler_t);
+
+
+
+

Create listening connection.

+
+
+

See mg_bind_opt for full documentation.

+
+
+
+

mg_bind_opt()

+
+
+
struct mg_connection *mg_bind_opt(struct mg_mgr *mgr, const char *address,
+                                  mg_event_handler_t handler,
+                                  struct mg_bind_opts opts);
+
+
+
+

Create listening connection.

+
+
+

address parameter tells which address to bind to. It’s format is the same +as for the mg_connect() call, where HOST part is optional. address +can be just a port number, e.g. :8000. To bind to a specific interface, +an IP address can be specified, e.g. 1.2.3.4:8000. By default, a TCP +connection is created. To create UDP connection, prepend udp:// prefix, +e.g. udp://:8000. To summarize, address paramer has following format: +[PROTO://][IP_ADDRESS]:PORT, where PROTO could be tcp or udp.

+
+
+

See the mg_bind_opts structure for a description of the optional +parameters.

+
+
+

Return a new listening connection, or NULL on error. +NOTE: Connection remains owned by the manager, do not free().

+
+
+
+

mg_connect()

+
+
+
struct mg_connection *mg_connect(struct mg_mgr *mgr, const char *address,
+                                 mg_event_handler_t handler);
+
+
+
+

Connect to a remote host.

+
+
+

See mg_connect_opt() for full documentation.

+
+
+
+

mg_connect_opt()

+
+
+
struct mg_connection *mg_connect_opt(struct mg_mgr *mgr, const char *address,
+                                     mg_event_handler_t handler,
+                                     struct mg_connect_opts opts);
+
+
+
+

Connect to a remote host.

+
+
+

address format is [PROTO://]HOST:PORT. PROTO could be tcp or udp. +HOST could be an IP address, +IPv6 address (if Mongoose is compiled with -DMG_ENABLE_IPV6), or a host +name. If HOST is a name, Mongoose will resolve it asynchronously. Examples +of valid addresses: google.com:80, udp://1.2.3.4:53, 10.0.0.1:443, +[::1]:80

+
+
+

See the mg_connect_opts structure for a description of the optional +parameters.

+
+
+

Returns a new outbound connection, or NULL on error.

+
+
+ + + + + +
+Note + +Connection remains owned by the manager, do not free(). +
+
+
+ + + + + +
+Note + +To enable IPv6 addresses, -DMG_ENABLE_IPV6 should be specified +in the compilation flags. +
+
+
+ + + + + +
+Note + +New connection will receive MG_EV_CONNECT as it’s first event +which will report connect success status. +If asynchronous resolution fail, or connect() syscall fail for whatever +reason (e.g. with ECONNREFUSED or ENETUNREACH), then MG_EV_CONNECT +event report failure. Code example below: +
+
+
+
+
static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) {
+  int connect_status;
+
+  switch (ev) {
+    case MG_EV_CONNECT:
+      connect_status = * (int *) ev_data;
+      if (connect_status == 0) {
+        // Success
+      } else  {
+        // Error
+        printf("connect() error: %s\n", strerror(connect_status));
+      }
+      break;
+    ...
+  }
+}
+
+  ...
+  mg_connect(mgr, "my_site.com:80", ev_handler);
+
+
+
+
+

mg_set_ssl()

+
+
+
const char *mg_set_ssl(struct mg_connection *nc, const char *cert,
+                       const char *ca_cert);
+
+
+
+

Enable SSL for a given connection. +cert is a server certificate file name for a listening connection, +or a client certificate file name for an outgoing connection. +Certificate files must be in PEM format. Server certificate file +must contain a certificate, concatenated with a private key, optionally +concatenated with parameters. +ca_cert is a CA certificate, or NULL if peer verification is not +required. +Return: NULL on success, or error message on error.

+
+
+
+

mg_send()

+
+
+
void mg_send(struct mg_connection *, const void *buf, int len);
+
+
+
+

Send data to the connection.

+
+
+

Note that sending functions do not actually push data to the socket. +They just append data to the output buffer. MG_EV_SEND will be delivered when +the data has actually been pushed out.

+
+
+
+

mg_printf()

+
+
+
int mg_printf(struct mg_connection *, const char *fmt, ...);
+
+
+
+

Send printf-style formatted data to the connection.

+
+
+

See mg_send for more details on send semantics.

+
+
+
+

mg_vprintf()

+
+
+
int mg_vprintf(struct mg_connection *, const char *fmt, va_list ap);
+
+
+
+

Same as mg_printf(), but takes va_list ap as an argument.

+
+
+
+

mg_socketpair()

+
+
+
int mg_socketpair(sock_t[2], int sock_type);
+
+
+
+

Create a socket pair. +sock_type can be either SOCK_STREAM or SOCK_DGRAM. +Return 0 on failure, 1 on success.

+
+
+
+

mg_check_ip_acl()

+
+
+
int mg_check_ip_acl(const char *acl, uint32_t remote_ip);
+
+
+
+

Verify given IP address against the ACL.

+
+
+

remote_ip - an IPv4 address to check, in host byte order +acl - a comma separated list of IP subnets: x.x.x.x/x or x.x.x.x. +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:

+
+
+

-0.0.0.0/0,+192.168/16 - deny all acccesses, only allow 192.168/16 subnet

+
+
+

To learn more about subnet masks, see the +Wikipedia page on Subnetwork

+
+
+

Return -1 if ACL is malformed, 0 if address is disallowed, 1 if allowed.

+
+
+
+

mg_enable_multithreading()

+
+
+
void mg_enable_multithreading(struct mg_connection *nc);
+
+
+
+

Enable multi-threaded handling for the given listening connection nc. +For each accepted connection, Mongoose will create a separate thread +and run event handler in that thread. Thus, if an event hanler is doing +a blocking call or some long computation, that will not slow down +other connections.

+
+
+
+

mg_enable_javascript()

+
+
+
enum v7_err mg_enable_javascript(struct mg_mgr *m, struct v7 *v7,
+                                 const char *init_js_file_name);
+
+
+
+

Enable server-side JavaScript scripting. +Requires -DMG_ENABLE_JAVASCRIPT compilation flag, and V7 engine sources. +v7 instance must not be destroyed during manager’s lifetime. +Return V7 error.

+
+
+
+

mg_set_timer()

+
+
+
double mg_set_timer(struct mg_connection *c, double timestamp);
+
+
+
+

Schedule MG_EV_TIMER event to be delivered at timestamp time. +timestamp is a UNIX time (a number of seconds since Epoch). It is +double instead of time_t to allow for sub-second precision. +Return the old timer value.

+
+
+

Example: set connect timeout to 1.5 seconds:

+
+
+
+
 c = mg_connect(&mgr, "cesanta.com", ev_handler);
+ mg_set_timer(c, mg_time() + 1.5);
+ ...
+
+ void ev_handler(struct mg_connection *c, int ev, void *ev_data) {
+ switch (ev) {
+   case MG_EV_CONNECT:
+     mg_set_timer(c, 0);  // Clear connect timer
+     break;
+   case MG_EV_TIMER:
+     log("Connect timeout");
+     c->flags |= MG_F_CLOSE_IMMEDIATELY;
+     break;
+
+
+
+
+

mg_time()

+
+
+
double mg_time();
+
+
+
+

A sub-second precision version of time().

+
+
+
+
+

HTTP + Websocket

+
+

struct http_message

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

+
+
+
+

struct websocket_message

+
+
+
struct websocket_message {
+  unsigned char *data;
+  size_t size;
+  unsigned char flags;
+};
+
+
+
+

WebSocket message

+
+
+
+

struct mg_http_multipart_part

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

+
+
+
+

struct mg_serve_http_opts

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

+
+
+
+

mg_set_protocol_http_websocket()

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

    +
    • +
+
+
+
+

mg_send_websocket_handshake()

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

+
+
+
+

mg_send_websocket_handshake2()

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

+
+
+
+

mg_connect_ws()

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

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

mg_connect_ws_opt()

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

+
+
+
+

mg_send_websocket_frame()

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

+
+
+
+

mg_send_websocket_framev()

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

+
+
+
+

mg_printf_websocket_frame()

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

+
+
+
+

mg_send_http_chunk()

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

mg_printf_http_chunk()

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

+
+
+
+

mg_send_response_line()

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

mg_send_head()

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

mg_printf_html_escape()

+
+
+
void mg_printf_html_escape(struct mg_connection *nc, const char *fmt, ...);
+
+
+
+

Send printf-formatted HTTP chunk, escaping HTML tags.

+
+
+
+

mg_parse_http()

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

+
+
+
+

mg_get_http_header()

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

mg_http_parse_header()

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

+
+
+
+

mg_parse_multipart()

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

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

mg_get_http_var()

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

+
+
+
+

mg_url_decode()

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

+
+
+
+

mg_http_create_digest_auth_header()

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

+
+
+
+

mg_connect_http()

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

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

mg_connect_http_opt()

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

+
+
+
+

mg_serve_http()

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

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

mg_register_http_endpoint()

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

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

mg_file_upload_handler()

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

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

JSON-RPC

+
+

struct mg_rpc_request

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

+
+
+
+

struct mg_rpc_reply

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

+
+
+
+

struct mg_rpc_error

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

+
+
+
+

mg_rpc_parse_reply()

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

    +
    • +
+
+
+
+

mg_rpc_create_request()

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

+
+
+
+

mg_rpc_create_reply()

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

+
+
+
+

mg_rpc_create_error()

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

+
+
+
+

mg_rpc_create_std_error()

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

    +
    • +
+
+
+
+

mg_rpc_dispatch()

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

+
+
+
+
+

DNS

+
+

struct mg_dns_resource_record

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

+
+
+
+

struct mg_dns_message

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

+
+
+
+

mg_dns_parse_record_data()

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

+
+
+
+

mg_send_dns_query()

+
+
+
void mg_send_dns_query(struct mg_connection *nc, const char *name,
+                       int query_type);
+
+
+
+

Send a DNS query to the remote end.

+
+
+
+

mg_dns_insert_header()

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

+
+
+
+

mg_dns_copy_questions()

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

+
+
+
+

mg_dns_encode_record()

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

+
+
+
+

mg_parse_dns()

+
+
+
int mg_parse_dns(const char *buf, int len, struct mg_dns_message *msg);
+
+
+
+

Low-level: parses a DNS response.

+
+
+
+

mg_dns_uncompress_name()

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

+
+
+
+

mg_set_protocol_dns()

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

+
+
+
+
+

DNS server

+
+

Disabled by default; enable with -DMG_ENABLE_DNS_SERVER.

+
+
+

mg_dns_create_reply()

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

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

mg_dns_reply_record()

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

+
+
+
+

mg_dns_send_reply()

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

+
+
+
+
+

MQTT

+
+

mg_set_protocol_mqtt()

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

    +
    • +
+
+
+
+

mg_send_mqtt_handshake()

+
+
+
void mg_send_mqtt_handshake(struct mg_connection *nc, const char *client_id);
+
+
+
+

Send MQTT handshake.

+
+
+
+

mg_send_mqtt_handshake_opt()

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

+
+
+
+

mg_mqtt_publish()

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

+
+
+
+

mg_mqtt_subscribe()

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

+
+
+
+

mg_mqtt_unsubscribe()

+
+
+
void mg_mqtt_unsubscribe(struct mg_connection *nc, char **topics,
+                         size_t topics_len, uint16_t message_id);
+
+
+
+

Unsubscribe from a bunch of topics.

+
+
+
+

mg_mqtt_disconnect()

+
+
+
void mg_mqtt_disconnect(struct mg_connection *nc);
+
+
+
+

Send a DISCONNECT command.

+
+
+
+

mg_mqtt_connack()

+
+
+
void mg_mqtt_connack(struct mg_connection *nc, uint8_t return_code);
+
+
+
+

Send a CONNACK command with a given return_code.

+
+
+
+

mg_mqtt_puback()

+
+
+
void mg_mqtt_puback(struct mg_connection *nc, uint16_t message_id);
+
+
+
+

Send a PUBACK command with a given message_id.

+
+
+
+

mg_mqtt_pubrec()

+
+
+
void mg_mqtt_pubrec(struct mg_connection *nc, uint16_t message_id);
+
+
+
+

Send a PUBREC command with a given message_id.

+
+
+
+

mg_mqtt_pubrel()

+
+
+
void mg_mqtt_pubrel(struct mg_connection *nc, uint16_t message_id);
+
+
+
+

Send a PUBREL command with a given message_id.

+
+
+
+

mg_mqtt_pubcomp()

+
+
+
void mg_mqtt_pubcomp(struct mg_connection *nc, uint16_t message_id);
+
+
+
+

Send a PUBCOMP command with a given message_id.

+
+
+
+

mg_mqtt_suback()

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

+
+
+
+

mg_mqtt_unsuback()

+
+
+
void mg_mqtt_unsuback(struct mg_connection *nc, uint16_t message_id);
+
+
+
+

Send a UNSUBACK command with a given message_id.

+
+
+
+

mg_mqtt_ping()

+
+
+
void mg_mqtt_ping(struct mg_connection *nc);
+
+
+
+

Send a PINGREQ command.

+
+
+
+

mg_mqtt_pong()

+
+
+
void mg_mqtt_pong(struct mg_connection *nc);
+
+
+
+

Send a PINGRESP command.

+
+
+
+

mg_mqtt_next_subscribe_topic()

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

+
+
+
+
+

MQTT Broker

+
+

struct mg_mqtt_session

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

+
+
+
+

struct mg_mqtt_broker

+
+
+
struct mg_mqtt_broker {
+  struct mg_mqtt_session *sessions; /* Session list */
+  void *user_data;                  /* User data */
+};
+
+
+
+

MQTT broker.

+
+
+
+

mg_mqtt_broker_init()

+
+
+
void mg_mqtt_broker_init(struct mg_mqtt_broker *brk, void *user_data);
+
+
+
+

Initialize a MQTT broker.

+
+
+
+

mg_mqtt_broker()

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

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

+
+
+
+

mg_mqtt_next()

+
+
+
struct mg_mqtt_session *mg_mqtt_next(struct mg_mqtt_broker *brk,
+                                     struct mg_mqtt_session *s);
+
+
+
+

Iterate over all mqtt sessions connections. Example:

+
+
+
+
struct mg_mqtt_session *s;
+for (s = mg_mqtt_next(brk, NULL); s != NULL; s = mg_mqtt_next(brk, s)) {
+  // Do something
+}
+
+
+
+
+
+

CoAP

+
+

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

struct mg_coap_option

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

+
+
+
+

struct mg_coap_message

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

+
+
+
+

mg_set_protocol_coap()

+
+
+
int mg_set_protocol_coap(struct mg_connection *nc);
+
+
+
+

Set CoAP protocol handler - trigger CoAP specific events

+
+
+
+

mg_coap_add_option()

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

+
+
+
+

mg_coap_free_options()

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

+
+
+
+

mg_coap_send_message()

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

    +
    • +
+
+
+
+

mg_coap_send_ack()

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

+
+
+
+

mg_coap_parse()

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

+
+
+
+

mg_coap_compose()

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

+
+
+
+
+

Utilities

+
+

mg_skip()

+
+
+
const char *mg_skip(const char *s, const char *end_string,
+                    const char *delimiters, struct mg_str *v);
+
+
+
+

Fetch substring from input string s, end into v. +Skips initial delimiter characters. Records first non-delimiter character +as the beginning of substring v. Then scans the rest of the string +until a delimiter character or end-of-string is found. +delimiters is a 0-terminated string containing delimiter characters. +Either one of delimiters or end_string terminates the search. +Return an s pointer, advanced forward where parsing stopped.

+
+
+
+

mg_ncasecmp()

+
+
+
int mg_ncasecmp(const char *s1, const char *s2, size_t len);
+
+
+
+

Cross-platform version of strncasecmp().

+
+
+
+

mg_casecmp()

+
+
+
int mg_casecmp(const char *s1, const char *s2);
+
+
+
+

Cross-platform version of strcasecmp().

+
+
+
+

mg_vcmp()

+
+
+
int mg_vcmp(const struct mg_str *str2, const char *str1);
+
+
+
+

Cross-platform version of strcmp() where where first string is +specified by struct mg_str.

+
+
+
+

mg_vcasecmp()

+
+
+
int mg_vcasecmp(const struct mg_str *str2, const char *str1);
+
+
+
+

Cross-platform version of strncasecmp() where first string is +specified by struct mg_str.

+
+
+
+

mg_base64_decode()

+
+
+
int mg_base64_decode(const unsigned char *s, int len, char *dst);
+
+
+
+

Decode base64-encoded string s, len into the destination dst. +Destination has to have enough space to hold decoded buffer. +Decoding stops either when all string has been decoded, or invalid +character appeared. +Destination is '\0'-terminated. +Return number of decoded characters. On success, that should be equal to +len. On error (invalid character) the return value is smaller then len.

+
+
+
+

mg_base64_encode()

+
+
+
void mg_base64_encode(const unsigned char *src, int src_len, char *dst);
+
+
+
+

Base64-encode chunk of memory src, src_len into the destination dst. +Destination has to have enough space to hold encoded buffer. +Destination is '\0'-terminated.

+
+
+
+

mg_stat()

+
+
+
int mg_stat(const char *path, cs_stat_t *st);
+
+
+
+

Perform a 64-bit stat() call against given file.

+
+
+

path should be UTF8 encoded.

+
+
+

Return value is the same as for stat() syscall.

+
+
+
+

mg_fopen()

+
+
+
FILE *mg_fopen(const char *path, const char *mode);
+
+
+
+

Open the given file and return a file stream.

+
+
+

path and mode should be UTF8 encoded.

+
+
+

Return value is the same as for the fopen() call.

+
+
+
+

mg_open()

+
+
+
int mg_open(const char *path, int flag, int mode);
+
+
+
+

Open the given file and return a file stream.

+
+
+

path should be UTF8 encoded.

+
+
+

Return value is the same as for the open() syscall.

+
+
+
+

mg_start_thread()

+
+
+
void *mg_start_thread(void *(*thread_func);
+
+
+
+

Start a new detached thread. +Arguments and semantic is the same as pthead’s pthread_create(). +thread_func is a thread function, thread_func_param is a parameter +that is passed to the thread function.

+
+
+
+

mg_conn_addr_to_str()

+
+
+
void mg_conn_addr_to_str(struct mg_connection *nc, char *buf, size_t len,
+                         int flags);
+
+
+
+

Convert connection’s local or remote address into string.

+
+
+

The flags parameter is a bit mask that controls the behavior, +see MG_SOCK_STRINGIFY_* definitions.

+
+
+
    +
  • +

    MG_SOCK_STRINGIFY_IP - print IP address

    +
    • +
  • +

    MG_SOCK_STRINGIFY_PORT - print port number

    +
    • +
  • +

    MG_SOCK_STRINGIFY_REMOTE - print remote peer’s IP/port, not local address

    +
    • +
+
+
+

If both port number and IP address are printed, they are separated by :. +If compiled with -DMG_ENABLE_IPV6, IPv6 addresses are supported.

+
+
+
+

mg_sock_to_str()

+
+
+
void mg_sock_to_str(sock_t sock, char *buf, size_t len, int flags);
+
+
+
+

Legacy interface.

+
+
+
+

mg_sock_addr_to_str()

+
+
+
void mg_sock_addr_to_str(const union socket_address *sa, char *buf, size_t len,
+                         int flags);
+
+
+
+

Convert socket’s address into string.

+
+
+

flags is MG_SOCK_STRINGIFY_IP and/or MG_SOCK_STRINGIFY_PORT.

+
+
+
+

mg_hexdump()

+
+
+
int mg_hexdump(const void *buf, int len, char *dst, int dst_len);
+
+
+
+

Generates human-readable hexdump of memory chunk.

+
+
+

Takes a memory buffer buf of length len and creates a hex dump of that +buffer in dst. Generated output is a-la hexdump(1). +Return length of generated string, excluding terminating \0. If returned +length is bigger than dst_len, overflow bytes are discarded.

+
+
+
+

mg_hexdump_connection()

+
+
+
void mg_hexdump_connection(struct mg_connection *nc, const char *path,
+                           const void *buf, int num_bytes, int ev);
+
+
+
+

Generates human-readable hexdump of the data sent or received by connection. +path is a file name where hexdump should be written. num_bytes is +a number of bytes sent/received. ev is one of the MG_* events sent to +an event handler. This function is supposed to be called from the +event handler.

+
+
+
+

mg_avprintf()

+
+
+
int mg_avprintf(char **buf, size_t size, const char *fmt, va_list ap);
+
+
+
+

Print message to buffer. If buffer is large enough to hold the message, +return buffer. If buffer is to small, allocate large enough buffer on heap, +and return allocated buffer. +This is a supposed use case:

+
+
+
+
char buf[5], *p = buf;
+p = mg_avprintf(&p, sizeof(buf), "%s", "hi there");
+use_p_somehow(p);
+if (p != buf) {
+  free(p);
+}
+
+
+
+

The purpose of this is to avoid malloc-ing if generated strings are small.

+
+
+
+

mg_is_big_endian()

+
+
+
int mg_is_big_endian(void);
+
+
+
+

Return true if target platform is big endian.

+
+
+
+

mg_next_comma_list_entry()

+
+
+
const char *mg_next_comma_list_entry(const char *list, struct mg_str *val,
+                                     struct mg_str *eq_val);
+
+
+
+

A helper function for traversing a comma separated list of values. +It returns a list pointer shifted to the next value, or NULL if the end +of the list found. +Value is stored in val vector. If value has form "x=y", then eq_val +vector is initialized to point to the "y" part, and val vector length +is adjusted to point only to "x". +If list is just a comma separated list of entries, like "aa,bb,cc" then +eq_val will contain zero-length string.

+
+
+

The purpose of this function is to parse comma separated string without +any copying/memory allocation.

+
+
+
+

mg_match_prefix()

+
+
+
int mg_match_prefix(const char *pattern, int pattern_len, const char *str);
+
+
+
+

Match 0-terminated string (mg_match_prefix) or string with given length +mg_match_prefix_n against a glob pattern. +Match is case-insensitive. Return number of bytes matched, or -1 if no match.

+
+
+
+

mg_mk_str()

+
+
+
struct mg_str mg_mk_str(const char *s);
+
+
+
+

A helper function for creating mg_str struct from plain C string. +NULL is allowed and becomes {NULL, 0}.

+
+
+
+

MG_MK_STR()

+
+
+
#define MG_MK_STR(str_literal);
+
+
+
+

Macro for initializing mg_str.

+
+
+
+
+
+
+ + + \ No newline at end of file diff --git a/docs/internal.adoc b/docs/internal.adoc new file mode 100644 index 00000000..a0c86672 --- /dev/null +++ b/docs/internal.adoc @@ -0,0 +1,36 @@ +==== mg_do_connect() + +[source,c] +---- +MG_INTERNAL struct mg_connection *mg_do_connect(struct mg_connection *nc, + int proto, + union socket_address *sa); +---- +internals that need to be accessible in unit tests + +==== to_wchar() + +[source,c] +---- +int to_wchar(const char *path, wchar_t *wbuf, size_t wbuf_len); +---- +Retur value is the same as for MultiByteToWideChar. + +==== mg_handle_chunked() + +[source,c] +---- +MG_INTERNAL size_t mg_handle_chunked(struct mg_connection *nc, + struct http_message *hm, char *buf, + size_t blen); +---- +Reassemble the content of the buffer (buf, blen) which should be +in the HTTP chunked encoding, by collapsing data chunks to the +beginning of the buffer. + +If chunks get reassembled, modify hm->body to point to the reassembled +body and fire MG_EV_HTTP_CHUNK event. If handler sets MG_F_DELETE_CHUNK +in nc->flags, delete reassembled body from the mbuf. + +Return reassembled body size. + diff --git a/docs/items.json b/docs/items.json deleted file mode 100644 index 7360d015..00000000 --- a/docs/items.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "items": [ - { "type": "section", "name": "usage-example" }, - { "type": "section", "name": "design-concept" }, - { "type": "section", "name": "build-options" }, - { "type": "flat_sections_set", "name": "c-api" } - ] -} diff --git a/docs/json-rpc.adoc b/docs/json-rpc.adoc new file mode 100644 index 00000000..e3604b6b --- /dev/null +++ b/docs/json-rpc.adoc @@ -0,0 +1,143 @@ +=== JSON-RPC + +==== struct mg_rpc_request + +[source,c] +---- +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 + +==== struct mg_rpc_reply + +[source,c] +---- +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 + +==== struct mg_rpc_error + +[source,c] +---- +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 + +==== mg_rpc_parse_reply() + +[source,c] +---- +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` + +==== mg_rpc_create_request() + +[source,c] +---- +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 + +==== mg_rpc_create_reply() + +[source,c] +---- +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 + +==== mg_rpc_create_error() + +[source,c] +---- +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 + +==== mg_rpc_create_std_error() + +[source,c] +---- +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)` + +==== mg_rpc_dispatch() + +[source,c] +---- +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. + diff --git a/docs/mbuf.adoc b/docs/mbuf.adoc new file mode 100644 index 00000000..58ef00ac --- /dev/null +++ b/docs/mbuf.adoc @@ -0,0 +1,85 @@ +=== Memory Buffers + +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. + +==== struct mbuf + +[source,c] +---- +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 + +==== mbuf_init() + +[source,c] +---- +void mbuf_init(struct mbuf *, size_t initial_capacity); +---- +Initialize an Mbuf. +`initial_capacity` specifies the initial capacity of the mbuf. + +==== mbuf_free() + +[source,c] +---- +void mbuf_free(struct mbuf *); +---- +Free the space allocated for the mbuffer and resets the mbuf structure. + +==== mbuf_append() + +[source,c] +---- +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. + +==== mbuf_insert() + +[source,c] +---- +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. + +==== mbuf_remove() + +[source,c] +---- +void mbuf_remove(struct mbuf *, size_t data_size); +---- +Remove `data_size` bytes from the beginning of the buffer. + +==== mbuf_resize() + +[source,c] +---- +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. + +==== mbuf_trim() + +[source,c] +---- +void mbuf_trim(struct mbuf *); +---- +Shrink an Mbuf by resizing its `size` to `len`. + diff --git a/docs/mqtt-broker.adoc b/docs/mqtt-broker.adoc new file mode 100644 index 00000000..12254075 --- /dev/null +++ b/docs/mqtt-broker.adoc @@ -0,0 +1,82 @@ +=== MQTT Broker + +==== struct mg_mqtt_session + +[source,c] +---- +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). + +==== struct mg_mqtt_broker + +[source,c] +---- +struct mg_mqtt_broker { + struct mg_mqtt_session *sessions; /* Session list */ + void *user_data; /* User data */ +}; +---- +MQTT broker. + +==== mg_mqtt_broker_init() + +[source,c] +---- +void mg_mqtt_broker_init(struct mg_mqtt_broker *brk, void *user_data); +---- +Initialize a MQTT broker. + +==== mg_mqtt_broker() + +[source,c] +---- +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`. + +==== mg_mqtt_next() + +[source,c] +---- +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 +} +``` + diff --git a/docs/mqtt.adoc b/docs/mqtt.adoc new file mode 100644 index 00000000..466e034d --- /dev/null +++ b/docs/mqtt.adoc @@ -0,0 +1,161 @@ +=== MQTT + +==== mg_set_protocol_mqtt() + +[source,c] +---- +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 + +==== mg_send_mqtt_handshake() + +[source,c] +---- +void mg_send_mqtt_handshake(struct mg_connection *nc, const char *client_id); +---- +Send MQTT handshake. + +==== mg_send_mqtt_handshake_opt() + +[source,c] +---- +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. + +==== mg_mqtt_publish() + +[source,c] +---- +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. + +==== mg_mqtt_subscribe() + +[source,c] +---- +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. + +==== mg_mqtt_unsubscribe() + +[source,c] +---- +void mg_mqtt_unsubscribe(struct mg_connection *nc, char **topics, + size_t topics_len, uint16_t message_id); +---- +Unsubscribe from a bunch of topics. + +==== mg_mqtt_disconnect() + +[source,c] +---- +void mg_mqtt_disconnect(struct mg_connection *nc); +---- +Send a DISCONNECT command. + +==== mg_mqtt_connack() + +[source,c] +---- +void mg_mqtt_connack(struct mg_connection *nc, uint8_t return_code); +---- +Send a CONNACK command with a given `return_code`. + +==== mg_mqtt_puback() + +[source,c] +---- +void mg_mqtt_puback(struct mg_connection *nc, uint16_t message_id); +---- +Send a PUBACK command with a given `message_id`. + +==== mg_mqtt_pubrec() + +[source,c] +---- +void mg_mqtt_pubrec(struct mg_connection *nc, uint16_t message_id); +---- +Send a PUBREC command with a given `message_id`. + +==== mg_mqtt_pubrel() + +[source,c] +---- +void mg_mqtt_pubrel(struct mg_connection *nc, uint16_t message_id); +---- +Send a PUBREL command with a given `message_id`. + +==== mg_mqtt_pubcomp() + +[source,c] +---- +void mg_mqtt_pubcomp(struct mg_connection *nc, uint16_t message_id); +---- +Send a PUBCOMP command with a given `message_id`. + +==== mg_mqtt_suback() + +[source,c] +---- +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. + +==== mg_mqtt_unsuback() + +[source,c] +---- +void mg_mqtt_unsuback(struct mg_connection *nc, uint16_t message_id); +---- +Send a UNSUBACK command with a given `message_id`. + +==== mg_mqtt_ping() + +[source,c] +---- +void mg_mqtt_ping(struct mg_connection *nc); +---- +Send a PINGREQ command. + +==== mg_mqtt_pong() + +[source,c] +---- +void mg_mqtt_pong(struct mg_connection *nc); +---- +Send a PINGRESP command. + +==== mg_mqtt_next_subscribe_topic() + +[source,c] +---- +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. + diff --git a/docs/net.adoc b/docs/net.adoc new file mode 100644 index 00000000..ed9b4ca5 --- /dev/null +++ b/docs/net.adoc @@ -0,0 +1,499 @@ +=== Core: TCP/UDP/SSL + +NOTE: Mongoose manager is single threaded. It does not protect +its data structures by mutexes, therefore all functions that are dealing +with particular event manager should be called from the same thread, +with exception of `mg_broadcast()` function. It is fine to have different +event managers handled by different threads. + +==== struct mg_str + +[source,c] +---- +struct mg_str { + const char *p; /* Memory chunk pointer */ + size_t len; /* Memory chunk length */ +}; +---- +Describes chunk of memory + +==== struct mg_mgr + +[source,c] +---- +struct mg_mgr { + struct mg_connection *active_connections; + const char *hexdump_file; /* Debug hexdump file path */ +#ifndef MG_DISABLE_SOCKETPAIR + sock_t ctl[2]; /* Socketpair for mg_wakeup() */ +#endif + void *user_data; /* User data */ + void *mgr_data; /* Implementation-specific event manager's data. */ +#ifdef MG_ENABLE_JAVASCRIPT + struct v7 *v7; +#endif +}; +---- +Mongoose event manager. + +==== struct mg_connection + +[source,c] +---- +struct mg_connection { + struct mg_connection *next, *prev; /* mg_mgr::active_connections linkage */ + struct mg_connection *listener; /* Set only for accept()-ed connections */ + struct mg_mgr *mgr; /* Pointer to containing manager */ + + sock_t sock; /* Socket to the remote peer */ + int err; + union socket_address sa; /* Remote peer address */ + size_t recv_mbuf_limit; /* Max size of recv buffer */ + struct mbuf recv_mbuf; /* Received data */ + struct mbuf send_mbuf; /* Data scheduled for sending */ + SSL *ssl; + SSL_CTX *ssl_ctx; + time_t last_io_time; /* Timestamp of the last socket IO */ + double ev_timer_time; /* Timestamp of the future MG_EV_TIMER */ + mg_event_handler_t proto_handler; /* Protocol-specific event handler */ + void *proto_data; /* Protocol-specific data */ + void (*proto_data_destructor)(void *proto_data); + mg_event_handler_t handler; /* Event handler function */ + void *user_data; /* User-specific data */ + union { + void *v; + /* + * the C standard is fussy about fitting function pointers into + * void pointers, since some archs might have fat pointers for functions. + */ + mg_event_handler_t f; + } priv_1; /* Used by mg_enable_multithreading() */ + void *priv_2; /* Used by mg_enable_multithreading() */ + void *mgr_data; /* Implementation-specific event manager's data. */ + unsigned long flags; +/* Flags set by Mongoose */ +#define MG_F_LISTENING (1 << 0) /* This connection is listening */ +#define MG_F_UDP (1 << 1) /* This connection is UDP */ +#define MG_F_RESOLVING (1 << 2) /* Waiting for async resolver */ +#define MG_F_CONNECTING (1 << 3) /* connect() call in progress */ +#define MG_F_SSL_HANDSHAKE_DONE (1 << 4) /* SSL specific */ +#define MG_F_WANT_READ (1 << 5) /* SSL specific */ +#define MG_F_WANT_WRITE (1 << 6) /* SSL specific */ +#define MG_F_IS_WEBSOCKET (1 << 7) /* Websocket specific */ + +/* Flags that are settable by user */ +#define MG_F_SEND_AND_CLOSE (1 << 10) /* Push remaining data and close */ +#define MG_F_CLOSE_IMMEDIATELY (1 << 11) /* Disconnect */ +#define MG_F_WEBSOCKET_NO_DEFRAG (1 << 12) /* Websocket specific */ +#define MG_F_DELETE_CHUNK (1 << 13) /* HTTP specific */ + +#define MG_F_USER_1 (1 << 20) /* Flags left for application */ +#define MG_F_USER_2 (1 << 21) +#define MG_F_USER_3 (1 << 22) +#define MG_F_USER_4 (1 << 23) +#define MG_F_USER_5 (1 << 24) +#define MG_F_USER_6 (1 << 25) +}; +---- +Mongoose connection. + +==== struct mg_add_sock_opts + +[source,c] +---- +struct mg_add_sock_opts { + void *user_data; /* Initial value for connection's user_data */ + unsigned int flags; /* Initial connection flags */ + const char **error_string; /* Placeholder for the error string */ +}; +---- +Optional parameters to `mg_add_sock_opt()`. + +`flags` is an initial `struct mg_connection::flags` bitmask to set, +see `MG_F_*` flags definitions. + +==== struct mg_bind_opts + +[source,c] +---- +struct mg_bind_opts { + void *user_data; /* Initial value for connection's user_data */ + unsigned int flags; /* Extra connection flags */ + const char **error_string; /* Placeholder for the error string */ +#ifdef MG_ENABLE_SSL + /* SSL settings. */ + const char *ssl_cert; /* Server certificate to present to clients */ + const char *ssl_ca_cert; /* Verify client certificates with this CA bundle */ +#endif +}; +---- +Optional parameters to `mg_bind_opt()`. + +`flags` is an initial `struct mg_connection::flags` bitmask to set, +see `MG_F_*` flags definitions. + +==== struct mg_connect_opts + +[source,c] +---- +struct mg_connect_opts { + void *user_data; /* Initial value for connection's user_data */ + unsigned int flags; /* Extra connection flags */ + const char **error_string; /* Placeholder for the error string */ +#ifdef MG_ENABLE_SSL + /* SSL settings. */ + const char *ssl_cert; /* Client certificate to present to the server */ + const char *ssl_ca_cert; /* Verify server certificate using this CA bundle */ + + /* + * Server name verification. If ssl_ca_cert is set and the certificate has + * passed verification, its subject will be verified against this string. + * By default (if ssl_server_name is NULL) hostname part of the address will + * be used. Wildcard matching is supported. A special value of "*" disables + * name verification. + */ + const char *ssl_server_name; +#endif +}; +---- +Optional parameters to `mg_connect_opt()` + +==== mg_mgr_init() + +[source,c] +---- +void mg_mgr_init(struct mg_mgr *mgr, void *user_data); +---- +Initialize Mongoose manager. Side effect: ignores SIGPIPE signal. +`mgr->user_data` field will be initialized with `user_data` parameter. +That is an arbitrary pointer, where user code can associate some data +with the particular Mongoose manager. For example, a C++ wrapper class +could be written, in which case `user_data` can hold a pointer to the +class instance. + +==== mg_mgr_free() + +[source,c] +---- +void mg_mgr_free(struct mg_mgr *); +---- +De-initializes Mongoose manager. + +Close and deallocate all active connections. + +==== mg_mgr_poll() + +[source,c] +---- +time_t mg_mgr_poll(struct mg_mgr *, int milli); +---- +This function performs the actual IO, and must be called in a loop +(an event loop). Returns the current timestamp. +`milli` is the maximum number of milliseconds to sleep. +`mg_mgr_poll()` checks all connection for IO readiness. If at least one +of the connections is IO-ready, `mg_mgr_poll()` triggers respective +event handlers and returns. + +==== mg_broadcast() + +[source,c] +---- +void mg_broadcast(struct mg_mgr *, mg_event_handler_t func, void *, size_t); +---- +Pass a message of a given length to all connections. + +Must be called from a thread that does NOT call `mg_mgr_poll()`. +Note that `mg_broadcast()` is the only function +that can be, and must be, called from a different (non-IO) thread. + +`func` callback function will be called by the IO thread for each +connection. When called, event would be `MG_EV_POLL`, and message will +be passed as `ev_data` pointer. Maximum message size is capped +by `MG_CTL_MSG_MESSAGE_SIZE` which is set to 8192 bytes. + +==== mg_next() + +[source,c] +---- +struct mg_connection *mg_next(struct mg_mgr *, struct mg_connection *); +---- +Iterate over all active connections. + +Returns next connection from the list +of active connections, or `NULL` if there is no more connections. Below +is the iteration idiom: + +```c +for (c = mg_next(srv, NULL); c != NULL; c = mg_next(srv, c)) { + // Do something with connection `c` +} +``` + +==== mg_add_sock() + +[source,c] +---- +struct mg_connection *mg_add_sock(struct mg_mgr *, sock_t, mg_event_handler_t); +---- +Create a connection, associate it with the given socket and event handler, +and add it to the manager. + +For more options see the `mg_add_sock_opt` variant. + +==== mg_add_sock_opt() + +[source,c] +---- +struct mg_connection *mg_add_sock_opt(struct mg_mgr *, sock_t, + mg_event_handler_t, + struct mg_add_sock_opts); +---- +Create a connection, associate it with the given socket and event handler, +and add to the manager. + +See the `mg_add_sock_opts` structure for a description of the options. + +==== mg_bind() + +[source,c] +---- +struct mg_connection *mg_bind(struct mg_mgr *, const char *, + mg_event_handler_t); +---- +Create listening connection. + +See `mg_bind_opt` for full documentation. + +==== mg_bind_opt() + +[source,c] +---- +struct mg_connection *mg_bind_opt(struct mg_mgr *mgr, const char *address, + mg_event_handler_t handler, + struct mg_bind_opts opts); +---- +Create listening connection. + +`address` parameter tells which address to bind to. It's format is the same +as for the `mg_connect()` call, where `HOST` part is optional. `address` +can be just a port number, e.g. `:8000`. To bind to a specific interface, +an IP address can be specified, e.g. `1.2.3.4:8000`. By default, a TCP +connection is created. To create UDP connection, prepend `udp://` prefix, +e.g. `udp://:8000`. To summarize, `address` paramer has following format: +`[PROTO://][IP_ADDRESS]:PORT`, where `PROTO` could be `tcp` or `udp`. + +See the `mg_bind_opts` structure for a description of the optional +parameters. + +Return a new listening connection, or `NULL` on error. +NOTE: Connection remains owned by the manager, do not free(). + +==== mg_connect() + +[source,c] +---- +struct mg_connection *mg_connect(struct mg_mgr *mgr, const char *address, + mg_event_handler_t handler); +---- +Connect to a remote host. + +See `mg_connect_opt()` for full documentation. + +==== mg_connect_opt() + +[source,c] +---- +struct mg_connection *mg_connect_opt(struct mg_mgr *mgr, const char *address, + mg_event_handler_t handler, + struct mg_connect_opts opts); +---- +Connect to a remote host. + +`address` format is `[PROTO://]HOST:PORT`. `PROTO` could be `tcp` or `udp`. +`HOST` could be an IP address, +IPv6 address (if Mongoose is compiled with `-DMG_ENABLE_IPV6`), or a host +name. If `HOST` is a name, Mongoose will resolve it asynchronously. Examples +of valid addresses: `google.com:80`, `udp://1.2.3.4:53`, `10.0.0.1:443`, +`[::1]:80` + +See the `mg_connect_opts` structure for a description of the optional +parameters. + +Returns a new outbound connection, or `NULL` on error. + +NOTE: Connection remains owned by the manager, do not free(). + +NOTE: To enable IPv6 addresses, `-DMG_ENABLE_IPV6` should be specified +in the compilation flags. + +NOTE: New connection will receive `MG_EV_CONNECT` as it's first event +which will report connect success status. +If asynchronous resolution fail, or `connect()` syscall fail for whatever +reason (e.g. with `ECONNREFUSED` or `ENETUNREACH`), then `MG_EV_CONNECT` +event report failure. Code example below: + +```c +static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) { + int connect_status; + + switch (ev) { + case MG_EV_CONNECT: + connect_status = * (int *) ev_data; + if (connect_status == 0) { + // Success + } else { + // Error + printf("connect() error: %s\n", strerror(connect_status)); + } + break; + ... + } +} + + ... + mg_connect(mgr, "my_site.com:80", ev_handler); +``` + +==== mg_set_ssl() + +[source,c] +---- +const char *mg_set_ssl(struct mg_connection *nc, const char *cert, + const char *ca_cert); +---- +Enable SSL for a given connection. +`cert` is a server certificate file name for a listening connection, +or a client certificate file name for an outgoing connection. +Certificate files must be in PEM format. Server certificate file +must contain a certificate, concatenated with a private key, optionally +concatenated with parameters. +`ca_cert` is a CA certificate, or NULL if peer verification is not +required. +Return: NULL on success, or error message on error. + +==== mg_send() + +[source,c] +---- +void mg_send(struct mg_connection *, const void *buf, int len); +---- +Send data to the connection. + +Note that sending functions do not actually push data to the socket. +They just append data to the output buffer. MG_EV_SEND will be delivered when +the data has actually been pushed out. + +==== mg_printf() + +[source,c] +---- +int mg_printf(struct mg_connection *, const char *fmt, ...); +---- +Send `printf`-style formatted data to the connection. + +See `mg_send` for more details on send semantics. + +==== mg_vprintf() + +[source,c] +---- +int mg_vprintf(struct mg_connection *, const char *fmt, va_list ap); +---- +Same as `mg_printf()`, but takes `va_list ap` as an argument. + +==== mg_socketpair() + +[source,c] +---- +int mg_socketpair(sock_t[2], int sock_type); +---- +Create a socket pair. +`sock_type` can be either `SOCK_STREAM` or `SOCK_DGRAM`. +Return 0 on failure, 1 on success. + +==== mg_check_ip_acl() + +[source,c] +---- +int mg_check_ip_acl(const char *acl, uint32_t remote_ip); +---- +Verify given IP address against the ACL. + +`remote_ip` - an IPv4 address to check, in host byte order +`acl` - a comma separated list of IP subnets: `x.x.x.x/x` or `x.x.x.x`. +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: + +`-0.0.0.0/0,+192.168/16` - deny all acccesses, only allow 192.168/16 subnet + +To learn more about subnet masks, see the +link:https://en.wikipedia.org/wiki/Subnetwork[Wikipedia page on Subnetwork] + +Return -1 if ACL is malformed, 0 if address is disallowed, 1 if allowed. + +==== mg_enable_multithreading() + +[source,c] +---- +void mg_enable_multithreading(struct mg_connection *nc); +---- +Enable multi-threaded handling for the given listening connection `nc`. +For each accepted connection, Mongoose will create a separate thread +and run event handler in that thread. Thus, if an event hanler is doing +a blocking call or some long computation, that will not slow down +other connections. + +==== mg_enable_javascript() + +[source,c] +---- +enum v7_err mg_enable_javascript(struct mg_mgr *m, struct v7 *v7, + const char *init_js_file_name); +---- +Enable server-side JavaScript scripting. +Requires `-DMG_ENABLE_JAVASCRIPT` compilation flag, and V7 engine sources. +v7 instance must not be destroyed during manager's lifetime. +Return V7 error. + +==== mg_set_timer() + +[source,c] +---- +double mg_set_timer(struct mg_connection *c, double timestamp); +---- +Schedule MG_EV_TIMER event to be delivered at `timestamp` time. +`timestamp` is a UNIX time (a number of seconds since Epoch). It is +`double` instead of `time_t` to allow for sub-second precision. +Return the old timer value. + +Example: set connect timeout to 1.5 seconds: + +``` + c = mg_connect(&mgr, "cesanta.com", ev_handler); + mg_set_timer(c, mg_time() + 1.5); + ... + + void ev_handler(struct mg_connection *c, int ev, void *ev_data) { + switch (ev) { + case MG_EV_CONNECT: + mg_set_timer(c, 0); // Clear connect timer + break; + case MG_EV_TIMER: + log("Connect timeout"); + c->flags |= MG_F_CLOSE_IMMEDIATELY; + break; +``` + +==== mg_time() + +[source,c] +---- +double mg_time(); +---- +A sub-second precision version of time(). + diff --git a/docs/net_if.adoc b/docs/net_if.adoc new file mode 100644 index 00000000..7666aa2a --- /dev/null +++ b/docs/net_if.adoc @@ -0,0 +1,127 @@ +==== mg_if_connect_tcp() + +[source,c] +---- +void mg_if_connect_tcp(struct mg_connection *nc, + const union socket_address *sa); +---- +Request that a TCP connection is made to the specified address. + +==== mg_if_connect_udp() + +[source,c] +---- +void mg_if_connect_udp(struct mg_connection *nc); +---- +Open a UDP socket. Doesn't actually connect anything. + +==== mg_if_connect_cb() + +[source,c] +---- +void mg_if_connect_cb(struct mg_connection *nc, int err); +---- +Callback invoked by connect methods. err = 0 -> ok, != 0 -> error. + +==== mg_if_listen_tcp() + +[source,c] +---- +int mg_if_listen_tcp(struct mg_connection *nc, union socket_address *sa); +---- +Set up a listening TCP socket on a given address. rv = 0 -> ok. + +==== mg_if_accept_new_conn() + +[source,c] +---- +struct mg_connection *mg_if_accept_new_conn(struct mg_connection *lc); +---- +Deliver a new TCP connection. Returns NULL in case on error (unable to +create connection, in which case interface state should be discarded. +This is phase 1 of the two-phase process - MG_EV_ACCEPT will be delivered +when mg_if_accept_tcp_cb is invoked. + +==== mg_if_listen_udp() + +[source,c] +---- +int mg_if_listen_udp(struct mg_connection *nc, union socket_address *sa); +---- +Request that a "listening" UDP socket be created. + +==== mg_if_tcp_send() + +[source,c] +---- +void mg_if_tcp_send(struct mg_connection *nc, const void *buf, size_t len); +---- +Send functions for TCP and UDP. Sent data is copied before return. + +==== mg_if_sent_cb() + +[source,c] +---- +void mg_if_sent_cb(struct mg_connection *nc, int num_sent); +---- +Callback that reports that data has been put on the wire. + +==== mg_if_recv_tcp_cb() + +[source,c] +---- +void mg_if_recv_tcp_cb(struct mg_connection *nc, void *buf, int len); +---- +Receive callback. +buf must be heap-allocated and ownership is transferred to the core. +Core will acknowledge consumption by calling mg_if_recved. + +==== mg_if_poll() + +[source,c] +---- +void mg_if_poll(struct mg_connection *nc, time_t now); +---- +Deliver a POLL event to the connection. + +==== mg_if_timer() + +[source,c] +---- +void mg_if_timer(struct mg_connection *c, double now); +---- +Deliver a TIMER event to the connection. + +==== mg_if_create_conn() + +[source,c] +---- +int mg_if_create_conn(struct mg_connection *nc); +---- +Perform interface-related connection initialization. Return 1 on success. + +==== mg_if_destroy_conn() + +[source,c] +---- +void mg_if_destroy_conn(struct mg_connection *nc); +---- +Perform interface-related cleanup on connection before destruction. + +==== mg_if_get_conn_addr() + +[source,c] +---- +void mg_if_get_conn_addr(struct mg_connection *nc, int remote, + union socket_address *sa); +---- +Put connection's address into *sa, local (remote = 0) or remote. + +==== mg_sock_set() + +[source,c] +---- +void mg_sock_set(struct mg_connection *nc, sock_t sock); +---- +Associate a socket to a connection. + diff --git a/docs/resolv.adoc b/docs/resolv.adoc new file mode 100644 index 00000000..ba70bf7a --- /dev/null +++ b/docs/resolv.adoc @@ -0,0 +1,64 @@ +=== Asynchronouns DNS resolver + +==== struct mg_resolve_async_opts + +[source,c] +---- +struct mg_resolve_async_opts { + const char *nameserver_url; + int max_retries; /* defaults to 2 if zero */ + int timeout; /* in seconds; defaults to 5 if zero */ + int accept_literal; /* pseudo-resolve literal ipv4 and ipv6 addrs */ + int only_literal; /* only resolves literal addrs; sync cb invocation */ + struct mg_connection **dns_conn; /* return DNS connection */ +}; +---- +Options for `mg_resolve_async_opt`. + +==== mg_resolve_async() + +[source,c] +---- +int mg_resolve_async(struct mg_mgr *mgr, const char *name, int query, + mg_resolve_callback_t cb, void *data); +---- +See `mg_resolve_async_opt()` + +==== mg_resolve_async_opt() + +[source,c] +---- +int mg_resolve_async_opt(struct mg_mgr *mgr, const char *name, int query, + mg_resolve_callback_t cb, void *data, + struct mg_resolve_async_opts opts); +---- +Resolved a DNS name asynchronously. + +Upon successful resolution, the user callback will be invoked +with the full DNS response message and a pointer to the user's +context `data`. + +In case of timeout while performing the resolution the callback +will receive a NULL `msg`. + +The DNS answers can be extracted with `mg_next_record` and +`mg_dns_parse_record_data`: + +[source,c] +---- +struct in_addr ina; +struct mg_dns_resource_record *rr = mg_next_record(msg, MG_DNS_A_RECORD, + NULL); +mg_dns_parse_record_data(msg, rr, &ina, sizeof(ina)); +---- + +==== mg_resolve_from_hosts_file() + +[source,c] +---- +int mg_resolve_from_hosts_file(const char *host, union socket_address *usa); +---- +Resolve a name from `/etc/hosts`. + +Returns 0 on success, -1 on failure. + diff --git a/docs/usage-example/intro.md b/docs/tutorial.adoc similarity index 53% rename from docs/usage-example/intro.md rename to docs/tutorial.adoc index 410e0657..9ade7b6a 100644 --- a/docs/usage-example/intro.md +++ b/docs/tutorial.adoc @@ -1,16 +1,16 @@ ---- -title: Usage Example ---- -- Copy `mongoose.c` and `mongoose.h` to your build tree -- Write code that uses Mongoose API, e.g. in `my_app.c` -- Compile application: `$ cc my_app.c mongoose.c` +== Usage Example -```c -#include "mongoose.h" // Include Mongoose API definitions +1. Copy `mongoose.c` and `mongoose.h` to your build tree +2. Write code that uses Mongoose API, e.g. in `my_app.c` +3. Compile application: `$ cc my_app.c mongoose.c` -// Define an event handler function -static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) { +[source,c] +.my_app.c +---- +#include "mongoose.h" // <1> + +static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) { // <2> struct mbuf *io = &nc->recv_mbuf; switch (ev) { @@ -27,18 +27,23 @@ static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) { int main(void) { struct mg_mgr mgr; - mg_mgr_init(&mgr, NULL); // Initialize event manager object + mg_mgr_init(&mgr, NULL); // <3> // Note that many connections can be added to a single event manager // Connections can be created at any point, e.g. in event handler function - mg_bind(&mgr, "1234", ev_handler); // Create listening connection and add it to the event manager + mg_bind(&mgr, "1234", ev_handler); // <4> - for (;;) { // Start infinite event loop + for (;;) { // <5> mg_mgr_poll(&mgr, 1000); } mg_mgr_free(&mgr); return 0; } -``` +---- +<1> Include Mongoose API definitions +<2> Define an event handler function +<3> Initialize event manager object +<4> Create listening connection and add it to the event manager +<5> Start infinite event loop diff --git a/docs/uri.adoc b/docs/uri.adoc new file mode 100644 index 00000000..c7173cad --- /dev/null +++ b/docs/uri.adoc @@ -0,0 +1,33 @@ +=== URI + +==== mg_parse_uri() + +[source,c] +---- +int mg_parse_uri(struct mg_str uri, struct mg_str *scheme, + struct mg_str *user_info, struct mg_str *host, + unsigned int *port, struct mg_str *path, struct mg_str *query, + struct mg_str *fragment); +---- +Parses an URI and fills string chunks with locations of the respective +uri components within the input uri string. NULL pointers will be +ignored. + +General syntax: + + [scheme://[user_info@]]host[:port][/path][?query][#fragment] + +Example: + + foo.com:80 + tcp://foo.com:1234 + http://foo.com:80/bar?baz=1 + https://user:pw@foo.com:443/blah + +`path` will include the leading slash. `query` won't include the leading `?`. +`host` can contain embedded colons if surrounded by square brackets in order +to support IPv6 literal addresses. + + +Returns 0 on success, -1 on error. + diff --git a/docs/usage-example/items.json b/docs/usage-example/items.json deleted file mode 100644 index bc7e70d8..00000000 --- a/docs/usage-example/items.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "items": [ - { "type": "markdown", "name": "intro.md" } - ] -} diff --git a/docs/util.adoc b/docs/util.adoc new file mode 100644 index 00000000..24e75c62 --- /dev/null +++ b/docs/util.adoc @@ -0,0 +1,260 @@ +=== Utilities + +==== mg_skip() + +[source,c] +---- +const char *mg_skip(const char *s, const char *end_string, + const char *delimiters, struct mg_str *v); +---- +Fetch substring from input string `s`, `end` into `v`. +Skips initial delimiter characters. Records first non-delimiter character +as the beginning of substring `v`. Then scans the rest of the string +until a delimiter character or end-of-string is found. +`delimiters` is a 0-terminated string containing delimiter characters. +Either one of `delimiters` or `end_string` terminates the search. +Return an `s` pointer, advanced forward where parsing stopped. + +==== mg_ncasecmp() + +[source,c] +---- +int mg_ncasecmp(const char *s1, const char *s2, size_t len); +---- +Cross-platform version of `strncasecmp()`. + +==== mg_casecmp() + +[source,c] +---- +int mg_casecmp(const char *s1, const char *s2); +---- +Cross-platform version of `strcasecmp()`. + +==== mg_vcmp() + +[source,c] +---- +int mg_vcmp(const struct mg_str *str2, const char *str1); +---- +Cross-platform version of `strcmp()` where where first string is +specified by `struct mg_str`. + +==== mg_vcasecmp() + +[source,c] +---- +int mg_vcasecmp(const struct mg_str *str2, const char *str1); +---- +Cross-platform version of `strncasecmp()` where first string is +specified by `struct mg_str`. + +==== mg_base64_decode() + +[source,c] +---- +int mg_base64_decode(const unsigned char *s, int len, char *dst); +---- +Decode base64-encoded string `s`, `len` into the destination `dst`. +Destination has to have enough space to hold decoded buffer. +Decoding stops either when all string has been decoded, or invalid +character appeared. +Destination is '\0'-terminated. +Return number of decoded characters. On success, that should be equal to +`len`. On error (invalid character) the return value is smaller then `len`. + +==== mg_base64_encode() + +[source,c] +---- +void mg_base64_encode(const unsigned char *src, int src_len, char *dst); +---- +Base64-encode chunk of memory `src`, `src_len` into the destination `dst`. +Destination has to have enough space to hold encoded buffer. +Destination is '\0'-terminated. + +==== mg_stat() + +[source,c] +---- +int mg_stat(const char *path, cs_stat_t *st); +---- +Perform a 64-bit `stat()` call against given file. + +`path` should be UTF8 encoded. + +Return value is the same as for `stat()` syscall. + +==== mg_fopen() + +[source,c] +---- +FILE *mg_fopen(const char *path, const char *mode); +---- +Open the given file and return a file stream. + +`path` and `mode` should be UTF8 encoded. + +Return value is the same as for the `fopen()` call. + +==== mg_open() + +[source,c] +---- +int mg_open(const char *path, int flag, int mode); +---- +Open the given file and return a file stream. + +`path` should be UTF8 encoded. + +Return value is the same as for the `open()` syscall. + +==== mg_start_thread() + +[source,c] +---- +void *mg_start_thread(void *(*thread_func); +---- +Start a new detached thread. +Arguments and semantic is the same as pthead's `pthread_create()`. +`thread_func` is a thread function, `thread_func_param` is a parameter +that is passed to the thread function. + +==== mg_conn_addr_to_str() + +[source,c] +---- +void mg_conn_addr_to_str(struct mg_connection *nc, char *buf, size_t len, + int flags); +---- +Convert connection's local or remote address into string. + +The `flags` parameter is a bit mask that controls the behavior, +see `MG_SOCK_STRINGIFY_*` definitions. + +- MG_SOCK_STRINGIFY_IP - print IP address +- MG_SOCK_STRINGIFY_PORT - print port number +- MG_SOCK_STRINGIFY_REMOTE - print remote peer's IP/port, not local address + +If both port number and IP address are printed, they are separated by `:`. +If compiled with `-DMG_ENABLE_IPV6`, IPv6 addresses are supported. + +==== mg_sock_to_str() + +[source,c] +---- +void mg_sock_to_str(sock_t sock, char *buf, size_t len, int flags); +---- +Legacy interface. + +==== mg_sock_addr_to_str() + +[source,c] +---- +void mg_sock_addr_to_str(const union socket_address *sa, char *buf, size_t len, + int flags); +---- +Convert socket's address into string. + +`flags` is MG_SOCK_STRINGIFY_IP and/or MG_SOCK_STRINGIFY_PORT. + +==== mg_hexdump() + +[source,c] +---- +int mg_hexdump(const void *buf, int len, char *dst, int dst_len); +---- +Generates human-readable hexdump of memory chunk. + +Takes a memory buffer `buf` of length `len` and creates a hex dump of that +buffer in `dst`. Generated output is a-la hexdump(1). +Return length of generated string, excluding terminating `\0`. If returned +length is bigger than `dst_len`, overflow bytes are discarded. + +==== mg_hexdump_connection() + +[source,c] +---- +void mg_hexdump_connection(struct mg_connection *nc, const char *path, + const void *buf, int num_bytes, int ev); +---- +Generates human-readable hexdump of the data sent or received by connection. +`path` is a file name where hexdump should be written. `num_bytes` is +a number of bytes sent/received. `ev` is one of the `MG_*` events sent to +an event handler. This function is supposed to be called from the +event handler. + +==== mg_avprintf() + +[source,c] +---- +int mg_avprintf(char **buf, size_t size, const char *fmt, va_list ap); +---- +Print message to buffer. If buffer is large enough to hold the message, +return buffer. If buffer is to small, allocate large enough buffer on heap, +and return allocated buffer. +This is a supposed use case: + + char buf[5], *p = buf; + p = mg_avprintf(&p, sizeof(buf), "%s", "hi there"); + use_p_somehow(p); + if (p != buf) { + free(p); + } + +The purpose of this is to avoid malloc-ing if generated strings are small. + +==== mg_is_big_endian() + +[source,c] +---- +int mg_is_big_endian(void); +---- +Return true if target platform is big endian. + +==== mg_next_comma_list_entry() + +[source,c] +---- +const char *mg_next_comma_list_entry(const char *list, struct mg_str *val, + struct mg_str *eq_val); +---- +A helper function for traversing a comma separated list of values. +It returns a list pointer shifted to the next value, or NULL if the end +of the list found. +Value is stored in val vector. If value has form "x=y", then eq_val +vector is initialized to point to the "y" part, and val vector length +is adjusted to point only to "x". +If list is just a comma separated list of entries, like "aa,bb,cc" then +`eq_val` will contain zero-length string. + +The purpose of this function is to parse comma separated string without +any copying/memory allocation. + +==== mg_match_prefix() + +[source,c] +---- +int mg_match_prefix(const char *pattern, int pattern_len, const char *str); +---- +Match 0-terminated string (mg_match_prefix) or string with given length +mg_match_prefix_n against a glob pattern. +Match is case-insensitive. Return number of bytes matched, or -1 if no match. + +==== mg_mk_str() + +[source,c] +---- +struct mg_str mg_mk_str(const char *s); +---- +A helper function for creating mg_str struct from plain C string. +`NULL` is allowed and becomes `{NULL, 0}`. + +==== MG_MK_STR() + +[source,c] +---- +#define MG_MK_STR(str_literal); +---- +Macro for initializing mg_str. +