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

此页面由 Cloud Translation API 翻译。

nl::Weave::TLV::TLVUpdater

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

提供统一的 Reader/Writer 接口，用于修改/添加/删除 TLV 编码中的元素。

摘要

TLVUpdater 是 TLVReader 和 TLVWriter 对象的并集，提供用于修改/删除编码中的数据以及向 TLV 编码添加新元素的接口方法。TLVUpdater 对象实质上就像两个游标，一个用于读取现有编码，另一个用于写入（用于复制现有数据或写入新数据）。

在语义上，TLVUpdater 对象的功能类似于 TLVReader 和 TLVWriter 的并集。TLVUpdater 方法与 TLVReader/TLVWriter 中类似名称的对应方法具有或多或少的相似含义。如果语义上存在差异，则 WeaveTLVUpdater.cpp 中的函数的注释部分会明确记录这些差异。

关于 TLVUpdater 的 PutBytes() 和 PutString() 方法，需要特别注意的一点是，它会使编码处于损坏状态，在发生溢出时仅写入元素标头。应用可以调用 GetRemainingFreeLength()，以确保有足够的可用空间来写入编码。请注意，GetRemainingFreeLength() 只会告诉您可用的空闲字节数，应用无法知道要写入的编码数据的长度。如果发生溢出，PutBytes() 和 PutString() 都会向调用方返回 WEAVE_ERROR_BUFFER_TOO_SMALL。

另请注意，Next() 方法已重载，既跳过当前元素，又将内部读取器前进到下一个元素。由于跳过已编码的元素需要更改内部写入器的可用空间状态变量以反映新的释放空间（通过跳过来实现），因此应用应在其不想回写（相当于跳过当前元素）的 Get() 方法之后对更新程序调用 Next()。

。

公共函数
`CopyElement(TLVReader & reader)`	`WEAVE_ERROR`
`CopyElement(uint64_t tag, TLVReader & reader)`	`WEAVE_ERROR`
`DupBytes(uint8_t *& buf, uint32_t & dataLen)`	`WEAVE_ERROR`
`DupString(char *& buf)`	`WEAVE_ERROR`
`EndContainer(TLVType outerContainerType)`	`WEAVE_ERROR`
`EnterContainer(TLVType & outerContainerType)`	`WEAVE_ERROR` 准备用于读取容器元素的 TLVUpdater 对象。
`ExitContainer(TLVType outerContainerType)`	`WEAVE_ERROR` 完成 TLV 容器元素的读取，并对输出 TLV 中的 TLV 元素的结尾进行编码。
`Finalize(void)`	`WEAVE_ERROR`
`Get(bool & v)`	`WEAVE_ERROR`
`Get(int8_t & v)`	`WEAVE_ERROR`
`Get(int16_t & v)`	`WEAVE_ERROR`
`Get(int32_t & v)`	`WEAVE_ERROR`
`Get(int64_t & v)`	`WEAVE_ERROR`
`Get(uint8_t & v)`	`WEAVE_ERROR`
`Get(uint16_t & v)`	`WEAVE_ERROR`
`Get(uint32_t & v)`	`WEAVE_ERROR`
`Get(uint64_t & v)`	`WEAVE_ERROR`
`Get(float & v)`	`WEAVE_ERROR`
`Get(double & v)`	`WEAVE_ERROR`
`GetBytes(uint8_t *buf, uint32_t bufSize)`	`WEAVE_ERROR`
`GetContainerType(void) const`	`TLVType`
`GetDataPtr(const uint8_t *& data)`	`WEAVE_ERROR`
`GetImplicitProfileId(void)`	`uint32_t`
`GetLength(void) const`	`uint32_t`
`GetLengthRead(void) const`	`uint32_t`
`GetLengthWritten(void)`	`uint32_t`
`GetReader(TLVReader & containerReader)`	`void`
`GetRemainingFreeLength(void)`	`uint32_t`
`GetRemainingLength(void) const`	`uint32_t`
`GetString(char *buf, uint32_t bufSize)`	`WEAVE_ERROR`
`GetTag(void) const`	`uint64_t`
`GetType(void) const`	`TLVType`
`Init(uint8_t *buf, uint32_t dataLen, uint32_t maxLen)`	`WEAVE_ERROR` 初始化 TLVUpdater 对象以修改单个输入缓冲区。
`Init(TLVReader & aReader, uint32_t freeLen)`	`WEAVE_ERROR` 使用 TLVUpdater 初始化 TLVReader 对象。
`Move(void)`	`WEAVE_ERROR` 复制输入 TLV 中的当前元素，以输出 TLV。
`MoveUntilEnd(void)`	`void` 将所有内容从 TLVUpdater 的当前读取点一直移至输入 TLV 缓冲区结束，然后移至输出。
`Next(void)`	`WEAVE_ERROR` 跳过当前元素，并将 TLVUpdater 对象前进到输入 TLV 中的下一个元素。
`Put(uint64_t tag, int8_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, int16_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, int32_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, int64_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint8_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint16_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint32_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint64_t v)`	`WEAVE_ERROR`
`Put(uint64_t tag, int8_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, int16_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, int32_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, int64_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint8_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint16_t v, bool preserveSize)`	`WEAVE_ERROR`
`Put(uint64_t tag, uint32_t v, bool preserveSize)`	`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`
`PutBoolean(uint64_t tag, bool v)`	`WEAVE_ERROR`
`PutBytes(uint64_t tag, const uint8_t *buf, uint32_t len)`	`WEAVE_ERROR`
`PutNull(uint64_t tag)`	`WEAVE_ERROR`
`PutString(uint64_t tag, const char *buf)`	`WEAVE_ERROR`
`PutString(uint64_t tag, const char *buf, uint32_t len)`	`WEAVE_ERROR`
`SetImplicitProfileId(uint32_t profileId)`	`void` 为 TLVUpdater 对象设置隐式个人资料 ID。
`StartContainer(uint64_t tag, TLVType containerType, TLVType & outerContainerType)`	`WEAVE_ERROR`
`VerifyEndOfContainer(void)`	`WEAVE_ERROR`

