Detailed Description

template<typename KEYTYPE = const char*>
class satcat5::cbor::MapReader< KEYTYPE >

Reads a series of key-value pairs from a CBOR Map.

A common CBOR use case is to have a single Map at the top level with several keys of the same type (string, uint, etc.). This class assumes this CBOR payload structure and provides readers for these, templated by supported QCBOR key types. Most return their value wrapped by util::optional<> to indicate whether the value was found in the Map. This silently clears errors with the code QCBOR_ERR_LABEL_NOT_FOUND to allow trivial recovery from this class of decoder errors. Array reading functions can have more complex errors and therefore have their own return codes defined. A template parameter is provided for the key type to be written to the map - QCBOR currently only supports usage of string (const char*) and integer (s64) keys.

See also: satcat5::cbor::MapReaderStatic

Creates an ephemeral reader for the Concise Binary Object Representation (CBOR, IETF RFC8949), holding underlying objects and providing more concise member functions. This reader wraps the QCBOR library into a more familiar interface that performs stack buffer allocation and io::Readable handling automatically. QCBOR decode requires a working buffer to hold the in-progress object, which should be allocated by a child class, typically cbor::ListReaderStatic or cbor::MapReaderStatic.

Most users should be able to hit target functionality with usage of cbor::ListReader cbor::MapReader or other future wrappers. However, the QCBOR decode context cbor is a public member variable that may be used for calls to QCBORDecode_* functions for complex use-cases outside the scope of provided wrapper classes.

Usage:

Create a CborReader object, which copies from any io::Readable sink and calls read_finalize(). If no io::Readable is passed, the given buffer is assumed to be populated with a CBOR payload.
Use member functions of a child class such as cbor::ListReader or cbor::MapReader to read a valid CBOR list or map, respectively.
For any edge cases, use QCBORDecode_* functions with the given QCBOR context cbor.

Most users should instantiate ListReaderStatic or MapReaderStatic instead of this to perform all stack buffer allocation.

See also: satcat5::cbor::ListReader, satcat5::cbor::MapReader

Definition at line 678 of file io_cbor.h.

#include <io_cbor.h>

Inheritance diagram for satcat5::cbor::MapReader< KEYTYPE >:

[legend]

Collaboration diagram for satcat5::cbor::MapReader< KEYTYPE >:

[legend]

Public Member Functions
constexpr	MapReader (QCBORDecodeContext *decode)
	Create a MapReader from an existing decoder context. More...

bool	is_null (KEYTYPE key) const
	Check if a key in the Map exists and is NULL.

satcat5::util::optional< satcat5::io::ArrayRead >	get_string (KEYTYPE key) const
	Read a string from the Map. More...

satcat5::util::optional< satcat5::io::ArrayRead >	get_bytes (KEYTYPE key) const
	Read a byte sequence from the Map. More...

QCBORDecodeContext *	open_list (KEYTYPE key) const
	Read a nested list from the Map. More...

QCBORDecodeContext *	open_map (KEYTYPE key) const
	Read a nested dictionary from the Map. More...

optional< bool >	get_bool (s64 key) const

optional< bool >	get_bool (const char *key) const

optional< s64 >	get_int (s64 key) const

optional< s64 >	get_int (const char *key) const

optional< u64 >	get_uint (s64 key) const

optional< u64 >	get_uint (const char *key) const

optional< double >	get_double (s64 key) const

optional< double >	get_double (const char *key) const

bool	is_null (s64 key) const

bool	is_null (const char *key) const

optional< ArrayRead >	get_string (s64 key) const

optional< ArrayRead >	get_string (const char *key) const

optional< ArrayRead >	get_bytes (s64 key) const

optional< ArrayRead >	get_bytes (const char *key) const

QCBORDecodeContext *	open_list (s64 key) const

QCBORDecodeContext *	open_list (const char *key) const

QCBORDecodeContext *	open_map (s64 key) const

