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

此页面由 Cloud Translation API 翻译。

nl::Weave::TLV::TLVWriter

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

提供一个内存高效的编码器，用于以 Weave TLV 格式写入数据。

摘要

TLVWriter 为 Weave TLV 数据实现一种仅限前向流样式的编码器。应用通过调用写入器的 Put() 方法之一，根据需要传递关联的标记和值信息，将数据写入编码。同样，应用可以通过调用写入者的 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` TLVWriterFinalizeBuffer 函数的实现，用于向 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() 方法时，就会调用此类函数。该函数应执行与使用 writer 对象输出相关的所有必要的清理或完成操作。例如记录编码的最终长度，或关闭文件描述符。

具体说明

参数

`[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 或平台特定的错误代码，表示发生错误，导致函数无法生成额外的缓冲区空间。

公共属性

AppData

void * AppData

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

FinalizeBuffer

FinalizeBufferFunct FinalizeBuffer

指向将在 TLVWriter 完成时调用的函数的指针。

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

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

GetNewBuffer

GetNewBufferFunct GetNewBuffer

指向函数的指针，用于向 TLVWriter 提供新的输出缓冲区空间。

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

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

有关实现 GetNewBuffer 函数的更多信息，请参阅 GetNewBufferFunct 类型定义。

ImplicitProfileId

uint32_t ImplicitProfileId

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

当要求写入者对新元素进行编码时，如果与新元素相关联的标记的个人资料 ID 与 ImplicitProfileId 成员的值匹配，则写入者将以隐式形式对该标记进行编码，在此过程中会忽略个人资料 ID。

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

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

受保护的属性

mBufHandle

uintptr_t mBufHandle

mBufStart

uint8_t * mBufStart

mContainerType

TLVType mContainerType

mLenWritten

uint32_t mLenWritten

mMaxLen

uint32_t mMaxLen

mRemainingLen

uint32_t mRemainingLen

mWritePoint

uint8_t * mWritePoint

公共函数

CloseContainer

WEAVE_ERROR CloseContainer(
  TLVWriter & containerWriter
)

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

调用 OpenContainer() 后，CloseContainer() 方法会恢复父 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 或平台特定错误。

ContinuePutBytes

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 或平台特定错误。

CopyContainer

WEAVE_ERROR CopyContainer(
  TLVReader & container
)

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

CopyContainer() 通过复制位于 TLVReader 对象当前位置的预编码容器元素，对新的 TLV 容器元素进行编码。该方法在一次调用中写入整个新容器元素，从而从源编码中复制容器的类型、标记和元素。当该方法返回时，writer 对象可用于写入容器元素之后的其他 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 或平台特定错误。

CopyContainer

WEAVE_ERROR CopyContainer(
  uint64_t tag,
  TLVReader & container
)

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

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

当该方法返回时，writer 对象可用于写入容器元素之后的其他 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 或平台特定错误。

CopyContainer

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

对 TLV 容器元素（其中包含来自预编码容器的成员元素）进行编码。

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

当该方法返回时，writer 对象可用于写入容器元素之后的其他 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 或平台特定错误。

CopyElement

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 或平台特定错误。

CopyElement

WEAVE_ERROR CopyElement(
  uint64_t tag,
  TLVReader & reader
)

EndContainer

WEAVE_ERROR EndContainer(
  TLVType outerContainerType
)

完成对 TLV 容器元素的编码。

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

注意：在调用 StartContainer() 和 EndContainer() 期间对写入器配置所做的任何更改都不会被 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。

GetLengthWritten

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() 返回时，writer 对象可用于写入容器元素之后的其他 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`	指向要编码的以 null 结尾的 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，能够调用自定义回调来代替 putchar。

平台提供了一个名为 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` 的底层调用失败，则其错误会立即向调用堆栈中转发。

StartContainer

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 字节字符串进行编码。

它应与 ContinuePutBytes 一起使用。

具体说明

参数

`[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，能够调用自定义回调来代替 putchar。

平台提供了一个名为 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
)

TLVWriterFinalizeBuffer 函数的实现，用于向 PacketBuffer 链写入数据。

使用 TLVWriter 写入 PacketBuffer 链时，FinalizePacketBuffer() 函数会执行必要的终结。此函数旨在与 GetNewPacketBuffer() 函数结合使用。

如需详细了解 FinalizePacketBuffer() 函数的 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
)

WriteData

WEAVE_ERROR WriteData(
  const uint8_t *p,
  uint32_t len
)

WriteElementHead

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

WriteElementWithData

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