QCborStreamWriter ¶

QCborStreamWriter class is a simple CBOR encoder operating on a one-way stream. 更多 …

New in version 5.12.

概要 ¶

函数 ¶

def append (b)
def append (ba)
def append (d)
def append (f)
def append (i)
def append (i)
def append (st)
def append (str[, size=-1])
def append (tag)
def append (u)
def append (u)
def appendByteString (data, len)
def appendNull ()
def appendTextString (utf8, len)
def appendUndefined ()
def device ()
def endArray ()
def endMap ()
def setDevice (device)
def startArray ()
def startArray (count)
def startMap ()
def startMap (count)

详细描述 ¶

This class can be used to quickly encode a stream of CBOR content directly to either a QByteArray or 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 .

QCborStreamWriter provides a StAX-like API, similar to that of QXmlStreamWriter . It is rather low-level and requires a bit of knowledge of CBOR encoding. For a simpler API, see QCborValue and especially the encoding function toCbor() .

The typical use of QCborStreamWriter is to create the object on the target QByteArray or QIODevice , then call one of the append() overloads with the desired type to be encoded. To create arrays and maps, QCborStreamWriter 提供 startArray() and startMap() overloads, which must be terminated by the corresponding endArray() and endMap() 函数。

The following example encodes the equivalent of this JSON content:

{ “label”: “journald”, “autoDetect”: false, “condition”: “libs.journald”, “output”: [ “privateFeature” ] }
writer.startMap(4);    // 4 elements in the map
writer.append(QLatin1String("label"));
writer.append(QLatin1String("journald"));
writer.append(QLatin1String("autoDetect"));
writer.append(false);
writer.append(QLatin1String("condition"));
writer.append(QLatin1String("libs.journald"));
writer.append(QLatin1String("output"));
writer.startArray(1);
writer.append(QLatin1String("privateFeature"));
writer.endArray();
writer.endMap();
											

CBOR 支持 ¶

QCborStreamWriter supports all CBOR features required to create canonical and strict streams. It implements almost all of the features specified in RFC 7049 .

The following table lists the CBOR features that QCborStreamWriter 支持。

Feature

支持

无符号数字

Yes (full range)

负数

Yes (full range)

字节字符串

Yes

Text strings

Yes

Chunked strings

No

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)

Canonical CBOR encoding ¶

Canonical CBOR encoding is defined by Section 3.9 of RFC 7049 . Canonical encoding is not a requirement for Qt’s CBOR decoding functionality, but it may be required for some protocols. In particular, protocols that require the ability to reproduce the same stream identically may require this.

In order to be considered “canonical”, a CBOR stream must meet the following requirements:

Integers must be as small as possible. QCborStreamWriter always does this (no user action is required and it is not possible to write overlong integers).

Array, map and string lengths must be as short as possible. As above, QCborStreamWriter automatically does this.

Arrays, maps and strings must use explicit length. QCborStreamWriter always does this for strings; for arrays and maps, be sure to call startArray() and startMap() overloads with explicit length.

Keys in every map must be sorted in ascending order. QCborStreamWriter offers no help in this item: the developer must ensure that before calling append() for the map pairs.

Floating point values should be as small as possible. QCborStreamWriter will not convert floating point values; it is up to the developer to perform this check prior to calling append() (see those functions’ examples).

Strict CBOR mode ¶

Strict mode is defined by Section 3.10 of RFC 7049 . As for Canonical encoding above, QCborStreamWriter makes it possible to create strict CBOR streams, but does not require them or validate that the output is so.

Keys in a map must be unique. QCborStreamWriter performs no validation of map keys.

Tags may be required to be paired only with the correct types, according to their specification. QCborStreamWriter performs no validation of tag usage.

Text Strings must be properly-encoded UTF-8. QCborStreamWriter always writes proper UTF-8 for strings added with append() , but performs no validation for strings added with appendTextString() .

Invalid CBOR stream ¶

It is also possible to misuse QCborStreamWriter and produce invalid CBOR streams that will fail to be decoded by a receiver. The following actions will produce invalid streams:

Append a tag and not append the corresponding tagged value ( QCborStreamWriter produces no diagnostic).

Append too many or too few items to an array or map with explicit length ( endMap() and endArray() will return false and QCborStreamWriter will log with qWarning() ).

另请参阅

QCborStreamReader QCborValue QXmlStreamWriter

class QCborStreamWriter ( data ) ¶

QCborStreamWriter(device)

param device

QIODevice

param data

QByteArray

创建 QCborStreamWriter object that will append the stream to data . All streaming is done immediately to the byte array, without the need for flushing any buffers.

