Google 致力于为黑人社区推动种族平等。查看具体举措。

此页面由 Cloud Translation API 翻译。

nl::Weave::TLV::TLVWriter

#include <src/lib/core/WeaveTLV.h>

提供用于节省内存的编码器，用于以 Weave TLV 格式写入数据。

摘要

TLVWriter 为 Weave TLV 数据实现了仅支持流的流式编码器。应用通过调用 writers 的 Put() 方法将数据写入编码，并根据需要传递关联的标记和值信息。同样，应用可通过调用 Writer's 的 OpenContainer() 或 EnterContainer() 方法对 TLV 容器类型（结构、数组或路径）进行编码。

TLVWriter 对象可以直接将数据写入固定的输出缓冲区，也可以写入一个或多个 PacketBuffer 对象的链。此外，应用可以提供自己的 GetNewBuffer 和 FinalizeBuffer 函数，将输出定向到任意目标位置，例如套接字或事件队列。

继承

直接已知子类：nl::Weave::TLV::CircularTLVWriter

受保护的类型
`@72{ kEndOfContainerMarkerSize = 1 }`	枚举

公共类型
`FinalizeBufferFunct)(TLVWriter &writer, uintptr_t bufHandle, uint8_t *bufStart, uint32_t bufLen)`	WEAVE_ERROR（* `WEAVE_ERROR(*` 用于执行 TLVWriter 对象输出的函数。
`GetNewBufferFunct)(TLVWriter &writer, uintptr_t &bufHandle, uint8_t *&bufStart, uint32_t &bufLen)`	WEAVE_ERROR（* `WEAVE_ERROR(*` 为 TLVWriter 提供新的输出缓冲区空间的函数。

公共属性
`AppData`	`void *` 可用于应用专用数据的指针字段。
`FinalizeBuffer`	`FinalizeBufferFunct` 指向一个函数的指针，当 TLVWriter 被最终确定时，系统会调用该函数。
`GetNewBuffer`	`GetNewBufferFunct` 指向将为 TLVWriter 提供新输出缓冲区空间的函数的指针。
`ImplicitProfileId`	`uint32_t` 应以隐式形式编码的代码的配置文件 ID。

受保护的属性
`mBufHandle`	`uintptr_t`
`mBufStart`	`uint8_t *`
`mContainerType`	`TLVType`
`mLenWritten`	`uint32_t`
`mMaxLen`	`uint32_t`
`mRemainingLen`	`uint32_t`
`mWritePoint`	`uint8_t *`

公共函数
`CloseContainer(TLVWriter & containerWriter)`	`WEAVE_ERROR` 在调用 OpenContainer() 后完成 TLV 容器的写入。
`ContinuePutBytes(const uint8_t *buf, uint32_t len)`	`WEAVE_ERROR` 对 TLV 字节字符串值进行编码。
`CopyContainer(TLVReader & container)`	`WEAVE_ERROR` 从 TLVReader 对象中复制 TLV 容器元素。
`CopyContainer(uint64_t tag, TLVReader & container)`	`WEAVE_ERROR` 对一组预编码的成员元素中的 TLV 容器元素进行编码。
`CopyContainer(uint64_t tag, const uint8_t *encodedContainer, uint16_t encodedContainerLen)`	`WEAVE_ERROR` 对包含预编码容器中成员元素的 TLV 容器元素进行编码。
`CopyElement(TLVReader & reader)`	`WEAVE_ERROR` 将 TLV 元素从读取器对象复制到写入器。
`CopyElement(uint64_t tag, TLVReader & reader)`	`WEAVE_ERROR`
`EndContainer(TLVType outerContainerType)`	`WEAVE_ERROR` 用于完成 TLV 容器元素的编码。
`Finalize(void)`	`WEAVE_ERROR` 完成 TLV 编码的写入工作。
`GetContainerType(void) const`	`TLVType` 返回 TLVWriter 当前写入的容器类型。
`GetLengthWritten(void)`	`uint32_t` 返回写入器自初始化以来写入的总字节数。
`Init(uint8_t *buf, uint32_t maxLen)`	`void` 初始化 TLVWriter 对象，以写入单个输出缓冲区。
`Init(PacketBuffer *buf, uint32_t maxLen)`	`void` 初始化 TLVWriter 对象，以写入单个 PacketBuffer。
`Init(PacketBuffer *buf, uint32_t maxLen, bool allowDiscontiguousBuffers)`	`void` 初始化 TLVWriter 对象，以写入一个或多个 PacketBuffer。
`InitMalloced(uint8_t *& outBuf, uint32_t initialBufSize, uint32_t maxLen)`	`void` 初始化 TLVWriter 对象，以写入动态缓冲区。
`OpenContainer(uint64_t tag, TLVType containerType, TLVWriter & containerWriter)`	`WEAVE_ERROR` 初始化新的 TLVWriter 对象，以写入 TLV 容器元素的成员。
`Put(uint64_t tag, int8_t v)`	`WEAVE_ERROR` 对带 TLV 符号的整数值进行编码。
`Put(uint64_t tag, int8_t v, bool preserveSize)`	`WEAVE_ERROR` 对带 TLV 符号的整数值进行编码。
`Put(uint64_t tag, int16_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, int16_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, int32_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, int32_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, int64_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, int64_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint8_t v)`	`WEAVE_ERROR` 对 TLV 无符号整数值进行编码。
`Put(uint64_t tag, uint8_t v, bool preserveSize)`	`WEAVE_ERROR` 对 TLV 无符号整数值进行编码。
`Put(uint64_t tag, uint16_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint16_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint32_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint32_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint64_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint64_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, float v)`	`WEAVE_ERROR`
`Put(uint64_t tag, double v)`	`WEAVE_ERROR` 对 TLV 浮点值进行编码。
`PutBoolean(uint64_t tag, bool v)`	`WEAVE_ERROR` 对 TLV 布尔值进行编码。
`PutBytes(uint64_t tag, const uint8_t *buf, uint32_t len)`	`WEAVE_ERROR` 对 TLV 字节字符串值进行编码。
`PutNull(uint64_t tag)`	`WEAVE_ERROR` 对 TLV null 值进行编码。
`PutPreEncodedContainer(uint64_t tag, TLVType containerType, const uint8_t *data, uint32_t dataLen)`	`WEAVE_ERROR` 对一组预编码的成员元素中的 TLV 容器元素进行编码。
`PutString(uint64_t tag, const char *buf)`	`WEAVE_ERROR` 对 TLV UTF8 字符串值进行编码。
`PutString(uint64_t tag, const char *buf, uint32_t len)`	`WEAVE_ERROR` 对 TLV UTF8 字符串值进行编码。
`PutStringF(uint64_t tag, const char *fmt, ...)`	`WEAVE_ERROR` 根据 TLV 元素中的格式对字符串输出进行编码。
`StartContainer(uint64_t tag, TLVType containerType, TLVType & outerContainerType)`	`WEAVE_ERROR` 开始对新的 TLV 容器元素进行编码。
`StartPutBytes(uint64_t tag, uint32_t totalLen)`	`WEAVE_ERROR` 对多个区块中的 TLV 字节字符串进行编码。
`VPutStringF(uint64_t tag, const char *fmt, va_list ap)`	`WEAVE_ERROR` 根据 TLV 元素中的格式对字符串输出进行编码。

