nl::Weave::TLV::TLVUpdater

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

提供统一的 Reader/Writer 界面,用于以 TLV 编码修改/添加/删除元素。

摘要

TLVUpdaterTLVReaderTLVWriter 对象的并集,提供了在编码中修改/删除数据以及向 TLV 编码添加新元素的接口方法。TLVUpdater 对象本质上类似于两个游标,一个用于读取现有编码,另一个用于写入(用于复制现有数据或写入新数据)。

在语义上,TLVUpdater 对象的功能类似于 TLVReaderTLVWriter 的并集。TLVUpdater 方法与 TLVReader/TLVWriter 中名称类似的方法基本上具有类似的含义。如果语义存在差异,请在 WeaveTLVUpdater.cpp 中函数的注释部分明确记录差异。

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

另请注意,Next() 方法已重载,不仅会跳过当前元素,还会让内部读取器转到下一个元素。由于跳过已编码的元素需要更改内部写入器的可用空间状态变量以考虑新的释放空间(通过跳过提供空间),因此应用应先在 Get() 方法(其值不想写回,相当于跳过当前元素)之后对更新程序调用 Next()

公共函数

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

公共函数

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 容器元素的读取,并对输出 TLVTLV 元素的结束进行编码。

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

ExitContainer() 返回时,TLVUpdater 读取器会紧挨着输入 TLV 中位于容器之后的第一个元素之前。从此时开始,应用可以调用 Next() 遍历所有剩余元素。

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

具体说明
参数
[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
)

获取

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
)

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
)

使用 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
读取器是否在缓冲区链上初始化。

移动

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

具体说明
返回值
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
)