Read
APIs for unpacking MessagePack data into object and reading their values. More...
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
◆ 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
◆ 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
- MSGPACK_TYPE_BOOL
- MSGPACK_TYPE_INT8
- MSGPACK_TYPE_UINT8
- MSGPACK_TYPE_INT16
- MSGPACK_TYPE_UINT16
- MSGPACK_TYPE_INT32
- MSGPACK_TYPE_UINT32
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 suppliedbuffer
◆ 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
- MSGPACK_TYPE_BOOL
- MSGPACK_TYPE_INT8
- MSGPACK_TYPE_UINT8
- MSGPACK_TYPE_INT16
- MSGPACK_TYPE_UINT16
- MSGPACK_TYPE_INT32
- MSGPACK_TYPE_UINT32
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 theobj
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 instr
◆ 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