satcat5::cbor::CborWriter Class Reference

Detailed Description

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

#include <io_cbor.h>

Inheritance diagram for satcat5::cbor::CborWriter:

Collaboration diagram for satcat5::cbor::CborWriter:

Public Member Functions
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...

Public Attributes
QCBOREncodeContext *const	cbor
	QCBOR context pointer.

Protected Member Functions
	CborWriter (satcat5::io::Writeable *dst, QCBOREncodeContext *encode, u8 *buff, unsigned size, bool automap=false)
	Constructor requires child class to provide a working buffer. More...
constexpr	CborWriter (QCBOREncodeContext *encode)
	Create a CborWriter from an existing encoder context. More...
	CborWriter (const CborWriter &other)=delete
CborWriter &	operator= (const CborWriter &other)=delete
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

CborWriter() [1/2]

satcat5::cbor::CborWriter::CborWriter ( satcat5::io::Writeable *  dst, QCBOREncodeContext *  encode, u8 *  buff, unsigned  size, bool  automap = false  )

protected

Constructor requires child class to provide a working buffer.

This constructor is protected for use by child objects only.

See also

ListWriterStatic, MapWriterStatic.

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.
automap	Open/close a top-level Map automatically.

Note: automap is necessary in the base class due to the potential existence of multiple templated MapWriter classes.

Definition at line 19 of file io_cbor.cc.

CborWriter() [2/2]

constexpr satcat5::cbor::CborWriter::CborWriter ( QCBOREncodeContext *  encode )

inlineexplicitconstexprprotected

Create a CborWriter from an existing encoder context.

This constructor is protected for use by child objects only.

See also

ListWriter, MapWriter.

Definition at line 149 of file io_cbor.h.

Member Function Documentation

close_list()

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

inline

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

inline

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

(

)

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

(

)

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.

---

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

• io_cbor.h
• io_cbor.cc