公共静态函数
`FinalizePacketBuffer(TLVWriter & writer, uintptr_t bufHandle, uint8_t *bufStart, uint32_t dataLen)`	`WEAVE_ERROR` TLVWriter FinalizeBuffer 函数的实现，用于将数据写入 PacketBuffer 链。
`GetNewBuffer_Malloced(TLVWriter & writer, uintptr_t & bufHandle, uint8_t *& bufStart, uint32_t & bufLen)`	`WEAVE_ERROR` 用于写入动态缓冲区的 TLVWriter GetNewBuffer 函数实现。
`GetNewPacketBuffer(TLVWriter & writer, uintptr_t & bufHandle, uint8_t *& bufStart, uint32_t & bufLen)`	`WEAVE_ERROR` TLVWriter GetNewBuffer 函数实现，用于将数据写入 PacketBuffer 链。

受保护的函数
`IsCloseContainerReserved(void) const`	`bool` 确定容器是否应在开始 / 打开容器时为 CloseContainer 符号预留空间。
`IsContainerOpen(void) const`	`bool`
`SetCloseContainerReserved(bool aCloseContainerReserved)`	`void` 设置容器是否应在开始 / 打开容器时为 CloseContainer 符号预留空间。
`SetContainerOpen(bool aContainerOpen)`	`void`
`WriteData(const uint8_t *p, uint32_t len)`	`WEAVE_ERROR`
`WriteElementHead(TLVElementType elemType, uint64_t tag, uint64_t lenOrVal)`	`WEAVE_ERROR`
`WriteElementWithData(TLVType type, uint64_t tag, const uint8_t *data, uint32_t dataLen)`	`WEAVE_ERROR`

受保护的类型

@72

@72

公共类型

FinalizeBufferFunct

WEAVE_ERROR(* FinalizeBufferFunct)(TLVWriter &writer, uintptr_t bufHandle, uint8_t *bufStart, uint32_t bufLen)

用于执行 TLVWriter 对象输出的函数。

调用 TLVWriter 的 Finalize() 方法时，会调用此类型的函数。该函数应执行与使用写入器对象输出相关的任何必要清理或收尾操作。例如，记录编码的最终长度或关闭文件描述符。

详细信息

参数

`[in] writer`	对即将完成的 TLVWriter 对象的引用。
`[in,out] bufHandle`	通过之前调用 `GetNewBuffer` 函数设置的 uintptr_t 上下文值。
`[in,out] bufStart`	指向当前（以及最终）输出缓冲区开头的指针。
`[in,out] bufLen`	`bufStart` 所指向的缓冲区中包含的字节数。

返回值

`WEAVE_NO_ERROR`	最终确定是否成功。
`other`	其他 Weave 或平台错误代码，用于指示在敲定过程中发生错误。

GetNewBufferFunct

WEAVE_ERROR(* GetNewBufferFunct)(TLVWriter &writer, uintptr_t &bufHandle, uint8_t *&bufStart, uint32_t &bufLen)

为 TLVWriter 提供新的输出缓冲区空间的函数。

