Universal Binary JSON

A library to read and write UBJSON serialized data. More...

Detailed Description

Files

file  ubjson.h
 Headers for the UBJSON module.
 

Data Structures

struct  ubjson_cookie
 See ubjson_cookie_t. More...
 

Typedefs

typedef struct ubjson_cookie ubjson_cookie_t
 A cookie passed between the read and write functions. More...
 
typedef ssize_t(* ubjson_read_t) (ubjson_cookie_t *__restrict cookie, void *buf, size_t max_len)
 Method called by ubjson_read() to get more data. More...
 
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)
 Method called by ubjson_read() to denote the next element in the structure. More...
 
typedef ssize_t(* ubjson_write_t) (ubjson_cookie_t *__restrict cookie, const void *buf, size_t len)
 Method called by ubjson_write_null() and friends. More...
 

Enumerations

enum  ubjson_type_t {
  UBJSON_ABSENT, UBJSON_TYPE_NULL, UBJSON_TYPE_NOOP, UBJSON_TYPE_BOOL,
  UBJSON_TYPE_INT32, UBJSON_TYPE_INT64, UBJSON_TYPE_FLOAT, UBJSON_TYPE_DOUBLE,
  UBJSON_TYPE_STRING, UBJSON_ENTER_ARRAY, UBJSON_ENTER_OBJECT, UBJSON_INDEX,
  UBJSON_KEY
}
 Status code of ubjson_read(), ubjson_read_array() and ubjson_read_object() callback. More...
 
enum  ubjson_int32_type_t { UBJSON_INT32_INT8, UBJSON_INT32_UINT8, UBJSON_INT32_INT16, UBJSON_INT32_INT32 }
 Length of the UBJSON_TYPE_INT32 datum. More...
 
enum  ubjson_read_callback_result_t {
  UBJSON_OKAY, UBJSON_ABORTED, UBJSON_INVALID_DATA, UBJSON_PREMATURELY_ENDED,
  UBJSON_SIZE_ERROR
}
 Return value of ubjson_read_callback_t and ubjson_read() More...
 

Functions

ubjson_read_callback_result_t ubjson_read_next (ubjson_cookie_t *__restrict cookie)
 Used to read with a setup cookie. More...
 
static ubjson_read_callback_result_t ubjson_read (ubjson_cookie_t *__restrict cookie, ubjson_read_t read, ubjson_read_callback_t callback)
 The entry function to read UBJSON serialized data. More...
 
ubjson_read_callback_result_t ubjson_peek_value (ubjson_cookie_t *__restrict cookie, ubjson_type_t *type, ssize_t *content)
 Use in a callback if type1 is UBJSON_KEY or UBJSON_INDEX. More...
 
ssize_t ubjson_get_i32 (ubjson_cookie_t *__restrict cookie, ssize_t content, int32_t *dest)
 Call if type1 of the callback was UBJSON_TYPE_INT32. More...
 
ssize_t ubjson_get_i64 (ubjson_cookie_t *__restrict cookie, ssize_t content, int64_t *dest)
 Call if type1 of the callback was UBJSON_TYPE_INT64. More...
 
ssize_t ubjson_get_string (ubjson_cookie_t *__restrict cookie, ssize_t content, void *dest)
 Call if type1 of the callback was UBJSON_TYPE_STRING. More...
 
static ssize_t ubjson_get_bool (ubjson_cookie_t *__restrict cookie, ssize_t content, bool *dest)
 Call if type1 of the callback was UBJSON_TYPE_BOOL. More...
 
static ssize_t ubjson_get_float (ubjson_cookie_t *__restrict cookie, ssize_t content, float *dest)
 Call if type1 of the callback was UBJSON_TYPE_FLOAT. More...
 
static ssize_t ubjson_get_double (ubjson_cookie_t *__restrict cookie, ssize_t content, double *dest)
 Call if type1 of the callback was UBJSON_TYPE_DOUBLE. More...
 
ubjson_read_callback_result_t ubjson_read_array (ubjson_cookie_t *__restrict cookie)
 Call if type1 of the callback was UBJSON_ENTER_ARRAY. More...
 
ubjson_read_callback_result_t ubjson_read_object (ubjson_cookie_t *__restrict cookie)
 Call if type1 of the callback was UBJSON_ENTER_OBJECT. More...
 
static void ubjson_write_init (ubjson_cookie_t *__restrict cookie, ubjson_write_t write_fun)
 The first call when you serialize data to UBJSON. More...
 
ssize_t ubjson_write_null (ubjson_cookie_t *__restrict cookie)
 Write a null value. More...
 
