nl::Weave::TLV::WeaveCircularTLVBuffer

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

WeaveCircularTLVBuffer 为 nl::Weave::TLV::TLVWriter 和 nl::Weave::TLVTLVReader 提供循环存储。

摘要

nl::Weave::TLV::TLVWriter 能够将任意数量的 TLV 条目写入 WeaveCircularTLVBuffer，前提是每个 TLV 条目都完全位于提供的存储空间内。nl::Weave::TLV::TLVReader 最多会读取缓冲区的大小，但会调整缓冲区内的回卷。

构造函数和析构函数
WeaveCircularTLVBuffer(uint8_t *inBuffer, size_t inBufferLength)
WeaveCircularTLVBuffer 构造函数。
WeaveCircularTLVBuffer(uint8_t *inBuffer, size_t inBufferLength, uint8_t *inHead)
WeaveCircularTLVBuffer 构造函数。

公共类型
ProcessEvictedElementFunct)(WeaveCircularTLVBuffer &inBuffer, void *inAppData, TLVReader &inReader) WEAVE_ERROR(*
为处理 TLV 元素而调用的函数，然后再从 nl::Weave::TLV::WeaveCircularTLVBuffer 中逐出该元素。

公共属性
mAppData
void *
用户提供的可选上下文，与处理被逐出元素的回调一起使用。
mImplicitProfileId
uint32_t
mProcessEvictedElement
用户提供的可选回调，用于在将相应元素从环形缓冲区中逐出之前对其进行处理。

公共函数
AvailableDataLength(void) const
size_t
DataLength(void) const
size_t
EvictHead(void)
逐出 WeaveCircularTLVBuffer 中最旧的顶级 TLV 元素。
FinalizeBuffer(TLVWriter & ioWriter, uint8_t *inBufStart, uint32_t inBufLen)
在 TLVWriter 的输出完成后，FinalizeBuffer 会调整 WeaveCircularTLVBuffer 状态。
GetNewBuffer(TLVWriter & ioWriter, uint8_t *& outBufStart, uint32_t & outBufLen)
为 TLVWriter 获取额外的空间。
GetNextBuffer(TLVReader & ioReader, const uint8_t *& outBufStart, uint32_t & outBufLen)
为 TLVReader 获取额外的空间。
GetQueue(void) const
uint8_t *
GetQueueSize(void) const
size_t
QueueHead(void) const
uint8_t *
QueueTail(void) const
uint8_t *
SetQueueHead(uint8_t *aQueueHead)
void
SetQueueLength(size_t aQueueLength)
void

公共静态函数
FinalizeBufferFunct(TLVWriter & ioWriter, uintptr_t inBufHandle, uint8_t *inBufStart, uint32_t inBufLen)
GetNewBufferFunct(TLVWriter & ioWriter, uintptr_t & inBufHandle, uint8_t *& outBufStart, uint32_t & outBufLen)
用于为 TLVWriter 提取更多空间的 trampoline。
GetNextBufferFunct(TLVReader & ioReader, uintptr_t & inBufHandle, const uint8_t *& outBufStart, uint32_t & outBufLen)
指向 WeaveCircularTLVBuffer::GetNextBuffer 的 trampoline。

公共类型

ProcessEvictedElementFunct

WEAVE_ERROR(* ProcessEvictedElementFunct)(WeaveCircularTLVBuffer &inBuffer, void *inAppData, TLVReader &inReader)

为处理 TLV 元素而调用的函数，然后再从 nl::Weave::TLV::WeaveCircularTLVBuffer 中逐出该元素。

此类型的函数用于处理即将从缓冲区中逐出的 TLV 元素。该函数将获得一个 nl::Weave::TLV::TLVReader（位于即将删除的元素上），以及用户可能已为回调提供其他环境的 void * 上下文。如果函数成功处理了该元素，则必须返回 WEAVE_NO_ERROR；这表示 WeaveCircularTLVBuffer 可安全逐出该元素。其他任何返回值都将被视为错误，并会阻止 WeaveCircularTLVBuffer 逐出考虑因素的元素。

注意：此回调可用于强制 WeaveCircularTLVBuffer 不逐出元素。这在很多情况下可能很有用，当需要底层环形缓冲区，但不替换其中的任何元素时。

具体说明
参数
[in] inBuffer
对执行逐出的缓冲区的引用
[in] inAppData
指向用户提供的结构的指针，其中包含此回调的其他上下文
[in] inReader
位于要逐出的元素处的 TLVReader。
返回值
WEAVE_NO_ERROR
成功时。将逐出元素。
other
处理事件时发生错误。元素保留在缓冲区中。触发此元素逐出的写入函数将会失败。

公共属性

mAppData

void * mAppData

用户提供的可选上下文，与处理被逐出元素的回调一起使用。

mImplicitProfileId

uint32_t mImplicitProfileId

mProcessEvictedElement

ProcessEvictedElementFunct mProcessEvictedElement

用户提供的可选回调，用于在将相应元素从环形缓冲区中逐出之前对其进行处理。

如需详细了解如何实现 mProcessEvictedElement 函数，请参阅 ProcessEvictedElementFunct 类型定义。

公共函数

AvailableDataLength

size_t AvailableDataLength(
  void
) const

DataLength

size_t DataLength(
  void
) const

EvictHead

WEAVE_ERROR EvictHead(
  void
)

逐出 WeaveCircularTLVBuffer 中最旧的顶级 TLV 元素。

此函数用于移除缓冲区中最早的顶级 TLV 元素。在移除元素之前，该函数会调用在 mProcessEvictedElement 中注册的回调来处理元素。如果回调返回除 WEAVE_NO_ERROR 以外的任何内容，则不会移除该元素。同样，如果发生任何其他错误，缓冲区内没有任何元素等，底层 WeaveCircularTLVBuffer 将保持不变。

具体说明
返回值
WEAVE_NO_ERROR
成功时。
other
当回调或 TLVReader 返回任何其他错误时。

FinalizeBuffer

WEAVE_ERROR FinalizeBuffer(
  TLVWriter & ioWriter,
  uint8_t *inBufStart,
  uint32_t inBufLen
)

在 TLVWriter 的输出完成后，FinalizeBuffer 会调整 WeaveCircularTLVBuffer 状态。

此函数会影响队列尾部的位置。

具体说明
参数
[in,out] ioWriter
TLVWriter 调用此函数
[in] inBufStart
指向数据开头的指针（从 TLVWriter 角度）
[in] inBufLen
inbufStart 所指向的缓冲区中数据的长度
返回值
WEAVE_NO_ERROR
无条件。

GetNewBuffer

WEAVE_ERROR GetNewBuffer(
  TLVWriter & ioWriter,
  uint8_t *& outBufStart,
  uint32_t & outBufLen
)

为 TLVWriter 获取额外的空间。

实际上，该函数会从环形缓冲区中逐出一个元素，并调整此缓冲区队列的头部

具体说明
参数
[in,out] ioWriter
TLVWriter 调用此函数
[out] outBufStart
指向新缓冲区的指针
[out] outBufLen
可用的写入长度
返回值
WEAVE_NO_ERROR
成功时。
other
如果函数无法省略完整的顶级 TLV 元素。

GetNextBuffer

WEAVE_ERROR GetNextBuffer(
  TLVReader & ioReader,
  const uint8_t *& outBufStart,
  uint32_t & outBufLen
)

为 TLVReader 获取额外的空间。

WeaveCircularTLVBuffer 提供的存储空间可环绕在缓冲区内。此函数使我们能够将环形缓冲区的缓冲与 TLVReader 约束条件进行匹配。读取器最多只能从缓冲区读取 mQueueSize 个字节。

具体说明
参数
[in] ioReader
TLVReader 时调用此函数。
[in,out] outBufStart
对数据缓冲区的引用。返回时，它会被设置为此缓冲区中的某个值。
[out] outBufLen
返回时，请将此项设为可从缓冲区读取的连续字节数。
返回值
WEAVE_NO_ERROR
无条件成功。

GetQueue

uint8_t * GetQueue(
  void
) const

GetQueueSize

size_t GetQueueSize(
  void
) const

QueueHead

uint8_t * QueueHead(
  void
) const

QueueTail

uint8_t * QueueTail(
  void
) const

SetQueueHead

void SetQueueHead(
  uint8_t *aQueueHead
)

SetQueueLength

void SetQueueLength(
  size_t aQueueLength
)

WeaveCircularTLVBuffer

 WeaveCircularTLVBuffer(
  uint8_t *inBuffer,
  size_t inBufferLength
)

WeaveCircularTLVBuffer 构造函数。

具体说明
参数
[in] inBuffer
指向队列后备存储空间的指针
[in] inBufferLength
后备存储空间的长度（以字节为单位）

WeaveCircularTLVBuffer

 WeaveCircularTLVBuffer(
  uint8_t *inBuffer,
  size_t inBufferLength,
  uint8_t *inHead
)

WeaveCircularTLVBuffer 构造函数。

具体说明
参数
[in] inBuffer
指向队列后备存储空间的指针
[in] inBufferLength
后备存储空间的长度（以字节为单位）
[in] inHead
头部的初始点。inHead 指针必须位于环形缓冲区的后备存储内，即 inBuffer 和 &(inBuffer[inBufferLength])

公共静态函数

FinalizeBufferFunct

WEAVE_ERROR FinalizeBufferFunct(
  TLVWriter & ioWriter,
  uintptr_t inBufHandle,
  uint8_t *inBufStart,
  uint32_t inBufLen
)

指向 WeaveCircularTLVBuffer::FinalizeBuffer 的 trampoline。

具体说明
参数
[in,out] ioWriter
TLVWriter 调用此函数
[in,out] inBufHandle
CircularTLVWriter 对象的句柄
[in] inBufStart
指向数据开头的指针（从 TLVWriter 角度）
[in] inBufLen
inbufStart 所指向的缓冲区中数据的长度
返回值
WEAVE_NO_ERROR
无条件。

GetNewBufferFunct

WEAVE_ERROR GetNewBufferFunct(
  TLVWriter & ioWriter,
  uintptr_t & inBufHandle,
  uint8_t *& outBufStart,
  uint32_t & outBufLen
)

用于为 TLVWriter 提取更多空间的 trampoline。

具体说明
参数
[in,out] ioWriter
TLVWriter 调用此函数
[in,out] inBufHandle
CircularTLVWriter 对象的句柄
[out] outBufStart
指向新缓冲区的指针
[out] outBufLen
可用的写入长度
返回值
WEAVE_NO_ERROR
成功时。
other
如果函数无法省略完整的顶级 TLV 元素。

GetNextBufferFunct

WEAVE_ERROR GetNextBufferFunct(
  TLVReader & ioReader,
  uintptr_t & inBufHandle,
  const uint8_t *& outBufStart,
  uint32_t & outBufLen
)

指向 WeaveCircularTLVBuffer::GetNextBuffer 的 trampoline。

具体说明
参数
[in,out] ioReader
TLVReader 会调用此函数
[in,out] inBufHandle
CircularTLVWriter 对象的句柄
[in,out] outBufStart
对数据缓冲区的引用。返回时，它会被设置为此缓冲区中的某个值。
[out] outBufLen
返回时，请将此项设为可从缓冲区读取的连续字节数。
返回值
WEAVE_NO_ERROR
无条件成功。