3b8deac3e9
Summary for Users ================= Deprecation is scheduled for 2020.01. Users which depend on this module and cannot switch libraries may copy the code into to their own application. As expressed in PR #11724, the UBJSON module has issues which are not easy or worth fixing. Before removing the module, it should be marked as deprecated to give users time to either migrate to another library, or copy the code to their own private repo. The deprecation warning has been supressed from the unit tests. This has the ugly side-effect of supressing deprecation warning in other unit tests too, but that should not last long, only until the module is finally deleted.
583 lines
23 KiB
C
583 lines
23 KiB
C
/*
|
|
* Copyright (C) 2014 René Kijewski <rene.kijewski@fu-berlin.de>
|
|
*
|
|
* This library is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU Lesser General Public
|
|
* License as published by the Free Software Foundation; either
|
|
* version 2.1 of the License, or (at your option) any later version.
|
|
*
|
|
* This library is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
* Lesser General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU Lesser General Public
|
|
* License along with this library; if not, write to the Free Software
|
|
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
|
*/
|
|
|
|
/**
|
|
* @defgroup sys_ubjson Universal Binary JSON library
|
|
* @ingroup sys_serialization
|
|
* @brief Provides a library to read and write UBJSON serialized data
|
|
* @{
|
|
*
|
|
* @file
|
|
* @brief Headers for the UBJSON module
|
|
*
|
|
* @author René Kijewski <rene.kijewski@fu-berlin.de>
|
|
*/
|
|
|
|
#ifndef UBJSON_H
|
|
#define UBJSON_H
|
|
|
|
#include <stdbool.h>
|
|
#include <stddef.h>
|
|
#include <stdint.h>
|
|
#include <stdlib.h>
|
|
|
|
#include <sys/types.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* ***************************************************************************
|
|
* READ FUNCTIONS / DEFINITIONS
|
|
*************************************************************************** */
|
|
|
|
/**
|
|
* @brief Status code of ubjson_read(), ubjson_read_array() and ubjson_read_object() callback
|
|
*
|
|
* When ubjson_read(), ubjson_read_array() and ubjson_read_object() iteratively invokes the gives callback function.
|
|
* The callback function then has to invoke another function such as ubjson_get_i32(), depending on the parameter `type`.
|
|
*/
|
|
typedef enum {
|
|
/**
|
|
* @brief There is no such value.
|
|
*
|
|
* Only used in the callback of ubjson_read() for parameter `type2`.
|
|
*/
|
|
UBJSON_ABSENT,
|
|
|
|
/**
|
|
* @brief The next datum is a null value.
|
|
*
|
|
* As you might have already guessed: you cannot read a null value.
|
|
*/
|
|
UBJSON_TYPE_NULL,
|
|
|
|
/**
|
|
* @brief The next datum is a no-op value.
|
|
*
|
|
* As you might have already guessed: you cannot read a no-op value.
|
|
*/
|
|
UBJSON_TYPE_NOOP,
|
|
|
|
/**
|
|
* @brief The next datum is a boolean.
|
|
*
|
|
* The `content` is the boolean value.
|
|
* Use ubjson_get_bool() or use `content` verbatim.
|
|
*/
|
|
UBJSON_TYPE_BOOL,
|
|
|
|
/**
|
|
* @brief The next datum is an integer that fits into an int32_t.
|
|
*
|
|
* Use ubjson_get_i32() to read the value.
|
|
* `content` is one of ::ubjson_int32_type_t.
|
|
*/
|
|
UBJSON_TYPE_INT32,
|
|
|
|
/**
|
|
* @brief The next datum is an integer that fits into an int64_t.
|
|
*
|
|
* Use ubjson_get_i64() to read the value.
|
|
*/
|
|
UBJSON_TYPE_INT64,
|
|
|
|
/**
|
|
* @brief The next datum is a 32 bit floating point value.
|
|
*
|
|
* Use ubjson_get_float() to read the value.
|
|
*/
|
|
UBJSON_TYPE_FLOAT,
|
|
|
|
/**
|
|
* @brief The next datum is a 64 bit floating point value.
|
|
*
|
|
* Use ubjson_get_double() to read the value.
|
|
*/
|
|
UBJSON_TYPE_DOUBLE,
|
|
|
|
/* NOTE: High-precision numbers are not implemented, yet. Implement if needed. */
|
|
/* UBJSON_TYPE_HP_NUMBER, */
|
|
|
|
/**
|
|
* @brief The next datum is a string (blob).
|
|
*
|
|
* Use ubjson_get_string() to read the value.
|
|
* `content` is the length of the blob.
|
|
*/
|
|
UBJSON_TYPE_STRING,
|
|
|
|
/**
|
|
* @brief The next datum is an array.
|
|
*
|
|
* Use ubjson_read_array() to read its contents.
|
|
*/
|
|
UBJSON_ENTER_ARRAY,
|
|
|
|
/**
|
|
* @brief The next datum is an object.
|
|
*
|
|
* Use ubjson_read_object() to read its contents.
|
|
*/
|
|
UBJSON_ENTER_OBJECT,
|
|
|
|
/**
|
|
* @brief The next datum is an array index.
|
|
*
|
|
* This value is emitted for every index in a call to ubjson_read_array().
|
|
*
|
|
* `content1` is the array index.
|
|
* `type2` and `content2` describe the value of the index.
|
|
*
|
|
* Arrays can be nested.
|
|
*/
|
|
UBJSON_INDEX,
|
|
|
|
/**
|
|
* @brief The next datum is an object key.
|
|
*
|
|
* This value is emitted for every index in a call to ubjson_read_object().
|
|
*
|
|
* `content1` is the length of the key, invoke ubjson_get_string().
|
|
* `type2` and `content2` describe the value.
|
|
*
|
|
* Objects can be nested.
|
|
*/
|
|
UBJSON_KEY,
|
|
} ubjson_type_t;
|
|
|
|
/**
|
|
* @brief Length of the UBJSON_TYPE_INT32 datum.
|
|
*/
|
|
typedef enum {
|
|
UBJSON_INT32_INT8, /**< The stream contains an int8_t. */
|
|
UBJSON_INT32_UINT8, /**< The stream contains an uint8_t. */
|
|
UBJSON_INT32_INT16, /**< The stream contains an int16_t. */
|
|
UBJSON_INT32_INT32, /**< The stream contains an int32_t. */
|
|
} ubjson_int32_type_t;
|
|
|
|
/**
|
|
* @brief Return value of ::ubjson_read_callback_t and ubjson_read()
|
|
*
|
|
* The callback invoked by ubjson_read(), ubjson_read_array() or ubjson_read_object() can return an error value.
|
|
* The error value is then returned by the read function.
|
|
*
|
|
* The values UBJSON_INVALID_DATA, UBJSON_PREMATURELY_ENDED, and UBJSON_SIZE_ERROR are returned on encoding errors, too.
|
|
*/
|
|
typedef enum {
|
|
UBJSON_OKAY, /**< success / do continue */
|
|
UBJSON_ABORTED, /**< aborted / do abort */
|
|
UBJSON_INVALID_DATA, /**< invalid marker or type*/
|
|
UBJSON_PREMATURELY_ENDED, /**< the stream abruptly ended */
|
|
UBJSON_SIZE_ERROR, /**< the length of a field exceeded SSIZE_MAX */
|
|
} ubjson_read_callback_result_t;
|
|
|
|
struct __attribute__ ((deprecated("The UBJSON module will be removed in release 2020.01"))) ubjson_cookie;
|
|
|
|
/**
|
|
* @brief A cookie passed between the read and write functions.
|
|
* @details You probably want to wrap the cookie in some other data structure,
|
|
* which you retrieve with container_of() in the callback.
|
|
*/
|
|
typedef struct ubjson_cookie ubjson_cookie_t
|
|
__attribute__ ((deprecated("The UBJSON module will be removed in release 2020.01")));
|
|
|
|
/**
|
|
* @brief Method called by ubjson_read() to get more data.
|
|
* @param[in] cookie The cookie that was passed to ubjson_read().
|
|
* @param[out] buf The buffer that should be written to.
|
|
* @param[in] max_len The length of the buffer. Always `>= 1`.
|
|
* @return @arg `< 0` on error. UBJSON_PREMATURELY_ENDED will be return by ubjson_read().
|
|
* @arg `> 0` the amount of read data, which must not exceed max_len.
|
|
*/
|
|
typedef ssize_t (*ubjson_read_t)(ubjson_cookie_t *__restrict cookie, void *buf, size_t max_len);
|
|
|
|
/**
|
|
* @brief Method called by ubjson_read() to denote the next element in the structure.
|
|
* @details Depending on the value of type1 a different function, such as ubjson_get_i32(),
|
|
* must be invoked by the callback function.
|
|
*
|
|
* With ubjson_read_array() or ubjson_read_object() the value of type1 is
|
|
* UBJSON_INDEX or UBJSON_KEY, resp.
|
|
* @param[in] cookie The cookie that was passed to ubjson_read().
|
|
* @param[in] type1 The type of the next datum.
|
|
* @param[in] content1 The sub-type of the next datum.
|
|
* @param[in] type2 The type of the value that belongs to the next key/index, or UBJSON_ABSENT.
|
|
* @param[in] content2 The sub-type of the value that belongs to the next key/index.
|
|
* @returns Either UBJSON_OKAY or UBJSON_ABORTED.
|
|
*/
|
|
typedef ubjson_read_callback_result_t (*ubjson_read_callback_t)(ubjson_cookie_t *__restrict cookie,
|
|
ubjson_type_t type1, ssize_t content1,
|
|
ubjson_type_t type2, ssize_t content2);
|
|
|
|
/**
|
|
* @brief Method called by ubjson_write_null() and friends.
|
|
* @details The function in invoked multiple times per written value.
|
|
* You should use some kind of buffer if you send the data over a stream.
|
|
*
|
|
* The function must write the whole buffer before returning.
|
|
* @param[in] cookie The cookie that was passed to ubjson_write_init().
|
|
* @param[in] buf Data to write, never NULL.
|
|
* @param[in] len Data to write, always >= 0.
|
|
* @returns @arg `< 0` to indicate an error.
|
|
* @arg `> 0` to indicate success.
|
|
*/
|
|
typedef ssize_t (*ubjson_write_t)(ubjson_cookie_t *__restrict cookie, const void *buf, size_t len);
|
|
|
|
/**
|
|
* @brief See @ref ubjson_cookie_t.
|
|
*/
|
|
struct ubjson_cookie {
|
|
/**
|
|
* @brief Read/write function
|
|
* @internal
|
|
*/
|
|
union {
|
|
ubjson_read_t read; /**< read function */
|
|
ubjson_write_t write; /**< write function */
|
|
} rw;
|
|
|
|
/**
|
|
* @brief Callback function
|
|
* @internal
|
|
*/
|
|
union {
|
|
ubjson_read_callback_t read; /**< Callback when a datum was read. */
|
|
} callback; /**< @internal */
|
|
|
|
/**
|
|
* @brief One byte push-back buffer.
|
|
* @internal
|
|
*/
|
|
char marker;
|
|
};
|
|
|
|
/**
|
|
* @brief Used to read with a setup cookie.
|
|
* @details You need to use this function instead of ubjson_read() only if
|
|
* your UBJSON data contains further UBJSON serialized data in a string.
|
|
*
|
|
* UBJSON data in a typed array may or may not work.
|
|
* @param[in] cookie The cookie that is passed to the callback function.
|
|
* @returns The same as ubjson_read().
|
|
*/
|
|
ubjson_read_callback_result_t ubjson_read_next(ubjson_cookie_t *__restrict cookie);
|
|
|
|
/**
|
|
* @brief The entry function to read UBJSON serialized data.
|
|
* @details This function invokes the callback function.
|
|
* The value of type1 in the callback indicates which function
|
|
* to call inside the callback function, e.g. ubjson_get_i32().
|
|
*
|
|
* Nested calls to ubjson_read_array(), ubjson_read_object() or ubjson_read_next()
|
|
* invoke the same callback function, possibly multiple times.
|
|
*
|
|
* You probably want to wrap the cookie in some other data structure,
|
|
* which you retrieve with container_of() in the callback.
|
|
* @param[in] cookie The cookie that is passed to the callback function.
|
|
* @param[in] read The function that is called to receive more data.
|
|
* @param[in] callback The callback function.
|
|
* @returns See \ref ubjson_read_callback_result_t
|
|
*/
|
|
static inline ubjson_read_callback_result_t ubjson_read(ubjson_cookie_t *__restrict cookie,
|
|
ubjson_read_t read,
|
|
ubjson_read_callback_t callback)
|
|
{
|
|
cookie->rw.read = read;
|
|
cookie->callback.read = callback;
|
|
cookie->marker = 0;
|
|
return ubjson_read_next(cookie);
|
|
}
|
|
|
|
/**
|
|
* @brief Use in a callback if type1 is UBJSON_KEY or UBJSON_INDEX.
|
|
* @details Call like ``ubjson_peek_value(cookie, &type2, &content2)``.
|
|
* @param[in] cookie The cookie that was passed to the callback.
|
|
* @param[in,out] type Pointer to a variable that was initialized with the value of type2, returns the new type1.
|
|
* @param[in,out] content Pointer to a variable that was initialized with the value of content2, returns the new content1.
|
|
* @returns The same as ubjson_read().
|
|
*/
|
|
ubjson_read_callback_result_t ubjson_peek_value(ubjson_cookie_t *__restrict cookie,
|
|
ubjson_type_t *type, ssize_t *content);
|
|
|
|
/**
|
|
* @brief Call if type1 of the callback was UBJSON_TYPE_INT32.
|
|
* @details The value of content1 is one of ubjson_int32_type_t.
|
|
* @param[in] cookie The cookie that was passed to the callback function.
|
|
* @param[in] content The content1 that was passed to the callback function.
|
|
* @param[out] dest The read datum.
|
|
* @returns The result of the read callback, probably the amount of read bytes.
|
|
*/
|
|
ssize_t ubjson_get_i32(ubjson_cookie_t *__restrict cookie, ssize_t content, int32_t *dest);
|
|
|
|
/**
|
|
* @brief Call if type1 of the callback was UBJSON_TYPE_INT64.
|
|
* @param[in] cookie The cookie that was passed to the callback function.
|
|
* @param[in] content The content1 that was passed to the callback function.
|
|
* @param[out] dest The read datum.
|
|
* @returns The result of the read callback, probably the amount of read bytes.
|
|
*/
|
|
ssize_t ubjson_get_i64(ubjson_cookie_t *__restrict cookie, ssize_t content, int64_t *dest);
|
|
|
|
/**
|
|
* @brief Call if type1 of the callback was UBJSON_TYPE_STRING.
|
|
* @details content1 is the length of the string/blob.
|
|
* The result is not null-terminated!
|
|
* @param[in] cookie The cookie that was passed to the callback function.
|
|
* @param[in] content The content1 that was passed to the callback function.
|
|
* @param[out] dest Buffer to read the string into.
|
|
* @returns The result of the read callback, probably the amount of read bytes.
|
|
*/
|
|
ssize_t ubjson_get_string(ubjson_cookie_t *__restrict cookie, ssize_t content, void *dest);
|
|
|
|
/**
|
|
* @brief Call if type1 of the callback was UBJSON_TYPE_BOOL.
|
|
* @details content1 is the value of the bool. The function only exists for symmetry.
|
|
* @param[in] cookie The cookie that was passed to the callback function.
|
|
* @param[in] content The content1 that was passed to the callback function.
|
|
* @param[out] dest The read datum.
|
|
* @returns `1`, the invocation cannot fail.
|
|
*/
|
|
static inline ssize_t ubjson_get_bool(ubjson_cookie_t *__restrict cookie, ssize_t content, bool *dest)
|
|
{
|
|
(void) cookie;
|
|
*dest = content;
|
|
return 1;
|
|
}
|
|
|
|
/**
|
|
* @brief Call if type1 of the callback was UBJSON_TYPE_FLOAT.
|
|
* @param[in] cookie The cookie that was passed to the callback function.
|
|
* @param[in] content The content1 that was passed to the callback function.
|
|
* @param[out] dest The read datum.
|
|
* @returns The result of the read callback, probably the amount of read bytes.
|
|
*/
|
|
static inline ssize_t ubjson_get_float(ubjson_cookie_t *__restrict cookie, ssize_t content, float *dest)
|
|
{
|
|
(void) content;
|
|
union {
|
|
float f;
|
|
int32_t i;
|
|
} value;
|
|
ubjson_read_callback_result_t result = ubjson_get_i32(cookie, UBJSON_INT32_INT32, &value.i);
|
|
*dest = value.f;
|
|
return result;
|
|
}
|
|
|
|
/**
|
|
* @brief Call if type1 of the callback was UBJSON_TYPE_DOUBLE.
|
|
* @param[in] cookie The cookie that was passed to the callback function.
|
|
* @param[in] content The content1 that was passed to the callback function.
|
|
* @param[out] dest The read datum.
|
|
* @returns The result of the read callback, probably the amount of read bytes.
|
|
*/
|
|
static inline ssize_t ubjson_get_double(ubjson_cookie_t *__restrict cookie, ssize_t content, double *dest)
|
|
{
|
|
(void) content;
|
|
union {
|
|
double f;
|
|
int64_t i;
|
|
} value;
|
|
ubjson_read_callback_result_t result = ubjson_get_i64(cookie, -1, &value.i);
|
|
*dest = value.f;
|
|
return result;
|
|
}
|
|
|
|
/**
|
|
* @brief Call if type1 of the callback was UBJSON_ENTER_ARRAY.
|
|
* @details Inside this call the callback function will be invoked multiple times,
|
|
* once per array element, with type1=UBJSON_INDEX,
|
|
* and content1=running index in the array.
|
|
*
|
|
* Use ubjson_peek_value() to determine the type of the element.
|
|
* @param[in] cookie The cookie that was passed to the callback function.
|
|
* @returns The same as ubjson_read().
|
|
*/
|
|
ubjson_read_callback_result_t ubjson_read_array(ubjson_cookie_t *__restrict cookie);
|
|
|
|
|
|
/**
|
|
* @brief Call if type1 of the callback was UBJSON_ENTER_OBJECT.
|
|
* @details Inside this call the callback function will be invoked multiple times,
|
|
* once per object element, with type1=UBJSON_KEY,
|
|
* and content1=length of the key string.
|
|
*
|
|
* First read the key with ubjson_get_string(), then
|
|
* use ubjson_peek_value() to determine the type of the element.
|
|
* @param[in] cookie The cookie that was passed to the callback function.
|
|
* @returns The same as ubjson_read().
|
|
*/
|
|
ubjson_read_callback_result_t ubjson_read_object(ubjson_cookie_t *__restrict cookie);
|
|
|
|
/* ***************************************************************************
|
|
* WRITE FUNCTIONS / DEFINITIONS
|
|
*************************************************************************** */
|
|
|
|
/**
|
|
* @brief The first call when you serialize data to UBJSON.
|
|
* @details There is no corresponding "ubjson_write_finish" function.
|
|
* The programmer needs to ensure that the API is used correctly.
|
|
* The library won't complain if you write multiple values that are not
|
|
* inside an array or object. The result will just not be properly serialized.
|
|
* @param[out] cookie The cookie that will be passed to ubjson_write_null() and friends.
|
|
* @param[in] write_fun The function that will be called to write data.
|
|
*/
|
|
static inline void ubjson_write_init(ubjson_cookie_t *__restrict cookie, ubjson_write_t write_fun)
|
|
{
|
|
cookie->rw.write = write_fun;
|
|
}
|
|
|
|
/**
|
|
* @brief Write a null value.
|
|
* @param[in] cookie The cookie that was initialized with ubjson_write_init().
|
|
*/
|
|
ssize_t ubjson_write_null(ubjson_cookie_t *__restrict cookie);
|
|
|
|
/**
|
|
* @brief Write a no-operation value.
|
|
* @param[in] cookie The cookie that was initialized with ubjson_write_init().
|
|
* @returns The result of the supplied @ref ubjson_write_t function.
|
|
*/
|
|
ssize_t ubjson_write_noop(ubjson_cookie_t *__restrict cookie);
|
|
|
|
/**
|
|
* @brief Write a boolean value.
|
|
* @param[in] cookie The cookie that was initialized with ubjson_write_init().
|
|
* @param[in] value The boolean value to write.
|
|
* @returns The result of the supplied @ref ubjson_write_t function.
|
|
*/
|
|
ssize_t ubjson_write_bool(ubjson_cookie_t *__restrict cookie, bool value);
|
|
|
|
/**
|
|
* @brief Write an integer value.
|
|
* @details The library will determine the smallest serialization for the value itself.
|
|
* @param[in] cookie The cookie that was initialized with ubjson_write_init().
|
|
* @param[in] value The integer value to write.
|
|
*/
|
|
ssize_t ubjson_write_i32(ubjson_cookie_t *__restrict cookie, int32_t value);
|
|
|
|
/**
|
|
* @brief Write an integer value.
|
|
* @details The library will determine the smallest serialization for the value itself.
|
|
* @param[in] cookie The cookie that was initialized with ubjson_write_init().
|
|
* @param[in] value The integer value to write.
|
|
* @returns The result of the supplied @ref ubjson_write_t function.
|
|
*/
|
|
ssize_t ubjson_write_i64(ubjson_cookie_t *__restrict cookie, int64_t value);
|
|
|
|
/**
|
|
* @brief Write a floating point value.
|
|
* @param[in] cookie The cookie that was initialized with ubjson_write_init().
|
|
* @param[in] value The integer value to write.
|
|
* @returns The result of the supplied @ref ubjson_write_t function.
|
|
*/
|
|
ssize_t ubjson_write_float(ubjson_cookie_t *__restrict cookie, float value);
|
|
|
|
/**
|
|
* @brief Write a floating point value.
|
|
* @param[in] cookie The cookie that was initialized with ubjson_write_init().
|
|
* @param[in] value The integer value to write.
|
|
* @returns The result of the supplied @ref ubjson_write_t function.
|
|
*/
|
|
ssize_t ubjson_write_double(ubjson_cookie_t *__restrict cookie, double value);
|
|
|
|
/**
|
|
* @brief Write a string or blob.
|
|
* @param[in] cookie The cookie that was initialized with ubjson_write_init().
|
|
* @param[in] value The string or blob to write.
|
|
* @param[in] len The length of the string or blob.
|
|
* @returns The result of the supplied @ref ubjson_write_t function.
|
|
*/
|
|
ssize_t ubjson_write_string(ubjson_cookie_t *__restrict cookie, const void *value, size_t len);
|
|
|
|
/**
|
|
* @brief Open an array.
|
|
* @details Write multiple elements inside this array.
|
|
* Call ubjson_close_array() after the whole content was written.
|
|
* @param[in] cookie The cookie that was initialized with ubjson_write_init().
|
|
* @returns The result of the supplied @ref ubjson_write_t function.
|
|
*/
|
|
ssize_t ubjson_open_array(ubjson_cookie_t *__restrict cookie);
|
|
|
|
/**
|
|
* @brief Open an array with a known length.
|
|
* @details Do not call ubjson_close_array().
|
|
* @param[in] cookie The cookie that was initialized with ubjson_write_init().
|
|
* @param[in] len Length of the array.
|
|
* @returns The result of the supplied @ref ubjson_write_t function.
|
|
*/
|
|
ssize_t ubjson_open_array_len(ubjson_cookie_t *__restrict cookie, size_t len);
|
|
|
|
/**
|
|
* @brief Close an array that was opened with ubjson_open_array().
|
|
* @param[in] cookie The cookie that was initialized with ubjson_write_init().
|
|
* @returns The result of the supplied @ref ubjson_write_t function.
|
|
*/
|
|
ssize_t ubjson_close_array(ubjson_cookie_t *__restrict cookie);
|
|
|
|
/**
|
|
* @brief Open an object.
|
|
* @details Write multiple keys inside this object.
|
|
* Call ubjson_close_object() after the whole content was written.
|
|
*
|
|
* For each element first write the key with ubjson_write_key(),
|
|
* then invoke the function to write the value.
|
|
* @param[in] cookie The cookie that was initialized with ubjson_write_init().
|
|
* @returns The result of the supplied @ref ubjson_write_t function.
|
|
*/
|
|
ssize_t ubjson_open_object(ubjson_cookie_t *__restrict cookie);
|
|
|
|
/**
|
|
* @brief Open an object with a known length.
|
|
* @details For each element first write the key with ubjson_write_key(),
|
|
* then invoke the function to write the value.
|
|
*
|
|
* Do not call ubjson_close_object().
|
|
* @param[in] cookie The cookie that was initialized with ubjson_write_init().
|
|
* @param[in] len Number of keys inside the object.
|
|
* @returns The result of the supplied @ref ubjson_write_t function.
|
|
*/
|
|
ssize_t ubjson_open_object_len(ubjson_cookie_t *__restrict cookie, size_t len);
|
|
|
|
/**
|
|
* @brief Write a key inside an object.
|
|
* @details For each element first write the key,
|
|
* then invoke the function to write the value.
|
|
*
|
|
* It is up to the programmer to ensure that there are no duplicated keys.
|
|
* @param[in] cookie The cookie that was initialized with ubjson_write_init().
|
|
* @param[in] value The key, should be a UTF-8 string.
|
|
* @param[in] len The length of the key.
|
|
* @returns The result of the supplied @ref ubjson_write_t function.
|
|
*/
|
|
ssize_t ubjson_write_key(ubjson_cookie_t *__restrict cookie, const void *value, size_t len);
|
|
|
|
/**
|
|
* @brief Close an array that was opened with ubjson_open_object().
|
|
* @param[in] cookie The cookie that was initialized with ubjson_write_init().
|
|
* @returns The result of the supplied @ref ubjson_write_t function.
|
|
*/
|
|
ssize_t ubjson_close_object(ubjson_cookie_t *__restrict cookie);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* UBJSON_H */
|
|
/** @} */
|