QCborStreamReader Class Reference

\inmodule QtCore\reentrant More...

#include <qcborstreamreader.h>

Collaboration diagram for QCborStreamReader:

Classes
class	StringResult
	\inmodule QtCore More...

Public Types
enum	Type : quint8 {   UnsignedInteger = 0x00 , NegativeInteger = 0x20 , ByteString = 0x40 , ByteArray = ByteString ,   TextString = 0x60 , String = TextString , Array = 0x80 , Map = 0xa0 ,   Tag = 0xc0 , SimpleType = 0xe0 , HalfFloat = 0xf9 , Float16 = HalfFloat ,   Float = 0xfa , Double = 0xfb , Invalid = 0xff }
	This enumeration contains all possible CBOR types as decoded by QCborStreamReader. More...
enum	StringResultCode { EndOfString = 0 , Ok = 1 , Error = -1 }
	This enum is returned by readString() and readByteArray() and is used to indicate what the status of the parsing is. More...

Public Member Functions
	QCborStreamReader ()
	Creates a QCborStreamReader object with no source data.
	QCborStreamReader (const char *data, qsizetype len)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Creates a QCborStreamReader object with len bytes of data starting at data.
	QCborStreamReader (const quint8 *data, qsizetype len)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Creates a QCborStreamReader object with len bytes of data starting at data.
	QCborStreamReader (const QByteArray &data)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Creates a QCborStreamReader object that will parse the CBOR stream found in data.
	QCborStreamReader (QIODevice *device)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Creates a QCborStreamReader object that will parse the CBOR stream found by reading from device.
	~QCborStreamReader ()
	Destroys this QCborStreamReader object and frees any associated resources.
void	setDevice (QIODevice *device)
	Sets the source of data to device, resetting the decoder to its initial state.
QIODevice *	device () const
	Returns the QIODevice that was set with either setDevice() or the QCborStreamReader constructor.
void	addData (const QByteArray &data)
	Adds data to the CBOR stream and reparses the current element.
void	addData (const char *data, qsizetype len)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Adds len bytes of data starting at data to the CBOR stream and reparses the current element.
void	addData (const quint8 *data, qsizetype len)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Adds len bytes of data starting at data to the CBOR stream and reparses the current element.
void	reparse ()
	Reparses the current element.
void	clear ()
	Clears the decoder state and resets the input source data to an empty byte array.
void	reset ()
	Resets the source back to the beginning and clears the decoder state.
QCborError	lastError ()
	Returns the last error in decoding the stream, if any.
qint64	currentOffset () const
	Returns the offset in the input stream of the item currently being decoded.
bool	isValid () const
	Returns true if the current element is valid, false otherwise.
int	containerDepth () const
	Returns the number of containers that this stream has entered with enterContainer() but not yet left.
QCborStreamReader::Type	parentContainerType () const
	Returns either QCborStreamReader::Array or QCborStreamReader::Map, indicating whether the container that contains the current item was an array or map, respectively.
bool	hasNext () const noexcept Q_DECL_PURE_FUNCTION
	Returns true if there are more items to be decoded in the current container or false of we've reached its end.
bool	next (int maxRecursion=10000)
	Advance the CBOR stream decoding one element.
Type	type () const
	\variable QCborStreamReader::StringResult::data
bool	isUnsignedInteger () const
	Returns true if the type of the current element is an unsigned integer (that is if type() returns QCborStreamReader::UnsignedInteger).
bool	isNegativeInteger () const
	Returns true if the type of the current element is a negative integer (that is if type() returns QCborStreamReader::NegativeInteger).
bool	isInteger () const
	Returns true if the type of the current element is either an unsigned integer or a negative one (that is, if type() returns QCborStreamReader::UnsignedInteger or QCborStreamReader::NegativeInteger).
bool	isByteArray () const
	Returns true if the type of the current element is a byte array (that is, if type() returns QCborStreamReader::ByteArray).
bool	isString () const
	Returns true if the type of the current element is a text string (that is, if type() returns QCborStreamReader::String).
bool	isArray () const
	Returns true if the type of the current element is an array (that is, if type() returns QCborStreamReader::Array).
bool	isMap () const
	Returns true if the type of the current element is a map (that is, if type() returns QCborStreamReader::Map).
bool	isTag () const
	Returns true if the type of the current element is a CBOR tag (that is, if type() returns QCborStreamReader::Tag).
bool	isSimpleType () const
	Returns true if the type of the current element is any CBOR simple type, including a boolean value (true and false) as well as null and undefined.
bool	isFloat16 () const
	Returns true if the type of the current element is an IEEE 754 half-precision floating point (that is, if type() returns QCborStreamReader::Float16).
bool	isFloat () const
	Returns true if the type of the current element is an IEEE 754 single-precision floating point (that is, if type() returns QCborStreamReader::Float).
bool	isDouble () const
	Returns true if the type of the current element is an IEEE 754 double-precision floating point (that is, if type() returns QCborStreamReader::Double).
bool	isInvalid () const
	Returns true if the current element is invalid, false otherwise.
bool	isSimpleType (QCborSimpleType st) const
	Returns true if the type of the current element is the simple type st, false otherwise.
bool	isFalse () const
	Returns true if the current element is the false value, false if it is anything else.
bool	isTrue () const
	Returns true if the current element is the true value, false if it is anything else.
bool	isBool () const
	Returns true if the current element is a boolean value (true or false), false if it is anything else.
bool	isNull () const
	Returns true if the current element is the null value, false if it is anything else.
bool	isUndefined () const
	Returns true if the current element is the undefined value, false if it is anything else.