QCBORDecodeContext *	open_map (const char *key) const

int	get_bool_array (s64 key, Writeable &dst) const

int	get_bool_array (const char *key, Writeable &dst) const

int	get_s64_array (s64 key, Writeable &dst) const

int	get_s64_array (const char *key, Writeable &dst) const

int	get_double_array (s64 key, Writeable &dst) const

int	get_double_array (const char *key, Writeable &dst) const

bool	ok () const
	Check if any errors have been encountered yet during decoding.

QCBORError	get_error () const
	Get the QCBOR decoding error, if any.

void	close_list () const
	Resume parsing at the end of a nested list. More...

void	close_map () const
	Resume parsing at the end of a nested dictionary. More...

bool	copy_item (QCBOREncodeContext *dst)
	Copy the next CBOR item to the specified destination. More...

unsigned	copy_all (QCBOREncodeContext *dst)
	Copy all remaining CBOR item(s) to the specified destination. More...


satcat5::util::optional< bool >	get_bool (KEYTYPE key) const
	Read a scalar value from the Map.

satcat5::util::optional< s64 >	get_int (KEYTYPE key) const
	Read a scalar value from the Map.

satcat5::util::optional< u64 >	get_uint (KEYTYPE key) const
	Read a scalar value from the Map.

satcat5::util::optional< double >	get_double (KEYTYPE key) const
	Read a scalar value from the Map.


int	get_bool_array (KEYTYPE key, satcat5::io::Writeable &dst) const
	Read an array of boolean values from the Map, always written as u8 values regardless of platform `sizeof(bool)`. More...

int	get_bool_array (KEYTYPE key, u8 *arr, unsigned arr_len) const
	Read an array of boolean values from the Map, always written as u8 values regardless of platform `sizeof(bool)`. More...


int	get_s64_array (KEYTYPE key, satcat5::io::Writeable &dst) const
	Read an array of integer values from the Map, always written as 64-bit length signed values (s64) to cover any size in the Map. More...

int	get_s64_array (KEYTYPE key, s64 *arr, unsigned arr_len) const
	Read an array of integer values from the Map, always written as 64-bit length signed values (s64) to cover any size in the Map. More...


int	get_double_array (KEYTYPE key, satcat5::io::Writeable &dst) const
	Read an array of floating-point values from the Map, always written as doubles to cover any precision in the Map. More...

int	get_double_array (KEYTYPE key, double *arr, unsigned arr_len) const
	Read an array of floating-point values from the Map, always written as doubles to cover any precision in the Map. More...

Public Attributes
QCBORDecodeContext *const	cbor
	QCBOR context pointer.

Static Public Attributes
static const int	ERR_NOT_FOUND = -1
	Key not found.

static const int	ERR_OVERFLOW = -2
	Overflowed user array.

static const int	ERR_BAD_TYPE = -3
	Non-matching type.

static const int	ERR_QCBOR_INT = -4
	Misc QCBOR error.

Protected Member Functions
	MapReader (satcat5::io::Readable src, QCBORDecodeContext decode, u8 *buff, unsigned size)
	Opens a QCBOR Decode Context from an io::Readable. More...

int	get_array_internal (satcat5::io::Writeable &dst, u8 qcbor_type, u8 type_size) const
	Internal function for shared array logic. More...

unsigned	peek_integer_len (const u8 *rdptr) const
	Predict the length of the next integer value. More...

Protected Attributes
QCBORItem	m_item
	QCBOR Decoder item.

Constructor & Destructor Documentation

◆ MapReader() [1/2]

template<typename KEYTYPE = const char*>

constexpr satcat5::cbor::MapReader< KEYTYPE >::MapReader ( QCBORDecodeContext * decode )

inlineexplicitconstexpr

Create a MapReader from an existing decoder context.

The caller MUST have already entered the map in question.