ssize_t ubjson_write_noop (ubjson_cookie_t *__restrict cookie)
 Write a no-operation value. More...
 
ssize_t ubjson_write_bool (ubjson_cookie_t *__restrict cookie, bool value)
 Write a boolean value. More...
 
ssize_t ubjson_write_i32 (ubjson_cookie_t *__restrict cookie, int32_t value)
 Write an integer value. More...
 
ssize_t ubjson_write_i64 (ubjson_cookie_t *__restrict cookie, int64_t value)
 Write an integer value. More...
 
ssize_t ubjson_write_float (ubjson_cookie_t *__restrict cookie, float value)
 Write a floating point value. More...
 
ssize_t ubjson_write_double (ubjson_cookie_t *__restrict cookie, double value)
 Write a floating point value. More...
 
ssize_t ubjson_write_string (ubjson_cookie_t *__restrict cookie, const void *value, size_t len)
 Write a string or blob. More...
 
ssize_t ubjson_open_array (ubjson_cookie_t *__restrict cookie)
 Open an array. More...
 
ssize_t ubjson_open_array_len (ubjson_cookie_t *__restrict cookie, size_t len)
 Open an array with a known length. More...
 
ssize_t ubjson_close_array (ubjson_cookie_t *__restrict cookie)
 Close an array that was opened with ubjson_open_array(). More...
 
ssize_t ubjson_open_object (ubjson_cookie_t *__restrict cookie)
 Open an object. More...
 
ssize_t ubjson_open_object_len (ubjson_cookie_t *__restrict cookie, size_t len)
 Open an object with a known length. More...
 
ssize_t ubjson_write_key (ubjson_cookie_t *__restrict cookie, const void *value, size_t len)
 Write a key inside an object. More...
 
ssize_t ubjson_close_object (ubjson_cookie_t *__restrict cookie)
 Close an array that was opened with ubjson_open_object(). More...
 

Typedef Documentation

◆ ubjson_cookie_t

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

Definition at line 201 of file ubjson.h.

◆ ubjson_read_callback_t

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)

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.

Parameters
[in]cookieThe cookie that was passed to ubjson_read().
[in]type1The type of the next datum.
[in]content1The sub-type of the next datum.
[in]type2The type of the value that belongs to the next key/index, or UBJSON_ABSENT.
[in]content2The sub-type of the value that belongs to the next key/index.
Returns
Either UBJSON_OKAY or UBJSON_ABORTED.

Definition at line 227 of file ubjson.h.

◆ ubjson_read_t

typedef ssize_t(* ubjson_read_t) (ubjson_cookie_t *__restrict cookie, void *buf, size_t max_len)
Parameters
[in]cookieThe cookie that was passed to ubjson_read().
[out]bufThe buffer that should be written to.
[in]max_lenThe length of the buffer. Always >= 1.
Returns
  • < 0 on error. UBJSON_PREMATURELY_ENDED will be return by ubjson_read().
  • > 0 the amount of read data, which must not exceed max_len.

Definition at line 211 of file ubjson.h.

◆ ubjson_write_t

typedef ssize_t(* ubjson_write_t) (ubjson_cookie_t *__restrict cookie, const void *buf, size_t len)

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
[in]cookieThe cookie that was passed to ubjson_write_init().
[in]bufData to write, never NULL.
[in]lenData to write, always >= 0.
Returns
  • < 0 to indicate an error.
  • > 0 to indicate success.

Definition at line 243 of file ubjson.h.

Enumeration Type Documentation

◆ ubjson_int32_type_t

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

Definition at line 171 of file ubjson.h.

◆ ubjson_read_callback_result_t

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.

Enumerator
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

Definition at line 186 of file ubjson.h.

◆ ubjson_type_t

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.

Enumerator
UBJSON_ABSENT 

There is no such value.

Only used in the callback of 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_get_bool() or use content verbatim.

UBJSON_TYPE_INT32 

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_INT64 

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

Use ubjson_get_i64() to read the value.

UBJSON_TYPE_FLOAT 

The next datum is a 32 bit floating point value.

Use ubjson_get_float() to read the value.

UBJSON_TYPE_DOUBLE 

The next datum is a 64 bit floating point value.

Use ubjson_get_double() to read the value.

UBJSON_TYPE_STRING 

The next datum is a string (blob).

Use 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_read_array() to read its contents.

UBJSON_ENTER_OBJECT 

The next datum is an object.

Use 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_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_read_object().

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

Objects can be nested.

Definition at line 59 of file ubjson.h.

Function Documentation

◆ ubjson_close_array()