bool	isLengthKnown () const noexcept Q_DECL_PURE_FUNCTION
	Returns true if the length of the current array, map, byte array or string is known (explicit in the CBOR stream), false otherwise.
quint64	length () const
	Returns the length of the string or byte array, or the number of items in an array or the number, of item pairs in a map, if known.
bool	isContainer () const
	Returns true if the current element is a container (that is, an array or a map), false if it is anything else.
bool	enterContainer ()
	Enters the array or map that is the current item and prepares for iterating the elements contained in the container.
bool	leaveContainer ()
	Leaves the array or map whose items were being processed and positions the decoder at the next item after the end of the container.
StringResult< QString >	readString ()
	Decodes one string chunk from the CBOR string and returns it.
StringResult< QByteArray >	readByteArray ()
	Decodes one byte array chunk from the CBOR string and returns it.
qsizetype	currentStringChunkSize () const
	Returns the size of the current text or byte string chunk.
StringResult< qsizetype >	readStringChunk (char *ptr, qsizetype maxlen)
	Reads the current string chunk into the buffer pointed to by ptr, whose size is maxlen.
bool	toBool () const
	Returns the boolean value of the current element.
QCborTag	toTag () const
	Returns the tag value of the current element.
quint64	toUnsignedInteger () const
	Returns the unsigned integer value of the current element.
QCborNegativeInteger	toNegativeInteger () const
	Returns the negative integer value of the current element.
QCborSimpleType	toSimpleType () const
	Returns value of the current simple type.
qfloat16	toFloat16 () const
	Returns the 16-bit half-precision floating point value of the current element.
float	toFloat () const
	Returns the 32-bit single-precision floating point value of the current element.
double	toDouble () const
	Returns the 64-bit double-precision floating point value of the current element.
qint64	toInteger () const
	Returns the integer value of the current element, be it negative, positive or zero.

Friends
class	QCborContainerPrivate

Detailed Description

\inmodule QtCore

\reentrant

Since

5.12

The QCborStreamReader class is a simple CBOR stream decoder, operating on either a QByteArray or QIODevice.

This class can be used to decode a stream of CBOR content directly from either a QByteArray or a QIODevice. CBOR is the Concise Binary Object Representation, a very compact form of binary data encoding that is compatible with JSON. It was created by the IETF Constrained RESTful Environments (CoRE) WG, which has used it in many new RFCs. It is meant to be used alongside the \l{RFC 7252}{CoAP protocol}.

QCborStreamReader provides a StAX-like API, similar to that of \l{QXmlStreamReader}. Using it requires a bit of knowledge of CBOR encoding. For a simpler API, see \l{QCborValue} and especially the decoding function QCborValue::fromCbor().

Typically, one creates a QCborStreamReader by passing the source QByteArray or QIODevice as a parameter to the constructor, then pop elements off the stream if there were no errors in decoding. There are three kinds of CBOR types:

\table \header

• Kind
• Types
• Behavior \row
• Fixed-width
• Integers, Tags, Simple types, Floating point
• Value is pre-parsed by QCborStreamReader, so accessor functions are const. Must call next() to advance. \row
• Strings
• Byte arrays, Text strings
• Length (if known) is pre-parsed, but the string itself is not. The accessor functions are not const and may allocate memory. Once called, the accessor functions automatically advance to the next element. \row
• Containers
• Arrays, Maps
• Length (if known) is pre-parsed. To access the elements, you must call enterContainer(), read all elements, then call leaveContainer(). That function advances to the next element. \endtable

So a processor function typically looks like this:

   void handleStream(QCborStreamReader &reader)
   {
       switch (reader.type())
       case QCborStreamReader::UnsignedInteger:
       case QCborStreamReader::NegativeInteger:
       case QCborStreamReader::SimpleType:
       case QCborStreamReader::Float16:
       case QCborStreamReader::Float:
       case QCborStreamReader::Double:
           handleFixedWidth(reader);
           reader.next();
           break;
       case QCborStreamReader::ByteArray:
       case QCborStreamReader::String:
           handleString(reader);
           break;
       case QCborStreamReader::Array:
       case QCborStreamReader::Map:
           reader.enterContainer();
           while (reader.lastError() == QCborError::NoError)
               handleStream(reader);
           if (reader.lastError() == QCborError::NoError)
               reader.leaveContainer();
       }
   }

Definition at line 27 of file qcborstreamreader.h.

Member Enumeration Documentation

StringResultCode

enum QCborStreamReader::StringResultCode

This enum is returned by readString() and readByteArray() and is used to indicate what the status of the parsing is.

\value EndOfString The parsing for the string is complete, with no error. \value Ok The function returned data; there was no error. \value Error Parsing failed with an error.

Enumerator
EndOfString
Ok
Error

Definition at line 51 of file qcborstreamreader.h.

Type

enum QCborStreamReader::Type : quint8

This enumeration contains all possible CBOR types as decoded by QCborStreamReader.

CBOR has 7 major types, plus a number of simple types carrying no value, and floating point values.

\value UnsignedInteger (Major type 0) Ranges from 0 to 2\sup{64} - 1 (18,446,744,073,709,551,616) \value NegativeInteger (Major type 1) Ranges from -1 to -2\sup{64} (-18,446,744,073,709,551,616) \value ByteArray (Major type 2) Arbitrary binary data. \value ByteString An alias to ByteArray. \value String (Major type 3) Unicode text, possibly containing NULs. \value TextString An alias to String \value Array (Major type 4) Array of heterogeneous items. \value Map (Major type 5) Map/dictionary of heterogeneous items. \value Tag (Major type 6) Numbers giving further semantic value to generic CBOR items. See \l QCborTag for more information. \value SimpleType (Major type 7) Types carrying no further value. Includes booleans (true and false), null, undefined. \value Float16 IEEE 754 half-precision floating point (qfloat16). \value HalfFloat An alias to Float16. \value Float IEEE 754 single-precision floating point (\tt float). \value Double IEEE 754 double-precision floating point (\tt double). \value Invalid Not a valid type, either due to parsing error or due to reaching the end of an array or map.