公共函数

CopyElement

WEAVE_ERROR CopyElement(
  TLVReader & reader
)

CopyElement

WEAVE_ERROR CopyElement(
  uint64_t tag,
  TLVReader & reader
)

DupBytes

WEAVE_ERROR DupBytes(
  uint8_t *& buf,
  uint32_t & dataLen
)

DupString

WEAVE_ERROR DupString(
  char *& buf
)

EndContainer

WEAVE_ERROR EndContainer(
  TLVType outerContainerType
)

EnterContainer

WEAVE_ERROR EnterContainer(
  TLVType & outerContainerType
)

准备用于读取容器元素的 TLVUpdater 对象。

它还会对输出 TLV 中的容器对象的开头进行编码。

EnterContainer() 方法会准备当前的 TLVUpdater 对象，以开始读取 TLV 容器（结构、数组或路径）的成员元素。每次调用 EnterContainer() 时，应用都必须对 ExitContainer() 进行相应的调用。

调用 EnterContainer() 时，TLVUpdater 的读取器必须位于容器元素上。该方法将对 TLVType 值的引用作为参数，该值将用于在更新器读取容器时保存更新程序的上下文。

当 EnterContainer() 方法返回时，更新程序将放置在容器的第一个成员之前、且紧邻该成员的位置。反复调用 Next() 会使更新程序遍历集合中的成员，直至到达结尾，届时该更新程序将返回 WEAVE_END_OF_TLV。

应用读取完容器后，即可通过调用 ExitContainer() 方法在容器之后继续读取元素。

详细信息

参数

[out] outerContainerType

对将接收更新程序上下文的 TLVType 值的引用。

返回值

`WEAVE_NO_ERROR`	如果方法执行成功。
`WEAVE_ERROR_INCORRECT_STATE`	如果 TLVUpdater 读取器未位于容器元素上。
`other`	TLVWriter::StartContainer() 或 TLVReader::EnterContainer() 返回的任何其他 Weave 或平台错误代码。

ExitContainer

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

完成 TLV 容器元素的读取，并对输出 TLV 中的 TLV 元素的结尾进行编码。

ExitContainer() 方法会在调用 EnterContainer() 后恢复 TLVUpdater 对象的状态。每次调用 EnterContainer() 时，应用都必须对 ExitContainer() 进行相应的调用，并传递 EnterContainer() 方法返回的上下文值。

当 ExitContainer() 返回时，TLVUpdater 读取器将放置在输入 TLV 中跟在容器后面的第一个元素之前，且紧邻该元素。从此时开始，应用可以调用 Next() 遍历所有剩余元素。

调用 EnterContainer() 后，应用可以随时在更新程序上调用 ExitContainer()，无论底层容器中的所有元素是否已读取。另请注意，在读取容器中的所有元素之前调用 ExitContainer()，会导致更新后的容器在输出 TLV 中被截断。