The following example writes a number to a byte array then returns it.

												QByteArray encodedNumber(qint64 value)
{
    QByteArray ba;
    QCborStreamWriter writer(&ba);
    writer.append(value);
    return ba;
}
												
											

QCborStreamWriter 未拥有所有权对于 data .

创建 QCborStreamWriter object that will write the stream to device . The device must be opened before the first append() call is made. This constructor can be used with any class that derives from QIODevice ，譬如 QFile , QProcess or QTcpSocket .

QCborStreamWriter has no buffering, so every append() call will result in one or more calls to the device’s write() 方法。

The following example writes an empty map to a file:

												QFile f("output", QIODevice::WriteOnly);
QCborStreamWriter writer(&f);
writer.startMap(0);
writer.endMap();
												
											

QCborStreamWriter 未拥有所有权对于 device .

另请参阅

device() setDevice()

PySide2.QtCore.QCborStreamWriter. append ( u ) ¶

参数: u – uint

PySide2.QtCore.QCborStreamWriter. append ( u ) ¶

参数: u – quint64

这是重载函数。

Appends the 64-bit unsigned value u to the CBOR stream, creating a CBOR Unsigned Integer value. In the following example, we write the values 0, 2 ³² and UINT64_MAX :

												writer.append(0U);
writer.append(Q_UINT64_C(4294967296));
writer.append(std::numeric_limits<quint64>::max());
												
											

另请参阅

isUnsignedInteger() toUnsignedInteger()

PySide2.QtCore.QCborStreamWriter. append ( i ) ¶

参数: i – qint64

这是重载函数。

Appends the 64-bit signed value i to the CBOR stream. This will create either a CBOR Unsigned Integer or CBOR NegativeInteger value based on the sign of the parameter. In the following example, we write the values 0, -1, 2 ³² and INT64_MAX :

												writer.append(0);
writer.append(-1);
writer.append(Q_INT64_C(4294967296));
writer.append(std::numeric_limits<qint64>::max());
												
											

另请参阅

isInteger() toInteger()

PySide2.QtCore.QCborStreamWriter. append ( i ) ¶

参数: i – int

PySide2.QtCore.QCborStreamWriter. append ( f ) ¶

参数: f – float

这是重载函数。

Appends the floating point number f to the stream, creating a CBOR 32-bit Single-Precision Floating Point value. The following code can be used to convert a C++ double to float if there’s no loss of precision and append it, or instead append the double .

												void writeFloat(QCborStreamWriter &writer, double d)
{
    float f = d;
    if (qIsNaN(d) || d == f)
        writer.append(f);
    else
        writer.append(d);
}
												
											

另请参阅

isFloat() toFloat()

PySide2.QtCore.QCborStreamWriter. append ( str [ , size=-1 ] ) ¶

参数

str – str
size – long long

这是重载函数。

追加 size bytes of text starting from str to the stream, creating a CBOR Text String value. QCborStreamWriter will attempt to write the entire string in one chunk. If size is -1, this function will write strlen(\a str) 字节。

The string pointed to by str is expected to be properly encoded UTF-8. QCborStreamWriter performs no validation that this is the case.

不像 QLatin1String overload of append() , this function is not limited to 2 GB. However, note that neither QCborStreamReader nor QCborValue support reading CBOR streams with text strings larger than 2 GB.

另请参阅

append(QLatin1String) append(QStringView) isString() readString()

PySide2.QtCore.QCborStreamWriter. append ( ba ) ¶

参数: ba – QByteArray

PySide2.QtCore.QCborStreamWriter. append ( b ) ¶

参数: b – bool

这是重载函数。

Appends the boolean value b to the stream, creating either a CBOR False value or a CBOR True value. This function is equivalent to (and implemented as):

writer.append(b ? QCborSimpleType::True : QCborSimpleType::False);

另请参阅

appendNull() appendUndefined() isBool() toBool()

PySide2.QtCore.QCborStreamWriter. append ( st ) ¶

参数: st – QCborSimpleType

这是重载函数。

Appends the CBOR simple type st to the stream, creating a CBOR Simple Type value. In the following example, we write the simple type for Null as well as for type 32, which Qt has no support for.

												writer.append(QCborSimpleType::Null);
writer.append(QCborSimpleType(32));

注意

Using Simple Types for which there is no specification can lead to validation errors by the remote receiver. In addition, simple type values 24 through 31 (inclusive) are reserved and must not be used.

另请参阅

isSimpleType() toSimpleType()

PySide2.QtCore.QCborStreamWriter. append ( tag ) ¶

参数: tag – QCborKnownTags

这是重载函数。

Appends the CBOR tag tag to the stream, creating a CBOR Tag value. All tags must be followed by another type which they provide meaning for.