Enumerator
UnsignedInteger
NegativeInteger
ByteString
ByteArray
TextString
String
Array
Map
Tag
SimpleType
HalfFloat
Float16
Float
Double
Invalid

Definition at line 31 of file qcborstreamreader.h.

Constructor & Destructor Documentation

QCborStreamReader() [1/5]

QCborStreamReader::QCborStreamReader

(

)

Creates a QCborStreamReader object with no source data.

After construction, QCborStreamReader will report an error parsing.

You can add more data by calling addData() or by setting a different source device using setDevice().

See also

addData(), isValid()

Definition at line 754 of file qcborstreamreader.cpp.

QCborStreamReader() [2/5]

QCborStreamReader::QCborStreamReader	(	const char *	data,
		qsizetype	len
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Creates a QCborStreamReader object with len bytes of data starting at data.

The pointer must remain valid until QCborStreamReader is destroyed.

Definition at line 765 of file qcborstreamreader.cpp.

QCborStreamReader() [3/5]

QCborStreamReader::QCborStreamReader	(	const quint8 *	data,
		qsizetype	len
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Creates a QCborStreamReader object with len bytes of data starting at data.

The pointer must remain valid until QCborStreamReader is destroyed.

Definition at line 776 of file qcborstreamreader.cpp.

QCborStreamReader() [4/5]

QCborStreamReader::QCborStreamReader ( const QByteArray &  data )

explicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Creates a QCborStreamReader object that will parse the CBOR stream found in data.

Definition at line 787 of file qcborstreamreader.cpp.

QCborStreamReader() [5/5]

QCborStreamReader::QCborStreamReader ( QIODevice *  device )

explicit

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Creates a QCborStreamReader object that will parse the CBOR stream found by reading from device.

QCborStreamReader does not take ownership of device, so it must remain valid until this object is destroyed.

Definition at line 800 of file qcborstreamreader.cpp.

~QCborStreamReader()

QCborStreamReader::~QCborStreamReader

(

)

Destroys this QCborStreamReader object and frees any associated resources.

Definition at line 809 of file qcborstreamreader.cpp.

Member Function Documentation

addData() [1/3]

void QCborStreamReader::addData	(	const char *	data,
		qsizetype	len
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Adds len bytes of data starting at data to the CBOR stream and reparses the current element.

This function is useful if the end of the data was previously reached while processing the stream, but now more data is available.

Definition at line 861 of file qcborstreamreader.cpp.

References QByteArray::append(), QCborStreamReaderPrivate::buffer, QCborStreamReaderPrivate::device, qWarning, and reparse().

Here is the call graph for this function:

addData() [2/3]

void QCborStreamReader::addData

(

const QByteArray &

data

)

Adds data to the CBOR stream and reparses the current element.

This function is useful if the end of the data was previously reached while processing the stream, but now more data is available.

Definition at line 838 of file qcborstreamreader.cpp.

References addData().

Referenced by addData().

Here is the call graph for this function:

Here is the caller graph for this function:

addData() [3/3]

void QCborStreamReader::addData ( const quint8 *  data, qsizetype  len  )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Adds len bytes of data starting at data to the CBOR stream and reparses the current element.

This function is useful if the end of the data was previously reached while processing the stream, but now more data is available.

Definition at line 74 of file qcborstreamreader.h.

clear()

void QCborStreamReader::clear

(

)

Clears the decoder state and resets the input source data to an empty byte array.

After this function is called, QCborStreamReader will be indicating an error parsing.

Call addData() to add more data to be parsed.

See also

reset(), setDevice()

Definition at line 899 of file qcborstreamreader.cpp.

References setDevice().

Here is the call graph for this function:

containerDepth()

int QCborStreamReader::containerDepth

(

)

const

Returns the number of containers that this stream has entered with enterContainer() but not yet left.

See also

enterContainer(), leaveContainer()

Definition at line 956 of file qcborstreamreader.cpp.

References QCborStreamReaderPrivate::containerStack, and QList< T >::size().

Here is the call graph for this function:

currentOffset()

qint64 QCborStreamReader::currentOffset

(

)

const

Returns the offset in the input stream of the item currently being decoded.

The current offset is the number of decoded bytes so far only if the source data is a QByteArray or it is a QIODevice that was positioned at its beginning when decoding started.

See also

reset(), clear(), device()

Definition at line 945 of file qcborstreamreader.cpp.

References QCborStreamReaderPrivate::bufferStart, QCborStreamReaderPrivate::device, and QIODevice::pos().

Here is the call graph for this function:

currentStringChunkSize()

qsizetype QCborStreamReader::currentStringChunkSize ( ) const

inline

Returns the size of the current text or byte string chunk.

If the CBOR stream contains a non-chunked string (that is, if isLengthKnown() returns true), this function returns the size of the entire string, the same as length().

This function is useful to pre-allocate the buffer whose pointer can be passed to readStringChunk() later.

See also

readString(), readByteArray(), readStringChunk()

Definition at line 122 of file qcborstreamreader.h.

References Q_ASSERT.

device()

QIODevice * QCborStreamReader::device

(

)

const

Returns the QIODevice that was set with either setDevice() or the QCborStreamReader constructor.

If this object was reading from a QByteArray, this function returns nullptr instead.

Definition at line 828 of file qcborstreamreader.cpp.

References QCborStreamReaderPrivate::device.

Referenced by setDevice().

Here is the caller graph for this function:

enterContainer()

bool QCborStreamReader::enterContainer ( )

inline

Enters the array or map that is the current item and prepares for iterating the elements contained in the container.

Returns true if entering the container succeeded, false otherwise (usually, a parsing error). Each call to enterContainer() must be paired with a call to leaveContainer().

This function may only be called if the current item is an array or a map (that is, if isArray(), isMap() or isContainer() is true). Calling it in any other condition is an error.

See also

leaveContainer(), isContainer(), isArray(), isMap()

Definition at line 117 of file qcborstreamreader.h.

References Q_ASSERT.

Referenced by next().

Here is the caller graph for this function:

hasNext()

bool QCborStreamReader::hasNext ( ) const

noexcept

Returns true if there are more items to be decoded in the current container or false of we've reached its end.

If we're parsing the root element, hasNext() returning false indicates the parsing is complete; otherwise, if the container depth is non-zero, then the outer code needs to call leaveContainer().

See also

parentContainerType(), containerDepth(), leaveContainer()

Definition at line 985 of file qcborstreamreader.cpp.

References QCborStreamReaderPrivate::currentElement.

Referenced by next().

Here is the caller graph for this function:

isArray()

bool QCborStreamReader::isArray ( ) const

inline

Returns true if the type of the current element is an array (that is, if type() returns QCborStreamReader::Array).

If this function returns true, you may call enterContainer() to begin parsing that container.

When the current element is an array, you may also call isLengthKnown() to find out if the array's size is explicit in the CBOR stream. If it is, that size can be obtained by calling length().

The following example pre-allocates a QVariantList given the array's size for more efficient decoding:

   QVariantList populateFromCbor(QCborStreamReader &reader)
   {
       QVariantList list;
       if (reader.isLengthKnown())
           list.reserve(reader.length());
 
       reader.enterContainer();
       while (reader.lastError() == QCborError::NoError && reader.hasNext())
           list.append(readOneElement(reader));
       if (reader.lastError() == QCborError::NoError)
           reader.leaveContainer();
   }

Note

The code above does not validate that the length is a sensible value. If the input stream reports that the length is 1 billion elements, the above function will try to allocate some 16 GB or more of RAM, which can lead to a crash.

See also

type(), isMap(), isLengthKnown(), length(), enterContainer(), leaveContainer()

Definition at line 97 of file qcborstreamreader.h.

isBool()

bool QCborStreamReader::isBool ( ) const

inline

Returns true if the current element is a boolean value (true or false), false if it is anything else.

If this function returns true, you may call toBool() to retrieve the value of the boolean. You may also call toSimpleType() and compare to either QCborSimpleValue::True or QCborSimpleValue::False.

See also

type(), isFalse(), isTrue(), toBool(), isSimpleType(), toSimpleType()

Definition at line 109 of file qcborstreamreader.h.

isByteArray()

bool QCborStreamReader::isByteArray ( ) const

inline

Returns true if the type of the current element is a byte array (that is, if type() returns QCborStreamReader::ByteArray).

If this function returns true, you may call readByteArray() to read that data.

See also

type(), readByteArray(), isString()

Definition at line 95 of file qcborstreamreader.h.

Referenced by next().

Here is the caller graph for this function:

isContainer()

bool QCborStreamReader::isContainer ( ) const

inline

Returns true if the current element is a container (that is, an array or a map), false if it is anything else.

If the current element is a container, the isLengthKnown() function may be used to find out if the container's size is explicit in the stream and, if so, length() can be used to get that size.

More importantly, for a container, the enterContainer() function is available to begin iterating through the elements contained therein.

See also

type(), isArray(), isMap(), isLengthKnown(), length(), enterContainer(), leaveContainer(), containerDepth()

Definition at line 116 of file qcborstreamreader.h.

Referenced by next().

Here is the caller graph for this function:

isDouble()

bool QCborStreamReader::isDouble ( ) const

inline

Returns true if the type of the current element is an IEEE 754 double-precision floating point (that is, if type() returns QCborStreamReader::Double).

If this function returns true, you may call toDouble() to read that data.

See also

type(), toDouble(), isFloat16(), isFloat()

Definition at line 103 of file qcborstreamreader.h.

References Double.

isFalse()

bool QCborStreamReader::isFalse ( ) const

inline

Returns true if the current element is the false value, false if it is anything else.

See also

type(), isTrue(), isBool(), toBool(), isSimpleType(), toSimpleType()

Definition at line 107 of file qcborstreamreader.h.

References False, and isSimpleType().

Here is the call graph for this function:

isFloat()

bool QCborStreamReader::isFloat ( ) const

inline

Returns true if the type of the current element is an IEEE 754 single-precision floating point (that is, if type() returns QCborStreamReader::Float).

If this function returns true, you may call toFloat() to read that data.

See also

type(), toFloat(), isFloat16(), isDouble()

Definition at line 102 of file qcborstreamreader.h.

References Float.

isFloat16()

bool QCborStreamReader::isFloat16 ( ) const

inline

Returns true if the type of the current element is an IEEE 754 half-precision floating point (that is, if type() returns QCborStreamReader::Float16).

If this function returns true, you may call toFloat16() to read that data.

See also

type(), toFloat16(), isFloat(), isDouble()

Definition at line 101 of file qcborstreamreader.h.

References Float16.

isInteger()

bool QCborStreamReader::isInteger ( ) const

inline

Returns true if the type of the current element is either an unsigned integer or a negative one (that is, if type() returns QCborStreamReader::UnsignedInteger or QCborStreamReader::NegativeInteger).

If this function returns true, you may call toInteger() to read that value.

See also

type(), toInteger(), toUnsignedInteger(), toNegativeInteger(), isUnsignedInteger(), isNegativeInteger()

Definition at line 94 of file qcborstreamreader.h.

isInvalid()

bool QCborStreamReader::isInvalid ( ) const

inline

Returns true if the current element is invalid, false otherwise.

The current element may be invalid if there was a decoding error or we've just parsed the last element in an array or map.

Note

This function is not to be confused with isNull(). Null is a normal CBOR type that must be handled by the application.

See also

type(), isValid()

Definition at line 104 of file qcborstreamreader.h.

References Invalid.

isLengthKnown()

bool QCborStreamReader::isLengthKnown ( ) const

noexcept

Returns true if the length of the current array, map, byte array or string is known (explicit in the CBOR stream), false otherwise.

This function should only be called if the element is one of those.

If the length is known, it may be obtained by calling length().

If the length of a map or an array is not known, it is implied by the number of elements present in the stream. QCborStreamReader has no API to calculate the length in that condition.

Strings and byte arrays may also have indeterminate length (that is, they may be transmitted in multiple chunks). Those cannot currently be created with QCborStreamWriter, but they could be with other encoders, so QCborStreamReader supports them.

See also

length(), QCborStreamWriter::startArray(), QCborStreamWriter::startMap()

Definition at line 1064 of file qcborstreamreader.cpp.

References QCborStreamReaderPrivate::currentElement.

Referenced by length().

Here is the caller graph for this function:

isMap()

bool QCborStreamReader::isMap ( ) const

inline

Returns true if the type of the current element is a map (that is, if type() returns QCborStreamReader::Map).

If this function returns true, you may call enterContainer() to begin parsing that container.

When the current element is a map, you may also call isLengthKnown() to find out if the map's size is explicit in the CBOR stream. If it is, that size can be obtained by calling length().

The following example pre-allocates a QVariantMap given the map's size for more efficient decoding:

   QVariantMap populateFromCbor(QCborStreamReader &reader)
   {
       QVariantMap map;
       if (reader.isLengthKnown())
           map.reserve(reader.length());
 
       reader.enterContainer();
       while (reader.lastError() == QCborError::NoError && reader.hasNext()) {
           QString key = readElementAsString(reader);
           map.insert(key, readOneElement(reader));
       }
       if (reader.lastError() == QCborError::NoError)
           reader.leaveContainer();
   }

The example above uses a function called readElementAsString to read the map's keys and obtain a string. That is because CBOR maps may contain any type as keys, not just strings. User code needs to either perform this conversion, reject non-string keys, or instead use a different container besides \l QVariantMap and \l QVariantHash. For example, if the map is expected to contain integer keys, which is recommended as it reduces stream size and parsing, the correct container would be {\l{QMap}<int, QVariant>} or {\l{QHash}<int, QVariant>}.

Note

The code above does not validate that the length is a sensible value. If the input stream reports that the length is 1 billion elements, the above function will try to allocate some 24 GB or more of RAM, which can lead to a crash.

See also

type(), isArray(), isLengthKnown(), length(), enterContainer(), leaveContainer()

Definition at line 98 of file qcborstreamreader.h.

isNegativeInteger()

bool QCborStreamReader::isNegativeInteger ( ) const

inline

Returns true if the type of the current element is a negative integer (that is if type() returns QCborStreamReader::NegativeInteger).

If this function returns true, you may call toNegativeInteger() or toInteger() to read that value.

See also

type(), toNegativeInteger(), toInteger(), isInteger(), isUnsignedInteger()

Definition at line 93 of file qcborstreamreader.h.

isNull()

bool QCborStreamReader::isNull ( ) const

inline

Returns true if the current element is the null value, false if it is anything else.

Null values may be used to indicate the absence of some optional data.

Note

This function is not the opposite of isValid(). A Null value is a valid CBOR value.

See also

type(), isSimpleType(), toSimpleType()

Definition at line 110 of file qcborstreamreader.h.

References isSimpleType(), and Null.

Here is the call graph for this function:

isSimpleType() [1/2]

bool QCborStreamReader::isSimpleType ( ) const

inline

Returns true if the type of the current element is any CBOR simple type, including a boolean value (true and false) as well as null and undefined.

To find out which simple type this is, call toSimpleType(). Alternatively, to test for one specific simple type, call the overload that takes a QCborSimpleType parameter.

CBOR simple types are types that do not carry extra value. There are 255 possibilities, but there are currently only four values that have defined meaning. Code is not expected to cope with unknown simple types and may simply discard the stream as invalid if it finds an unknown one.

See also

QCborSimpleType, type(), isSimpleType(QCborSimpleType), toSimpleType()

Definition at line 100 of file qcborstreamreader.h.

isSimpleType() [2/2]

bool QCborStreamReader::isSimpleType ( QCborSimpleType  st ) const

inline

Returns true if the type of the current element is the simple type st, false otherwise.

If this function returns true, then toSimpleType() will return st.

CBOR simple types are types that do not carry extra value. There are 255 possibilities, but there are currently only four values that have defined meaning. Code is not expected to cope with unknown simple types and may simply discard the stream as invalid if it finds an unknown one.

See also

QCborSimpleType, type(), isSimpleType(), toSimpleType()

Definition at line 106 of file qcborstreamreader.h.

References isSimpleType().

Referenced by isSimpleType().

Here is the call graph for this function:

Here is the caller graph for this function:

isString()

bool QCborStreamReader::isString ( ) const

inline

Returns true if the type of the current element is a text string (that is, if type() returns QCborStreamReader::String).

If this function returns true, you may call readString() to read that data.

See also

type(), readString(), isByteArray()

Definition at line 96 of file qcborstreamreader.h.

Referenced by next().

Here is the caller graph for this function:

isTag()

bool QCborStreamReader::isTag ( ) const

inline

Returns true if the type of the current element is a CBOR tag (that is, if type() returns QCborStreamReader::Tag).

If this function returns true, you may call toTag() to read that data.

See also

type(), toTag()

Definition at line 99 of file qcborstreamreader.h.

isTrue()

bool QCborStreamReader::isTrue ( ) const

inline

Returns true if the current element is the true value, false if it is anything else.

See also

type(), isFalse(), isBool(), toBool(), isSimpleType(), toSimpleType()

Definition at line 108 of file qcborstreamreader.h.

References isSimpleType(), and True.

Here is the call graph for this function:

isUndefined()

bool QCborStreamReader::isUndefined ( ) const

inline

Returns true if the current element is the undefined value, false if it is anything else.

Undefined values may be encoded to indicate that some conversion failed or was not possible when creating the stream. QCborStreamReader never performs any replacement and this function will only return true if the stream contains an explicit undefined value.

See also

type(), isSimpleType(), toSimpleType()

Definition at line 111 of file qcborstreamreader.h.

References isSimpleType(), and Undefined.

Here is the call graph for this function:

isUnsignedInteger()

bool QCborStreamReader::isUnsignedInteger ( ) const

inline

Returns true if the type of the current element is an unsigned integer (that is if type() returns QCborStreamReader::UnsignedInteger).

If this function returns true, you may call toUnsignedInteger() or toInteger() to read that value.

See also

type(), toUnsignedInteger(), toInteger(), isInteger(), isNegativeInteger()

Definition at line 92 of file qcborstreamreader.h.

References UnsignedInteger.

isValid()

bool QCborStreamReader::isValid ( ) const

inline

Returns true if the current element is valid, false otherwise.

The current element may be invalid if there was a decoding error or we've just parsed the last element in an array or map.

Note

This function is not the opposite of isNull(). Null is a normal CBOR type that must be handled by the application.

See also

type(), isInvalid()

Definition at line 84 of file qcborstreamreader.h.

lastError()

QCborError QCborStreamReader::lastError

(

)

Returns the last error in decoding the stream, if any.

If no error was encountered, this returns an QCborError::NoError.

See also

isValid()

Definition at line 932 of file qcborstreamreader.cpp.

References QCborStreamReaderPrivate::lastError.

Referenced by next(), and readStringChunk().

Here is the caller graph for this function:

leaveContainer()

bool QCborStreamReader::leaveContainer

(

)

Leaves the array or map whose items were being processed and positions the decoder at the next item after the end of the container.

Returns true if leaving the container succeeded, false otherwise (usually, a parsing error). Each call to enterContainer() must be paired with a call to leaveContainer().

This function may only be called if hasNext() has returned false and containerDepth() is not zero. Calling it in any other condition is an error.

See also

enterContainer(), parentContainerType(), containerDepth()

Definition at line 1138 of file qcborstreamreader.cpp.

References QCborStreamReaderPrivate::containerStack, QCborStreamReaderPrivate::corrupt, QCborStreamReaderPrivate::currentElement, QCborStreamReaderPrivate::handleError(), QList< T >::isEmpty(), QStack< T >::pop(), and qWarning.

Referenced by next().

Here is the call graph for this function:

Here is the caller graph for this function:

length()

quint64 QCborStreamReader::length

(

)

const

Returns the length of the string or byte array, or the number of items in an array or the number, of item pairs in a map, if known.

This function must not be called if the length is unknown (that is, if isLengthKnown() returned false). It is an error to do that and it will cause QCborStreamReader to stop parsing the input stream.

See also

isLengthKnown(), QCborStreamWriter::startArray(), QCborStreamWriter::startMap()

Definition at line 1078 of file qcborstreamreader.cpp.

References Array, ByteArray, QCborStreamReaderPrivate::handleError(), isLengthKnown(), Map, and String.

Here is the call graph for this function:

next()

bool QCborStreamReader::next

(

int

maxRecursion = 10000

)

Advance the CBOR stream decoding one element.

You should usually call this function when parsing fixed-width basic elements (that is, integers, simple values, tags and floating point values). But this function can be called when the current item is a string, array or map too and it will skip over that entire element, including all contained elements.

This function returns true if advancing was successful, false otherwise. It may fail if the stream is corrupt, incomplete or if the nesting level of arrays and maps exceeds maxRecursion. Calling this function when hasNext() has returned false is also an error. If this function returns false, lastError() will return the error code detailing what the failure was.

See also

lastError(), isValid(), hasNext()

Definition at line 1007 of file qcborstreamreader.cpp.

References QCborStreamReaderPrivate::currentElement, enterContainer(), QCborStreamReaderPrivate::handleError(), hasNext(), isByteArray(), isContainer(), isString(), QCborStreamReaderPrivate::lastError, lastError(), leaveContainer(), next, QCborError::NoError, Ok, readString(), and readStringChunk().

Here is the call graph for this function:

parentContainerType()

QCborStreamReader::Type QCborStreamReader::parentContainerType

(

)

const

Returns either QCborStreamReader::Array or QCborStreamReader::Map, indicating whether the container that contains the current item was an array or map, respectively.

If we're currently parsing the root element, this function returns QCborStreamReader::Invalid.

See also

containerDepth(), enterContainer()

Definition at line 969 of file qcborstreamreader.cpp.

References QCborStreamReaderPrivate::containerStack, Invalid, and QList< T >::isEmpty().

Here is the call graph for this function:

readByteArray()

QCborStreamReader::StringResult< QByteArray > QCborStreamReader::readByteArray ( )

inline

Decodes one byte array chunk from the CBOR string and returns it.

This function is used for both regular and chunked contents, so the caller must always loop around calling this function, even if isLengthKnown() has is true. The typical use of this function is as follows:

   QBytearray decodeBytearray(QCborStreamReader &reader)
   {
       QBytearray result;
       auto r = reader.readBytearray();
       while (r.code == QCborStreamReader::Ok) {
           result += r.data;
           r = reader.readByteArray();
       }
 
       if (r.code == QCborStreamReader::Error) {
           // handle error condition
           result.clear();
       }
       return result;
   }

This function does not perform any type conversions, including from integers or from strings. Therefore, it may only be called if isByteArray() is true; calling it in any other condition is an error.

See also

readString(), isByteArray(), readStringChunk()

Definition at line 121 of file qcborstreamreader.h.

References Q_ASSERT.

readString()

QCborStreamReader::StringResult< QString > QCborStreamReader::readString ( )

inline

Decodes one string chunk from the CBOR string and returns it.

This function is used for both regular and chunked string contents, so the caller must always loop around calling this function, even if isLengthKnown() has is true. The typical use of this function is as follows:

   QString decodeString(QCborStreamReader &reader)
   {
       QString result;
       auto r = reader.readString();
       while (r.code == QCborStreamReader::Ok) {
           result += r.data;
           r = reader.readString();
       }
 
       if (r.code == QCborStreamReader::Error) {
           // handle error condition
           result.clear();
       }
       return result;
   }

This function does not perform any type conversions, including from integers or from byte arrays. Therefore, it may only be called if isString() returned true; calling it in any other condition is an error.

See also

readByteArray(), isString(), readStringChunk()

Definition at line 120 of file qcborstreamreader.h.

References Q_ASSERT.

Referenced by next().

Here is the caller graph for this function:

readStringChunk()

QCborStreamReader::StringResult< qsizetype > QCborStreamReader::readStringChunk	(	char *	ptr,
		qsizetype	maxlen
	)

Reads the current string chunk into the buffer pointed to by ptr, whose size is maxlen.

This function returns a \l StringResult object, with the number of bytes copied into ptr saved in the \l StringResult::data member. The \l StringResult::status member indicates whether there was an error reading the string, whether data was copied or whether this was the last chunk.

This function can be called for both \l String and \l ByteArray types. For the latter, this function will read the same data that readByteArray() would have returned. For strings, it returns the UTF-8 equivalent of the \l QString that would have been returned.

This function is usually used alongside currentStringChunkSize() in a loop. For example:

    QCborStreamReader<qsizetype> result;
    do {
        qsizetype size = reader.currentStringChunkSize();
        qsizetype oldsize = buffer.size();
        buffer.resize(oldsize + size);
        result = reader.readStringChunk(buffer.data() + oldsize, size);
    } while (result.status() == QCborStreamReader::Ok);

Unlike readByteArray() and readString(), this function is not limited by implementation limits of QByteArray and QString.

Note

This function does not perform verification that the UTF-8 contents are properly formatted. That means this function does not produce the QCborError::InvalidUtf8String error, even when readString() does.

See also

currentStringChunkSize(), readString(), readByteArray(), isString(), isByteArray()

Definition at line 1412 of file qcborstreamreader.cpp.

References EndOfString, lastError(), QCborError::NoError, ptr(), and QCborStreamReaderPrivate::readStringChunk().

Referenced by next().

Here is the call graph for this function:

Here is the caller graph for this function:

reparse()

void QCborStreamReader::reparse

(

)

Reparses the current element.

This function must be called when more data becomes available in the source QIODevice after parsing failed due to reaching the end of the input data before the end of the CBOR stream.

When reading from QByteArray(), the addData() function automatically calls this function. Calling it when the reading had not failed is a no-op.

Definition at line 880 of file qcborstreamreader.cpp.

References QCborStreamReaderPrivate::currentElement, QCborStreamReaderPrivate::handleError(), QCborStreamReaderPrivate::lastError, and QCborStreamReaderPrivate::preread().

Referenced by addData().

Here is the call graph for this function:

Here is the caller graph for this function:

reset()

void QCborStreamReader::reset

(

)

Resets the source back to the beginning and clears the decoder state.

If the source data was a QByteArray, QCborStreamReader will restart from the beginning of the array.

If the source data is a QIODevice, this function will call QIODevice::reset(), which will seek to byte position 0. If the CBOR stream is not found at the beginning of the device (e.g., beginning of a file), then this function will likely do the wrong thing. Instead, position the QIODevice to the right offset and call setDevice().

See also

clear(), setDevice()

Definition at line 917 of file qcborstreamreader.cpp.

References QCborStreamReaderPrivate::device, QCborStreamReaderPrivate::initDecoder(), QCborStreamReaderPrivate::lastError, and QIODevice::reset().

Here is the call graph for this function:

setDevice()

void QCborStreamReader::setDevice

(

QIODevice *

device

)

Sets the source of data to device, resetting the decoder to its initial state.

Definition at line 817 of file qcborstreamreader.cpp.

References device(), and QCborStreamReaderPrivate::setDevice().

Referenced by clear().

Here is the call graph for this function:

Here is the caller graph for this function:

toBool()

bool QCborStreamReader::toBool ( ) const

inline

Returns the boolean value of the current element.

This function does not perform any type conversions, including from integer. Therefore, it may only be called if isTrue(), isFalse() or isBool() returned true; calling it in any other condition is an error.

See also

isBool(), isTrue(), isFalse(), toInteger()

Definition at line 125 of file qcborstreamreader.h.

References False, and Q_ASSERT.

toDouble()

double QCborStreamReader::toDouble ( ) const

inline

Returns the 64-bit double-precision floating point value of the current element.

This function does not perform any type conversions, including from other floating point types or from integer values. Therefore, it may only be called if isDouble() is true; calling it in any other condition is an error.

See also

isDouble(), toFloat16(), toFloat()

Definition at line 132 of file qcborstreamreader.h.

References Q_ASSERT.

toFloat()

float QCborStreamReader::toFloat ( ) const

inline

Returns the 32-bit single-precision floating point value of the current element.

This function does not perform any type conversions, including from other floating point types or from integer values. Therefore, it may only be called if isFloat() is true; calling it in any other condition is an error.

See also

isFloat(), toFloat16(), toDouble()

Definition at line 131 of file qcborstreamreader.h.

References Q_ASSERT.

toFloat16()

qfloat16 QCborStreamReader::toFloat16 ( ) const

inline

Returns the 16-bit half-precision floating point value of the current element.

This function does not perform any type conversions, including from other floating point types or from integer values. Therefore, it may only be called if isFloat16() is true; calling it in any other condition is an error.

See also

isFloat16(), toFloat(), toDouble()

Definition at line 130 of file qcborstreamreader.h.

References Q_ASSERT.

toInteger()

qint64 QCborStreamReader::toInteger ( ) const

inline

Returns the integer value of the current element, be it negative, positive or zero.

If the value is larger than 2\sup{63} - 1 or smaller than -2\sup{63}, the returned value will overflow and will have an incorrect sign. If handling those values is required, use toUnsignedInteger() or toNegativeInteger() instead.

This function does not perform any type conversions, including from boolean or CBOR tag. Therefore, it may only be called if isInteger() is true; calling it in any other condition is an error.

See also

isInteger(), toUnsignedInteger(), toNegativeInteger()

Definition at line 134 of file qcborstreamreader.h.

References Q_ASSERT.

toNegativeInteger()

QCborNegativeValue QCborStreamReader::toNegativeInteger ( ) const

inline

Returns the negative integer value of the current element.

QCborNegativeValue is a 64-bit unsigned integer containing the absolute value of the negative number that was stored in the CBOR stream. Additionally, QCborNegativeValue(0) represents the number -2\sup{64}.

This function does not perform any type conversions, including from boolean or CBOR tag. Therefore, it may only be called if isNegativeInteger() is true; calling it in any other condition is an error.

This function may be used to obtain numbers beyond the range of the return type of toInteger(). However, use of negative numbers smaller than -2\sup{63} is extremely discouraged.

See also

type(), toInteger(), isNegativeInteger(), isUnsignedInteger()

Definition at line 128 of file qcborstreamreader.h.

References Q_ASSERT.

toSimpleType()

QCborSimpleType QCborStreamReader::toSimpleType ( ) const

inline

Returns value of the current simple type.

This function does not perform any type conversions, including from integer. Therefore, it may only be called if isSimpleType() is true; calling it in any other condition is an error.

See also

isSimpleType(), isTrue(), isFalse(), isBool(), isNull(), isUndefined()

Definition at line 129 of file qcborstreamreader.h.

References isSimpleType(), and Q_ASSERT.

Here is the call graph for this function:

toTag()

QCborTag QCborStreamReader::toTag ( ) const

inline

Returns the tag value of the current element.

This function does not perform any type conversions, including from integer. Therefore, it may only be called if isTag() is true; calling it in any other condition is an error.

Tags are 64-bit numbers attached to generic CBOR types that give them further meaning. For a list of known tags, see the \l QCborKnownTags enumeration.

See also

isTag(), toInteger(), QCborKnownTags

Definition at line 126 of file qcborstreamreader.h.

References Q_ASSERT.

toUnsignedInteger()

quint64 QCborStreamReader::toUnsignedInteger ( ) const

inline

Returns the unsigned integer value of the current element.

This function does not perform any type conversions, including from boolean or CBOR tag. Therefore, it may only be called if isUnsignedInteger() is true; calling it in any other condition is an error.

This function may be used to obtain numbers beyond the range of the return type of toInteger().

See also

type(), toInteger(), isUnsignedInteger(), isNegativeInteger()

Definition at line 127 of file qcborstreamreader.h.

References Q_ASSERT.

type()

QCborStreamReader::Type QCborStreamReader::type ( ) const

inline

\variable QCborStreamReader::StringResult::data

Contains the actual data from the string if \l status is Ok.

\variable QCborStreamReader::StringResult::status

Contains the status of the attempt of reading the string from the stream.

Returns the type of the current element. It is one of the valid types or Invalid.

See also

isValid(), isUnsignedInteger(), isNegativeInteger(), isInteger(), isByteArray(), isString(), isArray(), isMap(), isTag(), isSimpleType(), isBool(), isFalse(), isTrue(), isNull(), isUndefined(), isFloat16(), isFloat(), isDouble()

Definition at line 91 of file qcborstreamreader.h.

Friends And Related Symbol Documentation

QCborContainerPrivate

friend class QCborContainerPrivate

friend

Definition at line 160 of file qcborstreamreader.h.

---

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

• qtbase/src/corelib/serialization/qcborstreamreader.h
• qtbase/src/corelib/serialization/qcborstreamreader.cpp