注意：调用 ExitContainer() 后，在调用 EnterContainer() 和 ExitContainer() 之间对更新程序配置所做的任何更改都不会撤消。例如，退出容器后，对隐式个人资料 ID (ImplicitProfileId) 的更改不会撤消。因此，应用有责任在适当的时间相应地调整配置。

详细信息

参数

[in] outerContainerType

EnterContainer() 方法返回的 TLVType 值。

返回值

`WEAVE_NO_ERROR`	如果方法执行成功。
`WEAVE_ERROR_TLV_UNDERRUN`	底层 TLV 编码提前结束。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	更新程序遇到无效或不受支持的 TLV 元素类型时抛出的异常。
`WEAVE_ERROR_INVALID_TLV_TAG`	如果更新程序在无效上下文中遇到 TLV 标记。
`other`	TLVWriter::EndContainer() 或 TLVReader::ExitContainer() 返回的任何其他 Weave 或平台错误代码。

完成

WEAVE_ERROR Finalize(
  void
)

Get

WEAVE_ERROR Get(
  bool & v
)

Get

WEAVE_ERROR Get(
  int8_t & v
)

Get

WEAVE_ERROR Get(
  int16_t & v
)

Get

WEAVE_ERROR Get(
  int32_t & v
)

Get

WEAVE_ERROR Get(
  int64_t & v
)

Get

WEAVE_ERROR Get(
  uint8_t & v
)

Get

WEAVE_ERROR Get(
  uint16_t & v
)

Get

WEAVE_ERROR Get(
  uint32_t & v
)

Get

WEAVE_ERROR Get(
  uint64_t & v
)

Get

WEAVE_ERROR Get(
  float & v
)

Get

WEAVE_ERROR Get(
  double & v
)

GetBytes

WEAVE_ERROR GetBytes(
  uint8_t *buf,
  uint32_t bufSize
)

GetContainerType

TLVType GetContainerType(
  void
) const

GetDataPtr

WEAVE_ERROR GetDataPtr(
  const uint8_t *& data
)

GetImplicitProfileId

uint32_t GetImplicitProfileId(
  void
)

GetLength

uint32_t GetLength(
  void
) const

GetLengthRead

uint32_t GetLengthRead(
  void
) const

GetLengthWritten

uint32_t GetLengthWritten(
  void
)

GetReader

void GetReader(
  TLVReader & containerReader
)

GetRemainingFreeLength

uint32_t GetRemainingFreeLength(
  void
)

GetRemainingLength

uint32_t GetRemainingLength(
  void
) const

GetString

WEAVE_ERROR GetString(
  char *buf,
  uint32_t bufSize
)

GetTag

uint64_t GetTag(
  void
) const

GetType

TLVType GetType(
  void
) const

Init

WEAVE_ERROR Init(
  uint8_t *buf,
  uint32_t dataLen,
  uint32_t maxLen
)

初始化 TLVUpdater 对象以修改单个输入缓冲区。

调用此方法时，缓冲区中的 TLV 数据会移至缓冲区的末尾，私有 TLVReader 对象会在此重新定位的缓冲区上初始化。私有 TLVWriter 对象也会在最初可用的可用空间中初始化。应用可以使用 TLVUpdater 对象解析 TLV 数据，以及修改/删除现有元素或向编码添加新元素。

详细信息

参数

`[in] buf`	指向包含要修改的 TLV 数据的缓冲区的指针。
`[in] dataLen`	缓冲区中 TLV 数据的长度。
`[in] maxLen`	缓冲区的总长度。

返回值

`WEAVE_NO_ERROR`	如果方法执行成功。
`WEAVE_ERROR_INVALID_ARGUMENT`	如果缓冲区地址无效。
`WEAVE_ERROR_BUFFER_TOO_SMALL`	如果缓冲区过小。

Init

WEAVE_ERROR Init(
  TLVReader & aReader,
  uint32_t freeLen
)

使用 TLVUpdater 初始化 TLVReader 对象。

调用此方法时，TLVReader 所指向的缓冲区中的 TLV 数据会从当前读取点移到缓冲区的末尾。系统会初始化一个新的私有 TLVReader 对象，以便从这个新位置读取数据，同时初始化新的私有 TLVWriter 对象，以写入释放的缓冲区空间。

请注意，如果 TLVReader 已定位为“on”元素时，系统会先后退到该元素的开头。另请注意，这种退避对容器元素非常有效，也就是说，如果 TLVReader 已经用于调用 EnterContainer()，就没有什么可以退避的了。但是，如果 TLVReader 位于容器元素上，并且尚未调用 EnterContainer()，则 TLVReader 对象会回退到容器标头的起始位置。

