nl::Weave::TLV::TLVReader

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

为以 Weave TLV 格式编码的数据提供内存高效的解析器。

摘要

TLVReader 会针对 Weave TLV 数据实现仅前向的“拉取式”解析器。TLVReader 对象以游标的形式运行,可用于遍历一系列 TLV 元素并解读其内容。置于元素上时,应用可以调用读取器的 Get() 方法,查询当前元素的类型和标记,并提取任何关联值。读取器的 Next() 方法用于从一个元素前进到另一个元素。

TLVReader 对象始终位于 TLV 元素之前、之后或之后。首次初始化时,TLVReader 位于编码的第一个元素之前,且紧邻该元素。要开始读取,应用必须首次调用 Next() 方法,将读取器置于第一个元素上。当容器元素遇到结构、数组或路径时,可以使用 OpenContainer()EnterContainer() 方法遍历容器的内容。

当读取器到达 TLV 编码的末尾或容器中的最后一个元素时,它会通过从 Next() 方法返回 WEAVE_END_OF_TLV 错误,向应用发出信号。读取器将继续返回 WEAVE_END_OF_TLV,直到重新初始化或通过 CloseContainer() / ExitContainer() 退出当前容器为止。

TLVReader 对象可以直接从固定输入缓冲区解析数据,也可以解析由一个或多个 PacketBuffer 组成的链中的数据。此外,应用还可以提供 GetNextBuffer 函数,将来自任意来源的数据馈送给读取器,例如套接字或串行端口。

继承

直接已知的子类:
  nl::Weave::Profiles::DataManagement_Current::CircularEventReader
  nl::Weave::TLV::CircularTLVReader

公共类型