此类函数用于准备要写入的 TLVWriter 的新缓冲区空间。调用时，该函数应该会返回一个指针，指向应写入新数据的内存位置以及相关的最大长度。此函数可以通过分配新缓冲区来存放数据，或通过从现有缓冲区中清除之前写入的数据来提供写入空间。

详细信息

参数

`[in] writer`	对请求新缓冲区空间的 TLVWriter 对象的引用。
`[in,out] bufHandle`	对 uintptr_t 值的引用，该函数可用于在调用之间存储上下文数据。此值将在第一次调用之前初始化为 0。
`[in,out] bufStart`	对数据指针的引用。进入该函数时，`bufStart` 会指向当前输出缓冲区的开头。退出时，`bufStart` 应指向新输出缓冲区的开头。新指针的值可以与先前的值相同（例如，该函数将现有数据复制到其他位置），也可以指向全新的位置。
`[in,out] bufLen`	对无符号整数的引用。进入函数时，`bufLen` 包含当前缓冲区中未使用空间的字节数。退出时，`bufLen` 预计包含可写入新输出缓冲区的最大字节数。

返回值

`WEAVE_NO_ERROR`	该函数是否能够为写入器提供更多缓冲区空间。
`other`	其他 Weave 或平台错误代码，指示发生错误，发生错误，导致函数产生额外的缓冲区空间。

公共属性

应用数据

void * AppData

可用于应用专用数据的指针字段。

FinalizeBuffer

FinalizeBufferFunct FinalizeBuffer

指向一个函数的指针，当 TLVWriter 被最终确定时，系统会调用该函数。

每当调用 Finalize() 方法时，TLVWriter 对象都会调用 FinalizeBuffer 函数。应用可以在调用 Finalize() 之前随时设置函数指针。默认情况下，指针设置为 NULL，这会导致 Finalize() 方法放弃调用函数。

如需详细了解如何实现 FinalizeBuffer 函数，请参阅 FinalizeBufferFunct 类型定义。

GetNewBuffer

GetNewBufferFunct GetNewBuffer

指向将为 TLVWriter 提供新输出缓冲区空间的函数的指针。

每当尝试写入超出当前输出缓冲区大小的数据时，TLVWriter 对象都会调用 GetNewBuffer 函数。如果设置为 NULL（默认值），如果输出数据溢出当前缓冲区，写入器将返回 WEAVE_ERROR_NO_MEMORY。

GetNewBuffer 可以随时由应用设置，但通常是在写入器初始化时进行设置。

如需详细了解如何实现 GetNewBuffer 函数，请参阅 GetNewBufferFunct 类型定义。

隐式配置文件 ID

uint32_t ImplicitProfileId

应以隐式形式编码的代码的配置文件 ID。

要求写入者对新元素进行编码时，如果与新元素关联的标记的配置文件 ID 与 ImplicitProfileId 成员的值匹配，则写入者将以隐式形式对标记进行编码，并在过程中省略配置文件 ID。

默认情况下，ImplicitProfileId 属性会设置为 kProfileIdNotSpecified，用于指示写入者不要发出隐式编码的标记。应用可以随时设置 ImplicitProfileId，以启用从编码的当前点开始的隐式形式的编码标记。要设置的配置文件 ID 通常取决于所使用的应用或协议的上下文。

注意：ImplicitProfileId 成员的值仅会影响配置文件专用标记的编码；上下文专用标记的编码保持不变。

受保护的属性

mBufHandle

uintptr_t mBufHandle

mBufStart 中

uint8_t * mBufStart

mContainerType

TLVType mContainerType

mLenWriter 写入

uint32_t mLenWritten

mMaxLen

uint32_t mMaxLen

mRemainingLen

uint32_t mRemainingLen

mWritePoint

uint8_t * mWritePoint

公共函数

关闭容器

WEAVE_ERROR CloseContainer(
  TLVWriter & containerWriter
)

在调用 OpenContainer() 后完成 TLV 容器的写入。

CloseContainer() 方法会在调用 OpenContainer() 后恢复父 TLVWriter 对象的状态。每次调用 OpenContainer() 时，应用都必须对 CloseContainer() 进行相应的调用，将对同一容器写入程序的引用传递给这两种方法。

当 CloseContainer() 返回时，应用可以继续使用父写入器来写入容器元素之后显示的附加 TLV 元素。此时，提供的容器写入器应被视为“已初始化”，不得在未重新初始化的情况下使用。

详细信息

参数

[in] containerWriter

对提供给 OpenContainer() 方法的 TLVWriter 对象的引用。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INCORRECT_STATE`	如果提供的容器写入器的状态不正确。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已在提供的容器写入程序上打开另一个容器写入程序，但尚未关闭。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果完成容器编码会超出初始化写入器时指定的字节数上限。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

继续放置字节

WEAVE_ERROR ContinuePutBytes(
  const uint8_t *buf,
  uint32_t len
)

对 TLV 字节字符串值进行编码。

它应该与 StartPutBytes 搭配使用。

详细信息

参数

`[in] buf`	指向包含要编码的字节字符串的缓冲区的指针。
`[in] len`	要编码的字节数。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_INVALID_TLV_TAG`	指定的标记值在写入值的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

