Universal Binary JSON library

Provides a library to read and write UBJSON serialized data.

enum ubjson_type_t
UBJSON_ABSENT

There is no such value.

Only used in the callback of ubjson.h::ubjson_read() for parameter type2.

UBJSON_TYPE_NULL

The next datum is a null value.

As you might have already guessed: you cannot read a null value.

UBJSON_TYPE_NOOP

The next datum is a no-op value.

As you might have already guessed: you cannot read a no-op value.

UBJSON_TYPE_BOOL

The next datum is a boolean.

The content is the boolean value. Use ubjson.h::ubjson_get_bool() or use content verbatim.

UBJSON_TYPE_INT32

The next datum is an integer that fits into an int32_t.

Use ubjson.h::ubjson_get_i32() to read the value. content is one of ubjson.h::ubjson_int32_type_t.

UBJSON_TYPE_INT64

The next datum is an integer that fits into an int64_t.

Use ubjson.h::ubjson_get_i64() to read the value.

UBJSON_TYPE_FLOAT

The next datum is a 32 bit floating point value.

Use ubjson.h::ubjson_get_float() to read the value.

UBJSON_TYPE_DOUBLE

The next datum is a 64 bit floating point value.

Use ubjson.h::ubjson_get_double() to read the value.

UBJSON_TYPE_STRING

The next datum is a string (blob).

Use ubjson.h::ubjson_get_string() to read the value. content is the length of the blob.

UBJSON_ENTER_ARRAY

The next datum is an array.

Use ubjson.h::ubjson_read_array() to read its contents.

UBJSON_ENTER_OBJECT

The next datum is an object.

Use ubjson.h::ubjson_read_object() to read its contents.

UBJSON_INDEX

The next datum is an array index.

This value is emitted for every index in a call to ubjson.h::ubjson_read_array().

content1 is the array index. type2 and content2 describe the value of the index.

Arrays can be nested.

UBJSON_KEY

The next datum is an object key.

This value is emitted for every index in a call to ubjson.h::ubjson_read_object().

content1 is the length of the key, invoke ubjson.h::ubjson_get_string(). type2 and content2 describe the value.

Objects can be nested.

enum ubjson_int32_type_t
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.
enum ubjson_read_callback_result_t
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
struct ubjson_cookie ubjson_cookie_t

A cookie passed between the read and write functions.

You probably want to wrap the cookie in some other data structure, which you retrieve with kernel_defines.h::container_of in the callback.

