Read
Utilities > MessagePack

APIs for unpacking MessagePack data into object and reading their values. More...

Functions

gos_result_t gos_msgpack_deserialize_with_buffer ( gos_msgpack_object_t **root_ptr, const void *buffer, uint32_t length, gos_msgpack_flag_t flags)
void gos_msgpack_free_objects (void *root_obj)
gos_msgpack_object_t * gos_msgpack_get_dict_object (const gos_msgpack_object_dict_t *dict, const char *key, gos_msgpack_type_t type)
gos_msgpack_object_t * gos_msgpack_get_array_object (const gos_msgpack_object_array_t *array, uint32_t index, gos_msgpack_type_t type)
gos_result_t gos_msgpack_foreach (const gos_msgpack_object_t *dict_or_array, gos_msgpack_iterator_t iterator_callback, void *arg, uint32_t depth)
char * gos_msgpack_to_str (const gos_msgpack_object_t *obj, char *buffer, uint32_t max_length)
bool gos_msgpack_object_is_type (const gos_msgpack_object_t *object, gos_msgpack_type_t type)
int32_t gos_msgpack_get_int (const gos_msgpack_object_t *object)
uint32_t gos_msgpack_get_uint (const gos_msgpack_object_t *object)
int64_t * gos_msgpack_get_long (const gos_msgpack_object_t *object, int64_t *buffer)
uint64_t * gos_msgpack_get_ulong (const gos_msgpack_object_t *object, uint64_t *buffer)
char * gos_msgpack_get_str (const gos_msgpack_object_t *object, char *buffer, uint16_t max_length)

Detailed Description

APIs for unpacking MessagePack data into object and reading their values.

Function Documentation

◆ gos_msgpack_deserialize_with_buffer()

gos_result_t gos_msgpack_deserialize_with_buffer ( gos_msgpack_object_t ** root_ptr,
const void * buffer,
uint32_t length,
gos_msgpack_flag_t flags
)

Convert a 'packed' MessagePack binary string to a linked list of gos_msgpack_object_t

This will parse the binary MessagePack data into a linked list of gos_msgpack_object_t . Each gos_msgpack_object_t is dynamically allocated.

Use gos_msgpack_free_objects() to release the allocated memory.

This function does NOT allocate additional memory for binary strings and strings. Thus the given buffer MUST persist for as long as the return objects are referenced. If the given buffer is released, the memory a MSGPACK_TYPE_STR or MSGPACK_TYPE_BIN object references will be invalid.

Note
The returned root object will be a gos_msgpack_object_array_t OR gos_msgpack_object_dict_t
Parameters
root_ptr Pointer to hold allocated linked list of MessagePack object
buffer Buffer containing 'packed' MessagePack data, this buffer MUST persist for as long as the return object are referenced IF binary strings or strings are used
length Length of buffer to parse
flags gos_msgpack_flag_t
Returns
result of API, see gos_result_t
Examples:
utility/msgpack/read_write_buffer.c , and utility/msgpack/read_write_stream.c .

◆ gos_msgpack_foreach()

gos_result_t gos_msgpack_foreach ( const gos_msgpack_object_t * dict_or_array,
gos_msgpack_iterator_t iterator_callback,
void * arg,
uint32_t depth
)

Iterate the entries in a dictionary or array

This invokes the supplied iterator_callback for each entry in the supplied dict_or_array . See gos_msgpack_iterator_t for more details on how the callback works.

The arg argument will be supplied to the iterator_callback callback.

If the depth argument is greater than zero then dictionary/array entries will be recursively iterated.

Parameters
dict_or_array A gos_msgpack_object_dict_t or gos_msgpack_object_array_t object to iterate
iterator_callback gos_msgpack_iterator_t callback to be invoked for each entry in the dictionary or array
arg Custom argument to pass to the iterator_callback
depth Recursion depth, 0 will only iterate the entries in the given dict_or_array , greater than 0 will iterate sub array/dictionaries
Returns
GOS_SUCCESS if all all entries iterated, else gos_result_t returned by gos_msgpack_iterator_t

◆ gos_msgpack_free_objects()

void gos_msgpack_free_objects ( void * root_obj )

Release all gos_msgpack_object_t the supplied object references

This should be used to release the memory that's allocated with gos_msgpack_deserialize_with_buffer()

Parameters
root_obj Object to release
Examples:
dms/messages/main.c .

◆ gos_msgpack_get_array_object()