复制容器

WEAVE_ERROR CopyContainer(
  TLVReader & container
)

从 TLVReader 对象中复制 TLV 容器元素。

CopyContainer() 通过复制位于 TLVReader 对象的当前位置的预编码容器元素，对新的 TLV 容器元素进行编码。该方法通过一次调用写入整个新容器元素，同时复制源编码的容器类型、标记和元素。该方法返回后，写入对象可用于写入容器元素之后的其他 TLV 元素。

详细信息

参数

[in] container

引用一个 TLVReader 对象，以标识要复制的预编码 TLV 容器。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INCORRECT_STATE`	提供的读取器未放置在容器元素上。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_TLV_UNDERRUN`	与提供的读取器关联的底层 TLV 编码提前结束。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	提供的读取器遇到无效或不受支持的 TLV 元素类型。
`WEAVE_ERROR_INVALID_TLV_TAG`	提供的读取器在无效的上下文中遇到 TLV 标记，或者与源容器关联的标记在写入新容器的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	由已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数，或与读取器对象关联的 GetNextBuffer() 函数返回的其他 Weave 或平台错误。

复制容器

WEAVE_ERROR CopyContainer(
  uint64_t tag,
  TLVReader & container
)

对一组预编码的成员元素中的 TLV 容器元素进行编码。

CopyContainer() 方法会对一个新的 TLV 容器元素（一种结构、数组或路径）进行编码，该元素包含一组从 TLVReader 对象中获取的成员元素。调用该方法时，提供的读取器对象应定位在 TLV 容器元素上。新编码的容器将与输入容器的类型和成员相同。系统会将新容器的代码指定为输入参数。

该方法返回后，写入对象可用于写入容器元素之后的其他 TLV 元素。

详细信息

参数

`[in] tag`	使用容器进行编码的 TLV 代码，或者在没有代码的情况下对容器进行编码时使用 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] container`	引用一个 TLVReader 对象，该对象用于标识应复制其类型和成员的预编码 TLV 容器。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INCORRECT_STATE`	提供的读取器未放置在容器元素上。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_TLV_UNDERRUN`	与提供的读取器关联的底层 TLV 编码提前结束。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	提供的读取器遇到无效或不受支持的 TLV 元素类型。
`WEAVE_ERROR_INVALID_TLV_TAG`	所提供的读取器在无效上下文中遇到 TLV 标记，或者提供的标记在写入新容器的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	由已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数，或与读取器对象关联的 GetNextBuffer() 函数返回的其他 Weave 或平台错误。

复制容器

WEAVE_ERROR CopyContainer(
  uint64_t tag,
  const uint8_t *encodedContainer,
  uint16_t encodedContainerLen
)

对包含预编码容器中成员元素的 TLV 容器元素进行编码。

CopyContainer() 方法会对一个新的 TLV 容器元素（结构、数组或路径）进行编码，该元素包含一组从提供的预编码容器内容中提取的成员元素。调用该方法时，所提供的输入缓冲区中的数据将被解析为 TLV 容器元素，并会写入与输入容器具有相同类型和成员的新容器。系统会将新容器的代码指定为输入参数。

该方法返回后，写入对象可用于写入容器元素之后的其他 TLV 元素。

详细信息

参数

`[in] tag`	使用容器进行编码的 TLV 代码，或者在没有代码的情况下对容器进行编码时使用 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] encodedContainer`	一个缓冲区，其中包含应复制其类型和成员的预编码 TLV 容器。
`[in] encodedContainerLen`	预编码容器的长度（以字节为单位）。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_TLV_UNDERRUN`	编码容器提前结束。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	编码容器包含无效或不受支持的 TLV 元素类型。
`WEAVE_ERROR_INVALID_TLV_TAG`	编码容器包含的 TLV 标记在无效的上下文中，或者提供的标记在写入新容器的上下文中无效或不合适。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	由已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数，或与读取器对象关联的 GetNextBuffer() 函数返回的其他 Weave 或平台错误。

复制元素

WEAVE_ERROR CopyElement(
  TLVReader & reader
)

将 TLV 元素从读取器对象复制到写入器。

CopyElement() 方法可对新的 TLV 元素进行编码，该元素的类型、标记和值取自 TLVReader 对象。调用该方法时，提供的读取器对象应定位在源 TLV 元素上。新编码的元素将具有与输入容器相同的类型、标记和内容。如果提供的元素是 TLV 容器（结构、数组或路径），则容器的全部内容都将被复制。

详细信息

参数

[in] reader

对 TLVReader 对象的引用，该对象用于标识应复制的预编码 TLV 元素。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INCORRECT_STATE`	提供的读取器未定位在元素上。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_TLV_UNDERRUN`	与提供的读取器关联的底层 TLV 编码提前结束。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	提供的读取器遇到无效或不受支持的 TLV 元素类型。
`WEAVE_ERROR_INVALID_TLV_TAG`	所提供的读取器在无效上下文中遇到 TLV 标记，或者提供的标记在写入新容器的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	由已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数，或与读取器对象关联的 GetNextBuffer() 函数返回的其他 Weave 或平台错误。

复制元素

WEAVE_ERROR CopyElement(
  uint64_t tag,
  TLVReader & reader
)

结束容器

WEAVE_ERROR EndContainer(
  TLVType outerContainerType
)

用于完成 TLV 容器元素的编码。

EndContainer() 方法可完成 TLV 容器元素的编码，并在之前调用 StartContainer() 后恢复 TLVWrite 对象的状态。每次调用 StartContainer() 时，应用都必须对 EndContainer() 进行相应的调用，并传递 StartContainer() 调用返回的 TLVType 值。当 EndContainer() 返回时，写入器对象可用于写入容器元素后面的其他 TLV 元素。

注意：对 StartContainer() 和 EndContainer() 的调用之间对写入程序配置所做的任何更改都不会撤消。例如，容器完成时，对隐式配置文件 ID (ImplicitProfileId) 的更改不会撤消。因此，应用有责任在适当的时间相应地调整配置。

详细信息

参数

[in] outerContainerType

StartContainer() 方法返回的 TLVType 值。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_INCORRECT_STATE`	未进行相应的 StartContainer() 调用。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

