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)
|
|
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)
|
公共函数
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() 方法,在容器之后继续读取元素。
具体说明 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
||||||
返回值 |
|
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 )
获取
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 数据,以及修改/删除现有元素或向编码添加新元素。
具体说明 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
||||||
返回值 |
|
Init
WEAVE_ERROR Init( TLVReader & aReader, uint32_t freeLen )
使用 TLVReader 初始化 TLVUpdater 对象。
调用此方法时,TLVReader 所指向的缓冲区中的 TLV 数据将从当前读取点移至缓冲区的末尾。新的私有 TLVReader 对象会初始化为从这个新位置读取数据,同时新的私有 TLVWriter 对象会初始化为写入已释放的缓冲区空间。
请注意,如果 TLVReader 已经位于某个元素“上”,则会先退避到该元素的开头。另请注意,这种退避适用于容器元素,也就是说,如果 TLVReader 已用于调用 EnterContainer(),则没有退避。但是,如果 TLVReader 位于容器元素上,并且 EnterContainer() 尚未调用,那么 TLVReader 对象会退避到容器标头的开头。
输入 TLVReader 对象将在返回之前销毁,并且应用在返回时不得使用相同的对象。
具体说明 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
||||||
返回值 |
|
移动
WEAVE_ERROR Move( void )
Move() 方法会将 TLVUpdater 的读取器所在的当前元素复制到 TLVUpdater 的写入器。应用应调用 Next(),并将 TLVUpdater 的读取器放置在某个元素上,然后再调用此方法。与 TLVReader::Next() 方法一样,如果在调用时读取器位于容器元素上,系统会复制该容器的所有成员。如果读取器未放置在任何元素上,调用此方法时不会有任何变化。
具体说明 | |||||||||
---|---|---|---|---|---|---|---|---|---|
返回值 |
|
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_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 )