See also: QCBORDecode_EnterMap (item-by-item parsing, next is map); QCBORDecode_EnterMapFromMapN (map within an integer-keyed map); QCBORDecode_EnterMapFromMapSZ (map within a string-keyed map)

Definition at line 685 of file io_cbor.h.

◆ MapReader() [2/2]

template<typename KEYTYPE >

satcat5::cbor::MapReader< KEYTYPE >::MapReader	(	satcat5::io::Readable *	src,
		QCBORDecodeContext *	decode,
		u8 *	buff,
		unsigned	size
	)

protected

Opens a QCBOR Decode Context from an io::Readable.

This constructor assumes the first element is a map (i.e., a key/value dictionary) and automatically enters that map.

Opens a QCBOR Decode Context from an io::Readable. Constructor requires child class to provide a working buffer.

Parameters

src	Readable source to decode, or NULL if buffers are already populated.
decode	Pointer to an uninitialized QCBOR encoder object.
buff	Backing buffer for QCBOR.
size	Backing buffer size for QCBOR.

Definition at line 283 of file io_cbor.cc.

Member Function Documentation

◆ close_list()

void satcat5::cbor::CborReader::close_list ( ) const

inlineinherited

Resume parsing at the end of a nested list.

See also: ListReader::open_list, MapReader::open_list.

Definition at line 477 of file io_cbor.h.

◆ close_map()

void satcat5::cbor::CborReader::close_map ( ) const

inlineinherited

Resume parsing at the end of a nested dictionary.

See also: ListReader::open_map, MapReader::open_map.

Definition at line 482 of file io_cbor.h.

◆ copy_all()

unsigned satcat5::cbor::CborReader::copy_all ( QCBOREncodeContext * dst )

inherited

Copy all remaining CBOR item(s) to the specified destination.

Returns: The number of items copied.

Definition at line 227 of file io_cbor.cc.

◆ copy_item()

bool satcat5::cbor::CborReader::copy_item ( QCBOREncodeContext * dst )

inherited

Copy the next CBOR item to the specified destination.

If the next item is a nested data structure, this copies the entire data structure to the destination object.

Returns: True if an item was copied successfully.

Definition at line 194 of file io_cbor.cc.

◆ get_array_internal()

int satcat5::cbor::CborReader::get_array_internal	(	satcat5::io::Writeable &	dst,
		u8	qcbor_type,
		u8	type_size
	)		const

protectedinherited

Internal function for shared array logic.

This function is called by all other "get_array" variants.

Definition at line 520 of file io_cbor.cc.

◆ get_bool_array() [1/2]

template<typename KEYTYPE = const char*>

int satcat5::cbor::MapReader< KEYTYPE >::get_bool_array	(	KEYTYPE	key,
		satcat5::io::Writeable &	dst
	)		const

Read an array of boolean values from the Map, always written as u8 values regardless of platform sizeof(bool).

Two interfaces are provided: one takes a pointer to an array, and the other uses io::Writeable. All values are always written in CPU-native endian order.

Example usage to directly populate an array:

MapReaderStatic<const char*> r(&buf);
s64 buffer[10];
if (r.get_s64_array("int_arr_key", buffer, 10) < 0) {
    return false; // Error!
}
s8 val = (s8) buffer[2]; // Example cast down to 8-bit type

Parameters

key	The dictionary key to be read.
arr	Destination array for read values.
arr_len	Length of `arr`.
dst	Writeable destination for array elements.

Returns: Number of elements written to dst. If there was not enough space in dst, this returns -1. If any CBOR item has a mismatched type, this returns -2.

◆ get_bool_array() [2/2]

template<typename KEYTYPE = const char*>

int satcat5::cbor::MapReader< KEYTYPE >::get_bool_array	(	KEYTYPE	key,
		u8 *	arr,
		unsigned	arr_len
	)		const

inline

Read an array of boolean values from the Map, always written as u8 values regardless of platform sizeof(bool).

