Detailed Description

Write a series of consecutive items to a CBOR message.

See also: satcat5::ListWriterStatic, satcat5::cbor::MapWriter

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

#include <io_cbor.h>

Inheritance diagram for satcat5::cbor::ListWriter:

[legend]

Collaboration diagram for satcat5::cbor::ListWriter:

[legend]

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

QCBOREncodeContext *	open_list ()
	Add a nested list to the List. More...

QCBOREncodeContext *	open_map ()
	Add a nested dictionary to the List. More...

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

void	add_null () 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 (bool value) const
	Write a scalar value to the List.

void	add_item (s8 value) const
	Write a scalar value to the List.

void	add_item (s16 value) const
	Write a scalar value to the List.

void	add_item (s32 value) const
	Write a scalar value to the List.

void	add_item (s64 value) const
	Write a scalar value to the List.

void	add_item (u8 value) const
	Write a scalar value to the List.

void	add_item (u16 value) const
	Write a scalar value to the List.

void	add_item (u32 value) const
	Write a scalar value to the List.

void	add_item (u64 value) const
	Write a scalar value to the List.

void	add_item (float value) const
	Write a scalar value to the List.

void	add_item (double value) const
	Write a scalar value to the List.


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

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

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

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

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

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

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

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

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

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

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


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

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

Public Attributes
QCBOREncodeContext *const	cbor
	QCBOR context pointer.

Protected Member Functions
	ListWriter (satcat5::io::Writeable dst, QCBOREncodeContext encode, u8 *buff, unsigned size)
	Constructor requires child class to provide a working buffer. More...

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

◆ ListWriter()

satcat5::cbor::ListWriter::ListWriter	(	satcat5::io::Writeable *	dst,
		QCBOREncodeContext *	encode,
		u8 *	buff,
		unsigned	size
	)

inlineprotected

Constructor requires child class to provide a working buffer.

This constructor is protected for use by child objects only.

See also: CborWriter, ListWriterStatic.

Parameters

dst	Writeable destination, or NULL if child classes will access the buffer directly after `close()`.
encode	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.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::ListWriter::open_list ( )

Add a nested list to the List.

See also: close_list. This allows creation of a sub-item containing an array or list of items with various type(s). The user should call open_list(), write value(s) as desired, then call close_map().

Definition at line 143 of file io_cbor.cc.

◆ open_map()

QCBOREncodeContext * satcat5::cbor::ListWriter::open_map ( )

Add a nested dictionary to the List.

See also: close_map. Append a self-contained key/value dictionary. The user should call open_map(), write key/value pairs, then call close_map().

Definition at line 161 of file io_cbor.cc.

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