Add functions reference documentationguppy_6.99.4guppy/6.99.46.99.4

Only JSON helpers functions were documented before this commits. This add a description
for every function of the afb-helpers library.

Bug-AGL: SPEC-2114

Change-Id: I3ae941841ef4ad8e345dd4cd6bc012f6596eadc2
Signed-off-by: Romain Forlot <romain.forlot@iot.bzh>

1 files changed, 0 insertions, 335 deletions

diff --git a/wrap-json.md b/wrap-json.md
deleted file mode 100644
index 8f7693c..0000000
--- a/wrap-json.md
+++ /dev/null
@@ -1,335 +0,0 @@
-WRAP-JSON facility
-==================
-
-The facility wrap-json is based on the pack/unpack API on the
-library jansson. The two chapters below are copied from the
-documentation of jansson library copyrighted by Petri Lehtinen
-(see at end).
-
-Building Values
----------------
-
-This section describes functions that help to create, or *pack*, complex
-JSON values, especially nested objects and arrays. Value building is
-based on a *format string* that is used to tell the functions about the
-expected arguments.
-
-For example, the format string `"i"` specifies a single integer value,
-while the format string `"[ssb]"` or the equivalent `"[s, s, b]"`
-specifies an array value with two strings and a boolean as its items:
-
-    /* Create the JSON integer 42 */
-    wrap_json_pack(&result, "i", 42);
-
-    /* Create the JSON array ["foo", "bar", true] */
-    wrap_json_pack(&result, "[ssb]", "foo", "bar", 1);
-
-Here's the full list of format specifiers. The type in parentheses
-denotes the resulting JSON type, and the type in brackets (if any)
-denotes the C type that is expected as the corresponding argument or
-arguments.
-
-`s` (string) \[const char \*\]
-
-:   Convert a null terminated UTF-8 string to a JSON string.
-
-`s?` (string) \[const char \*\]
-
-:   Like `s`, but if the argument is *NULL*, output a JSON null value.
-
-`s*` (string) \[const char \*\]
-
-:   Like `s`, but if the argument is *NULL*, do not output any value.
-    This format can only be used inside an object or an array. If used
-    inside an object, the corresponding key is additionally suppressed
-    when the value is omitted. See below for an example.
-
-`s#` (string) \[const char \*, int\]
-
-:   Convert a UTF-8 buffer of a given length to a JSON string.
-
-`s%` (string) \[const char \*, size\_t\]
-
-:   Like `s#` but the length argument is of type size\_t.
-
-`+` \[const char \*\]
-
-:   Like `s`, but concatenate to the previous string. Only valid after
-    `s`, `s#`, `+` or `+#`.
-
-`+#` \[const char \*, int\]
-
-:   Like `s#`, but concatenate to the previous string. Only valid after
-    `s`, `s#`, `+` or `+#`.
-
-`+%` (string) \[const char \*, size\_t\]
-
-:   Like `+#` but the length argument is of type size\_t.
-
-`y` (byte array) \[const uint8_t \*, size\_t\]
-
-:   Convert the byte array whose length is given to
-    its base64url string representation.
-
-`Y` (byte array) \[const uint8_t \*, size\_t\]
-
-:   Like 'y' but output is base64.
-
-`y?`, `Y?` (byte array or null) \[const uint8_t \*, size\_t\]
-
-:   Like 'y' or 'Y' but allows to output a JSON null value
-    either when the buffer is *NULL* or when the size is *0*.
-
-`y*`, `y*` (optional byte array) \[const uint8_t \*, size\_t\]
-
-:   Like 'y' or 'Y' but do not put JSON value
-    either when the buffer is *NULL* or when the size is *0*.
-    This format can only be used inside an object or an array. If used
-    inside an object, the corresponding key is additionally suppressed
-    when the value is omitted. See below for an example.
-
-`n` (null)
-
-:   Output a JSON null value. No argument is consumed.
-
-`b` (boolean) \[int\]
-
-:   Convert a C int to JSON boolean value. Zero is converted to `false`
-    and non-zero to `true`.
-
-`i` (integer) \[int\]
-
-:   Convert a C int to JSON integer.
-
-`I` (integer) \[json\_int\_t\]
-
-:   Convert a C json\_int\_t to JSON integer.
-
-`f` (real) \[double\]
-
-:   Convert a C double to JSON real.
-
-`o` (any value) \[json\_t \*\]
-
-:   Output any given JSON value as-is. If the value is added to an array
-    or object, the reference to the value passed to `o` is stolen by the
-    container.
-
-`O` (any value) \[json\_t \*\]
-
-:   Like `o`, but the argument's reference count is incremented. This is
-    useful if you pack into an array or object and want to keep the
-    reference for the JSON value consumed by `O` to yourself.
-
-`o?`, `O?` (any value) \[json\_t \*\]
-
-:   Like `o` and `O`, respectively, but if the argument is *NULL*,
-    output a JSON null value.
-
-`o*`, `O*` (any value) \[json\_t \*\]
-
-:   Like `o` and `O`, respectively, but if the argument is *NULL*, do
-    not output any value. This format can only be used inside an object
-    or an array. If used inside an object, the corresponding key is
-    additionally suppressed. See below for an example.
-
-`[fmt]` (array)
-
-:   Build an array with contents from the inner format string. `fmt` may
-    contain objects and arrays, i.e. recursive value building is
-    supported.
-
-`{fmt}` (object)
-
-:   Build an object with contents from the inner format string `fmt`.
-    The first, third, etc. format specifier represent a key, and must be
-    a string (see `s`, `s#`, `+` and `+#` above), as object keys are
-    always strings. The second, fourth, etc. format specifier represent
-    a value. Any value may be an object or array, i.e. recursive value
-    building is supported.
-
-Whitespace, `:` and `,` are ignored.
-
-More examples:
-
-    /* Build an empty JSON object */
-    wrap_json_pack(&result, "{}");
-
-    /* Build the JSON object {"foo": 42, "bar": 7} */
-    wrap_json_pack(&result, "{sisi}", "foo", 42, "bar", 7);
-
-    /* Like above, ':', ',' and whitespace are ignored */
-    wrap_json_pack(&result, "{s:i, s:i}", "foo", 42, "bar", 7);
-
-    /* Build the JSON array [[1, 2], {"cool": true}] */
-    wrap_json_pack(&result, "[[i,i],{s:b}]", 1, 2, "cool", 1);
-
-    /* Build a string from a non-null terminated buffer */
-    char buffer[4] = {'t', 'e', 's', 't'};
-    wrap_json_pack(&result, "s#", buffer, 4);
-
-    /* Concatenate strings together to build the JSON string "foobarbaz" */
-    wrap_json_pack(&result, "s++", "foo", "bar", "baz");
-
-    /* Create an empty object or array when optional members are missing */
-    wrap_json_pack(&result, "{s:s*,s:o*,s:O*}", "foo", NULL, "bar", NULL, "baz", NULL);
-    wrap_json_pack(&result, "[s*,o*,O*]", NULL, NULL, NULL);
-
-Parsing and Validating Values
------------------------------
-
-This section describes functions that help to validate complex values
-and extract, or *unpack*, data from them. Like building values
-<apiref-pack>, this is also based on format strings.
-
-While a JSON value is unpacked, the type specified in the format string
-is checked to match that of the JSON value. This is the validation part
-of the process. In addition to this, the unpacking functions can also
-check that all items of arrays and objects are unpacked. This check be
-enabled with the format specifier `!` or by using the flag
-`JSON_STRICT`. See below for details.
-
-Here's the full list of format specifiers. The type in parentheses
-denotes the JSON type, and the type in brackets (if any) denotes the C
-type whose address should be passed.
-
-`s` (string) \[const char \*\]
-
-:   Convert a JSON string to a pointer to a null terminated UTF-8
-    string. The resulting string is extracted by using
-    json\_string\_value() internally, so it exists as long as there are
-    still references to the corresponding JSON string.
-
-`s%` (string) \[const char \*, size\_t \*\]
-
-:   Convert a JSON string to a pointer to a null terminated UTF-8 string
-    and its length.
-
-`y` (byte array) \[uint8_t \*\*, size\_t \*\]
-
-:   Convert an input string base64url encoded to its
-    byte array representation. The result and its length
-    are stored. The returned buffer must be freed by the caller.
-
-`Y` (byte array) \[uint8_t \*\*, size\_t \*\]
-
-:   Like 'y' but input is base64.
-
-`n` (null)
-
-:   Expect a JSON null value. Nothing is extracted.
-
-`b` (boolean) \[int\]
-
-:   Convert a JSON boolean value to a C int, so that `true` is converted
-    to 1 and `false` to 0.
-
-`i` (integer) \[int\]
-
-:   Convert a JSON integer to C int.
-
-`I` (integer) \[json\_int\_t\]
-
-:   Convert a JSON integer to C json\_int\_t.
-
-`f` (real) \[double\]
-
-:   Convert a JSON real to C double.
-
-`F` (integer or real) \[double\]
-
-:   Convert a JSON number (integer or real) to C double.
-
-`o` (any value) \[json\_t \*\]
-
-:   Store a JSON value with no conversion to a json\_t pointer.
-
-`O` (any value) \[json\_t \*\]
-
-:   Like `O`, but the JSON value's reference count is incremented.
-
-`[fmt]` (array)
-
-:   Convert each item in the JSON array according to the inner format
-    string. `fmt` may contain objects and arrays, i.e. recursive value
-    extraction is supported.
-
-`{fmt}` (object)
-
-:   Convert each item in the JSON object according to the inner format
-    string `fmt`. The first, third, etc. format specifier represent a
-    key, and must be `s`. The corresponding argument to unpack functions
-    is read as the object key. The second fourth, etc. format specifier
-    represent a value and is written to the address given as the
-    corresponding argument. **Note** that every other argument is read
-    from and every other is written to.
-
-    `fmt` may contain objects and arrays as values, i.e. recursive value
-    extraction is supported.
-
-`!`
-
-:   This special format specifier is used to enable the check that all
-    object and array items are accessed, on a per-value basis. It must
-    appear inside an array or object as the last format specifier before
-    the closing bracket or brace.
-
-`*`
-
-:   This special format specifier is the opposite of `!`. This is the default.
-    It must appear inside an array or object as the last format specifier
-    before the closing bracket or brace.
-
-Whitespace, `:` and `,` are ignored.
-
-Examples:
-
-    /* root is the JSON integer 42 */
-    int myint;
-    wrap_json_unpack(root, "i", &myint);
-    assert(myint == 42);
-
-    /* root is the JSON object {"foo": "bar", "quux": true} */
-    const char *str;
-    int boolean;
-    wrap_json_unpack(root, "{s:s, s:b}", "foo", &str, "quux", &boolean);
-    assert(strcmp(str, "bar") == 0 && boolean == 1);
-
-    /* root is the JSON array [[1, 2], {"baz": null} */
-    wrap_json_check(root, "[[i,i], {s:n}]", "baz");
-    /* returns 0 for validation success, nothing is extracted */
-
-    /* root is the JSON array [1, 2, 3, 4, 5] */
-    int myint1, myint2;
-    wrap_json_unpack(root, "[ii!]", &myint1, &myint2);
-    /* returns -1 for failed validation */
-
-    /* root is an empty JSON object */
-    int myint = 0, myint2 = 0, myint3 = 0;
-    wrap_json_unpack(root, "{s?i, s?[ii]}",
-                "foo", &myint1,
-                "bar", &myint2, &myint3);
-    /* myint1, myint2 or myint3 is no touched as "foo" and "bar" don't exist */
-
-Copyright
----------
-
-Copyright (c) 2009-2016 Petri Lehtinen <petri@digip.org>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.