输入 TLVReader 对象会在返回前销毁，应用不得在返回时使用同一对象。

详细信息

参数

`[in,out] aReader`	对在返回前销毁的 TLVReader 对象的引用。
`[in] freeLen`	预编码数据缓冲区中可用的可用空间长度（以字节为单位）。

返回值

`WEAVE_NO_ERROR`	如果方法执行成功。
`WEAVE_ERROR_INVALID_ARGUMENT`	如果缓冲区地址无效。
`WEAVE_ERROR_NOT_IMPLEMENTED`	读取器是否在缓冲区链上初始化。

Move

WEAVE_ERROR Move(
  void
)

复制输入 TLV 中的当前元素，以输出 TLV。

Move() 方法会将 TLVUpdater 读取器所在的当前元素复制到 TLVUpdater 的写入器。在调用此方法之前，应用应调用 Next() 并将 TLVUpdater 的读取器放置在元素上。与 TLVReader::Next() 方法一样，如果读取器在调用时位于容器元素上，则会复制该容器的所有成员。如果读取器未置于任何元素上，则调用此方法不会产生任何变化。

详细信息

返回值

`WEAVE_NO_ERROR`	TLVUpdater 读取器是否已成功定位到新元素上。
`WEAVE_END_OF_TLV`	TLVUpdater 的读取器是否指向容器末尾。
`WEAVE_ERROR_INVALID_TLV_ELEMENT`	如果 TLVIpdater 的读取器不在有效的 TLV 元素上。
`other`	返回 TLVReader::Skip() 方法返回的其他错误代码。

MoveUntilEnd

void MoveUntilEnd(
  void
)

将所有内容从 TLVUpdater 的当前读取点一直移至输入 TLV 缓冲区结束，然后移至输出。

此方法支持将所有内容从 TLVUpdater 的当前读取点一直到读取器缓冲区结尾处移动到 TLVUpdater 的写入器。

下一步

WEAVE_ERROR Next(
  void
)

跳过当前元素，并将 TLVUpdater 对象前进到输入 TLV 中的下一个元素。

Next() 方法会跳过输入 TLV 中的当前元素，并将 TLVUpdater 的读取器推进到位于同一包含上下文的下一个元素。特别是，如果读取器位于 TLV 编码的最外层，调用 Next() 会将其推进到下一个最顶层的元素。如果读取器位于 TLV 容器元素（结构、数组或路径）内，调用 Next() 会将其前进到容器的下一个成员元素。

由于 Next() 将读取器的动作限制在当前的包含上下文内，因此，当读取器位于容器元素上时，调用 Next() 会使读取器移到容器之上，并跳过其成员元素（以及任何嵌套容器的成员），直到它到达容器之后的第一个元素。

当特定包含内容上下文中没有其他元素时，Next() 方法将返回 WEAVE_END_OF_TLV 错误，并且 Reader 的位置将保持不变。

详细信息

返回值

`WEAVE_NO_ERROR`	TLVUpdater 读取器是否已成功定位到新元素上。
`other`	返回 TLVReader::Skip() 和 TLVReader::Next() 方法返回的 Weave 或平台错误代码。

放置

WEAVE_ERROR Put(
  uint64_t tag,
  int8_t v
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  int16_t v
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  int32_t v
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  int64_t v
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  uint8_t v
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  uint16_t v
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  uint32_t v
)

放置

WEAVE_ERROR Put(
  uint64_t tag,
  uint64_t v
)

放置

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

放置

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

放置

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

放置

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

放置

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

放置

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

放置

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

放置

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
)

PutBoolean

WEAVE_ERROR PutBoolean(
  uint64_t tag,
  bool v
)

PutBytes

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

PutNull

WEAVE_ERROR PutNull(
  uint64_t tag
)

PutString

WEAVE_ERROR PutString(
  uint64_t tag,
  const char *buf
)

PutString

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

SetImplicitProfileId

void SetImplicitProfileId(
  uint32_t profileId
)

为 TLVUpdater 对象设置隐式个人资料 ID。

此方法会为 TLVUpdater 对象设置隐式个人资料 ID。当要求更新程序对新元素进行编码时，如果与新元素关联的标记的配置文件 ID 与 profileId 的值匹配，则该更新程序将以隐式形式对该标记进行编码，从而在此过程中省略配置文件 ID。

详细信息

参数

[in] profileId

应以隐式形式编码的标记的个人资料 ID。

StartContainer

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

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)