ssize_t ubjson_close_array ( ubjson_cookie_t *__restrict  cookie)
Parameters
[in]cookieThe cookie that was initialized with ubjson_write_init().
Returns
The result of the supplied ubjson_write_t function.

◆ ubjson_close_object()

ssize_t ubjson_close_object ( ubjson_cookie_t *__restrict  cookie)
Parameters
[in]cookieThe cookie that was initialized with ubjson_write_init().
Returns
The result of the supplied ubjson_write_t function.

◆ ubjson_get_bool()

static ssize_t ubjson_get_bool ( ubjson_cookie_t *__restrict  cookie,
ssize_t  content,
bool *  dest 
)
inlinestatic

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

Parameters
[in]cookieThe cookie that was passed to the callback function.
[in]contentThe content1 that was passed to the callback function.
[out]destThe read datum.
Returns
1, the invocation cannot fail.

Definition at line 359 of file ubjson.h.

◆ ubjson_get_double()

static ssize_t ubjson_get_double ( ubjson_cookie_t *__restrict  cookie,
ssize_t  content,
double *  dest 
)
inlinestatic
Parameters
[in]cookieThe cookie that was passed to the callback function.
[in]contentThe content1 that was passed to the callback function.
[out]destThe read datum.
Returns
The result of the read callback, probably the amount of read bytes.

Definition at line 392 of file ubjson.h.

◆ ubjson_get_float()

static ssize_t ubjson_get_float ( ubjson_cookie_t *__restrict  cookie,
ssize_t  content,
float *  dest 
)
inlinestatic
Parameters
[in]cookieThe cookie that was passed to the callback function.
[in]contentThe content1 that was passed to the callback function.
[out]destThe read datum.
Returns
The result of the read callback, probably the amount of read bytes.

Definition at line 373 of file ubjson.h.

◆ ubjson_get_i32()

ssize_t ubjson_get_i32 ( ubjson_cookie_t *__restrict  cookie,
ssize_t  content,
int32_t *  dest 
)

The value of content1 is one of ubjson_int32_type_t.

Parameters
[in]cookieThe cookie that was passed to the callback function.
[in]contentThe content1 that was passed to the callback function.
[out]destThe read datum.
Returns
The result of the read callback, probably the amount of read bytes.

◆ ubjson_get_i64()

ssize_t ubjson_get_i64 ( ubjson_cookie_t *__restrict  cookie,
ssize_t  content,
int64_t *  dest 
)
Parameters
[in]cookieThe cookie that was passed to the callback function.
[in]contentThe content1 that was passed to the callback function.
[out]destThe read datum.
Returns
The result of the read callback, probably the amount of read bytes.

◆ ubjson_get_string()

ssize_t ubjson_get_string ( ubjson_cookie_t *__restrict  cookie,
ssize_t  content,
void *  dest 
)

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

Parameters
[in]cookieThe cookie that was passed to the callback function.
[in]contentThe content1 that was passed to the callback function.
[out]destBuffer to read the string into.
Returns
The result of the read callback, probably the amount of read bytes.

◆ ubjson_open_array()

ssize_t ubjson_open_array ( ubjson_cookie_t *__restrict  cookie)

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

Parameters
[in]cookieThe cookie that was initialized with ubjson_write_init().
Returns
The result of the supplied ubjson_write_t function.

◆ ubjson_open_array_len()

ssize_t ubjson_open_array_len ( ubjson_cookie_t *__restrict  cookie,
size_t  len 
)

Do not call ubjson_close_array().

Parameters
[in]cookieThe cookie that was initialized with ubjson_write_init().
[in]lenLength of the array.
Returns
The result of the supplied ubjson_write_t function.

◆ ubjson_open_object()

ssize_t ubjson_open_object ( ubjson_cookie_t *__restrict  cookie)

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.

Parameters
[in]cookieThe cookie that was initialized with ubjson_write_init().
Returns
The result of the supplied ubjson_write_t function.

◆ ubjson_open_object_len()

ssize_t ubjson_open_object_len ( ubjson_cookie_t *__restrict  cookie,
size_t  len 
)

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

Parameters
[in]cookieThe cookie that was initialized with ubjson_write_init().
[in]lenNumber of keys inside the object.
Returns
The result of the supplied ubjson_write_t function.

◆ ubjson_peek_value()

ubjson_read_callback_result_t ubjson_peek_value ( ubjson_cookie_t *__restrict  cookie,
ubjson_type_t type,
ssize_t *  content 
)

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

