mongoose.h 6.17

PUBLISHED_FROM=c0cbd13faf84fdac1f4566be02b596a232b68713

CONTRIBUTING.md

@@ -1,8 +0,0 @@
-People who have agreed to the
-[Cesanta CLA](https://docs.cesanta.com/contributors_la.shtml)
-can make contributions. Note that the CLA isn't a copyright
-_assigment_ but rather a copyright _license_.
-You retain the copyright on your contributions.
-
-We follow the Google C/C++ style guide: https://google.github.io/styleguide/cppguide.html
-We'd appreciate if your contribution follows the same style guide.

LICENSE

@@ -1,5 +1,5 @@
 Copyright (c) 2004-2013 Sergey Lyubka <valenok@gmail.com>
-Copyright (c) 2013-2016 Cesanta Software Limited
+Copyright (c) 2013-2018 Cesanta Software Limited
 All rights reserved
 
 This software is dual-licensed: you can redistribute it and/or modify

README.md

@@ -16,8 +16,8 @@ Check out [Mongoose OS](https://mongoose-os.com) - open source embedded operatin
 
 # Support
 - [Study mongoose example code](https://github.com/cesanta/mongoose/tree/master/examples)
-- [Read User Guide and API reference](https://docs.cesanta.com/mongoose)
-- [Support Forum - ask your technical questions here](https://forum.mongoose-os.com/categories/mongoose)
+- [Read User Guide and API reference](https://cesanta.com/docs/overview/intro.html)
+- [Support Forum - ask your technical questions here](https://community.mongoose-os.com/)
 - [Commercial licensing and support available](https://www.cesanta.com/licensing.html)
 - [Check our latest releases](https://github.com/cesanta/mongoose/releases)
 
@@ -62,7 +62,7 @@ the functionality:
 # Contributions
 
 To submit contributions, sign [Cesanta CLA](https://cesanta.com/cla.html)
-and send GitHub pull request. You retain the copyright on your contributions.
+and send GitHub pull request.
 
 # Looking for a pre-compiled Mongoose web server Windows or Mac binary?
 - [Download pre-compiled Mongoose web server binary.](https://www.cesanta.com/binary.html)

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

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

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

@@ -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);
----
-
-Parses the HTTP header `hdr`. Finds variable `var_name` and stores its value
-in the buffer `buf`, `buf_size`. Returns 0 if variable not found, non-zero
-otherwise.
-
-This function is supposed to parse cookies, authentication headers, etc.
-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));
-
-Returns the length of the variable's value. If buffer is not large enough,
-or variable not found, 0 is returned. 
-

docs/c-api/intro.md

@@ -1,16 +1,16 @@
 ---
 items:
   - { name: mbuf.h }
-  - { name: net.h }
-  - { name: http.h }
-  - { name: http_server.h }
-  - { name: http_client.h }
-  - { name: dns.h }
-  - { name: dns_server.h }
-  - { name: resolv.h }
-  - { name: mqtt.h }
-  - { name: mqtt_server.h }
-  - { name: coap.h }
-  - { name: util.h }
-  - { name: uri.h }
+  - { name: mg_net.h }
+  - { name: mg_http.h }
+  - { name: mg_http_server.h }
+  - { name: mg_http_client.h }
+  - { name: mg_dns.h }
+  - { name: mg_dns_server.h }
+  - { name: mg_resolv.h }
+  - { name: mg_mqtt.h }
+  - { name: mg_mqtt_server.h }
+  - { name: mg_coap.h }
+  - { name: mg_util.h }
+  - { name: mg_uri.h }
 ---

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

@@ -1,12 +1,15 @@
 ---
-title: "Memory Buffers"
+title: "mbuf.h"
 symbol_kind: "intro"
 decl_name: "mbuf.h"
 items:
   - { name: mbuf_append.md }
+  - { name: mbuf_append_and_free.md }
+  - { name: mbuf_clear.md }
   - { name: mbuf_free.md }
   - { name: mbuf_init.md }
   - { name: mbuf_insert.md }
+  - { name: mbuf_move.md }
   - { name: mbuf_remove.md }
   - { name: mbuf_resize.md }
   - { name: mbuf_trim.md }

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

@@ -0,0 +1,13 @@
+---
+title: "mbuf_append_and_free()"
+decl_name: "mbuf_append_and_free"
+symbol_kind: "func"
+signature: |
+  size_t mbuf_append_and_free(struct mbuf *, void *data, size_t data_size);
+---
+
+Appends data to the Mbuf and frees it (data must be heap-allocated).
+
+Returns the number of bytes appended or 0 if out of memory.
+data is freed irrespective of return value. 
+

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

@@ -0,0 +1,10 @@
+---
+title: "mbuf_clear()"
+decl_name: "mbuf_clear"
+symbol_kind: "func"
+signature: |
+  void mbuf_clear(struct mbuf *);
+---
+
+Removes all the data from mbuf (if any). 
+

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

@@ -0,0 +1,10 @@
+---
+title: "mbuf_move()"
+decl_name: "mbuf_move"
+symbol_kind: "func"
+signature: |
+  void mbuf_move(struct mbuf *from, struct mbuf *to);
+---
+
+Moves the state from one mbuf to the other. 
+

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

@@ -1,7 +1,7 @@
 ---
 title: "CoAP API reference"
 symbol_kind: "intro"
-decl_name: "coap.h"
+decl_name: "mg_coap.h"
 items:
   - { name: mg_coap_add_option.md }
   - { name: mg_coap_compose.md }

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

@@ -1,7 +1,7 @@
 ---
 title: "DNS API reference"
 symbol_kind: "intro"
-decl_name: "dns.h"
+decl_name: "mg_dns.h"
 items:
   - { name: mg_dns_copy_questions.md }
   - { name: mg_dns_encode_name.md }

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

@@ -1,7 +1,7 @@
 ---
 title: "DNS server API reference"
 symbol_kind: "intro"
-decl_name: "dns_server.h"
+decl_name: "mg_dns_server.h"
 items:
   - { name: mg_dns_create_reply.md }
   - { name: mg_dns_reply_record.md }

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

@@ -1,10 +1,12 @@
 ---
 title: "Common API reference"
 symbol_kind: "intro"
-decl_name: "http.h"
+decl_name: "mg_http.h"
 items:
   - { name: mg_connect_ws.md }
   - { name: mg_connect_ws_opt.md }
+  - { name: mg_http_is_authorized.md }
+  - { name: mg_http_send_digest_auth_request.md }
   - { name: mg_printf_websocket_frame.md }
   - { name: mg_send_websocket_frame.md }
   - { name: mg_send_websocket_framev.md }

docs/c-api/mg_http.h/mg_http_is_authorized.md

@@ -0,0 +1,16 @@
+---
+title: "mg_http_is_authorized()"
+decl_name: "mg_http_is_authorized"
+symbol_kind: "func"
+signature: |
+  int mg_http_is_authorized(struct http_message *hm, struct mg_str path,
+                            const char *domain, const char *passwords_file,
+                            int flags);
+---
+
+Checks whether an http request is authorized. `domain` is the authentication
+realm, `passwords_file` is a htdigest file (can be created e.g. with
+`htdigest` utility). If either `domain` or `passwords_file` is NULL, this
+function always returns 1; otherwise checks the authentication in the
+http request and returns 1 only if there is a match; 0 otherwise. 
+

docs/c-api/mg_http.h/mg_http_send_digest_auth_request.md

@@ -0,0 +1,11 @@
+---
+title: "mg_http_send_digest_auth_request()"
+decl_name: "mg_http_send_digest_auth_request"
+symbol_kind: "func"
+signature: |
+  void mg_http_send_digest_auth_request(struct mg_connection *c,
+                                        const char *domain);
+---
+
+Sends 401 Unauthorized response. 
+

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

@@ -7,8 +7,6 @@ signature: |
                                 const struct mg_str *strings, int num_strings);
 ---
 
-Sends multiple websocket frames.
-
-Like `mg_send_websocket_frame()`, but composes a frame from multiple
-*buffers. 
+Like `mg_send_websocket_frame()`, but composes a single frame from multiple
+buffers. 
 

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

@@ -30,7 +30,9 @@ The user-defined event handler will receive following extra events:
 - MG_EV_WEBSOCKET_HANDSHAKE_REQUEST: server has received the WebSocket
   handshake request. `ev_data` contains parsed HTTP request.
 - MG_EV_WEBSOCKET_HANDSHAKE_DONE: server has completed the WebSocket
-  handshake. `ev_data` is `NULL`.
+  handshake. `ev_data` is a `struct http_message` containing the
+  client's request (server mode) or server's response (client).
+  In client mode handler can examine `resp_code`, which should be 101.
 - MG_EV_WEBSOCKET_FRAME: new WebSocket frame has arrived. `ev_data` is
   `struct websocket_message *`
 

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

@@ -0,0 +1,24 @@
+---
+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;
+    /*
+     * User handler can indicate how much of the data was consumed
+     * by setting this variable. By default, it is assumed that all
+     * data has been consumed by the handler.
+     * If not all data was consumed, user's handler will be invoked again later
+     * with the remainder.
+     */
+    size_t num_data_consumed;
+  };
+---
+
+HTTP multipart part 
+

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

@@ -1,7 +1,7 @@
 ---
 title: "Client API reference"
 symbol_kind: "intro"
-decl_name: "http_client.h"
+decl_name: "mg_http_client.h"
 items:
   - { name: mg_connect_http.md }
   - { name: mg_connect_http_opt.md }

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

@@ -6,7 +6,7 @@ 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);
+                                        const char *passwd, const char *nonce);
 ---
 
 Creates digest authentication header for a client request. 

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

@@ -1,7 +1,7 @@
 ---
 title: "Server API reference"
 symbol_kind: "intro"
-decl_name: "http_server.h"
+decl_name: "mg_http_server.h"
 items:
   - { name: mg_check_digest_auth.md }
   - { name: mg_file_upload_handler.md }
@@ -10,6 +10,7 @@ items:
   - { name: mg_get_http_var.md }
   - { name: mg_http_check_digest_auth.md }
   - { name: mg_http_parse_header.md }
+  - { name: mg_http_parse_header2.md }
   - { name: mg_http_reverse_proxy.md }
   - { name: mg_http_send_error.md }
   - { name: mg_http_send_redirect.md }

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

@@ -0,0 +1,15 @@
+---
+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);
+---
+
+DEPRECATED: use mg_http_parse_header2() instead.
+
+Same as mg_http_parse_header2(), but takes buffer as a `char *` (instead of
+`char **`), and thus it cannot allocate a new buffer if the provided one
+is not enough, and just returns 0 in that case. 
+

docs/c-api/mg_http_server.h/mg_http_parse_header2.md

@@ -0,0 +1,30 @@
+---
+title: "mg_http_parse_header2()"
+decl_name: "mg_http_parse_header2"
+symbol_kind: "func"
+signature: |
+  int mg_http_parse_header2(struct mg_str *hdr, const char *var_name, char **buf,
+                            size_t buf_size);
+---
+
+Parses the HTTP header `hdr`. Finds variable `var_name` and stores its value
+in the buffer `*buf`, `buf_size`. If the buffer size is not enough,
+allocates a buffer of required size and writes it to `*buf`, similar to
+asprintf(). The caller should always check whether the buffer was updated,
+and free it if so.
+
+This function is supposed to parse cookies, authentication headers, etc.
+Example (error handling omitted):
+
+    char user_buf[20];
+    char *user = user_buf;
+    struct mg_str *hdr = mg_get_http_header(hm, "Authorization");
+    mg_http_parse_header2(hdr, "username", &user, sizeof(user_buf));
+    // ... do something useful with user
+    if (user != user_buf) {
+      free(user);
+    }
+
+Returns the length of the variable's value. If variable is not found, 0 is
+returned. 
+

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

@@ -1,7 +1,7 @@
 ---
 title: "MQTT API reference"
 symbol_kind: "intro"
-decl_name: "mqtt.h"
+decl_name: "mg_mqtt.h"
 items:
   - { name: mg_mqtt_connack.md }
   - { name: mg_mqtt_disconnect.md }