Two interfaces are provided: one takes a pointer to an array, and the other uses io::Writeable. All values are always written in CPU-native endian order.

Example usage to directly populate an array:

MapReaderStatic<const char*> r(&buf);
s64 buffer[10];
if (r.get_s64_array("int_arr_key", buffer, 10) < 0) {
    return false; // Error!
}
s8 val = (s8) buffer[2]; // Example cast down to 8-bit type

Parameters

key	The dictionary key to be read.
arr	Destination array for read values.
arr_len	Length of `arr`.
dst	Writeable destination for array elements.

Returns: Number of elements written to dst. If there was not enough space in dst, this returns -1. If any CBOR item has a mismatched type, this returns -2.

Definition at line 751 of file io_cbor.h.

◆ get_bytes()

template<typename KEYTYPE = const char*>

satcat5::util::optional<satcat5::io::ArrayRead> satcat5::cbor::MapReader< KEYTYPE >::get_bytes ( KEYTYPE key ) const

Read a byte sequence from the Map.

Returns: An io::ArrayRead containing the bytes in the working buffer - valid for the lifetime of this class.

◆ get_double_array() [1/2]

template<typename KEYTYPE = const char*>

int satcat5::cbor::MapReader< KEYTYPE >::get_double_array	(	KEYTYPE	key,
		double *	arr,
		unsigned	arr_len
	)		const

inline

Read an array of floating-point values from the Map, always written as doubles to cover any precision in the Map.

Two interfaces are provided: one takes a pointer to an array, and the other uses io::Writeable. All values are always written in CPU-native endian order.

Example usage to directly populate an array:

MapReaderStatic<const char*> r(&buf);
s64 buffer[10];
if (r.get_s64_array("int_arr_key", buffer, 10) < 0) {
    return false; // Error!
}
s8 val = (s8) buffer[2]; // Example cast down to 8-bit type

Parameters

key	The dictionary key to be read.
arr	Destination array for read values.
arr_len	Length of `arr`.
dst	Writeable destination for array elements.

Returns: Number of elements written to dst. If there was not enough space in dst, this returns -1. If any CBOR item has a mismatched type, this returns -2.

Definition at line 773 of file io_cbor.h.

◆ get_double_array() [2/2]

template<typename KEYTYPE = const char*>

int satcat5::cbor::MapReader< KEYTYPE >::get_double_array	(	KEYTYPE	key,
		satcat5::io::Writeable &	dst
	)		const

Read an array of floating-point values from the Map, always written as doubles to cover any precision in the Map.

Two interfaces are provided: one takes a pointer to an array, and the other uses io::Writeable. All values are always written in CPU-native endian order.

Example usage to directly populate an array:

MapReaderStatic<const char*> r(&buf);
s64 buffer[10];
if (r.get_s64_array("int_arr_key", buffer, 10) < 0) {
    return false; // Error!
}
s8 val = (s8) buffer[2]; // Example cast down to 8-bit type

Parameters

key	The dictionary key to be read.
arr	Destination array for read values.
arr_len	Length of `arr`.
dst	Writeable destination for array elements.

Returns: Number of elements written to dst. If there was not enough space in dst, this returns -1. If any CBOR item has a mismatched type, this returns -2.

◆ get_s64_array() [1/2]

template<typename KEYTYPE = const char*>

int satcat5::cbor::MapReader< KEYTYPE >::get_s64_array	(	KEYTYPE	key,
		s64 *	arr,
		unsigned	arr_len
	)		const

inline

Read an array of integer values from the Map, always written as 64-bit length signed values (s64) to cover any size in the Map.

Two interfaces are provided: one takes a pointer to an array, and the other uses io::Writeable. All values are always written in CPU-native endian order.

Example usage to directly populate an array:

MapReaderStatic<const char*> r(&buf);
s64 buffer[10];
if (r.get_s64_array("int_arr_key", buffer, 10) < 0) {
    return false; // Error!
}
s8 val = (s8) buffer[2]; // Example cast down to 8-bit type

