QCborStreamWriter¶
The
QCborStreamWriter
class is a simple CBOR encoder operating on a one-way stream. More…
New in version 5.12.
Synopsis¶
Functions¶
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)
Detailed Description¶
This class can be used to quickly encode a stream of CBOR content directly to either a
QByteArray
orQIODevice
. 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 ofQXmlStreamWriter
. It is rather low-level and requires a bit of knowledge of CBOR encoding. For a simpler API, seeQCborValue
and especially the encoding functiontoCbor()
.The typical use of
QCborStreamWriter
is to create the object on the targetQByteArray
orQIODevice
, then call one of theappend()
overloads with the desired type to be encoded. To create arrays and maps,QCborStreamWriter
providesstartArray()
andstartMap()
overloads, which must be terminated by the correspondingendArray()
andendMap()
functions.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 support¶
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
supports.
Feature
Support
Unsigned numbers
Yes (full range)
Negative numbers
Yes (full range)
Byte strings
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 callstartArray()
andstartMap()
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 callingappend()
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 callingappend()
(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 withappend()
, but performs no validation for strings added withappendTextString()
.
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()
andendArray()
will return false andQCborStreamWriter
will log withqWarning()
).See also
- class PySide2.QtCore.QCborStreamWriter(data)¶
PySide2.QtCore.QCborStreamWriter(device)
- param device:
- param data:
Creates a
QCborStreamWriter
object that will append the stream todata
. 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
does not take ownership ofdata
.Creates a
QCborStreamWriter
object that will write the stream todevice
. The device must be opened before the firstappend()
call is made. This constructor can be used with any class that derives fromQIODevice
, such asQFile
,QProcess
orQTcpSocket
.QCborStreamWriter
has no buffering, so everyappend()
call will result in one or more calls to the device’swrite()
method.The following example writes an empty map to a file:
QFile f("output", QIODevice::WriteOnly); QCborStreamWriter writer(&f); writer.startMap(0); writer.endMap();
QCborStreamWriter
does not take ownership ofdevice
.See also
- PySide2.QtCore.QCborStreamWriter.append(u)¶
- Parameters:
u –
uint
- PySide2.QtCore.QCborStreamWriter.append(u)
- Parameters:
u – int
This is an overloaded function.
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 32 andUINT64_MAX
:writer.append(0U); writer.append(Q_UINT64_C(4294967296)); writer.append(std::numeric_limits<quint64>::max());
See also
- PySide2.QtCore.QCborStreamWriter.append(i)
- Parameters:
i – int
This is an overloaded function.
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 32 andINT64_MAX
:writer.append(0); writer.append(-1); writer.append(Q_INT64_C(4294967296)); writer.append(std::numeric_limits<qint64>::max());
See also
- PySide2.QtCore.QCborStreamWriter.append(i)
- Parameters:
i – int
- PySide2.QtCore.QCborStreamWriter.append(f)
- Parameters:
f – float
This is an overloaded function.
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
tofloat
if there’s no loss of precision and append it, or instead append thedouble
.void writeFloat(QCborStreamWriter &writer, double d) { float f = d; if (qIsNaN(d) || d == f) writer.append(f); else writer.append(d); }
- PySide2.QtCore.QCborStreamWriter.append(str[, size=-1])
- Parameters:
str – str
size –
long long
This is an overloaded function.
Appends
size
bytes of text starting fromstr
to the stream, creating a CBOR Text String value.QCborStreamWriter
will attempt to write the entire string in one chunk. Ifsize
is -1, this function will writestrlen(\a str)
bytes.The string pointed to by
str
is expected to be properly encoded UTF-8.QCborStreamWriter
performs no validation that this is the case.Unlike the
QLatin1String
overload ofappend()
, this function is not limited to 2 GB. However, note that neitherQCborStreamReader
norQCborValue
support reading CBOR streams with text strings larger than 2 GB.See also
append(QLatin1String)
append(QStringView)
isString()
readString()
- PySide2.QtCore.QCborStreamWriter.append(ba)
- Parameters:
- PySide2.QtCore.QCborStreamWriter.append(b)
- Parameters:
b – bool
This is an overloaded function.
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);
See also
- PySide2.QtCore.QCborStreamWriter.append(st)
- Parameters:
st –
QCborSimpleType
This is an overloaded function.
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));
Note
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.
See also
- PySide2.QtCore.QCborStreamWriter.append(tag)
- Parameters:
tag –
QCborKnownTags
This is an overloaded function.
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 thetime()
function:void writeCurrentTime(QCborStreamWriter &writer) { writer.append(QCborKnownTags::UnixTime_t); writer.append(time(nullptr)); }
See also
isTag()
toTag()
- PySide2.QtCore.QCborStreamWriter.append(d)
- Parameters:
d –
double
This is an overloaded function.
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.
See also
- PySide2.QtCore.QCborStreamWriter.appendByteString(data, len)¶
- Parameters:
data – str
len –
long long
Appends
len
bytes of data starting fromdata
to the stream, creating a CBOR Byte String value.QCborStreamWriter
will attempt to write the entire string in one chunk.Unlike the
QByteArray
overload ofappend()
, this function is not limited byQByteArray
‘s size limits. However, note that neitherreadByteArray()
norQCborValue
support reading CBOR streams with byte arrays larger than 2 GB.
- PySide2.QtCore.QCborStreamWriter.appendNull()¶
Appends a CBOR Null value to the stream. This function is equivalent to (and implemented as):
writer.append(QCborSimpleType::Null);
See also
nullptr_t)
append(QCborSimpleType)
isNull()
- PySide2.QtCore.QCborStreamWriter.appendTextString(utf8, len)¶
- Parameters:
utf8 – str
len –
long long
Appends
len
bytes of text starting fromutf8
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.Unlike the
QLatin1String
overload ofappend()
, this function is not limited to 2 GB. However, note that neitherreadString()
norQCborValue
support reading CBOR streams with text strings larger than 2 GB.See also
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);
See also
append(QCborSimpleType)
isUndefined()
- PySide2.QtCore.QCborStreamWriter.device()¶
- Return type:
Returns the
QIODevice
that thisQCborStreamWriter
object is writing to. The device must have previously been set with either the constructor or withsetDevice()
.If this object was created by writing to a
QByteArray
, this function will return an internal instance ofQBuffer
, which is owned byQCborStreamWriter
.See also
- PySide2.QtCore.QCborStreamWriter.endArray()¶
- Return type:
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 everystartArray()
used.A return of false indicates error in the application and an unrecoverable error in this stream.
QCborStreamWriter
also writes a warning usingqWarning()
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.See also
startArray()
startArray(quint64)
endMap()
- PySide2.QtCore.QCborStreamWriter.endMap()¶
- Return type:
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 everystartMap()
used.A return of false indicates error in the application and an unrecoverable error in this stream.
QCborStreamWriter
also writes a warning usingqWarning()
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.See also
startMap()
startMap(quint64)
endArray()
- PySide2.QtCore.QCborStreamWriter.setDevice(device)¶
- Parameters:
device –
PySide2.QtCore.QIODevice
Replaces the device or byte array that this
QCborStreamWriter
object is writing to withdevice
.See also
- 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(); }
See also
startArray(quint64)
endArray()
startMap()
isArray()
isLengthKnown()
- PySide2.QtCore.QCborStreamWriter.startArray(count)
- Parameters:
count – int
This is an overloaded function.
Starts a CBOR Array with explicit length of
count
items in the CBOR stream. EachstartArray
call must be paired with oneendArray()
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 duringendArray()
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 64 -1 elements in the array. However, both
QCborStreamWriter
andQCborStreamReader
are currently limited to 2 32 -2 items on 32-bit systems and 2 64 -2 items on 64-bit ones. Also note thatQCborArray
is currently limited to 2 27 elements in any platform.
- 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(); }
See also
startMap(quint64)
endMap()
startArray()
isMap()
isLengthKnown()
- PySide2.QtCore.QCborStreamWriter.startMap(count)
- Parameters:
count – int
This is an overloaded function.
Starts a CBOR Map with explicit length of
count
items in the CBOR stream. EachstartMap
call must be paired with oneendMap()
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 duringendMap()
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 64 -1 pairs in the map. However, both
QCborStreamWriter
andQCborStreamReader
are currently limited to 2 31 -1 items on 32-bit systems and 2 63 -1 items on 64-bit ones. Also note thatQCborMap
is currently limited to 2 26 elements in any platform.See also
© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.