nl::编织:TLV::TLVUpdater

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

提供用于读取/添加/删除 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 容器元素的读取操作,并对输出 TLV 中的 TLV 元素的末尾进行编码。
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)

公共函数

复制元素

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 中被截断。

详情
参数
[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
)