完成

WEAVE_ERROR Finalize(
  void
)

完成 TLV 编码的写入工作。

Finalize() 方法完成将 TLV 编码写入底层输出缓冲区的过程。该方法必须由应用调用，然后才能使用缓冲区的内容。只有在没有针对当前写入者打开容器写入器时，才能调用 Finalize()。（请参阅 OpenContainer()）。

详细信息

返回值

`WEAVE_NO_ERROR`	编码是否已成功敲定。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`other`	已配置的 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

GetContainerType

TLVType GetContainerType(
  void
) const

返回 TLVWriter 当前写入的容器类型。

GetContainerType() 方法会返回 TLVWriter 当前写入所在的 TLV 容器的类型。如果 TLVWriter 不写入容器内的元素（即，在编码的最外层写入），则该方法会返回 kTLVType_NotSpecified。

详细信息
返回值	当前容器的 TLVType，如果 TLVWriter 未写入容器内的元素，则返回 kTLVType_NotSpecified。

获取长度

uint32_t GetLengthWritten(
  void
)

返回写入器自初始化以来写入的总字节数。

详细信息
返回值	自写入器初始化后写入的总字节数。

Init

void Init(
  uint8_t *buf,
  uint32_t maxLen
)

初始化 TLVWriter 对象，以写入单个输出缓冲区。

详细信息

参数

`[in] buf`	指向应写入 TLV 的缓冲区的指针。
`[in] maxLen`	应写入输出缓冲区的最大字节数。

Init

void Init(
  PacketBuffer *buf,
  uint32_t maxLen
)

初始化 TLVWriter 对象，以写入单个 PacketBuffer。

写入操作在提供的缓冲区中现有数据的最后一个字节之后立即开始。

详细信息

参数

`[in] buf`	指向应将数据包写入 TLV 的 PacketBuffer 的指针。
`[in] maxLen`	应写入输出缓冲区的最大字节数。

Init

void Init(
  PacketBuffer *buf,
  uint32_t maxLen,
  bool allowDiscontiguousBuffers
)

初始化 TLVWriter 对象，以写入一个或多个 PacketBuffer。

写入操作会紧跟指定缓冲区中现有数据的最后一个字节写入。如果 allowDiscontiguousBuffers 为 true，系统会根据需要分配其他 PacketBuffer，并将其链接到提供的缓冲区，以适应写入的数据量。如果指定的输出缓冲区已经是缓冲区链的头，系统会将输出写入该链中的后续缓冲区，然后再分配任何新的缓冲区。

详细信息

参数

`[in] buf`	指向应将数据包写入 TLV 数据的 PacketBuffer 指针。
`[in] maxLen`	应写入输出缓冲区的最大字节数。
`[in] allowDiscontiguousBuffers`	如果为 true，则将数据写入 PacketBuffer 链，根据需要分配新的缓冲区以存储写入的数据。如果为 false，如果写入的数据超过初始输出缓冲区中的可用空间，则写入将会失败，并显示 WEAVE_ERROR_BUFFER_TOO_SMALL。

InitMalloced

void InitMalloced(
  uint8_t *& outBuf,
  uint32_t initialBufSize,
  uint32_t maxLen
)

初始化 TLVWriter 对象，以写入动态缓冲区。

详细信息

参数

`[in] buf`	引用将接收分配的缓冲区的指针。
`[in] maxLen`	应写入输出缓冲区的最大字节数。
`[in] initialBufSize`	应分配给缓冲区的初始字节数。

OpenContainer

WEAVE_ERROR OpenContainer(
  uint64_t tag,
  TLVType containerType,
  TLVWriter & containerWriter
)

初始化新的 TLVWriter 对象，以写入 TLV 容器元素的成员。

OpenContainer() 方法用于将 TLV 容器元素（结构、数组或路径）写入编码。该方法接受新容器的类型和标记（如果有），以及对新写入的对象（容器写入者）的引用，该对象将被写入以写入容器的元素。应用使用容器写入器写入新容器的成员，然后调用 CloseContainer() 完成容器编码。

当容器写入器打开时，应用不得调用或以其他方式更改父写入器的状态。

