PySide6.QtCore.QCborStreamWriter¶

class QCborStreamWriter¶

QCborStreamWriter 类是一个简单的 CBOR 编码器，操作于单向流上。更多…

概要¶

方法¶

def __init__()
def append()
def appendByteString()
def appendNull()
def appendTextString()
def appendUndefined()
def device()
def endArray()
def endMap()
def setDevice()
def startArray()
def startMap()

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述¶

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

此类可用于快速将CBOR内容流直接编码为QByteArray或QIODevice。CBOR是简洁二进制对象表示法，是一种非常紧凑的二进制数据编码形式，与JSON兼容。它由IETF受限RESTful环境（CoRE）工作组创建，已在许多新的RFC中使用。它旨在与CoAP协议一起使用。

QCborStreamWriter 提供了一个类似于 QXmlStreamWriter 的 StAX 风格 API。它相当底层，需要对 CBOR 编码有一定的了解。对于更简单的 API，请参阅 QCborValue，特别是编码函数 toCbor()。

QCborStreamWriter 的典型用法是在目标 QByteArray 或 QIODevice 上创建对象，然后调用 append() 的重载函数来编码所需的类型。要创建数组和映射，QCborStreamWriter 提供了 startArray() 和 startMap() 的重载函数，这些函数必须由相应的 endArray() 和 endMap() 函数来终止。

以下示例编码了与此JSON内容等效的内容：

{ “label”: “journald”, “autoDetect”: false, “condition”: “libs.journald”, “output”: [ “privateFeature” ] }

writer.startMap(4) # 4 elements in the map
writer.append("label")
writer.append("journald")
writer.append("autoDetect")
writer.append(False)
writer.append("condition")
writer.append("libs.journald")
writer.append("output")
writer.startArray(1)
writer.append("privateFeature")
writer.endArray()
writer.endMap()

CBOR支持¶

QCborStreamWriter 支持创建规范化和严格流所需的所有CBOR功能。它实现了RFC 7049中规定的几乎所有功能。

下表列出了QCborStreamWriter支持的CBOR功能。

功能

支持

无符号数字

是（全范围）

负数

是（全范围）

字节字符串

是

文本字符串

是

分块字符串

否

标签

是（任意）

布尔值

是

空值

是

未定义

是

任意简单值

是

半精度浮点数（16位）

是

单精度浮点数（32位）

是

双精度浮点数（64位）

是

无穷大和NaN浮点数

是

定长数组和映射

是

不定长度数组和映射

是

除了字符串和整数之外的映射键类型

是（任意）

功能	支持
无符号数字	是（全范围）
负数	是（全范围）
字节字符串	是
文本字符串	是
分块字符串	否
标签	是（任意）
布尔值	是
空值	是
未定义	是
任意简单值	是
半精度浮点数（16位）	是
单精度浮点数（32位）	是
双精度浮点数（64位）	是
无穷大和NaN浮点数	是
定长数组和映射	是
不定长度数组和映射	是
除了字符串和整数之外的映射键类型	是（任意）

规范的CBOR编码¶

规范的CBOR编码由RFC 7049的第3.9节定义。规范的编码不是Qt的CBOR解码功能的要求，但某些协议可能需要它。特别是，那些要求能够完全重现相同流的协议可能需要这一点。

为了被认为是“规范的”，一个CBOR流必须满足以下要求：

整数必须尽可能小。QCborStreamWriter 始终会这样做（不需要用户操作，也不可能写入过长的整数）。

数组、映射和字符串的长度必须尽可能短。如上所述，QCborStreamWriter 会自动执行此操作。

数组、映射和字符串必须使用明确的长度。QCborStreamWriter 总是为字符串这样做；对于数组和映射，请确保调用带有明确长度的 startArray() 和 startMap() 重载。

每个映射中的键必须按升序排序。QCborStreamWriter 在这方面没有提供帮助：开发人员必须确保在调用 append() 之前完成此操作。

浮点数值应尽可能小。QCborStreamWriter 不会转换浮点数值；开发者在调用 append() 之前需要自行执行此检查（参见这些函数的示例）。

严格的CBOR模式¶

严格模式由RFC 7049的第3.10节定义。与上述的规范编码一样，QCborStreamWriter 使得创建严格的CBOR流成为可能，但并不要求或验证输出是否符合严格模式。

映射中的键必须是唯一的。QCborStreamWriter 不会对映射键进行验证。

根据规范，标签可能需要仅与正确的类型配对。QCborStreamWriter 不执行标签使用的验证。

文本字符串必须正确编码为UTF-8。QCborStreamWriter 总是为使用append()添加的字符串写入正确的UTF-8，但对于使用appendTextString()添加的字符串不执行验证。