Parameters

key	The dictionary key to be read.
arr	Destination array for read values.
arr_len	Length of `arr`.
dst	Writeable destination for array elements.

Returns: Number of elements written to dst. If there was not enough space in dst, this returns -1. If any CBOR item has a mismatched type, this returns -2.

Definition at line 762 of file io_cbor.h.

◆ get_s64_array() [2/2]

template<typename KEYTYPE = const char*>

int satcat5::cbor::MapReader< KEYTYPE >::get_s64_array	(	KEYTYPE	key,
		satcat5::io::Writeable &	dst
	)		const

Read an array of integer values from the Map, always written as 64-bit length signed values (s64) to cover any size in the Map.

Two interfaces are provided: one takes a pointer to an array, and the other uses io::Writeable. All values are always written in CPU-native endian order.

Example usage to directly populate an array:

MapReaderStatic<const char*> r(&buf);
s64 buffer[10];
if (r.get_s64_array("int_arr_key", buffer, 10) < 0) {
    return false; // Error!
}
s8 val = (s8) buffer[2]; // Example cast down to 8-bit type

Parameters

key	The dictionary key to be read.
arr	Destination array for read values.
arr_len	Length of `arr`.
dst	Writeable destination for array elements.

Returns: Number of elements written to dst. If there was not enough space in dst, this returns -1. If any CBOR item has a mismatched type, this returns -2.

◆ get_string()

template<typename KEYTYPE = const char*>

satcat5::util::optional<satcat5::io::ArrayRead> satcat5::cbor::MapReader< KEYTYPE >::get_string ( KEYTYPE key ) const

Read a string from the Map.

Returns: An io::ArrayRead containing the unterminated string in the working buffer - valid for the lifetime of this class.

◆ open_list()

template<typename KEYTYPE = const char*>

QCBORDecodeContext* satcat5::cbor::MapReader< KEYTYPE >::open_list ( KEYTYPE key ) const

Read a nested list from the Map.

See also: close_list. Allows parsing of keys where the value is a list of items, which may have different types. Once finished, the caller must then call CborReader::close_list.

Returns: Pointer to the decoder if found, otherwise null. (This pointer is suitable for creating another ListReader.)

◆ open_map()

template<typename KEYTYPE = const char*>

QCBORDecodeContext* satcat5::cbor::MapReader< KEYTYPE >::open_map ( KEYTYPE key ) const

Read a nested dictionary from the Map.

Allows parsing of keys where the value is another self-contained key/value dictionary. Once finished, the caller MUST then call CborReader::close_map.

Returns: Pointer to the decoder if found, otherwise null. (This pointer is suitable for creating another MapReader.)

◆ peek_integer_len()

unsigned satcat5::cbor::CborReader::peek_integer_len ( const u8 * rdptr ) const

protectedinherited

Predict the length of the next integer value.

Standard integers may be 1, 2, 3, 5, or 9 bytes.

Returns: Length in bytes, or zero on error.

Definition at line 237 of file io_cbor.cc.

The documentation for this class was generated from the following files:

Detailed Description

template<typename KEYTYPE = const char*> class satcat5::cbor::MapReader< KEYTYPE >

Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ MapReader() [1/2]

◆ MapReader() [2/2]

Member Function Documentation

◆ close_list()

◆ close_map()

◆ copy_all()

◆ copy_item()

◆ get_array_internal()

◆ get_bool_array() [1/2]

◆ get_bool_array() [2/2]

◆ get_bytes()

◆ get_double_array() [1/2]

◆ get_double_array() [2/2]

◆ get_s64_array() [1/2]

◆ get_s64_array() [2/2]

◆ get_string()

◆ open_list()

◆ open_map()

◆ peek_integer_len()

template<typename KEYTYPE = const char*>
class satcat5::cbor::MapReader< KEYTYPE >