msp430_types.h::ssize_t(* ubjson_read_t()

Method called by ubjson.h::ubjson_read() to get more data.

Parameters

cookie:The cookie that was passed to ubjson.h::ubjson_read().
buf:The buffer that should be written to.
max_len:The length of the buffer. Always >= 1.

Return values

    • < 0 on error. UBJSON_PREMATURELY_ENDED will be return by ubjson.h::ubjson_read().
    • > 0 the amount of read data, which must not exceed max_len.
ubjson.h::ubjson_read_callback_result_t(* ubjson_read_callback_t()

Method called by ubjson.h::ubjson_read() to denote the next element in the structure.

Depending on the value of type1 a different function, such as ubjson.h::ubjson_get_i32(), must be invoked by the callback function.

With ubjson.h::ubjson_read_array() or ubjson.h::ubjson_read_object() the value of type1 is UBJSON_INDEX or UBJSON_KEY, resp.

Parameters

cookie:The cookie that was passed to ubjson.h::ubjson_read().
type1:The type of the next datum.
content1:The sub-type of the next datum.
type2:The type of the value that belongs to the next key/index, or UBJSON_ABSENT.
content2:The sub-type of the value that belongs to the next key/index.

Return values

  • Either UBJSON_OKAY or UBJSON_ABORTED.
msp430_types.h::ssize_t(* ubjson_write_t()

Method called by ubjson.h::ubjson_write_null() and friends.

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.

Parameters

cookie:The cookie that was passed to ubjson.h::ubjson_write_init().
buf:Data to write, never NULL.
len:Data to write, always >= 0.

Return values

    • < 0 to indicate an error.
    • > 0 to indicate success.
ubjson.h::ubjson_read_callback_result_t ubjson_read_next(ubjson.h::ubjson_cookie_t *__restrict cookie)

Used to read with a setup cookie.

You need to use this function instead of ubjson.h::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.

Parameters

cookie:The cookie that is passed to the callback function.

Return values

ubjson.h::ubjson_read_callback_result_t ubjson_read(ubjson.h::ubjson_cookie_t *__restrict cookie, ubjson.h::ubjson_read_t read, ubjson.h::ubjson_read_callback_t callback)

The entry function to read UBJSON serialized data.

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.h::ubjson_get_i32().

Nested calls to ubjson.h::ubjson_read_array(), ubjson.h::ubjson_read_object() or ubjson.h::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 kernel_defines.h::container_of in the callback.

Parameters

cookie:The cookie that is passed to the callback function.
read:The function that is called to receive more data.
callback:The callback function.

Return values

ubjson.h::ubjson_read_callback_result_t ubjson_peek_value(ubjson.h::ubjson_cookie_t *__restrict cookie, ubjson.h::ubjson_type_t * type, msp430_types.h::ssize_t * content)

Use in a callback if type1 is UBJSON_KEY or UBJSON_INDEX.

Call like ubjson_peek_value(cookie, &type2, &content2).

Parameters

cookie:The cookie that was passed to the callback.
type:Pointer to a variable that was initialized with the value of type2, returns the new type1.
content:Pointer to a variable that was initialized with the value of content2, returns the new content1.

Return values

msp430_types.h::ssize_t ubjson_get_i32(ubjson.h::ubjson_cookie_t *__restrict cookie, msp430_types.h::ssize_t content, int32_t * dest)

Call if type1 of the callback was UBJSON_TYPE_INT32.

The value of content1 is one of ubjson_int32_type_t.

Parameters

cookie:The cookie that was passed to the callback function.
content:The content1 that was passed to the callback function.
dest:The read datum.

Return values

  • The result of the read callback, probably the amount of read bytes.
msp430_types.h::ssize_t ubjson_get_i64(ubjson.h::ubjson_cookie_t *__restrict cookie, msp430_types.h::ssize_t content, int64_t * dest)

Call if type1 of the callback was UBJSON_TYPE_INT64.

Parameters

cookie:The cookie that was passed to the callback function.
content:The content1 that was passed to the callback function.
dest:The read datum.

Return values

  • The result of the read callback, probably the amount of read bytes.
msp430_types.h::ssize_t ubjson_get_string(ubjson.h::ubjson_cookie_t *__restrict cookie, msp430_types.h::ssize_t content, void * dest)

Call if type1 of the callback was UBJSON_TYPE_STRING.

content1 is the length of the string/blob. The result is not null-terminated!

Parameters

cookie:The cookie that was passed to the callback function.
content:The content1 that was passed to the callback function.
dest:Buffer to read the string into.

Return values

  • The result of the read callback, probably the amount of read bytes.
msp430_types.h::ssize_t ubjson_get_bool(ubjson.h::ubjson_cookie_t *__restrict cookie, msp430_types.h::ssize_t content, bool * dest)

Call if type1 of the callback was UBJSON_TYPE_BOOL.

content1 is the value of the bool. The function only exists for symmetry.

Parameters

cookie:The cookie that was passed to the callback function.
content:The content1 that was passed to the callback function.
dest:The read datum.

Return values

  • 1, the invocation cannot fail.
msp430_types.h::ssize_t ubjson_get_float(ubjson.h::ubjson_cookie_t *__restrict cookie, msp430_types.h::ssize_t content, float * dest)

Call if type1 of the callback was UBJSON_TYPE_FLOAT.

Parameters

cookie:The cookie that was passed to the callback function.
content:The content1 that was passed to the callback function.
dest:The read datum.

Return values

  • The result of the read callback, probably the amount of read bytes.
msp430_types.h::ssize_t ubjson_get_double(ubjson.h::ubjson_cookie_t *__restrict cookie, msp430_types.h::ssize_t content, double * dest)

Call if type1 of the callback was UBJSON_TYPE_DOUBLE.

Parameters

cookie:The cookie that was passed to the callback function.
content:The content1 that was passed to the callback function.
dest:The read datum.

Return values

  • The result of the read callback, probably the amount of read bytes.
ubjson.h::ubjson_read_callback_result_t ubjson_read_array(ubjson.h::ubjson_cookie_t *__restrict cookie)

Call if type1 of the callback was UBJSON_ENTER_ARRAY.

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.h::ubjson_peek_value() to determine the type of the element.

Parameters

cookie:The cookie that was passed to the callback function.

Return values

ubjson.h::ubjson_read_callback_result_t ubjson_read_object(ubjson.h::ubjson_cookie_t *__restrict cookie)

Call if type1 of the callback was UBJSON_ENTER_OBJECT.

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.h::ubjson_get_string(), then use ubjson.h::ubjson_peek_value() to determine the type of the element.

Parameters

cookie:The cookie that was passed to the callback function.

Return values

void ubjson_write_init(ubjson.h::ubjson_cookie_t *__restrict cookie, ubjson.h::ubjson_write_t write_fun)

The first call when you serialize data to UBJSON.

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.

Parameters

cookie:The cookie that will be passed to ubjson.h::ubjson_write_null() and friends.
write_fun:The function that will be called to write data.

msp430_types.h::ssize_t ubjson_write_null(ubjson.h::ubjson_cookie_t *__restrict cookie)

Write a null value.

Parameters

cookie:The cookie that was initialized with ubjson.h::ubjson_write_init().

msp430_types.h::ssize_t ubjson_write_noop(ubjson.h::ubjson_cookie_t *__restrict cookie)

Write a no-operation value.

Parameters

cookie:The cookie that was initialized with ubjson.h::ubjson_write_init().

Return values

msp430_types.h::ssize_t ubjson_write_bool(ubjson.h::ubjson_cookie_t *__restrict cookie, bool value)

Write a boolean value.

Parameters

cookie:The cookie that was initialized with ubjson.h::ubjson_write_init().
value:The boolean value to write.

Return values

msp430_types.h::ssize_t ubjson_write_i32(ubjson.h::ubjson_cookie_t *__restrict cookie, int32_t value)

Write an integer value.

The library will determine the smallest serialization for the value itself.

Parameters

cookie:The cookie that was initialized with ubjson.h::ubjson_write_init().
value:The integer value to write.

msp430_types.h::ssize_t ubjson_write_i64(ubjson.h::ubjson_cookie_t *__restrict cookie, int64_t value)

Write an integer value.

The library will determine the smallest serialization for the value itself.

Parameters

cookie:The cookie that was initialized with ubjson.h::ubjson_write_init().
value:The integer value to write.

Return values

msp430_types.h::ssize_t ubjson_write_float(ubjson.h::ubjson_cookie_t *__restrict cookie, float value)

Write a floating point value.

Parameters

cookie:The cookie that was initialized with ubjson.h::ubjson_write_init().
value:The integer value to write.

Return values

msp430_types.h::ssize_t ubjson_write_double(ubjson.h::ubjson_cookie_t *__restrict cookie, double value)

Write a floating point value.

Parameters

cookie:The cookie that was initialized with ubjson.h::ubjson_write_init().
value:The integer value to write.

Return values

msp430_types.h::ssize_t ubjson_write_string(ubjson.h::ubjson_cookie_t *__restrict cookie, const void * value, msp430_types.h::size_t len)

Write a string or blob.

Parameters

cookie:The cookie that was initialized with ubjson.h::ubjson_write_init().
value:The string or blob to write.
len:The length of the string or blob.

Return values

msp430_types.h::ssize_t ubjson_open_array(ubjson.h::ubjson_cookie_t *__restrict cookie)

Open an array.

Write multiple elements inside this array. Call ubjson.h::ubjson_close_array() after the whole content was written.

Parameters

cookie:The cookie that was initialized with ubjson.h::ubjson_write_init().

Return values

msp430_types.h::ssize_t ubjson_open_array_len(ubjson.h::ubjson_cookie_t *__restrict cookie, msp430_types.h::size_t len)

Open an array with a known length.

Do not call ubjson.h::ubjson_close_array().

Parameters

cookie:The cookie that was initialized with ubjson.h::ubjson_write_init().
len:Length of the array.

Return values

msp430_types.h::ssize_t ubjson_close_array(ubjson.h::ubjson_cookie_t *__restrict cookie)

Close an array that was opened with ubjson.h::ubjson_open_array().

Parameters

cookie:The cookie that was initialized with ubjson.h::ubjson_write_init().

Return values

msp430_types.h::ssize_t ubjson_open_object(ubjson.h::ubjson_cookie_t *__restrict cookie)

Open an object.

Write multiple keys inside this object. Call ubjson.h::ubjson_close_object() after the whole content was written.

For each element first write the key with ubjson.h::ubjson_write_key(), then invoke the function to write the value.

Parameters

cookie:The cookie that was initialized with ubjson.h::ubjson_write_init().

Return values

msp430_types.h::ssize_t ubjson_open_object_len(ubjson.h::ubjson_cookie_t *__restrict cookie, msp430_types.h::size_t len)

Open an object with a known length.

For each element first write the key with ubjson.h::ubjson_write_key(), then invoke the function to write the value.

Do not call ubjson.h::ubjson_close_object().

Parameters

cookie:The cookie that was initialized with ubjson.h::ubjson_write_init().
len:Number of keys inside the object.

Return values

msp430_types.h::ssize_t ubjson_write_key(ubjson.h::ubjson_cookie_t *__restrict cookie, const void * value, msp430_types.h::size_t len)

Write a key inside an object.

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.

Parameters

cookie:The cookie that was initialized with ubjson.h::ubjson_write_init().
value:The key, should be a UTF-8 string.
len:The length of the key.

Return values

msp430_types.h::ssize_t ubjson_close_object(ubjson.h::ubjson_cookie_t *__restrict cookie)

Close an array that was opened with ubjson.h::ubjson_open_object().

Parameters

cookie:The cookie that was initialized with ubjson.h::ubjson_write_init().

Return values

struct ubjson_cookie

See ubjson.h::ubjson_cookie_t.

ubjson.h::ubjson_read_t read

read function

ubjson.h::ubjson_write_t write

write function

union ubjson_cookie::@201 rw

Read/write function.

ubjson.h::ubjson_read_callback_t read

Callback when a datum was read.

union ubjson_cookie::@202 callback

Callback function.

char marker

One byte push-back buffer.