无效的CBOR流¶

也有可能误用QCborStreamWriter并生成无效的CBOR流，这些流将无法被接收者解码。以下操作将生成无效的流：

附加一个标签但不附加相应的标签值（QCborStreamWriter 不产生诊断信息）。

向具有明确长度的数组或映射添加过多或过少的项目（endMap() 和 endArray() 将返回 false，并且 QCborStreamWriter 将使用 qWarning() 记录日志）。

{解析和显示CBOR数据}, {序列化转换器}, {保存和加载游戏}

另请参阅

QCborStreamReader QCborValue QXmlStreamWriter

__init__(data)¶

Parameters:: 数据 – QByteArray

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

创建一个QCborStreamWriter对象，该对象将流附加到data。所有流操作都会立即写入字节数组，无需刷新任何缓冲区。

以下示例将一个数字写入字节数组，然后返回它。

def encodedNumber(value):

    ba = QByteArray()
    writer = QCborStreamWriter(ba)
    writer.append(value)
    return ba

QCborStreamWriter 不拥有 data 的所有权。

__init__(device)

Parameters:: 设备 – QIODevice

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

创建一个QCborStreamWriter对象，该对象将流写入device。在第一次append()调用之前，设备必须被打开。此构造函数可用于任何从QIODevice派生的类，例如QFile、QProcess或QTcpSocket。

QCborStreamWriter 没有缓冲，因此每次 append() 调用都会导致对设备的 write() 方法进行一次或多次调用。

以下示例将一个空映射写入文件：

f = QFile("output", QIODevice.WriteOnly)
writer = QCborStreamWriter(f)
writer.startMap(0)
writer.endMap()

QCborStreamWriter 不拥有 device 的所有权。

另请参阅

device() setDevice()

append(tag)¶

Parameters:: 标签 – QCborKnownTags

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

将CBOR标签tag附加到流中，创建一个CBOR标签值。所有标签后面必须跟随另一个类型，这些类型为标签提供意义。

在以下示例中，我们向流中添加了一个CBOR标签1（Unix time_t）和一个表示当前时间的整数，该整数是使用time()函数获取的：

def writeCurrentTime(writer):

    writer.append(QCborKnownTags.UnixTime_t)
    writer.append(time(None))

另请参阅

isTag() toTag()

append(st)

Parameters:: st – QCborSimpleType

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

将CBOR简单类型st附加到流中，创建一个CBOR简单类型值。在下面的示例中，我们编写了Null的简单类型以及Qt不支持的32类型的简单类型。

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

注意

使用没有规范的简单类型可能会导致远程接收方的验证错误。此外，简单类型值24到31（包括24和31）是保留的，不得使用。

另请参阅

isSimpleType() toSimpleType()

append(tag)

Parameters:: 标签 – QCborTag

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

将CBOR标签tag附加到流中，创建一个CBOR标签值。所有标签后面必须跟随另一个类型，这些标签为其提供意义。

在以下示例中，我们将一个CBOR标签36（正则表达式）和一个QRegularExpression的模式附加到流中：

def writeRxPattern(writer, rx):

    writer.append(QCborTag(36))
    writer.append(rx.pattern())

另请参阅

isTag() toTag()

append(str)

Parameters:: str – QLatin1String

append(str)

Parameters:: str – 字符串

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

将文本字符串 str 附加到流中，创建一个 CBOR 文本字符串值。QCborStreamWriter 将尝试在一个块中写入整个字符串。

以下示例将一个任意的 QString 写入流中：

def writeString(writer, str):

    writer.append(str)
另请参阅

isString() readString()

append(b)

Parameters:: b – 布尔值

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

将布尔值 b 附加到流中，创建 CBOR False 值或 CBOR True 值。此函数等同于（并实现为）：

writer.append(b if QCborSimpleType.True else QCborSimpleType.False)
另请参阅

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

append(ba)

Parameters:: ba – QByteArray

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

将字节数组 ba 附加到流中，创建一个 CBOR 字节字符串值。QCborStreamWriter 将尝试在一个块中写入整个字符串。

以下示例将加载并将文件内容附加到流中：

def writeFile(writer, fileName):

    f = QFile(fileName)
    if f.open(QIODevice.ReadOnly):
        writer.append(f.readAll())

如示例所示，与JSON不同，CBOR不需要对二进制内容进行转义。

另请参阅

appendByteString() isByteArray() readByteArray()

append(d)

Parameters:: d – 浮点数

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