gos_msgpack_object_t * gos_msgpack_get_array_object ( const gos_msgpack_object_array_t * array,
uint32_t index,
gos_msgpack_type_t type
)

Return value of corresponding index in array

This returns the value at the given index in the supplied array

If the index is out-of-range or the array is invalid, NULL is returned.

Parameters
array gos_msgpack_object_array_t An array object
index Index to return value
type The expected type of object to return, see gos_msgpack_type_t , set to MSGPACK_TYPE_ANY to return any type
Returns
Array value IF found, NULL else

◆ gos_msgpack_get_dict_object()

gos_msgpack_object_t * gos_msgpack_get_dict_object ( const gos_msgpack_object_dict_t * dict,
const char * key,
gos_msgpack_type_t type
)

Return the value of the corresponding key in dictionary

This returns the value which has the given key in the supplied dict

If the key is not found or the dict is invalid, NULL is returned.

Parameters
dict gos_msgpack_object_dict_t A dictionary object
key The dictionary key of the desired value to return
type The expected type of object to return, see gos_msgpack_type_t , set to MSGPACK_TYPE_ANY to return any type
Returns
The dictionary value IF found, NULL else

◆ gos_msgpack_get_int()

int32_t gos_msgpack_get_int ( const gos_msgpack_object_t * object )

Return a MessagePack integer object as a signed 32bit value

This converts the following gos_msgpack_type_t to a signed 32bit value

This is useful is the actual bit-length is unknown

Parameters
object Integer object type to return as signed 32bit value
Returns
signed 32bit value of supplied object

◆ gos_msgpack_get_long()

int64_t* gos_msgpack_get_long ( const gos_msgpack_object_t * object,
int64_t * buffer
)

Return a MessagePack integer object as a signed 64bit value

This has exact same functionality as gos_msgpack_get_int() except it also supports the following gos_msgpack_type_t :

This is useful is the actual bit-length is unknown

Parameters
object Integer object to return a signed 64bit value
buffer Buffer to hold 64bit value (must be at least 8 bytes)
Returns
Pointer to 64bit value (same pointer as supplied buffer )

◆ gos_msgpack_get_str()

char* gos_msgpack_get_str ( const gos_msgpack_object_t * object,
char * buffer,
uint16_t max_length
)

Copy a MessagePack string object into the given buffer

A MessagePack string object is NOT null-terminated. This function copies a string object's string into the given buffer AND null-terminates the string.

Parameters
object MessagPacket MSGPACK_TYPE_STR object
buffer Buffer to hold string data, this buffer should contain an additional byte to hold the null-terminator
max_length The maximum length of the supplied buffer
Returns
Pointer to populated buffer , this is the same pointer as the supplied buffer

◆ gos_msgpack_get_uint()

uint32_t gos_msgpack_get_uint ( const gos_msgpack_object_t * object )

Return a MessagePack integer object as an unsigned 32bit value

This converts the following gos_msgpack_type_t to an unsigned 32bit value

This is useful is the actual bit-length is unknown

Parameters
object Integer object type to return as unsigned 32bit value
Returns
unsigned 32bit value of supplied object

◆ gos_msgpack_get_ulong()

uint64_t* gos_msgpack_get_ulong ( const gos_msgpack_object_t * object,
uint64_t * buffer
)

Return a MessagePack integer object as an unsigned 64bit value

This has exact same functionality as gos_msgpack_get_uint() except it also supports the following gos_msgpack_type_t :

This is useful is the actual bit-length is unknown

Parameters
object Integer object to return an unsigned 64bit value
buffer Buffer to hold 64bit value (must be at least 8 bytes)
Returns
Pointer to 64bit value (same pointer as supplied buffer )

◆ gos_msgpack_object_is_type()

bool gos_msgpack_object_is_type ( const gos_msgpack_object_t * object,
gos_msgpack_type_t type
)

Return if an object is a given type

Parameters
object msgpack object, see gos_msgpack_object_t
type msgpack object type, see gos_msgpack_type_t

◆ gos_msgpack_to_str()

char* gos_msgpack_to_str ( const gos_msgpack_object_t * obj,
char * buffer,
uint32_t max_length
)

Convert a gos_msgpack_object_t to a string

Convert a gos_msgpack_object_t to a string and add to provided buffer.

Note
The max_length MUST be at least 32 bytes
Parameters
obj gos_msgpack_object_t to convert to string
buffer Buffer to hold string
max_length The size of the provided buffer in bytes
Returns
Same pointer as buffer argument