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

此页面由 Cloud Translation API 翻译。

nl::编织:TLV::TLVUpdater

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

提供用于读取/添加/删除 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` 使用 TLVReader 初始化 TLVUpdater 对象。
`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`

公共函数

复制元素

WEAVE_ERROR 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
)

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 或平台错误代码。

退出容器

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

用于完成 TLV 容器元素的读取操作，并对输出 TLV 中的 TLV 元素的末尾进行编码。

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

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

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

注意：对 EnterContainer() 和 ExitContainer() 的调用之间对更新程序配置所做的任何更改都不会因调用 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

GetLengthWriter

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
)

使用 TLVReader 初始化 TLVUpdater 对象。

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

请注意，如果 TLVReader 已定位在元素上，则首先会退避到元素的开头。另请注意，此后备功能非常适合容器元素，也就是说，如果 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() 方法返回的其他错误代码。

移至结束

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 错误，读取器的位置将保持不变。

详情

返回值

`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
)

验证容器结束状态

WEAVE_ERROR VerifyEndOfContainer(
  void
)