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(*
用于对 TLVWriter 对象的输出执行最终确定的函数。
GetNewBufferFunct)(TLVWriter &writer, uintptr_t &bufHandle, uint8_t *&bufStart, uint32_t &bufLen) WEAVE_ERROR(*
为 TLVWriter 提供新的输出缓冲区空间的函数。

公共属性
AppData
void *
可用于应用特定数据的指针字段。
FinalizeBuffer
指向 TLVWriter 最终确定后将调用的函数的指针。
GetNewBuffer
指向将向 TLVWriter 提供新输出缓冲区空间的函数的指针。
ImplicitProfileId
uint32_t
应以隐式形式编码的标记的个人资料 ID。

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

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

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

受保护的函数
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)
WriteElementHead(TLVElementType elemType, uint64_t tag, uint64_t lenOrVal)
WriteElementWithData(TLVType type, uint64_t tag, const uint8_t *data, uint32_t dataLen)

受保护的类型

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 通常取决于正在使用的应用程序的上下文或使用的协议。

受保护的属性

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() 返回时，应用可以继续使用父 Writer 写入显示在容器元素之后的其他 TLV 元素。此时，提供的容器写入者应被视为“de-initialized”且不得在未重新初始化的情况下使用。

详细信息
参数
[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() 对新的 TLV 容器元素进行编码，方法是复制位于 TLVReader 对象当前位置的预编码容器元素。该方法会在一次调用中写入整个新容器元素，并从源编码中复制容器的类型、标记和元素。当该方法返回时，写入器对象可用于在容器元素之后写入其他 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 容器元素上。新编码的容器将具有与输入容器相同的类型和成员。新容器的代码被指定为输入参数。

当该方法返回时，写入器对象可用于在容器元素之后写入其他 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 容器元素，并写入与输入容器具有相同类型和成员的新容器。新容器的代码被指定为输入参数。

当该方法返回时，写入器对象可用于在容器元素之后写入其他 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 元素。

详细信息
参数
[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 对象以写入一个或多个 PacketBuffers。

在指定缓冲区中现有数据的最后一个字节之后，会立即开始写入。如果 allowDiscontiguousBuffers 为 true，则系统会根据需要分配额外的 PacketBuffers 并将其链接到所提供的缓冲区，以适应写入的数据量。如果指定的输出缓冲区已经是缓冲区链的头部，则在分配任何新缓冲区之前，输出将写入链中的后续缓冲区。

详细信息
参数
[in] buf
指向应将 TLV 数据写入到的 PacketBuffer 的指针。
[in] maxLen
应写入输出缓冲区的字节数上限。
[in] allowDiscontiguousBuffers
如果为 true，则将数据写入 PacketBuffers 链，并根据需要分配新的缓冲区来存储写入的数据。如果设为 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
指向要编码的以 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 元素中的格式对字符串输出进行编码。

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] 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，请参阅 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 函数的实现，用于写入 PacketBuffers 链。

GetNewPacketBuffer() 函数可根据需要分配由一个或多个 PacketBuffers 组成的链，以存储编码，从而为 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
)