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)
|
|
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)
|
|
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)
|
|
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() 方法继续读取容器之后的元素。
详情 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
||||||
返回值 |
|
退出容器
WEAVE_ERROR ExitContainer( TLVType outerContainerType )
用于完成 TLV 容器元素的读取操作,并对输出 TLV 中的 TLV 元素的末尾进行编码。
在调用 EnterContainer() 后,ExitContainer() 方法会恢复 TLVUpdater 对象的状态。每次调用 EnterContainer() 时,都必须对 ExitContainer() 进行相应的调用,并传递 EnterContainer() 方法返回的上下文值。
当 ExitContainer() 返回时,TLVUpdater 读取器会放置在紧邻输入 TLV 中的容器之后的第一个元素之前。从此时起,应用可以调用 Next() 以遍历所有剩余元素。
调用 EnterContainer() 后,应用可以随时在更新程序上调用 ExitContainer(),无论底层容器中的所有元素是否均已读取。另请注意,在读取容器中的所有元素之前调用 ExitContainer() 将导致更新后的容器在输出 TLV 中被截断。
详情 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||||
返回值 |
|
完成
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 数据,并修改/删除现有元素或向编码中添加新元素。
详情 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
||||||
返回值 |
|
Init
WEAVE_ERROR Init( TLVReader & aReader, uint32_t freeLen )
使用 TLVReader 初始化 TLVUpdater 对象。
调用此方法时,TLVReader 所指向的缓冲区中的 TLV 数据将从当前读取点移至缓冲区末尾。新的私有 TLVReader 对象会初始化为从这个新位置读取数据,同时新的私有 TLVWriter 对象会初始化为向释放的缓冲区空间写入数据。
请注意,如果 TLVReader 已定位在元素上,则首先会退避到元素的开头。另请注意,此后备功能非常适合容器元素,也就是说,如果 TLVReader 已用于调用 EnterContainer(),则无需执行退避操作。但如果 TLVReader 已放置在容器元素上,并且尚未调用 EnterContainer(),那么 TLVReader 对象会退避到容器标头的开头。
输入 TLVReader 对象会在返回之前销毁,应用不得在返回时使用同一对象。
详情 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
||||||
返回值 |
|
Move
WEAVE_ERROR Move( void )
Move() 方法会将 TLVUpdater 的读取器所在的当前元素复制到 TLVUpdater 的写入器。在调用此方法之前,应用应调用 Next() 并在元素上放置 TLVUpdater 的读取器。就像 TLVReader::Next() 方法一样,如果读取器在调用时位于容器元素上,那么容器的所有成员都将被复制。如果读取器不在任何元素上,调用该方法不会有任何变化。
详情 | |||||||||
---|---|---|---|---|---|---|---|---|---|
返回值 |
|
移至结束
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_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。
详情 | |||
---|---|---|---|
参数 |
|
StartContainer
WEAVE_ERROR StartContainer( uint64_t tag, TLVType containerType, TLVType & outerContainerType )