容器写入器从父写入器继承各种配置属性。这些概念包括：

隐式配置文件 ID (ImplicitProfileId)
应用数据指针 (AppData)
GetNewBuffer 和 FinalizeBuffer 函数指针

详细信息

参数

`[in] tag`	使用容器进行编码的 TLV 代码，或者在没有代码的情况下对容器进行编码时使用 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] containerType`	要编码的容器类型。必须是 `kTLVType_Structure`、`kTLVType_Array` 或 `kTLVType_Path` 中的一个。
`[out] containerWriter`	对 TLVWriter 对象的引用，该对象将用于写入新容器元素的成员。与提供的对象相关联的任何数据都会被覆盖。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	为 ContainerType 指定的值不正确。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_INVALID_TLV_TAG`	指定的标记值在写入值的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

放置

WEAVE_ERROR Put(
  uint64_t tag,
  int8_t v
)

对带 TLV 符号的整数值进行编码。

这是一个过载成员函数，旨在提供便利。它在上述参数中只接受一个参数，

详细信息

参数

`[in] tag`	要用该值编码的 TLV 标记，如果值应该不使用标记进行编码，则为 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] v`	要编码的值。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_INVALID_TLV_TAG`	指定的标记值在写入值的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

放置

WEAVE_ERROR Put(
  uint64_t tag,
  int8_t v,
  bool preserveSize
)

对带 TLV 符号的整数值进行编码。

这是一个过载成员函数，旨在提供便利。它在上述参数中只接受一个参数，

详细信息

参数

`[in] tag`	要用该值编码的 TLV 标记，如果值应该不使用标记进行编码，则为 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] v`	要编码的值。
`[in] preserveSize`	如果值应编码为与输入类型相同的字节数，则为 True。如果应将值编码为表示该值所需的最小字节数，则为 false。注意：强烈建议应用将此参数设置为 false。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_INVALID_TLV_TAG`	指定的标记值在写入值的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

放置

WEAVE_ERROR Put(
  uint64_t tag,
  int16_t v
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  int16_t v,
  bool preserveSize
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  int32_t v
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  int32_t v,
  bool preserveSize
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  int64_t v
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  int64_t v,
  bool preserveSize
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  uint8_t v
)

对 TLV 无符号整数值进行编码。

这是一个过载成员函数，旨在提供便利。它在上述参数中只接受一个参数，

详细信息

参数

`[in] tag`	要用该值编码的 TLV 标记，如果值应该不使用标记进行编码，则为 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] v`	要编码的值。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_INVALID_TLV_TAG`	指定的标记值在写入值的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

放置

WEAVE_ERROR Put(
  uint64_t tag,
  uint8_t v,
  bool preserveSize
)

对 TLV 无符号整数值进行编码。

这是一个过载成员函数，旨在提供便利。它在上述参数中只接受一个参数，

详细信息

参数

`[in] tag`	要用该值编码的 TLV 标记，如果值应该不使用标记进行编码，则为 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] v`	要编码的值。
`[in] preserveSize`	如果值应编码为与输入类型相同的字节数，则为 True。如果应将值编码为表示该值所需的最小字节数，则为 false。注意：强烈建议应用将此参数设置为 false。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_INVALID_TLV_TAG`	指定的标记值在写入值的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

放置

WEAVE_ERROR Put(
  uint64_t tag,
  uint16_t v
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  uint16_t v,
  bool preserveSize
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  uint32_t v
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  uint32_t v,
  bool preserveSize
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  uint64_t v
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  uint64_t v,
  bool preserveSize
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  float v
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  double v
)

对 TLV 浮点值进行编码。

这是一个过载成员函数，旨在提供便利。它在上述参数中只接受一个参数，

详细信息

参数

`[in] tag`	要用该值编码的 TLV 标记，如果值应该不使用标记进行编码，则为 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] v`	要编码的值。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_INVALID_TLV_TAG`	指定的标记值在写入值的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

PutBoolean

WEAVE_ERROR PutBoolean(
  uint64_t tag,
  bool v
)

对 TLV 布尔值进行编码。

详细信息

参数

`[in] tag`	要用该值编码的 TLV 标记，如果值应该不使用标记进行编码，则为 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] v`	要编码的值。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_INVALID_TLV_TAG`	指定的标记值在写入值的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

PutBytes

WEAVE_ERROR PutBytes(
  uint64_t tag,
  const uint8_t *buf,
  uint32_t len
)

对 TLV 字节字符串值进行编码。

详细信息

参数

`[in] tag`	要用该值编码的 TLV 标记，如果值应该不使用标记进行编码，则为 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] buf`	指向包含要编码的字节字符串的缓冲区的指针。
`[in] len`	要编码的字节数。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_INVALID_TLV_TAG`	指定的标记值在写入值的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

PutNull

WEAVE_ERROR PutNull(
  uint64_t tag
)

对 TLV null 值进行编码。

详细信息

参数

[in] tag