将浮点数 d 附加到流中，创建一个 CBOR 64 位双精度浮点值。QCborStreamWriter 总是按原样附加数字，不检查数字是否为 NaN 的规范形式、无穷大、是否为非规范化数字，或者是否可以用更短的格式写入。

以下代码执行所有这些检查，除了非规范化检查，这预计将由系统FPU或浮点仿真直接处理。

   def writeDouble(writer, d):

       f = float()
       if qIsNaN(d):
           writer.append(qfloat16(qQNaN()))
        elif qIsInf(d):
           writer.append(d < 0 if -qInf() else qInf())
        elif (f = d) == d:
           f16 = f
           if f16 == f:
               writer.append(f16)
else:
               writer.append(f)
       else:
           writer.append(d)

确定一个双精度数是否可以无损转换为整数留给读者作为练习。

另请参阅

isDouble() toDouble()

append(f)

Parameters:: f – 浮点数

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

将浮点数 f 附加到流中，创建一个 CBOR 32 位单精度浮点数值。以下代码可用于将 C++ 的 double 转换为 float（如果没有精度损失）并附加它，或者直接附加 double。

   def writeFloat(writer, d):

       f = d
       if qIsNaN(d) or d == f:
           writer.append(f)
else:
           writer.append(d)

另请参阅

isFloat() toFloat()

append(i)

Parameters:: i – 整数

append(i)

Parameters:: i – 整数

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

将64位有符号值i附加到CBOR流中。这将根据参数的符号创建一个CBOR无符号整数或CBOR负整数值。在以下示例中，我们写入值0、-1、2³²和INT64_MAX：

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

另请参阅

isInteger() toInteger()

append(u)

Parameters:: u – 整数

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

将64位无符号值u附加到CBOR流中，创建一个CBOR无符号整数值。在以下示例中，我们写入值0、2³²和UINT64_MAX：

writer.append(0U)
writer.append(Q_UINT64_C(4294967296))
writer.append(std.numeric_limits<quint64>.max())
另请参阅

isUnsignedInteger() toUnsignedInteger()

append(u)

Parameters:: u – 整数

append(str[, size=-1])

Parameters:

str – str
size – int

这是一个重载函数。

将起始于str的size字节文本附加到流中，创建一个CBOR文本字符串值。QCborStreamWriter将尝试一次性写入整个字符串。如果size为-1，此函数将写入strlen(\a str)字节。

由str指向的字符串预期是正确编码的UTF-8。QCborStreamWriter不会验证这一点。

与append()的QLatin1StringView重载不同，此函数不受2 GB的限制。然而，请注意，无论是QCborStreamReader还是QCborValue都不支持读取文本字符串大于2 GB的CBOR流。

另请参阅

append(QLatin1StringView) append(QStringView) isString() readString()

appendByteString(data, len)¶

Parameters:

data – 字符串
len – int

将起始于data的len字节数据附加到流中，创建一个CBOR字节字符串值。QCborStreamWriter将尝试一次性写入整个字符串。

与QByteArray的append()重载不同，此函数不受QByteArray的大小限制。然而，请注意，无论是readByteArray()还是QCborValue都不支持读取大于2 GB的字节数组的CBOR流。

另请参阅

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

appendNull()¶

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

向流中追加一个CBOR空值。此函数等同于（并实现为）：

writer.append(QCborSimpleType.Null)
另请参阅

nullptr_t) append(QCborSimpleType) isNull()

appendTextString(utf8, len)¶

Parameters:

utf8 – 字符串
len – int

将起始于utf8的len字节文本追加到流中，创建一个CBOR文本字符串值。QCborStreamWriter将尝试一次性写入整个字符串。

由utf8指向的字符串预期应为正确编码的UTF-8。QCborStreamWriter不会验证这一点。

与append()的QLatin1StringView重载不同，此函数不受2 GB的限制。然而，请注意，无论是readString()还是QCborValue都不支持读取文本字符串大于2 GB的CBOR流。

另请参阅

append(QLatin1StringView) append(QStringView) isString() readString()

appendUndefined()¶

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

向流中追加一个CBOR未定义值。此函数等同于（并实现为）：

writer.append(QCborSimpleType.Undefined)
另请参阅

append(QCborSimpleType) isUndefined()

device()¶

Return type:: QIODevice

返回此QCborStreamWriter对象正在写入的QIODevice。该设备必须先前已通过构造函数或setDevice()设置。

如果此对象是通过写入QByteArray创建的，此函数将返回一个QBuffer的内部实例，该实例由QCborStreamWriter拥有。

另请参阅

setDevice()

endArray()¶

Return type:: 布尔

