QCborStreamReader Class

Detailed Description

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:

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.

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 lastError() 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 addData(), if parsing from a QByteArray, or reparse(), if it is instead reading directly a the QIDOevice that now has more data available (see setDevice()).