要用该值编码的 TLV 标记，如果值应该不使用标记进行编码，则为 AnonymousTag。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_INVALID_TLV_TAG`	指定的标记值在写入值的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

PutPreEncodedContainer

WEAVE_ERROR PutPreEncodedContainer(
  uint64_t tag,
  TLVType containerType,
  const uint8_t *data,
  uint32_t dataLen
)

对一组预编码的成员元素中的 TLV 容器元素进行编码。

PutPreEncodedContainer() 方法会对一个新的 TLV 容器元素（结构、数组或路径）进行编码，该元素包含一组从预编码缓冲区获取的成员元素。输入缓冲区应包含零个或多个完全编码的 TLV 元素，这些标记符合与特定容器类型关联的规则（例如，结构成员必须包含标记，而数组成员则不能）。

该方法在一次调用中对整个容器元素进行编码。当 PutPreEncodedContainer() 返回时，写入对象可用于写入容器元素之后的其他 TLV 元素。

详细信息

参数

`[in] tag`	使用容器进行编码的 TLV 代码，或者在没有代码的情况下对容器进行编码时使用 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] containerType`	要编码的容器类型。必须是 `kTLVType_Structure`、`kTLVType_Array` 或 `kTLVType_Path` 中的一个。
`[in] data`	指向缓冲区的指针，其中包含零个或多个已编码的 TLV 元素，这些元素将成为新容器的成员。
`[in] dataLen`	`data` 缓冲区中的字节数。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	为 ContainerType 指定的值不正确。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_INVALID_TLV_TAG`	指定的标记值在写入值的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

PutString

WEAVE_ERROR PutString(
  uint64_t tag,
  const char *buf
)

对 TLV UTF8 字符串值进行编码。

详细信息

参数

`[in] tag`	要用该值编码的 TLV 标记，如果值应该不使用标记进行编码，则为 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] buf`	指向以空字符结尾的 UTF-8 字符串的指针。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_INVALID_TLV_TAG`	指定的标记值在写入值的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

PutString

WEAVE_ERROR PutString(
  uint64_t tag,
  const char *buf,
  uint32_t len
)

对 TLV UTF8 字符串值进行编码。

详细信息

参数

`[in] tag`	要用该值编码的 TLV 标记，如果值应该不使用标记进行编码，则为 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] buf`	指向要编码的 UTF-8 字符串的指针。
`[in] len`	要编码的字符串的长度（以字节为单位）。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_INVALID_TLV_TAG`	指定的标记值在写入值的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

PutStringF

WEAVE_ERROR PutStringF(
  uint64_t tag,
  const char *fmt,
  ...
)

根据 TLV 元素中的格式对字符串输出进行编码。

PutStringF 是 sprintf 的模拟，其中输出存储在 TLV 元素中，而不是字符缓冲区。当有扩展的 printf 功能可用时，该函数能够将结果字符串输出到不连续的底层存储空间。该实现支持以下 printf 增强功能：

平台提供了一个基于回调的 vcbprintf，提供了调用自定义回调来替代 makechar。

平台会提供一个名为 vsnprintf_ex 的 vsnprintf 变体，其行为与 vsnprintf 完全相同，只不过它具有省略输出的前 n 个字符的规定。

请注意，虽然基于回调的函数可能最简单且使用的代码最少，但 vsprintf_ex 各种函数的消耗更少。

如果以上两种方法都不可用，但平台提供了 malloc，该函数将分配临时缓冲区来保存输出。当平台既不向 printf 系列提供增强选项也不为 malloc 提供增强时，输出将被截断，使其适合当前 TLV 存储空间中的连续状态

详细信息

参数

`[in] tag`	要用该值编码的 TLV 标记，如果值应该不使用标记进行编码，则为 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] fmt`	用于设置参数列表的格式字符串。遵循与 `printf` 系列函数的格式字符串相同的语法和规则。
`[in] ...`	要在输出值中根据 fmt 设置的参数列表。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`other`	如果对 TLVWriter 方法 `WriteElementHead` 或 `GetNewBuffer` 的底层调用失败，其错误会立即转发给调用堆栈。

起始容器

WEAVE_ERROR StartContainer(
  uint64_t tag,
  TLVType containerType,
  TLVType & outerContainerType
)

开始对新的 TLV 容器元素进行编码。

StartContainer() 方法用于将 TLV 容器元素（结构、数组或路径）写入编码。该方法接受新容器的类型和标记（如果有），以及对 TLVType 值的引用，该值用于在写入容器时保存写入者的当前上下文。

StartContainer() 方法返回后，应用应使用当前的 TLVWriter 对象来写入容器的元素。完成后，应用必须调用 EndContainer() 方法来完成容器的编码。

详细信息

参数

`[in] tag`	使用容器进行编码的 TLV 代码，或者在没有代码的情况下对容器进行编码时使用 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] containerType`	要编码的容器类型。必须是 `kTLVType_Structure`、`kTLVType_Array` 或 `kTLVType_Path` 中的一个。
`[out] outerContainerType`	对将接收写入器上下文的 TLVType 值的引用。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_WRONG_TLV_TYPE`	为 ContainerType 指定的值不正确。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_INVALID_TLV_TAG`	指定的标记值在写入值的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

StartPutBytes

WEAVE_ERROR StartPutBytes(
  uint64_t tag,
  uint32_t totalLen
)

对多个区块中的 TLV 字节字符串进行编码。

它应该与 FollowPutBytes 一起使用。

详细信息

参数

`[in] tag`	要用该值编码的 TLV 标记，如果值应该不使用标记进行编码，则为 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] totalLen`	要编码的字节总数。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`WEAVE_ERROR_TLV_CONTAINER_OPEN`	已针对当前写入者打开容器编写器但尚未关闭。
`WEAVE_ERROR_INVALID_TLV_TAG`	指定的标记值在写入值的上下文中无效或不当。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果写入值超出初始化写入程序时指定的最大字节数限制。
`WEAVE_ERROR_NO_MEMORY`	尝试分配由于缺少内存而输出缓冲区失败。
`other`	已配置的 GetNewBuffer() 或 FinalizeBuffer() 函数返回的其他 Weave 或平台错误。

