QCborStreamReader¶

PyQt5.QtCore.QCborStreamReader

Description¶

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 CoAP protocol.

QCborStreamReader provides a StAX-like API, similar to that of QXmlStreamReader. Using it requires a bit of knowledge of CBOR encoding. For a simpler API, see 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:

Kind	Types	Behavior
Fixed-width	Integers, Tags, Simple types, Floating point	Value is pre-parsed by QCborStreamReader, so accessor functions are `const`. Must call to advance.
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.
Containers	Arrays, Maps	Length (if known) is pre-parsed. To access the elements, you must call , read all elements, then call . That function advances to the next element.

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();
#        }
#    }

CBOR support¶

The following table lists the CBOR features that QCborStreamReader supports.

Feature	Support
Unsigned numbers	Yes (full range)
Negative numbers	Yes (full range)
Byte strings	Yes
Text strings	Yes
Chunked strings	Yes
Tags	Yes (arbitrary)
Booleans	Yes
Null	Yes
Undefined	Yes
Arbitrary simple values	Yes
Half-precision float (16-bit)	Yes
Single-precision float (32-bit)	Yes
Double-precision float (64-bit)	Yes
Infinities and NaN floating point	Yes
Determinate-length arrays and maps	Yes
Indeterminate-length arrays and maps	Yes
Map key types other than strings and integers	Yes (arbitrary)

Dealing with invalid or incomplete CBOR streams¶

QCborStreamReader is capable of detecting corrupt input on its own. The library it uses has been extensively tested against invalid input of any kind and is quite able to report errors. If any is detected, QCborStreamReader will set to a value besides QCborError::NoError, indicating which situation was detected.

Most errors detected by QCborStreamReader during normal item parsing are not recoverable. The code using QCborStreamReader may opt to handle the data that was properly decoded or it can opt to discard the entire data.

The only recoverable error is QCborError::EndOfFile, which indicates that more data is required in order to complete the parsing. This situation is useful when data is being read from an asynchronous source, such as a pipe (QProcess) or a socket (QTcpSocket, QUdpSocket, QNetworkReply, etc.). When more data arrives, the surrounding code needs to call either , if parsing from a QByteArray, or , if it is instead reading directly a the QIDOevice that now has more data available (see ).

See also

QCborStreamWriter, QCborValue, QXmlStreamReader.

Enums¶

StringResultCode

TODO

Member	Value	Description
EndOfString	TODO	TODO
Error	TODO	TODO
Ok	TODO	TODO

Type

TODO

Member	Value	Description
Array	TODO	TODO
ByteArray	TODO	TODO
ByteString	TODO	TODO
Double	TODO	TODO
Float	TODO	TODO
Float16	TODO	TODO
HalfFloat	TODO	TODO
Invalid	TODO	TODO
Map	TODO	TODO
NegativeInteger	TODO	TODO
SimpleType	TODO	TODO
String	TODO	TODO
Tag	TODO	TODO
TextString	TODO	TODO
UnsignedInteger	TODO	TODO

Methods¶

__init__(): TODO

__init__(Union[QByteArray, bytes, bytearray])

This is an overloaded function.

Creates a QCborStreamReader object that will parse the CBOR stream found in data.

__init__(QIODevice)

This is an overloaded function.

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 oject is destroyed.

addData(Union[QByteArray, bytes, bytearray]): 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.

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 to add more data to be parsed.

See also

reset()setDevice().

containerDepth() → int: Returns the number of containers that this stream has entered with but not yet left.

See also

enterContainer()leaveContainer().

currentOffset() → int: 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().

device() → QIODevice: Returns the QIODevice that was set with either or the QCborStreamReader constructor. If this object was reading from a QByteArray, this function returns nullptr instead.

enterContainer() → bool: TODO

hasNext() → bool: 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, returning false indicates the parsing is complete; otherwise, if the container depth is non-zero, then the outer code needs to call .

See also

parentContainerType()containerDepth()leaveContainer().

isArray() → bool: TODO

isBool() → bool: TODO

isByteArray() → bool: TODO

isContainer() → bool: TODO

isDouble() → bool: TODO

isFalse() → bool: TODO

isFloat() → bool: TODO

isFloat16() → bool: TODO

isInteger() → bool: TODO

isInvalid() → bool: TODO

isLengthKnown() → bool

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 .

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

startArray(), startMap(), length().

isMap() → bool: TODO

isNegativeInteger() → bool: TODO

isNull() → bool: TODO

isSimpleType() → bool: TODO

isSimpleType(QCborSimpleType) → bool: TODO

isString() → bool: TODO

isTag() → bool: TODO

isTrue() → bool: TODO

isUndefined() → bool: TODO

isUnsignedInteger() → bool: TODO

isValid() → bool: TODO

lastError() → QCborError: Returns the last error in decoding the stream, if any. If no error was encountered, this returns an QCborError::NoError.

See also

isValid().

leaveContainer() → bool

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 must be paired with a call to .

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

See also

enterContainer()parentContainerType()containerDepth().

__len__() → int: TODO

length() → int: 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 returned false). It is an error to do that and it will cause QCborStreamReader to stop parsing the input stream.

See also

startArray(), startMap(), isLengthKnown().

next(maxRecursion: int = 10000) → bool

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 has returned false is also an error. If this function returns false, will return the error code detailing what the failure was.

See also

lastError()isValid()hasNext().

parentContainerType() → Type: 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().

readByteArray() → Tuple[QByteArray, StringResultCode]: TODO

readString() → Tuple[str, StringResultCode]: TODO

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 function automatically calls this function. Calling it when the reading had not failed is a no-op.

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 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 .

See also

clear()setDevice().

setDevice(QIODevice): Sets the source of data to device, resetting the decoder to its initial state.

toBool() → bool: TODO

toDouble() → float: TODO

toInteger() → int: TODO

toSimpleType() → QCborSimpleType: TODO

toUnsignedInteger() → int: TODO

type() → Type: TODO