Detailed Description

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

Write a series of key-value pairs to 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.). Appending multiple of these together is out of the CBOR specification and is a CBOR Sequence (CBORSEQ) defined in a separate specification, so only one map may be written with this class. 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.

Note: Virtual inheritance is used here to allow APIs with mixed integer and string keys, such as net::TelemetryCbor.

See also: satcat5::cbor::MapWriterStatic, satcat5::cbor::ListWriter

Creates an ephemeral writer for the Concise Binary Object Representation (CBOR, IETF RFC8949), holding underlying objects and adapting output to an io::Writeable destination. This writer wraps the QCBOR library into a more familiar interface that performs stack buffer allocation and io::Writeable handling automatically. Since CBOR key/value pairs and arrays require a length prefix, QCBOR requires a working buffer to hold the in-progress object, which is stack-allocated with size SATCAT5_QCBOR_BUFFER.

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

Usage:

Create a CborWriter object attached to any io::Writeable sink.
Use member functions of a child class such as cbor::ListWriter or cbor::MapWriter to write a valid CBOR Map object.
For any edge cases, use QCBOREncode_* functions with the given QCBOR context cbor.
Call close() or close_and_finalize() to validate the CBOR object and optionally write it to the io::Writeable sink if valid.
If close() was called instead of close_and_finalize(), write any remaining bytes (not typical) and call io::Writeable::write_finalize().

Most users should instantiate CborMapWriterStatic instead of this to perform all stack buffer allocation.

See also: satcat5::cbor::ListWriter, satcat5::cbor::MapWriter.

Definition at line 302 of file io_cbor.h.

#include <io_cbor.h>

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

[legend]

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

[legend]

Public Member Functions
constexpr	MapWriter (QCBOREncodeContext *encode)
	Create a MapWriter from an existing encoder context.

QCBOREncodeContext *	open_list (KEYTYPE key)
	Add a list to the Map. More...

QCBOREncodeContext *	open_map (KEYTYPE key)
	Add a nested dictionary to the Map. More...

void	add_string (KEYTYPE key, const char *value) const
	Write a null-terminated string to the Map.

void	add_null (KEYTYPE key) const
	Write a key with a null value to the Map.

QCBOREncodeContext *	open_list (s64 key)

QCBOREncodeContext *	open_list (const char *key)

QCBOREncodeContext *	open_map (s64 key)

QCBOREncodeContext *	open_map (const char *key)

bool	close ()
	Close the QCBOR encoder by calling `QCBOREncode_Finish` and copy the resulting bytes to `m_dst`, if one was provided.

bool	close_and_finalize ()
	Calls `close()` then `m_dst.write_finalize()`.

UsefulBufC	get_encoded ()
	Get encoded data as a UsefulBuf, useful if no `dst` was given. More...

satcat5::io::Readable *	get_buffer ()
	Get encoded data as a Readable, useful if no `dst` was given. More...

void	close_list ()
	Finish writing a list to the List. More...

void	close_map ()
	Finish writing a nested dictionary to the Map. More...


void	add_bool (KEYTYPE key, bool value) const
	Write a scalar value to the Map.

void	add_item (KEYTYPE key, s8 value) const
	Write a scalar value to the Map.

void	add_item (KEYTYPE key, s16 value) const
	Write a scalar value to the Map.

void	add_item (KEYTYPE key, s32 value) const
	Write a scalar value to the Map.

void	add_item (KEYTYPE key, s64 value) const
	Write a scalar value to the Map.

void	add_item (KEYTYPE key, u8 value) const
	Write a scalar value to the Map.

void	add_item (KEYTYPE key, u16 value) const
	Write a scalar value to the Map.

void	add_item (KEYTYPE key, u32 value) const
	Write a scalar value to the Map.

void	add_item (KEYTYPE key, u64 value) const
	Write a scalar value to the Map.

void	add_item (KEYTYPE key, float value) const
	Write a scalar value to the Map.

void	add_item (KEYTYPE key, double value) const
	Write a scalar value to the Map.


void	add_array (KEYTYPE key, u32 len, const bool *value) const
	Write an array of scalar values to the Map.

void	add_array (KEYTYPE key, u32 len, const s8 *value) const
	Write an array of scalar values to the Map.

void	add_array (KEYTYPE key, u32 len, const s16 *value) const
	Write an array of scalar values to the Map.

void	add_array (KEYTYPE key, u32 len, const s32 *value) const
	Write an array of scalar values to the Map.

void	add_array (KEYTYPE key, u32 len, const s64 *value) const
	Write an array of scalar values to the Map.

