Detailed Description

template<unsigned SIZE = SATCAT5_QCBOR_BUFFER>
class satcat5::cbor::ListReaderStatic< SIZE >

ListReader variant with a statically-allocated buffer.

Most users should instantiate this instead of ListReader. Optional template parameter specifies buffer size.

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

#include <io_cbor.h>

Inheritance diagram for satcat5::cbor::ListReaderStatic< SIZE >:

[legend]

Collaboration diagram for satcat5::cbor::ListReaderStatic< SIZE >:

[legend]

Public Member Functions
	ListReaderStatic (satcat5::io::Readable *src)
	Create this object and copy from a source io::Readable. 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
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.

Private Attributes
QCBORDecodeContext	m_cbor

u8	m_raw [SIZE]

Constructor & Destructor Documentation

◆ ListReaderStatic()

template<unsigned SIZE = SATCAT5_QCBOR_BUFFER>

satcat5::cbor::ListReaderStatic< SIZE >::ListReaderStatic ( satcat5::io::Readable * src )

inlineexplicit

Create this object and copy from a source io::Readable.

Parameters

src	Readable source to decode.

Definition at line 799 of file io_cbor.h.

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

inherited

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

inlineinherited

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

inherited

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

inlineinherited

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

inherited

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

inlineinherited

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

inherited

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

inherited

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

inherited

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

inherited

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 file:

io_cbor.h

Detailed Description

template<unsigned SIZE = SATCAT5_QCBOR_BUFFER> class satcat5::cbor::ListReaderStatic< SIZE >

Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Protected Attributes

Private Attributes

Constructor & Destructor Documentation

◆ ListReaderStatic()

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<unsigned SIZE = SATCAT5_QCBOR_BUFFER>
class satcat5::cbor::ListReaderStatic< SIZE >