GetNextBufferFunct)(TLVReader &reader, uintptr_t &bufHandle, const uint8_t *&bufStart, uint32_t &bufLen) WEAVE_ERROR(*
可用于检索要解析的其他 TLV 数据的函数。

公共属性

AppData
void *
可用于应用特定数据的指针字段。
GetNextBuffer
指向将为 TLVReader 对象生成输入数据的函数的指针。
ImplicitProfileId
uint32_t
用于以隐式形式编码的个人资料标记的个人资料 ID。

受保护的属性

mBufEnd
const uint8_t *
mBufHandle
uintptr_t
mContainerType
mControlByte
uint16_t
mElemLenOrVal
uint64_t
mElemTag
uint64_t
mLenRead
uint32_t
mMaxLen
uint32_t
mReadPoint
const uint8_t *

公共函数

CloseContainer(TLVReader & containerReader)
调用 OpenContainer() 后,完成对 TLV 容器的读取。
DupBytes(uint8_t *& buf, uint32_t & dataLen)
分配并返回包含当前字节或 UTF8 字符串值的缓冲区。
DupString(char *& buf)
分配并返回一个包含当前字节或 UTF8 字符串的以 null 结尾的值的缓冲区。
EnterContainer(TLVType & outerContainerType)
准备一个 TLVReader 对象,用于读取 TLV 容器元素的成员。
ExitContainer(TLVType outerContainerType)
完成 TLV 容器的读取,并准备 TLVReader 对象以读取容器之后的元素。
Get(bool & v)
以布尔值类型获取当前元素的值。
Get(int8_t & v)
获取当前元素的值(8 位有符号整数)。
Get(int16_t & v)
获取当前元素的值(16 位有符号整数)。
Get(int32_t & v)
获取当前元素的值(32 位有符号整数)。
Get(int64_t & v)
获取当前元素的值(64 位有符号整数)。
Get(uint8_t & v)
获取当前元素的值(8 位无符号整数)。
Get(uint16_t & v)
获取当前元素的值(16 位无符号整数)。
Get(uint32_t & v)
获取 32 位无符号整数当前元素的值。
Get(uint64_t & v)
获取 64 位无符号整数当前元素的值。
Get(float & v)
Get(double & v)
获取当前元素的值作为双精度浮点数。
GetBufHandle(void) const
uintptr_t
GetBytes(uint8_t *buf, uint32_t bufSize)
获取当前字节或 UTF8 字符串元素的值。
GetContainerType(void) const
返回 TLVReader 当前正在读取的容器的类型。
GetControlByte(void) const
uint16_t
返回与当前 TLV 元素关联的控制字节。
GetDataPtr(const uint8_t *& data)
获取指向 TLV 字节或 UTF8 字符串元素的初始编码字节的指针。
GetLength(void) const
uint32_t
返回与当前 TLV 元素关联的数据长度。
GetLengthRead(void) const
uint32_t
返回自该读取器初始化后读取的总字节数。
GetReadPoint(void) const
const uint8_t *
获取底层输入缓冲区中与读取器当前位置相对应的点。
GetRemainingLength(void) const
uint32_t
返回在达到最大读取长度之前可读取的总字节数。
GetString(char *buf, uint32_t bufSize)
获取当前字节或 UTF8 字符串元素的值(以 Null 终止的字符串)。
GetTag(void) const
uint64_t
返回与当前 TLV 元素关联的标记。
GetType(void) const
返回当前 TLV 元素的类型。
Init(const TLVReader & aReader)
void
从其他 TLVReader 对象初始化 TLVReader 对象。
Init(const uint8_t *data, uint32_t dataLen)
void
初始化 TLVReader 对象,以从单个输入缓冲区读取数据。
Init(PacketBuffer *buf, uint32_t maxLen)
void
初始化 TLVReader 对象,以从单个 PacketBuffer 读取数据。
Init(PacketBuffer *buf, uint32_t maxLen, bool allowDiscontiguousBuffers)
void
初始化 TLVReader 对象,以从一个或多个 PacketBuffers 读取数据。
Next(void)
TLVReader 对象推进到要读取的下一个 TLV 元素。
Next(TLVType expectedType, uint64_t expectedTag)
TLVReader 对象推进到要读取的下一个 TLV 元素,并断言新元素的类型和标记。
OpenContainer(TLVReader & containerReader)
初始化新的 TLVReader 对象,用于读取 TLV 容器元素的成员。
Skip(void)
TLVReader 对象推进到当前 TLV 元素之后。
VerifyEndOfContainer(void)
验证 TVLReader 对象是否位于 TLV 容器的末尾。

受保护的函数

ClearElementState(void)
void
清除 TLVReader 的状态。
ElementType(void) const
TLVElementType
这是一个私有方法,用于从 mControlByte 返回 TLVElementType。
EnsureData(WEAVE_ERROR noDataErr)
GetElementHeadLength(uint8_t & elemHeadBytes) const
这是用于计算 TLV 元素头部长度的私有方法。
IsContainerOpen(void) const
bool
ReadData(uint8_t *buf, uint32_t len)
ReadElement(void)
ReadTag(TLVTagControl tagControl, const uint8_t *& p)
uint64_t
SetContainerOpen(bool aContainerOpen)
void
SkipData(void)
通过在没有目标缓冲区的情况下读取数据来跳过当前 TLV 中包含的任何数据。
SkipToEndOfContainer(void)
VerifyElement(void)

受保护的静态函数

FailGetNextBuffer(TLVReader & reader, uintptr_t & bufHandle, const uint8_t *& bufStart, uint32_t & bufLen)
GetNextPacketBuffer(TLVReader & reader, uintptr_t & bufHandle, const uint8_t *& bufStart, uint32_t & bufLen)

公共类型

GetNextBufferFunct

WEAVE_ERROR(* GetNextBufferFunct)(TLVReader &reader, uintptr_t &bufHandle, const uint8_t *&bufStart, uint32_t &bufLen)

可用于检索要解析的其他 TLV 数据的函数。

此类函数用于向 TLVReader 馈送输入数据。被调用时,该函数应生成其他数据供读取器进行解析或告知读取器没有更多可用数据。

详细信息
参数
[in] reader
对请求输入数据的 TLVReader 对象的引用。
[in,out] bufHandle
对 uintptr_t 值的引用,函数可以使用该值在调用之间存储上下文数据。在第一次调用之前,该值初始化为 0。
[in,out] bufStart
对数据指针的引用。进入函数时,bufStart 指向读取器使用的最后一个 TLV 数据字节之后的一个字节。退出时,bufStart 应指向要解析的新 TLV 数据的第一个字节。新的指针值可以与之前使用的数据位于同一缓冲区内,也可以指向一个全新的缓冲区。
[out] bufLen
对无符号整数的引用,函数必须将它设为要返回的 TLV 数据字节数。如果到达输入 TLV 数据的末尾,函数应将此值设为 0。
返回值
WEAVE_NO_ERROR
如果函数成功生成了更多 TLV 数据,或者已到达输入数据末尾(在本例中,bufLen 应设为 0)。
other
其他 Weave 或平台特定的错误代码,表示发生了错误,导致函数无法生成请求的数据。

公共属性

AppData

void * AppData

可用于应用特定数据的指针字段。

GetNextBuffer

GetNextBufferFunct GetNextBuffer

指向将为 TLVReader 对象生成输入数据的函数的指针。

如果设置为 NULL(默认值),读取器会假定没有其他输入数据可用。

GetNextBuffer 可由应用随时设置,但通常在读取器初始化时进行设置。

如需详细了解如何实现 GetNextBuffer 函数,请参阅 GetNextBufferFunct 类型定义。

ImplicitProfileId

uint32_t ImplicitProfileId

用于以隐式形式编码的个人资料标记的个人资料 ID。

当读取器遇到以隐式形式编码的个人资料专属标记时,它会将 ImplicitProfileId 属性的值用作该标记的假定个人资料 ID。

默认情况下,ImplicitProfileId 属性设置为 kProfileIdNotSpecified。对包含隐式编码标记的 TLV 进行解码时,应用必须先设置 ImplicitProfileId,然后才能读取具有此类标记的 TLV 元素。TLV合适的个人资料 ID 通常取决于正在使用的应用程序的上下文或使用的协议。

如果在将 ImplicitProfileId 设为 kProfileIdNotSpecified 时遇到隐式编码的标记,读取器会返回 WEAVE_ERROR_UNKNOWN_IMPLICIT_TLV_TAG 错误。

受保护的属性

mBufEnd

const uint8_t * mBufEnd

mBufHandle

uintptr_t mBufHandle

mContainerType

TLVType mContainerType

mControlByte

uint16_t mControlByte

mElemLenOrVal

uint64_t mElemLenOrVal

mElemTag

uint64_t mElemTag

mLenRead

uint32_t mLenRead

mMaxLen

uint32_t mMaxLen

mReadPoint

const uint8_t * mReadPoint

公共函数

CloseContainer

WEAVE_ERROR CloseContainer(
  TLVReader & containerReader
)

调用 OpenContainer() 后,完成对 TLV 容器的读取。

调用 OpenContainer() 后,CloseContainer() 方法会恢复父 TLVReader 对象的状态。对于对 OpenContainer() 的每次调用,应用必须对 CloseContainer() 进行相应的调用,并将对同一容器读取器的引用传递给这两种方法。

CloseContainer() 返回时,父读取器将放置在紧随容器之后的第一个元素之前。从此时开始,应用可以使用 Next() 方法遍历所有剩余元素。

无论底层容器中的所有元素是否已读取,应用都可以随时对父读取器调用关闭 CloseContainer()。调用 CloseContainer() 后,应用应将容器读取器视为“de-initialized”并且不得在未重新初始化它的情况下进一步使用它。

详细信息
参数
[in] containerReader
对提供给 OpenContainer() 方法的 TLVReader 对象的引用。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_INCORRECT_STATE
如果未对读取器调用 OpenContainer(),或者容器读取器与传递给 OpenContainer() 方法的读取器不匹配。
WEAVE_ERROR_TLV_UNDERRUN
底层 TLV 编码提前结束。
WEAVE_ERROR_INVALID_TLV_ELEMENT
如果读取器遇到无效或不受支持的 TLV 元素类型。
WEAVE_ERROR_INVALID_TLV_TAG
如果读者在无效上下文中遇到 TLV 标记。
other
由配置的 GetNextBuffer() 函数返回的其他 Weave 或平台错误代码。仅当 GetNextBuffer 为非 NULL 时可能。

DupBytes

WEAVE_ERROR DupBytes(
  uint8_t *& buf,
  uint32_t & dataLen
)

分配并返回包含当前字节或 UTF8 字符串值的缓冲区。

该方法会为与当前位置的 byte 或 UTF-8 字符串元素关联的数据创建缓冲区,并传回数据副本。缓冲区的内存通过 malloc() 获取,并且当不再需要时应由调用方通过 free() 释放。

详细信息
参数
[out] buf
对某个指针的引用,在操作成功时,将为其分配 dataLen 字节的堆分配缓冲区。
[out] dataLen
成功时 buf 的存储空间引用(以字节为单位)。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_WRONG_TLV_TYPE
如果当前元素不是 TLV 字节或 UTF8 字符串,或者读取器不在某个元素上。
WEAVE_ERROR_NO_MEMORY
如果无法为输出缓冲区分配内存。
WEAVE_ERROR_TLV_UNDERRUN
底层 TLV 编码提前结束。
WEAVE_ERROR_UNSUPPORTED_WEAVE_FEATURE
如果目标平台不支持 malloc() 和 free()。
other
由配置的 GetNextBuffer() 函数返回的其他 Weave 或平台错误代码。仅当 GetNextBuffer 为非 NULL 时可能。

DupString

WEAVE_ERROR DupString(
  char *& buf
)

分配并返回一个包含当前字节或 UTF8 字符串的以 null 结尾的值的缓冲区。

该方法会为与当前位置的字节或 UTF-8 字符串元素关联的数据创建缓冲区,并返回以 null 结尾的数据副本。缓冲区的内存通过 malloc() 获取,并且当不再需要时应由调用方通过 free() 释放。

详细信息
参数
[out] buf
对一个指针的引用,在操作成功时,将会为其分配一个的堆分配缓冲区。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_WRONG_TLV_TYPE
如果当前元素不是 TLV 字节或 UTF8 字符串,或者读取器不在某个元素上。
WEAVE_ERROR_NO_MEMORY
如果无法为输出缓冲区分配内存。
WEAVE_ERROR_TLV_UNDERRUN
底层 TLV 编码提前结束。
WEAVE_ERROR_UNSUPPORTED_WEAVE_FEATURE
如果目标平台不支持 malloc() 和 free()。
other
由配置的 GetNextBuffer() 函数返回的其他 Weave 或平台错误代码。仅当 GetNextBuffer 为非 NULL 时可能。

EnterContainer

WEAVE_ERROR EnterContainer(
  TLVType & outerContainerType
)

准备一个 TLVReader 对象,用于读取 TLV 容器元素的成员。

EnterContainer() 方法会准备当前的 TLVReader 对象,以开始读取 TLV 容器(结构、数组或路径)的成员元素。每次调用 EnterContainer() 时,应用都必须对 ExitContainer() 进行相应的调用。

调用 EnterContainer() 时,必须将 TLVReader 对象放置在要读取的容器元素上。该方法将对 TLVType 值的引用作为参数,该值将用于在读者读取容器时保存读者的上下文。

EnterContainer() 方法返回时,读取器将被放置在容器的第一个成员之前。反复调用 Next() 会使读取器遍历集合的成员,直到到达终点,此时读取器将返回 WEAVE_END_OF_TLV。

应用读取完容器后,即可通过调用 ExitContainer() 方法在容器之后继续读取元素。

详细信息
参数
[out] outerContainerType
对将接收读者上下文的 TLVType 值的引用。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_INCORRECT_STATE
当前元素未放置在容器元素上。

ExitContainer

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

完成 TLV 容器的读取,并准备 TLVReader 对象以读取容器之后的元素。

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

ExitContainer() 返回时,读取器将被放置在容器之后的第一个元素之前,且紧邻该元素。从此时开始,应用可以使用 Next() 方法遍历所有剩余元素。

调用 EnterContainer() 后,应用可以随时对读取器调用 ExitContainer(),无论底层容器中的所有元素是否已读取。

详细信息
参数
[in] outerContainerType
EnterContainer() 方法返回的 TLVType 值。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_INCORRECT_STATE
如果未对读取器调用 OpenContainer(),或者容器读取器与传递给 OpenContainer() 方法的读取器不匹配。
WEAVE_ERROR_TLV_UNDERRUN
底层 TLV 编码提前结束。
WEAVE_ERROR_INVALID_TLV_ELEMENT
如果读取器遇到无效或不受支持的 TLV 元素类型。
WEAVE_ERROR_INVALID_TLV_TAG
如果读者在无效上下文中遇到 TLV 标记。
other
由配置的 GetNextBuffer() 函数返回的其他 Weave 或平台错误代码。仅当 GetNextBuffer 为非 NULL 时可能。

Get

WEAVE_ERROR Get(
  bool & v
)

以布尔值类型获取当前元素的值。

详细信息
参数
[out] v
接收与当前 TLV 元素关联的值。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_WRONG_TLV_TYPE
当前元素不是 TLV 布尔值类型,或者读取器不在某个元素上。

Get

WEAVE_ERROR Get(
  int8_t & v
)

获取当前元素的值(8 位有符号整数)。

如果编码的整数值大于输出数据类型,则所得值将被截断。

详细信息
参数
[out] v
接收与当前 TLV 元素关联的值。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_WRONG_TLV_TYPE
如果当前元素不是 TLV 整数类型(有符号或无符号),或者读取器不在某个元素上。

Get

WEAVE_ERROR Get(
  int16_t & v
)

获取当前元素的值(16 位有符号整数)。

如果编码的整数值大于输出数据类型,则所得值将被截断。

详细信息
参数
[out] v
接收与当前 TLV 元素关联的值。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_WRONG_TLV_TYPE
如果当前元素不是 TLV 整数类型(有符号或无符号),或者读取器不在某个元素上。

Get

WEAVE_ERROR Get(
  int32_t & v
)

获取当前元素的值(32 位有符号整数)。

如果编码的整数值大于输出数据类型,则所得值将被截断。

详细信息
参数
[out] v
接收与当前 TLV 元素关联的值。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_WRONG_TLV_TYPE
如果当前元素不是 TLV 整数类型(有符号或无符号),或者读取器不在某个元素上。

Get

WEAVE_ERROR Get(
  int64_t & v
)

获取当前元素的值(64 位有符号整数)。

如果编码的整数值大于输出数据类型,则所得值将被截断。

详细信息
参数
[out] v
接收与当前 TLV 元素关联的值。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_WRONG_TLV_TYPE
如果当前元素不是 TLV 整数类型(有符号或无符号),或者读取器不在某个元素上。

Get

WEAVE_ERROR Get(
  uint8_t & v
)

获取当前元素的值(8 位无符号整数)。

如果编码的整数值大于输出数据类型,则所得值将被截断。同样,如果编码整数值为负数,则该值将转换为无符号值。

详细信息
参数
[out] v
接收与当前 TLV 元素关联的值。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_WRONG_TLV_TYPE
如果当前元素不是 TLV 整数类型(有符号或无符号),或者读取器不在某个元素上。

Get

WEAVE_ERROR Get(
  uint16_t & v
)

获取当前元素的值(16 位无符号整数)。

如果编码的整数值大于输出数据类型,则所得值将被截断。同样,如果编码整数值为负数,则该值将转换为无符号值。

详细信息
参数
[out] v
接收与当前 TLV 元素关联的值。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_WRONG_TLV_TYPE
如果当前元素不是 TLV 整数类型(有符号或无符号),或者读取器不在某个元素上。

Get

WEAVE_ERROR Get(
  uint32_t & v
)

获取 32 位无符号整数当前元素的值。

如果编码的整数值大于输出数据类型,则所得值将被截断。同样,如果编码整数值为负数,则该值将转换为无符号值。

详细信息
参数
[out] v
接收与当前 TLV 元素关联的值。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_WRONG_TLV_TYPE
如果当前元素不是 TLV 整数类型(有符号或无符号),或者读取器不在某个元素上。

Get

WEAVE_ERROR Get(
  uint64_t & v
)

获取 64 位无符号整数当前元素的值。

如果编码整数值为负数,则值将转换为无符号。

详细信息
参数
[out] v
接收与当前 TLV 元素关联的值。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_WRONG_TLV_TYPE
如果当前元素不是 TLV 整数类型(有符号或无符号),或者读取器不在某个元素上。

Get

WEAVE_ERROR Get(
  float & v
)

Get

WEAVE_ERROR Get(
  double & v
)

获取当前元素的值作为双精度浮点数。

详细信息
参数
[out] v
接收与当前 TLV 元素关联的值。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_WRONG_TLV_TYPE
当前元素不是 TLV 浮点类型,或者读取器不在某个元素上。

GetBufHandle

uintptr_t GetBufHandle(
  void
) const 

GetBytes

WEAVE_ERROR GetBytes(
  uint8_t *buf,
  uint32_t bufSize
)

获取当前字节或 UTF8 字符串元素的值。

要确定所需的输入缓冲区大小,请先调用 GetLength() 方法,然后再调用 GetBytes()

详细信息
参数
[in] buf
指向用于接收字符串数据的缓冲区的指针。
[in] bufSize
buf 所指向的缓冲区的大小(以字节为单位)。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_WRONG_TLV_TYPE
如果当前元素不是 TLV 字节或 UTF8 字符串,或者读取器不在某个元素上。
WEAVE_ERROR_BUFFER_TOO_SMALL
如果提供的缓冲区太小,无法容纳与当前元素关联的数据。
WEAVE_ERROR_TLV_UNDERRUN
底层 TLV 编码提前结束。
other
由配置的 GetNextBuffer() 函数返回的其他 Weave 或平台错误代码。仅当 GetNextBuffer 为非 NULL 时可能。

GetContainerType

TLVType GetContainerType(
  void
) const 

返回 TLVReader 当前正在读取的容器的类型。

GetContainerType() 方法会返回 TLVReader 在其中读取数据的 TLV 容器的类型。如果 TLVReader 定位在 TLV 编码的最外层(即最外层的 TLV 元素之前、之后或之后),该方法将返回 kTLVType_NotSpecified。

详细信息
返回值
当前容器的 TLVType,或者如果 TLVReader 未放置在容器中,则为 kTLVType_NotSpecified。

GetControlByte

uint16_t GetControlByte(
  void
) const 

返回与当前 TLV 元素关联的控制字节。

理想情况下,没有人需要知道控制字节,只有 TLV 的内部实现才能访问控制字节。然而,访问控制字节对于 TLV调试实用程序(在美观输出 TLV 缓冲区内容时会尝试对标记控制字节进行解码)对于调试目的非常有帮助。

详细信息
返回值
无符号整数,包含与当前 TLV 元素关联的控制字节。如果读取器未置于某个元素上,则返回 kTLVControlByte_NotSpecified。

GetDataPtr

WEAVE_ERROR GetDataPtr(
  const uint8_t *& data
)

获取指向 TLV 字节或 UTF8 字符串元素的初始编码字节的指针。

此方法会返回一个直接指针,该指针指向底层输入缓冲区内已编码的字符串值。要成功,此方法要求整个字符串值都出现在单个缓冲区中。否则,该方法会返回 WEAVE_ERROR_TLV_UNDERRUN。这使得该方法在从多个不连续的缓冲区读取数据时用途有限。

详细信息
参数
[out] data
对常量指针的引用,该指针将接收指向底层字符串数据的指针。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_WRONG_TLV_TYPE
如果当前元素不是 TLV 字节或 UTF8 字符串,或者读取器不在某个元素上。
WEAVE_ERROR_TLV_UNDERRUN
底层 TLV 编码过早结束或当前字符串元素的值未包含在单个连续缓冲区中。
other
由配置的 GetNextBuffer() 函数返回的其他 Weave 或平台错误代码。仅当 GetNextBuffer 为非 NULL 时可能。

GetLength

uint32_t GetLength(
  void
) const 

返回与当前 TLV 元素关联的数据长度。

数据长度仅适用于 UTF8 字符串或字节字符串类型的元素。对于 UTF8 字符串,返回的值是字符串中的字节数,而不是字符数。

详细信息
返回值
与当前 TLV 元素相关联的数据的长度(以字节为单位)。如果当前元素不是 UTF8 字符串或字节字符串,或者读取器不在某个元素上,则为 0。

GetLengthRead

uint32_t GetLengthRead(
  void
) const 

返回自该读取器初始化后读取的总字节数。

详细信息
返回值
自初始化读取器后读取的总字节数。

GetReadPoint

const uint8_t * GetReadPoint(
  void
) const 

获取底层输入缓冲区中与读取器当前位置相对应的点。

详细信息
返回值
指向与读取器当前位置对应的底层输入缓冲区的指针。

GetRemainingLength

uint32_t GetRemainingLength(
  void
) const 

返回在达到最大读取长度之前可读取的总字节数。

详细信息
返回值
在达到读取长度上限之前可读取的总字节数。

GetString

WEAVE_ERROR GetString(
  char *buf,
  uint32_t bufSize
)

获取当前字节或 UTF8 字符串元素的值(以 Null 终止的字符串)。

要确定所需的输入缓冲区大小,请先调用 GetLength() 方法,然后再调用 GetBytes()。输入缓冲区应至少比字符串长度大一个字节,以容纳空字符。

详细信息
参数
[in] buf
指向用于接收字节字符串数据的缓冲区的指针。
[in] bufSize
buf 所指向的缓冲区的大小(以字节为单位)。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_WRONG_TLV_TYPE
如果当前元素不是 TLV 字节或 UTF8 字符串,或者读取器不在某个元素上。
WEAVE_ERROR_BUFFER_TOO_SMALL
如果提供的缓冲区太小,无法容纳与当前元素关联的数据。
WEAVE_ERROR_TLV_UNDERRUN
底层 TLV 编码提前结束。
other
由配置的 GetNextBuffer() 函数返回的其他 Weave 或平台错误代码。仅当 GetNextBuffer 为非 NULL 时可能。

GetTag

uint64_t GetTag(
  void
) const 

返回与当前 TLV 元素关联的标记。

GetTag() 返回的值可与标记实用函数(IsProfileTag()IsContextTag()ProfileIdFromTag() 等)搭配使用,以确定标记的类型并提取各种标记字段值。

详细信息
返回值
一个无符号整数,包含与当前 TLV 元素关联的标记的相关信息。

GetType

TLVType GetType(
  void
) const 

返回当前 TLV 元素的类型。

详细信息
返回值
一个 TLVType 值,用于描述当前 TLV 元素的数据类型。如果读取器不在 TLV 元素上,返回值将是 kTLVType_NotSpecified。

Init

void Init(
  const TLVReader & aReader
)

从其他 TLVReader 对象初始化 TLVReader 对象。

详细信息
参数
[in] aReader
TLVReader 进行初始化的只读引用。

Init

void Init(
  const uint8_t *data,
  uint32_t dataLen
)

初始化 TLVReader 对象,以从单个输入缓冲区读取数据。

详细信息
参数
[in] data
指向包含要解析的 TLV 数据的缓冲区的指针。
[in] dataLen
要解析的 TLV 数据的长度。

Init

void Init(
  PacketBuffer *buf,
  uint32_t maxLen
)

初始化 TLVReader 对象,以从单个 PacketBuffer 读取数据。

解析从缓冲区的起始位置 (buf->DataStart()) 开始,一直到缓冲区中的数据结束(由 buf->Datalen() 表示)或 maxLen 字节完成解析。

详细信息
参数
[in] buf
指向包含要解析的 TLV 数据的 PacketBuffer 的指针。
[in] maxLen
要解析的字节数上限。默认值为输入缓冲区中的数据量。

Init

void Init(
  PacketBuffer *buf,
  uint32_t maxLen,
  bool allowDiscontiguousBuffers
)

初始化 TLVReader 对象,以从一个或多个 PacketBuffers 读取数据。

从初始缓冲区的起始位置 (buf->DataStart()) 开始解析。如果 allowDiscontiguousBuffers 为 true,则读取器会前进到通过其 Next() 指针关联的缓冲区链。解析会一直持续,直到缓冲区链中的所有数据都被耗尽(用 buf->Datalen() 表示)或 maxLen 字节完成解析。

详细信息
参数
[in] buf
指向包含要解析的 TLV 数据的 PacketBuffer 的指针。
[in] maxLen
要解析的字节数上限。默认值为输入缓冲区链中的总数据量。
[in] allowDiscontiguousBuffers
如果为 true,则当当前缓冲区中的所有数据都被消耗完后,前进到链中的下一个缓冲区。如果为 false,则在初始缓冲区结束时停止解析。

下一步

WEAVE_ERROR Next(
  void
)

TLVReader 对象推进到要读取的下一个 TLV 元素。

Next() 方法将读取器对象放置在位于同一包含上下文的 TLV 编码中的下一个元素上。特别是,如果读取器位于 TLV 编码的最外层,调用 Next() 会将读取器前进到下一个最顶层的元素。如果读取器位于 TLV 容器元素(结构、数组或路径)内,调用 Next() 会将读取器前进到容器的下一个成员元素。

由于 Next() 将读取器的动作限制在当前的包含上下文内,因此,当读取器位于容器元素上时,调用 Next() 会使读取器移到容器之上,并跳过其成员元素(以及任何嵌套容器的成员),直到它到达容器之后的第一个元素。

当特定包含内容上下文中没有其他元素时,Next() 方法将返回 WEAVE_END_OF_TLV 错误,并且 Reader 的位置将保持不变。

详细信息
返回值
WEAVE_NO_ERROR
读取器是否成功定位到新元素上。
WEAVE_END_OF_TLV
如果没有其他元素可用。
WEAVE_ERROR_TLV_UNDERRUN
底层 TLV 编码提前结束。
WEAVE_ERROR_INVALID_TLV_ELEMENT
如果读取器遇到无效或不受支持的 TLV 元素类型。
WEAVE_ERROR_INVALID_TLV_TAG
如果读者在无效上下文中遇到 TLV 标记。
WEAVE_ERROR_UNKNOWN_IMPLICIT_TLV_TAG
如果读者遇到相应个人资料 ID 未知的隐式编码 TLV 标记,就会发生此错误。
other
由配置的 GetNextBuffer() 函数返回的其他 Weave 或平台错误代码。仅当 GetNextBuffer 为非 NULL 时可能。

下一步

WEAVE_ERROR Next(
  TLVType expectedType,
  uint64_t expectedTag
)

TLVReader 对象推进到要读取的下一个 TLV 元素,并断言新元素的类型和标记。

Next(TLVType expectedType, uint64_t expectedTag) 方法是一种便捷方法,它的行为与 Next() 相同,但还会验证新 TLV 元素的类型和标记是否与所提供的参数匹配。

详细信息
参数
[in] expectedType
下一个元素的预期数据类型。
[in] expectedTag
下一个元素的预期标记。
返回值
WEAVE_NO_ERROR
读取器是否成功定位到新元素上。
WEAVE_END_OF_TLV
如果没有其他元素可用。
WEAVE_ERROR_WRONG_TLV_TYPE
如果新元素的类型与 expectedType 参数的值不匹配。
WEAVE_ERROR_UNEXPECTED_TLV_ELEMENT
如果与新元素关联的标记与 expectedTag 参数的值不匹配。
WEAVE_ERROR_TLV_UNDERRUN
底层 TLV 编码提前结束。
WEAVE_ERROR_INVALID_TLV_ELEMENT
如果读取器遇到无效或不受支持的 TLV 元素类型。
WEAVE_ERROR_INVALID_TLV_TAG
如果读者在无效上下文中遇到 TLV 标记。
other
由配置的 GetNextBuffer() 函数返回的其他 Weave 或平台错误代码。仅当 GetNextBuffer 为非 NULL 时可能。

OpenContainer

WEAVE_ERROR OpenContainer(
  TLVReader & containerReader
)

初始化新的 TLVReader 对象,用于读取 TLV 容器元素的成员。

OpenContainer() 方法会初始化一个新的 TLVReader 对象,以读取 TLV 容器(结构、数组或路径)的成员元素。调用 OpenContainer() 时,当前的 TLVReader 对象必须放置在要读取的容器元素上。该方法将对新读取器的引用作为其唯一参数,该读取器将初始化为读取容器。此类读取器称为容器读取器,而对 OpenContainer() 调用的读取器称为父级读取器

OpenContainer() 方法返回时,容器读取器将放置在容器的第一个成员之前,且紧邻该元素。对容器读取器调用 Next() 将遍历集合的成员,直到到达结束位置,此时读取器将返回 WEAVE_END_OF_TLV。

当容器读取器处于打开状态时,应用不得对父级读取器进行调用或以其他方式更改它的状态。应用使用完容器读取器后,必须通过对父读取器调用 CloseContainer() 并以参数形式传递容器读取器来将其关闭。应用可以随时关闭容器读取器,无论是否读取底层容器中包含的所有元素。关闭容器读取器后,应用可以继续使用父级读取器。

容器读取器会从父级读取器继承各种配置属性。它们是:

  • 隐式个人资料 ID (ImplicitProfileId)
  • 应用数据指针 (AppData)
  • GetNextBuffer 函数指针

详细信息
参数
[out] containerReader
TLVReader 对象的引用,系统将初始化该对象以读取当前容器元素的成员。与所提供的对象关联的任何数据都会被覆盖。
返回值
WEAVE_NO_ERROR
如果方法执行成功。
WEAVE_ERROR_INCORRECT_STATE
当前元素未放置在容器元素上。

跳过

WEAVE_ERROR Skip(
  void
)

TLVReader 对象推进到当前 TLV 元素之后。

Skip() 方法会将读取器对象放置在当前 TLV 元素之后、紧邻该元素的位置,以便在后续调用 Next() 时将读取器推进到下一个元素。与 Next() 一样,如果在调用时将读取器置于容器元素上,则会跳过该容器的成员。如果读取器未放置在任何元素上,其位置将保持不变。

详细信息
返回值
WEAVE_NO_ERROR
读取器是否成功定位到新元素上。
WEAVE_END_OF_TLV
如果没有其他元素可用。
WEAVE_ERROR_TLV_UNDERRUN
底层 TLV 编码提前结束。
WEAVE_ERROR_INVALID_TLV_ELEMENT
如果读取器遇到无效或不受支持的 TLV 元素类型。
WEAVE_ERROR_INVALID_TLV_TAG
如果读者在无效上下文中遇到 TLV 标记。
other
由配置的 GetNextBuffer() 函数返回的其他 Weave 或平台错误代码。仅当 GetNextBuffer 为非 NULL 时可能。

VerifyEndOfContainer

WEAVE_ERROR VerifyEndOfContainer(
  void
)

验证 TVLReader 对象是否位于 TLV 容器的末尾。

VerifyEndOfContainer() 方法用于验证当前是否在 TLV 容器中没有其他可供读取的 TLV 元素。这是一种便捷方法,效果相当于调用 Next() 并检查返回值为 WEAVE_END_OF_TLV。

详细信息
返回值
WEAVE_NO_ERROR
如果没有要读取的其他 TLV 元素。
WEAVE_ERROR_UNEXPECTED_TLV_ELEMENT
如果在集合中发现了其他 TLV 元素。
WEAVE_ERROR_TLV_UNDERRUN
底层 TLV 编码提前结束。
WEAVE_ERROR_INVALID_TLV_ELEMENT
如果读取器遇到无效或不受支持的 TLV 元素类型。
WEAVE_ERROR_INVALID_TLV_TAG
如果读者在无效上下文中遇到 TLV 标记。
other
由配置的 GetNextBuffer() 函数返回的其他 Weave 或平台错误代码。仅当 GetNextBuffer 为非 NULL 时可能。

受保护的函数

ClearElementState

void ClearElementState(
  void
)

清除 TLVReader 的状态。

此方法用于将读取器定位在第一个 TLV 之前、两个 TLV 之间或最后一个 TLV 之后。

ElementType

TLVElementType ElementType(
  void
) const 

这是一个私有方法,用于从 mControlByte 返回 TLVElementType。

EnsureData

WEAVE_ERROR EnsureData(
  WEAVE_ERROR noDataErr
)

GetElementHeadLength

WEAVE_ERROR GetElementHeadLength(
  uint8_t & elemHeadBytes
) const 

这是用于计算 TLV 元素头部长度的私有方法。

IsContainerOpen

bool IsContainerOpen(
  void
) const 

ReadData

WEAVE_ERROR ReadData(
  uint8_t *buf,
  uint32_t len
)

ReadElement

WEAVE_ERROR ReadElement(
  void
)

ReadTag

uint64_t ReadTag(
  TLVTagControl tagControl,
  const uint8_t *& p
)

SetContainerOpen

void SetContainerOpen(
  bool aContainerOpen
)

SkipData

WEAVE_ERROR SkipData(
  void
)

通过在没有目标缓冲区的情况下读取数据来跳过当前 TLV 中包含的任何数据。

详细信息
返回值
WEAVE_NO_ERROR
读取器是否成功定位在数据末尾。
other
由配置的 GetNextBuffer() 函数返回的其他 Weave 或平台错误代码。仅当 GetNextBuffer 为非 NULL 时可能。

SkipToEndOfContainer

WEAVE_ERROR SkipToEndOfContainer(
  void
)

VerifyElement

WEAVE_ERROR VerifyElement(
  void
)

受保护的静态函数

FailGetNextBuffer

WEAVE_ERROR FailGetNextBuffer(
  TLVReader & reader,
  uintptr_t & bufHandle,
  const uint8_t *& bufStart,
  uint32_t & bufLen
)

GetNextPacketBuffer

WEAVE_ERROR GetNextPacketBuffer(
  TLVReader & reader,
  uintptr_t & bufHandle,
  const uint8_t *& bufStart,
  uint32_t & bufLen
)