Parameters
[in]cookieThe cookie that was passed to the callback.
[in,out]typePointer to a variable that was initialized with the value of type2, returns the new type1.
[in,out]contentPointer to a variable that was initialized with the value of content2, returns the new content1.
Returns
The same as ubjson_read().

◆ ubjson_read()

static ubjson_read_callback_result_t ubjson_read ( ubjson_cookie_t *__restrict  cookie,
ubjson_read_t  read,
ubjson_read_callback_t  callback 
)
inlinestatic

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.

Parameters
[in]cookieThe cookie that is passed to the callback function.
[in]readThe function that is called to receive more data.
[in]callbackThe callback function.
Returns
See ubjson_read_callback_result_t

Definition at line 300 of file ubjson.h.

◆ ubjson_read_array()

ubjson_read_callback_result_t ubjson_read_array ( ubjson_cookie_t *__restrict  cookie)

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.

Parameters
[in]cookieThe cookie that was passed to the callback function.
Returns
The same as ubjson_read().

◆ ubjson_read_next()

ubjson_read_callback_result_t ubjson_read_next ( ubjson_cookie_t *__restrict  cookie)

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.

Parameters
[in]cookieThe cookie that is passed to the callback function.
Returns
The same as ubjson_read().

◆ ubjson_read_object()

ubjson_read_callback_result_t ubjson_read_object ( ubjson_cookie_t *__restrict  cookie)

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.

Parameters
[in]cookieThe cookie that was passed to the callback function.
Returns
The same as ubjson_read().

◆ ubjson_write_bool()

ssize_t ubjson_write_bool ( ubjson_cookie_t *__restrict  cookie,
bool  value 
)
Parameters
[in]cookieThe cookie that was initialized with ubjson_write_init().
[in]valueThe boolean value to write.
Returns
The result of the supplied ubjson_write_t function.

◆ ubjson_write_double()

ssize_t ubjson_write_double ( ubjson_cookie_t *__restrict  cookie,
double  value 
)
Parameters
[in]cookieThe cookie that was initialized with ubjson_write_init().
[in]valueThe integer value to write.
Returns
The result of the supplied ubjson_write_t function.

◆ ubjson_write_float()

ssize_t ubjson_write_float ( ubjson_cookie_t *__restrict  cookie,
float  value 
)
Parameters
[in]cookieThe cookie that was initialized with ubjson_write_init().
[in]valueThe integer value to write.
Returns
The result of the supplied ubjson_write_t function.

◆ ubjson_write_i32()

ssize_t ubjson_write_i32 ( ubjson_cookie_t *__restrict  cookie,
int32_t  value 
)

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

Parameters
[in]cookieThe cookie that was initialized with ubjson_write_init().
[in]valueThe integer value to write.

◆ ubjson_write_i64()

ssize_t ubjson_write_i64 ( ubjson_cookie_t *__restrict  cookie,
int64_t  value 
)

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

Parameters
[in]cookieThe cookie that was initialized with ubjson_write_init().
[in]valueThe integer value to write.
Returns
The result of the supplied ubjson_write_t function.

◆ ubjson_write_init()

static void ubjson_write_init ( ubjson_cookie_t *__restrict  cookie,
ubjson_write_t  write_fun 
)
inlinestatic

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
[out]cookieThe cookie that will be passed to ubjson_write_null() and friends.
[in]write_funThe function that will be called to write data.

Definition at line 443 of file ubjson.h.

◆ ubjson_write_key()

ssize_t ubjson_write_key ( ubjson_cookie_t *__restrict  cookie,
const void *  value,
size_t  len 
)

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
[in]cookieThe cookie that was initialized with ubjson_write_init().
[in]valueThe key, should be a UTF-8 string.
[in]lenThe length of the key.
Returns
The result of the supplied ubjson_write_t function.

◆ ubjson_write_noop()

ssize_t ubjson_write_noop ( ubjson_cookie_t *__restrict  cookie)
Parameters
[in]cookieThe cookie that was initialized with ubjson_write_init().
Returns
The result of the supplied ubjson_write_t function.

◆ ubjson_write_null()

ssize_t ubjson_write_null ( ubjson_cookie_t *__restrict  cookie)
Parameters
[in]cookieThe cookie that was initialized with ubjson_write_init().

◆ ubjson_write_string()

ssize_t ubjson_write_string ( ubjson_cookie_t *__restrict  cookie,
const void *  value,
size_t  len 
)
Parameters
[in]cookieThe cookie that was initialized with ubjson_write_init().
[in]valueThe string or blob to write.
[in]lenThe length of the string or blob.
Returns
The result of the supplied ubjson_write_t function.