void	add_array (KEYTYPE key, u32 len, const u8 *value) const
	Write an array of scalar values to the Map.

void	add_array (KEYTYPE key, u32 len, const u16 *value) const
	Write an array of scalar values to the Map.

void	add_array (KEYTYPE key, u32 len, const u32 *value) const
	Write an array of scalar values to the Map.

void	add_array (KEYTYPE key, u32 len, const u64 *value) const
	Write an array of scalar values to the Map.

void	add_array (KEYTYPE key, u32 len, const float *value) const
	Write an array of scalar values to the Map.

void	add_array (KEYTYPE key, u32 len, const double *value) const
	Write an array of scalar values to the Map.


void	add_bytes (KEYTYPE key, u32 len, const u8 *value) const
	Write a byte sequence to the Map.

void	add_bytes (KEYTYPE key, const u8 *value, u32 len) const
	Write a byte sequence to the Map.

Public Attributes
QCBOREncodeContext *const	cbor
	QCBOR context pointer.

Protected Member Functions
	MapWriter ()
	Placeholder constructor with no side-effects. More...

void	add_key (KEYTYPE key) const
	Templated function to write the correct key type to the Map.

void	add_key (s64 key) const

void	add_key (const char *key) const

template<typename T >
void	add_unsigned_array (unsigned len, const T *value) const
	Templated function to add an array of unsigned values.

template<typename T >
void	add_signed_array (unsigned len, const T *value) const
	Templated function to add an array of signed values.

Protected Attributes
satcat5::io::Writeable *const	m_dst
	Writeable sink.

const u8 *	m_encoded
	Encoded data.

unsigned	m_encoded_len
	Encoded length.

u8	m_auto_close
	Auto-close QCBOR Type.

satcat5::io::ArrayRead	m_read
	Reads working buffer.

Constructor & Destructor Documentation

◆ MapWriter()

template<typename KEYTYPE = const char*>

satcat5::cbor::MapWriter< KEYTYPE >::MapWriter ( )

inlineprotected

Placeholder constructor with no side-effects.

This method should be used for virtual inheritance ONLY. Since this class has no internal members, it requires no arguments. Due to virtual inheritance, the placeholder call to the parent constructor (CborWriter) is never actually used. The child class should create CborWriter with automap = true.

Definition at line 392 of file io_cbor.h.

Member Function Documentation

◆ close_list()

void satcat5::cbor::CborWriter::close_list ( )

inlineinherited

Finish writing a list to the List.

When closing a List, the caller may use the original object that opened it or another CborWriter derived from the same context.

See also: ListWriter::open_list, MapWriter::open_list.

Definition at line 113 of file io_cbor.h.

◆ close_map()

void satcat5::cbor::CborWriter::close_map ( )

inlineinherited

Finish writing a nested dictionary to the Map.

When closing a Map, the caller may use the original object that opened it or another CborWriter derived from the same context.

See also: ListWriter::open_map, MapWriter::open_map.

Definition at line 120 of file io_cbor.h.

◆ get_buffer()

Readable * satcat5::cbor::CborWriter::get_buffer ( )

inherited

Get encoded data as a Readable, useful if no dst was given.

Automatically calls close() if the buffer is still open.

Definition at line 56 of file io_cbor.cc.

◆ get_encoded()

UsefulBufC satcat5::cbor::CborWriter::get_encoded ( )

inherited

Get encoded data as a UsefulBuf, useful if no dst was given.

Automatically calls close() if the buffer is still open.

Definition at line 51 of file io_cbor.cc.

◆ open_list()

template<typename KEYTYPE = const char*>

QCBOREncodeContext* satcat5::cbor::MapWriter< KEYTYPE >::open_list ( KEYTYPE key )

Add a list to the Map.

See also: CborWriter::close_list. This allows creation of a key where the associated value is is an array or list of items with various type(s). The user should call open_list(), write values, then call close_map().

◆ open_map()

template<typename KEYTYPE = const char*>

QCBOREncodeContext* satcat5::cbor::MapWriter< KEYTYPE >::open_map ( KEYTYPE key )

Add a nested dictionary to the Map.

See also: CborWriter::close_map. This allows creation of a key where the associated value is is a self-contained key/value dictionary. The user should call open_map(), write key/value pairs, then call close_map().

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

Detailed Description

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

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ MapWriter()

Member Function Documentation

◆ close_list()

◆ close_map()

◆ get_buffer()

◆ get_encoded()

◆ open_list()

◆ open_map()

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