In the following example, we append a CBOR Tag 1 (Unix time_t ) and an integer representing the current time to the stream, obtained using the time() 函数：

												void writeCurrentTime(QCborStreamWriter &writer)
{
    writer.append(QCborKnownTags::UnixTime_t);
    writer.append(time(nullptr));
}
												
											

另请参阅

isTag() toTag()

PySide2.QtCore.QCborStreamWriter. append ( d ) ¶

参数: d – double

这是重载函数。

Appends the floating point number d to the stream, creating a CBOR 64-bit Double-Precision Floating Point value. QCborStreamWriter always appends the number as-is, performing no check for whether the number is the canonical form for NaN, an infinite, whether it is denormal or if it could be written with a shorter format.

The following code performs all those checks, except for the denormal one, which is expected to be taken into account by the system FPU or floating point emulation directly.

												void writeDouble(QCborStreamWriter &writer, double d)
{
    float f;
    if (qIsNaN(d)) {
        writer.append(qfloat16(qQNaN()));
    } else if (qIsInf(d)) {
        writer.append(d < 0 ? -qInf() : qInf());
    } else if ((f = d) == d) {
        qfloat16 f16 = f;
        if (f16 == f)
            writer.append(f16);
        else
            writer.append(f);
    } else {
        writer.append(d);
    }
}
												
											

Determining if a double can be converted to an integral with no loss of precision is left as an exercise to the reader.

另请参阅

isDouble() toDouble()

PySide2.QtCore.QCborStreamWriter. appendByteString ( data , len ) ¶

参数

data – str
len – long long

追加 len bytes of data starting from data to the stream, creating a CBOR Byte String value. QCborStreamWriter will attempt to write the entire string in one chunk.

不像 QByteArray overload of append() , this function is not limited by QByteArray ‘s size limits. However, note that neither readByteArray() nor QCborValue support reading CBOR streams with byte arrays larger than 2 GB.

另请参阅

append() appendTextString() isByteArray() readByteArray()

PySide2.QtCore.QCborStreamWriter. appendNull ( ) ¶

Appends a CBOR Null value to the stream. This function is equivalent to (and implemented as):

												writer.append(QCborSimpleType::Null);
												
											

另请参阅

nullptr_t) append(QCborSimpleType) isNull()

PySide2.QtCore.QCborStreamWriter. appendTextString ( utf8 , len ) ¶

参数

utf8 – str
len – long long

追加 len bytes of text starting from utf8 to the stream, creating a CBOR Text String value. QCborStreamWriter will attempt to write the entire string in one chunk.

The string pointed to by utf8 is expected to be properly encoded UTF-8. QCborStreamWriter performs no validation that this is the case.

不像 QLatin1String overload of append() , this function is not limited to 2 GB. However, note that neither readString() nor QCborValue support reading CBOR streams with text strings larger than 2 GB.

另请参阅

append(QLatin1String) append(QStringView) isString() readString()

PySide2.QtCore.QCborStreamWriter. appendUndefined ( ) ¶

Appends a CBOR Undefined value to the stream. This function is equivalent to (and implemented as):

												writer.append(QCborSimpleType::Undefined);
												
											

另请参阅

append(QCborSimpleType) isUndefined()

PySide2.QtCore.QCborStreamWriter. device ( ) ¶

返回类型: QIODevice

返回 QIODevice that this QCborStreamWriter object is writing to. The device must have previously been set with either the constructor or with setDevice() .

If this object was created by writing to a QByteArray , this function will return an internal instance of QBuffer , which is owned by QCborStreamWriter .

另请参阅

setDevice()

PySide2.QtCore.QCborStreamWriter. endArray ( ) ¶

返回类型: bool

Terminates the array started by either overload of startArray() and returns true if the correct number of elements was added to the array. This function must be called for every startArray() used.

A return of false indicates error in the application and an unrecoverable error in this stream. QCborStreamWriter also writes a warning using qWarning() if that happens.

Calling this function when the current container is not an array is also an error, though QCborStreamWriter cannot currently detect this condition.

另请参阅

startArray() startArray(quint64) endMap()

PySide2.QtCore.QCborStreamWriter. endMap ( ) ¶

返回类型: bool

Terminates the map started by either overload of startMap() and returns true if the correct number of elements was added to the array. This function must be called for every startMap() used.

A return of false indicates error in the application and an unrecoverable error in this stream. QCborStreamWriter also writes a warning using qWarning() if that happens.

Calling this function when the current container is not a map is also an error, though QCborStreamWriter cannot currently detect this condition.

另请参阅

startMap() startMap(quint64) endArray()

PySide2.QtCore.QCborStreamWriter. setDevice ( device ) ¶

