Detailed Description

Read consecutive values from a CBOR Array/List.

CBOR makes no formal distinction between arrays and lists; they are simply consecutive values that may have different underlying types.

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 550 of file io_cbor.h.

#include <io_cbor.h>

Inheritance diagram for satcat5::cbor::ListReader:

[legend]

Collaboration diagram for satcat5::cbor::ListReader:

[legend]

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

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

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

QCBORDecodeContext *	open_list () const
	Read a nested list from the List. More...

QCBORDecodeContext *	open_map () const
	Read a nested dictionary from the List. More...

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< QCBORItem >	get_item () const
	Read the next scalar value from the List.

satcat5::util::optional< bool >	get_bool () const
	Read the next scalar value from the List.

satcat5::util::optional< s64 >	get_int () const
	Read the next scalar value from the List.

satcat5::util::optional< u64 >	get_uint () const
	Read the next scalar value from the List.

satcat5::util::optional< double >	get_double () const
	Read the next scalar value from the List.


int	get_bool_array (satcat5::io::Writeable &dst) const
	Read an array of boolean values from the List. More...

int	get_bool_array (u8 *arr, unsigned arr_len) const
	Read an array of boolean values from the List. More...


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

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


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

int	get_double_array (double *arr, unsigned arr_len) const
	Read an array of floating-point values from the List, always written as doubles to cover any precision in the List. 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
	ListReader (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

◆ ListReader() [1/2]

constexpr satcat5::cbor::ListReader::ListReader ( QCBORDecodeContext * decode )

inlineexplicitconstexpr

Create a ListReader from an existing decoder context.

The caller MUST have already entered the array/list in question.

See also: QCBORDecode_EnterArray (item-by-item parsing, next is list); QCBORDecode_EnterArrayFromMapN (list within an integer-keyed map); QCBORDecode_EnterArrayFromMapSZ (list within an string-keyed map)

Definition at line 557 of file io_cbor.h.

◆ ListReader() [2/2]

satcat5::cbor::ListReader::ListReader	(	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 an array and automatically enters that array.

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 273 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]

int satcat5::cbor::ListReader::get_bool_array ( satcat5::io::Writeable & dst ) const

Read an array of boolean values from the List.

This method always writes true/false values as single bytes (u8 per boolean value), 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

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 469 of file io_cbor.cc.

◆ get_bool_array() [2/2]

int satcat5::cbor::ListReader::get_bool_array	(	u8 *	arr,
		unsigned	arr_len
	)		const

inline

Read an array of boolean values from the List.

This method always writes true/false values as single bytes (u8 per boolean value), 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

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 621 of file io_cbor.h.

◆ get_bytes()

optional< ArrayRead > satcat5::cbor::ListReader::get_bytes ( ) const

Read a byte sequence from the List.

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

Definition at line 415 of file io_cbor.cc.

◆ get_double_array() [1/2]

int satcat5::cbor::ListReader::get_double_array	(	double *	arr,
		unsigned	arr_len
	)		const

inline

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

This method always writes true/false values as single bytes (u8 per boolean value), 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

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 643 of file io_cbor.h.

◆ get_double_array() [2/2]

int satcat5::cbor::ListReader::get_double_array ( satcat5::io::Writeable & dst ) const

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

This method always writes true/false values as single bytes (u8 per boolean value), 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

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 503 of file io_cbor.cc.

◆ get_s64_array() [1/2]

int satcat5::cbor::ListReader::get_s64_array	(	s64 *	arr,
		unsigned	arr_len
	)		const

inline

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

This method always writes true/false values as single bytes (u8 per boolean value), 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

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 632 of file io_cbor.h.

◆ get_s64_array() [2/2]

int satcat5::cbor::ListReader::get_s64_array ( satcat5::io::Writeable & dst ) const

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

This method always writes true/false values as single bytes (u8 per boolean value), 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

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 486 of file io_cbor.cc.

◆ get_string()

optional< ArrayRead > satcat5::cbor::ListReader::get_string ( ) const

Read a string from the List.

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

Definition at line 395 of file io_cbor.cc.

◆ open_list()

QCBORDecodeContext * satcat5::cbor::ListReader::open_list ( ) const

Read a nested list from the List.

Allows parsing of keys where the value is a list of items, which may have various type(s). 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.)

Definition at line 435 of file io_cbor.cc.

◆ open_map()

QCBORDecodeContext * satcat5::cbor::ListReader::open_map ( ) const

Read a nested dictionary from the List.

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

Definition at line 452 of file io_cbor.cc.

◆ 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

Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ ListReader() [1/2]

◆ ListReader() [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()