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)
gos_result_t gos_msgpack_remove_dict_object ( gos_msgpack_object_dict_t *dict_obj, void *obj)
gos_result_t gos_msgpack_set_user_context ( gos_msgpack_object_t *obj, void *user, bool auto_free)
gos_result_t gos_msgpack_get_user_context (const gos_msgpack_object_t *obj, void **user_ptr)
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)
int gos_msgpack_str_cmp (const gos_msgpack_object_t *object, const char *str)

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.

By default, 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. Use the flag MSGPACK_DESERIALIZE_WITH_PERSISTENT_STRINGS to ensure that the object data persists after the given buffer is de-allocated.

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:
demo/secure_element/commands.c , 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:
cloud/dps_demo/main.c , demo/secure_element/commands.c , dms/messages/main.c , hurricane/security_camera/camera.c , hurricane/security_camera/main.c , and network/http_server_stream/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_get_user_context()

gos_result_t gos_msgpack_get_user_context ( const gos_msgpack_object_t * obj,
void ** user_ptr
)

Retrieve user context pointer lined to object

This returns the user context pointer that was set via gos_msgpack_set_user_context()

Parameters
obj Object to retrieve user context pointer from
user_ptr Pointer to hold user context
Returns
gos_result_t of API call

◆ 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_remove_dict_object()

gos_result_t gos_msgpack_remove_dict_object ( gos_msgpack_object_dict_t * dict_obj,
void * obj
)

Remove an entry from a dictionary object

This removes and de-allocates the given object from the dictionary.

Parameters
dict_obj A dictionary object
obj Object to remove and de-allocate from dictionary
Returns
gos_result_t of API call

◆ gos_msgpack_set_user_context()

gos_result_t gos_msgpack_set_user_context ( gos_msgpack_object_t * obj,
void * user,
bool auto_free
)

Set user context for object

This associates a pointer to the given obj . This obj MUST be a dictionary or array object.

Optionally, if auto_free=true , when the obj is cleaned up, the given user context will also be cleaned via gos_free()

One use-case of this is to set the user context pointer as the buffer argument that was given to gos_msgpack_deserialize_with_buffer() . This way when the root object is cleaned the associated buffer is also automatically cleaned.

Note
Use gos_msgpack_get_user_context() to get the user context pointer
Parameters
obj Dictionary or array msgpack object
user User pointer to link to given obj
auto_free If true, the user is automatically freed via gos_free() when the obj is cleaned
Returns
gos_result_t of API call

◆ gos_msgpack_str_cmp()

int gos_msgpack_str_cmp ( const gos_msgpack_object_t * object,
const char * str
)

Compare a string object to a string

This has the same functionality as strcmp() but accepts a gos_msgpack_object_str_t as the first argument.

Parameters
object String msgpack object
str String to compare
Returns
<0 the first character that does not match has a lower value in `object` than in `str` 0 the contents of both strings are equal >0 the first character that does not match has a greater value in object than in str

◆ 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