VPutStringF

WEAVE_ERROR VPutStringF(
  uint64_t tag,
  const char *fmt,
  va_list ap
)

根据 TLV 元素中的格式对字符串输出进行编码。

平台提供了一个基于回调的 vcbprintf，提供了调用自定义回调来替代 makechar。

平台会提供一个名为 vsnprintf_ex 的 vsnprintf 变体，其行为与 vsnprintf 完全相同，只不过它具有省略输出的前 n 个字符的规定。

请注意，虽然基于回调的函数可能最简单且使用的代码最少，但 vsprintf_ex 各种函数的消耗更少。

详细信息

参数

`[in] tag`	要用该值编码的 TLV 标记，如果值应该不使用标记进行编码，则为 `AnonymousTag`。标记值应使用以下标记定义函数之一进行构建：ProfileTag()、ContextTag() 或 CommonTag()。
`[in] fmt`	用于设置参数列表的格式字符串。遵循与 `printf` 系列函数的格式字符串相同的语法和规则。
`[in] ap`	要在输出值中根据 fmt 设置的参数列表。

返回值

`WEAVE_NO_ERROR`	方法是否成功。
`other`	如果对 TLVWriter 方法 `WriteElementHead` 或 `GetNewBuffer` 的底层调用失败，其错误会立即转发给调用堆栈。

公共静态函数

FinalizePacketBuffer

WEAVE_ERROR FinalizePacketBuffer(
  TLVWriter & writer,
  uintptr_t bufHandle,
  uint8_t *bufStart,
  uint32_t dataLen
)

TLVWriter FinalizeBuffer 函数的实现，用于将数据写入 PacketBuffer 链。

使用 TLVWriter 向 PacketBuffer 链写入数据时，FinalizePacketBuffer() 函数会执行必要的完成操作。该函数旨在与 GetNewPacketBuffer() 函数结合使用。

如需详细了解 FinalizePacketBuffer() API 的 API，请参阅 FinalizeBufferFunct 类型定义。

GetNewBuffer_Malloced

WEAVE_ERROR GetNewBuffer_Malloced(
  TLVWriter & writer,
  uintptr_t & bufHandle,
  uint8_t *& bufStart,
  uint32_t & bufLen
)

用于写入动态缓冲区的 TLVWriter GetNewBuffer 函数实现。

GetNewBuffer_Malloced() 函数通过根据需要将底层动态缓冲区的大小加倍以存储编码，为 TLVWriter 提供新的输出空间。该函数旨在分配给 TLVWriter GetNewBuffer 函数指针。

如需详细了解 GetNewBuffer_Malloced() 函数的 API，请参阅 GetNewBufferFunct 类型定义。

GetNewPacketBuffer

WEAVE_ERROR GetNewPacketBuffer(
  TLVWriter & writer,
  uintptr_t & bufHandle,
  uint8_t *& bufStart,
  uint32_t & bufLen
)

TLVWriter GetNewBuffer 函数实现，用于将数据写入 PacketBuffer 链。

GetNewPacketBuffer() 函数通过根据需要分配一个或多个 PacketBuffer 链，为 TLVWriter 提供新的输出空间来存储编码。该函数旨在分配给 TLVWriter GetNewBuffer 函数指针。

请注意，将 GetNewPacketBuffer 与 TLVWriter 结合使用时，还应使用相应的 FinalizePacketBuffer() 函数（或等效函数）来最终确定缓冲区链。

如需详细了解 GetNewPacketBuffer() 函数的 API，请参阅 GetNewBufferFunct 类型定义。

受保护的函数

IsCloseContainerReserved

bool IsCloseContainerReserved(
  void
) const

确定容器是否应在开始 / 打开容器时为 CloseContainer 符号预留空间。

IsContainerOpen

bool IsContainerOpen(
  void
) const

SetCloseContainerReserved

void SetCloseContainerReserved(
  bool aCloseContainerReserved
)

设置容器是否应在开始 / 打开容器时为 CloseContainer 符号预留空间。

SetContainerOpen

void SetContainerOpen(
  bool aContainerOpen
)

写入数据

WEAVE_ERROR WriteData(
  const uint8_t *p,
  uint32_t len
)

写入元素头部

WEAVE_ERROR WriteElementHead(
  TLVElementType elemType,
  uint64_t tag,
  uint64_t lenOrVal
)

写入元素数据

WEAVE_ERROR WriteElementWithData(
  TLVType type,
  uint64_t tag,
  const uint8_t *data,
  uint32_t dataLen
)