satcat5::cbor::MapWriterStatic< KEYTYPE, SIZE > Class Template Reference

Detailed Description

template<typename KEYTYPE = const char*, unsigned SIZE = SATCAT5_QCBOR_BUFFER>
class satcat5::cbor::MapWriterStatic< KEYTYPE, SIZE >

MapWriter variant with a statically-allocated buffer.

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

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

#include <io_cbor.h>

Inheritance diagram for satcat5::cbor::MapWriterStatic< KEYTYPE, SIZE >:

Collaboration diagram for satcat5::cbor::MapWriterStatic< KEYTYPE, SIZE >:

Public Member Functions
	MapWriterStatic (satcat5::io::Writeable *dst=nullptr)
	Create this object and set the destination. More...
QCBOREncodeContext *	open_list (const char * key)
	Add a list to the Map. More...
QCBOREncodeContext *	open_list (s64 key)
QCBOREncodeContext *	open_list (const char *key)
QCBOREncodeContext *	open_map (const char * key)
	Add a nested dictionary to the Map. More...
QCBOREncodeContext *	open_map (s64 key)
QCBOREncodeContext *	open_map (const char *key)
void	add_string (const char * key, const char *value) const
	Write a null-terminated string to the Map.
void	add_null (const char * key) const
	Write a key with a null value to the Map.
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 (const char * key, bool value) const
	Write a scalar value to the Map.
void	add_item (const char * key, s8 value) const
	Write a scalar value to the Map.
void	add_item (const char * key, s16 value) const
	Write a scalar value to the Map.
void	add_item (const char * key, s32 value) const
	Write a scalar value to the Map.
void	add_item (const char * key, s64 value) const
	Write a scalar value to the Map.
void	add_item (const char * key, u8 value) const
	Write a scalar value to the Map.
void	add_item (const char * key, u16 value) const
	Write a scalar value to the Map.
void	add_item (const char * key, u32 value) const
	Write a scalar value to the Map.
void	add_item (const char * key, u64 value) const
	Write a scalar value to the Map.
void	add_item (const char * key, float value) const
	Write a scalar value to the Map.
void	add_item (const char * key, double value) const
	Write a scalar value to the Map.
void	add_array (const char * key, u32 len, const bool *value) const
	Write an array of scalar values to the Map.
void	add_array (const char * key, u32 len, const s8 *value) const
	Write an array of scalar values to the Map.
void	add_array (const char * key, u32 len, const s16 *value) const
	Write an array of scalar values to the Map.
void	add_array (const char * key, u32 len, const s32 *value) const
	Write an array of scalar values to the Map.
void	add_array (const char * key, u32 len, const s64 *value) const
	Write an array of scalar values to the Map.
void	add_array (const char * key, u32 len, const u8 *value) const
	Write an array of scalar values to the Map.
void	add_array (const char * key, u32 len, const u16 *value) const
	Write an array of scalar values to the Map.
void	add_array (const char * key, u32 len, const u32 *value) const
	Write an array of scalar values to the Map.
void	add_array (const char * key, u32 len, const u64 *value) const
	Write an array of scalar values to the Map.
void	add_array (const char * key, u32 len, const float *value) const
	Write an array of scalar values to the Map.
void	add_array (const char * key, u32 len, const double *value) const
	Write an array of scalar values to the Map.
void	add_bytes (const char * key, u32 len, const u8 *value) const
	Write a byte sequence to the Map.
void	add_bytes (const char * 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
void	add_key (const char * 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.

Private Attributes
QCBOREncodeContext	m_cbor
u8	m_raw [SIZE]

Constructor & Destructor Documentation

MapWriterStatic()

template<typename KEYTYPE = const char*, unsigned SIZE = SATCAT5_QCBOR_BUFFER>

satcat5::cbor::MapWriterStatic< KEYTYPE, SIZE >::MapWriterStatic ( satcat5::io::Writeable *  dst = nullptr )

inlineexplicit

Create this object and set the destination.

Parameters

dst	Writeable destination, or NULL if child classes will access the buffer directly after close().

Definition at line 428 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()

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

inherited

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

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

inherited

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

• io_cbor.h