参数: device – QIODevice

Replaces the device or byte array that this QCborStreamWriter object is writing to with device .

另请参阅

device()

PySide2.QtCore.QCborStreamWriter. startArray ( ) ¶

Starts a CBOR Array with indeterminate length in the CBOR stream. Each call must be paired with one endArray() call and the current CBOR element extends until the end of the array.

The array created by this function has no explicit length. Instead, its length is implied by the elements contained in it. Note, however, that use of indeterminate-length arrays is not compliant with canonical CBOR encoding.

The following example appends elements from the linked list of strings passed as input:

												void appendList(QCborStreamWriter &writer, const QLinkedList<QString> &list)
{
    writer.startArray();
    for (const QString &s : list)
        writer.append(s);
    writer.endArray();
}
												
											

另请参阅

startArray(quint64) endArray() startMap() isArray() isLengthKnown()

PySide2.QtCore.QCborStreamWriter. startArray ( count ) ¶

参数: count – quint64

这是重载函数。

Starts a CBOR Array with explicit length of count items in the CBOR stream. Each startArray call must be paired with one endArray() call and the current CBOR element extends until the end of the array.

The array created by this function has an explicit length and therefore exactly count items must be added to the CBOR stream. Adding fewer or more items will result in failure during endArray() and the CBOR stream will be corrupt. However, explicit-length arrays are required by canonical CBOR encoding.

The following example appends all strings found in the QStringList passed as input:

												void appendList(QCborStreamWriter &writer, const QStringList &list)
{
    writer.startArray(list.size());
    for (const QString &s : list)
        writer.append(s);
    writer.endArray();
}
												
											

Size limitations : The parameter to this function is quint64, which would seem to allow up to 2 ⁶⁴ -1 elements in the array. However, both QCborStreamWriter and QCborStreamReader are currently limited to 2 ³² -2 items on 32-bit systems and 2 ⁶⁴ -2 items on 64-bit ones. Also note that QCborArray is currently limited to 2 ²⁷ elements in any platform.

另请参阅

startArray() endArray() startMap() isArray() isLengthKnown()

PySide2.QtCore.QCborStreamWriter. startMap ( ) ¶

Starts a CBOR Map with indeterminate length in the CBOR stream. Each call must be paired with one endMap() call and the current CBOR element extends until the end of the map.

The map created by this function has no explicit length. Instead, its length is implied by the elements contained in it. Note, however, that use of indeterminate-length maps is not compliant with canonical CBOR encoding (canonical encoding also requires keys to be unique and in sorted order).

The following example appends elements from the linked list of int and string pairs passed as input:

												void appendMap(QCborStreamWriter &writer, const QLinkedList<QPair<int, QString>> &list)
{
    writer.startMap();
    for (const auto pair : list) {
        writer.append(pair.first)
        writer.append(pair.second);
    }
    writer.endMap();
}
												
											

另请参阅

startMap(quint64) endMap() startArray() isMap() isLengthKnown()

PySide2.QtCore.QCborStreamWriter. startMap ( count ) ¶

参数: count – quint64

这是重载函数。

Starts a CBOR Map with explicit length of count items in the CBOR stream. Each startMap call must be paired with one endMap() call and the current CBOR element extends until the end of the map.

The map created by this function has an explicit length and therefore exactly count pairs of items must be added to the CBOR stream. Adding fewer or more items will result in failure during endMap() and the CBOR stream will be corrupt. However, explicit-length map are required by canonical CBOR encoding.

The following example appends all strings found in the QMap passed as input:

												void appendMap(QCborStreamWriter &writer, const QMap<int, QString> &map)
{
    writer.startMap(map.size());
    for (auto it = map.begin(); it != map.end(); ++it) {
        writer.append(it.key());
        writer.append(it.value());
    }
    writer.endMap();
}
												
											

Size limitations : The parameter to this function is quint64, which would seem to allow up to 2 ⁶⁴ -1 pairs in the map. However, both QCborStreamWriter and QCborStreamReader are currently limited to 2 ³¹ -1 items on 32-bit systems and 2 ⁶³ -1 items on 64-bit ones. Also note that QCborMap is currently limited to 2 ²⁶ elements in any platform.

另请参阅

startMap() endMap() startArray() isMap() isLengthKnown()

Feature	支持
无符号数字	Yes (full range)
负数	Yes (full range)
字节字符串	Yes
Text strings	Yes
Chunked strings	No
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)

内容表

上一话题

下一话题

快速搜索

QCborStreamWriter ¶

概要 ¶

函数 ¶

详细描述 ¶

CBOR 支持 ¶

Canonical CBOR encoding ¶

Strict CBOR mode ¶

Invalid CBOR stream ¶