终止由startArray()的任何重载开始的数组，如果向数组中添加了正确数量的元素，则返回true。必须为每个使用的startArray()调用此函数。

返回false表示应用程序中存在错误，并且此流中存在不可恢复的错误。如果发生这种情况，QCborStreamWriter还会使用qWarning()写入警告。

在当前容器不是数组的情况下调用此函数也是一个错误，尽管QCborStreamWriter目前无法检测到这种情况。

另请参阅

startArray() startArray(quint64) endMap()

endMap()¶

Return type:: 布尔

终止由startMap()的任一重载启动的映射，如果正确数量的元素被添加到数组中，则返回true。必须为每个使用的startMap()调用此函数。

返回false表示应用程序中存在错误，并且此流中存在不可恢复的错误。如果发生这种情况，QCborStreamWriter 还会使用 qWarning() 写入警告。

在当前容器不是地图时调用此函数也是一个错误，尽管QCborStreamWriter目前无法检测到这种情况。

另请参阅

startMap() startMap(quint64) endArray()

setDevice(device)¶

Parameters:: 设备 – QIODevice

将此QCborStreamWriter对象正在写入的设备或字节数组替换为device。

另请参阅

device()

startArray()¶

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

在CBOR流中启动一个长度不确定的CBOR数组。每个startArray()调用必须与一个endArray()调用配对，并且当前的CBOR元素一直延伸到数组的末尾。

此函数创建的数组没有明确的长度。相反，其长度由其包含的元素隐含。但请注意，使用不确定长度的数组不符合规范的CBOR编码。

以下示例将从作为输入传递的字符串列表中追加元素：

def appendList(writer, values):

    writer.startArray()
    for s in values:
        writer.append(s)
    writer.endArray()

另请参阅

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

startArray(count)

Parameters:: count – int

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

在CBOR流中启动一个具有明确长度的CBOR数组，包含count个项目。每个startArray调用必须与一个endArray()调用配对，并且当前的CBOR元素一直延伸到数组的末尾。

此函数创建的数组具有明确的长度，因此必须向CBOR流中添加恰好count个项目。添加较少或较多的项目将在endArray()期间导致失败，并且CBOR流将损坏。然而，规范CBOR编码需要明确长度的数组。

以下示例将附加在作为输入传递的QStringList中找到的所有字符串：

def appendList(writer, list):

    writer.startArray(list.size())
    for s in list:
        writer.append(s)
    writer.endArray()

大小限制: 该函数的参数是quint64，这似乎允许数组中有多达2⁶⁴-1个元素。然而，QCborStreamWriter和QCborStreamReader目前在32位系统上限制为2³²-2个项目，在64位系统上限制为2⁶⁴-2个项目。还要注意的是，QCborArray目前在32位平台上限制为2²⁷个元素，在64位平台上限制为2⁵⁹个元素。

另请参阅

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

startMap()¶

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

在CBOR流中启动一个长度不确定的CBOR映射。每个startMap()调用必须与一个endMap()调用配对，并且当前的CBOR元素一直延伸到映射的结束。

此函数创建的地图没有明确的长度。相反，它的长度由其包含的元素暗示。但请注意，使用不确定长度的地图不符合规范的CBOR编码（规范编码还要求键是唯一的并按排序顺序排列）。

以下示例将作为输入传递的整数和字符串对列表中的元素附加到列表中：

def appendMap(writer, QList<std.pair<int, values):

    writer.startMap()
    for pair in values:
        writer.append(pair.first)
        writer.append(pair.second)

    writer.endMap()

另请参阅

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

startMap(count)

Parameters:: count – int

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

在CBOR流中启动一个具有明确长度的CBOR Map，包含count个项目。每个startMap调用必须与一个endMap()调用配对，并且当前的CBOR元素一直延伸到Map的末尾。

此函数创建的地图具有明确的长度，因此必须向CBOR流中添加恰好count对项目。添加较少或较多的项目将在endMap()期间导致失败，并且CBOR流将损坏。然而，规范CBOR编码需要明确长度的地图。

以下示例将附加在作为输入传递的QMap中找到的所有字符串：

def appendMap(writer, QMap<int, map):

    writer.startMap(map.size())
    for it in map:
        writer.append(it.key())
        writer.append(it.value())

    writer.endMap()

大小限制：该函数的参数是quint64，这似乎允许在映射中最多有2⁶⁴-1对。然而，QCborStreamWriter和QCborStreamReader目前在32位系统上限制为2³¹-1项，在64位系统上限制为2⁶³-1项。还要注意的是，QCborMap目前在32位平台上限制为2²⁶个元素，在64位平台上限制为2⁵⁸个元素。

另请参阅

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