nl::Weave::系统::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

数据包缓冲区类是用于处理八进制序列化数据包的核心结构,通常在数据通信网络(如蓝牙或互联网协议)环境中。

摘要

在基于 LwIP 的环境中,此类基于该库中定义的 pbuf 结构进行构建。在缺少 LwIP 的情况下,Weave 提供了基于 malloc 的实现或基于池的实现,它可以非常接近深度嵌入式设备的内存挑战。

与分层网络堆栈中使用的许多类似结构一样,PacketBuffer 类提供了一种机制,用于在可配置的通信堆栈的每一层上为协议标头预留空间。如需了解详情,请参阅 PacketBuffer::New() 以及 LwIP 文档。

PacketBuffer 对象会进行引用计数,Weave 中的主导使用模式是“即发即弃”。当数据包(及其底层的 PacketBuffer 对象)通过各种协议层进行分派时,层之间的成功调用或向下调用意味着所有权转移,并且被调用方负责释放缓冲区。如果跨层调用失败,则负责释放缓冲区的责任由调用方负责。

PacketBuffer 类的新对象会在从底层环境(例如从 LwIP pbuf 目标池、标准 C 库堆和内部缓冲区池)获取的内存分配开始时进行初始化。在简单的情况下,数据缓冲区的大小为 WEAVE_SYSTEM_PACKETBUFFER_SIZE。我们提供了一个编辑器,允许使用其他大小的数据缓冲区。

PacketBuffer 对象可以链接起来,以适应较大的载荷。但是链接链并不透明,该类的用户必须明确决定支持链接。以链式支持形式编写的类示例如下:

@ref nl::Weave::WeaveTLVReader
@ref nl::Weave::WeaveTLVWriter

继承

继承自:pbuf

公共函数

AddRef(void)
void
递增当前缓冲区的引用计数。
AddToEnd(PacketBuffer *aPacket)
void
将给定的数据包缓冲区添加到缓冲区链的末尾,并相应地调整链中每个缓冲区的总长度。
AlignPayload(uint16_t aAlignBytes)
bool
在指定字节边界上对齐缓冲区载荷。
AllocSize(void) const
size_t
返回分配的大小,包括预留空间和载荷数据空间,但不包含为 PacketBuffer 结构分配的空间。
AvailableDataLength(void) const
uint16_t
根据当前起始位置和数据长度,获取可添加到当前缓冲区的数据字节数。
CompactHead(void)
void
将链中后续缓冲区中的数据移至当前缓冲区中,直至该缓冲区已满。
Consume(uint16_t aConsumeLength)
消耗缓冲区链中的数据。
ConsumeHead(uint16_t aConsumeLength)
void
调整当前缓冲区以指示已用的数据量。
DataLength(void) const
uint16_t
获取数据包缓冲区中数据的长度(以字节为单位)。
DetachTail(void)
将当前缓冲区与其链分离,并返回一个指向其余缓冲区的指针。
EnsureReservedSize(uint16_t aReservedSize)
bool
确保缓冲区具有至少指定数量的预留空间。
MaxDataLength(void) const
uint16_t
根据当前起始位置和缓冲区大小,获取可存放在缓冲区中的数据的最大量(以字节为单位)。
Next(void) const
获取链中下一个缓冲区的指针。
ReservedSize(void) const
uint16_t
获取缓冲区缓冲区和当前数据起始位置之间当前缓冲区内的字节数。
SetDataLength(uint16_t aNewLen, PacketBuffer *aChainHead)
void
设置缓冲区中数据的长度(以字节为单位),并相应地调整总长度。
SetStart(uint8_t *aNewStart)
void
设置缓冲区中的起始数据,并相应地调整长度和总长度。
Start(void) const
uint8_t *
获取指向缓冲区中数据起始位置的指针。
TotalLength(void) const
uint16_t
获取缓冲区链中数据包数据的总长度。

公共静态函数

Free(PacketBuffer *aPacket)
void
释放链中的所有数据包缓冲区。
FreeHead(PacketBuffer *aPacket)
释放链中的第一个缓冲区,并返回一个指向其余缓冲区的指针。
New(void)
在载荷中分配具有默认预留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) 的默认大小上限 (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) 的单个 PacketBuffer
New(uint16_t aReservedSize)
根据总标头大小分配单个总大小的 PacketBuffer
NewWithAvailableSize(size_t aAvailableSize)
在标头的负载中分配具有默认预留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) 的 PacketBuffer,并在初始光标指针后分配至少 aAllocSize 字节的空间来存储额外数据。
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
分配一个 PacketBuffer 对象,为有效负载预留至少 aReservedSize 字节的标头空间,并在初始光标指针后为其他数据预留至少 aAllocSize 字节的空间。
RightSize(PacketBuffer *aPacket)
将给定的缓冲区复制到适当大小的缓冲区(如果适用)。

公共函数

添加引用

void AddRef(
  void
)

递增当前缓冲区的引用计数。

添加到结束日期

void AddToEnd(
  PacketBuffer *aPacket
)

将给定的数据包缓冲区添加到缓冲区链的末尾,并相应地调整链中每个缓冲区的总长度。

详细信息
参数
[in] aPacket
- 要添加到当前链路末尾的数据包缓冲区。

对齐载荷

bool AlignPayload(
  uint16_t aAlignBytes
)

在指定字节边界上对齐缓冲区载荷。

如有必要,将缓冲区中的载荷向前移动。

详细信息
参数
[in] aAlignBytes
- 指定载荷开始指针的字节数对齐。
返回值
如果对齐成功,则返回 true;如果缓冲区中没有足够的空间,则返回 false

分配大小

size_t AllocSize(
  void
) const 

返回分配的大小,包括预留空间和载荷数据空间,但不包含为 PacketBuffer 结构分配的空间。

详细信息
返回值
分配大小

可用数据长度

uint16_t AvailableDataLength(
  void
) const 

根据当前起始位置和数据长度,获取可添加到当前缓冲区的数据字节数。

详细信息
返回值
根据当前起始位置和数据长度,适合当前缓冲区的数据长度(以字节为单位)。

紧凑型

void CompactHead(
  void
)

将链中后续缓冲区中的数据移至当前缓冲区中,直至该缓冲区已满。

只有当前缓冲区会压缩:当前缓冲区中的数据会移动到缓冲区前端,从而消除所有预留空间。剩余的可用空间填充自链中后续缓冲区的数据,直到当前缓冲区已满。如果链中的后续缓冲区被整个移至当前缓冲区,则会将其从链中移除并释放。该方法不使用任何参数,不返回任何结果,并且不会失败。

使用

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

消耗缓冲区链中的数据。

消耗缓冲区缓冲区中的数据(从当前缓冲区开始,并继续执行链中的剩余缓冲区)。每个已完全用尽的缓冲区都将被释放,并且函数会返回包含剩余数据的第一个缓冲区(如果有)。当前缓冲区必须是缓冲区链的头。

详细信息
参数
[in] aConsumeLength
- 当前链中要消耗的字节数。
返回值
来自当前链的第一个包含任何剩余数据的缓冲区。如果没有剩余数据,则返回 NULL。

消耗头像

void ConsumeHead(
  uint16_t aConsumeLength
)

调整当前缓冲区以指示已用的数据量。

使当前缓冲区中的数据起始位置按指定的量(以字节为单位)提高,直至缓冲区中的数据长度达到上限。按长度减少长度和总长度。

详细信息
参数
[in] aConsumeLen
- 要从当前缓冲区消耗的字节数。

数据长度

uint16_t DataLength(
  void
) const 

获取数据包缓冲区中数据的长度(以字节为单位)。

详细信息
返回值
以字节为单位的长度(当前载荷长度)。

分离式

PacketBuffer * DetachTail(
  void
)

将当前缓冲区与其链分离,并返回一个指向其余缓冲区的指针。

当前缓冲区必须是链的头部。

详细信息
返回值
当前缓冲区链的尾部;如果当前缓冲区是链中唯一的缓冲区,则为 NULL。

确保预留的规模

bool EnsureReservedSize(
  uint16_t aReservedSize
)

确保缓冲区具有至少指定数量的预留空间。

如有必要,请确保缓冲区至少预留指定量的缓冲区空间来移动数据,以腾出空间。

详细信息
参数
[in] aReservedSize
- 标头所需的字节数。
返回值
如果请求的预留大小可用,则返回 true;如果缓冲区中没有足够的空间,则返回 false

最大数据长度

uint16_t MaxDataLength(
  void
) const 

根据当前起始位置和缓冲区大小,获取可存放在缓冲区中的数据的最大量(以字节为单位)。

详细信息
返回值
给定当前起始位置时可放入缓冲区的字节数。

下一步

PacketBuffer * Next(
  void
) const 

获取链中下一个缓冲区的指针。

详细信息
返回值
指向链中下一个缓冲区的指针。如果链中没有缓冲区,则返回 NULL

预留尺寸

uint16_t ReservedSize(
  void
) const 

获取缓冲区缓冲区和当前数据起始位置之间当前缓冲区内的字节数。

详细信息
返回值
缓冲区起始位置与当前数据起始位置之间的空间量(以字节为单位)。

设置数据长度

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

设置缓冲区中数据的长度(以字节为单位),并相应地调整总长度。

此函数设置缓冲区中数据的长度(以字节为单位),并适当调整总长度。如果该缓冲区不是缓冲区链的头(常见情况:调用方在调用较高层之前将数据添加到 PacketBuffer 链中的最后一个缓冲区),必须传入 aChainHead,以便在当前缓冲区之前适当地调整每个缓冲区的总长度。

详细信息
参数
[in] aNewLen
- 此缓冲区的新长度(以字节为单位)。
[in,out] aChainHead
- 当前缓冲区所属的缓冲区链的头。如果当前缓冲区是缓冲区链的头,可以为 NULL。

开始

void SetStart(
  uint8_t *aNewStart
)

设置缓冲区中的起始数据,并相应地调整长度和总长度。

详细信息
参数
[in] aNewStart
- 指向新负载起始位置的指针。在内部调整 newStart 以位于 PacketBuffer 链中第一个缓冲区的边界内。

开始

uint8_t * Start(
  void
) const 

获取指向缓冲区中数据起始位置的指针。

详细信息
返回值
指针指向数据的开头。

总长度

uint16_t TotalLength(
  void
) const 

获取缓冲区链中数据包数据的总长度。

详细信息
返回值
总长度(以八位字节为单位)。

公共静态函数

免费

void Free(
  PacketBuffer *aPacket
)

释放链中的所有数据包缓冲区。

将引用计数减少到当前链中的所有缓冲区。如果引用计数达到 0,则系统将相应地释放相应的缓冲区或将其返回到分配池。一般来讲,用户应将此方法视为与 free() 函数等效,而不是在调用后使用该参数。

详细信息
参数
[in] aPacket
- 要释放的数据包缓冲区。

自由头

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

释放链中的第一个缓冲区,并返回一个指向其余缓冲区的指针。

* @note When the buffer chain is referenced by multiple callers,FreeHead()` 会分离头部,但不会强制取消分配头部缓冲区。

详细信息
参数
[in] aPacket
- 缓冲区链。
返回值
由输入缓冲区尾部(可能是 NULL)组成的数据包缓冲区链。

新建

PacketBuffer * New(
  void
)

在载荷中分配具有默认预留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) 的默认大小上限 (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) 的单个 PacketBuffer

预留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) 足够大,可容纳传输层标头以及 WeaveMessageLayerWeaveExchangeLayer 所需的标头。

新建

PacketBuffer * New(
  uint16_t aReservedSize
)

根据总标头大小分配单个总大小的 PacketBuffer

传入的参数是在载荷之前预留的大小(用于适应来自不同堆栈层的数据包标头),而不是要分配的缓冲区的总大小。调用中指定的缓冲区 WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX 的大小,而不是。

  • PacketBuffer::New(0):以这种方式调用时,将返回缓冲区,而不保留任何标头,因此调用方可以使用整个载荷。在以下情况下,此模式尤其有用:用户堆栈会将载荷复制到包含相应标头预留的最终消息,或者创建通过 PacketBuffer::AddToEnd() 附加到 PacketBuffer 链的 PacketBuffer。参数
    [in] aReservedSize
    预留的标头空间量。
    返回值
    如果成功,则为 NULL 失败时指向 PacketBuffer 的指针。

有新尺寸

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

在标头的负载中分配具有默认预留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) 的 PacketBuffer,并在初始光标指针后分配至少 aAllocSize 字节的空间来存储额外数据。

在为应用层消息分配 PacketBuffer 时,这种用法最为合适。

详细信息
参数
[in] aAvailableSize
要在光标后分配的八位字节数。
返回值
成功后,系统会指向已分配块中的 PacketBuffer。失败时,NULL。*

有新尺寸

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

分配一个 PacketBuffer 对象,为有效负载预留至少 aReservedSize 字节的标头空间,并在初始光标指针后为其他数据预留至少 aAllocSize 字节的空间。

详细信息
参数
[in] aReservedSize
要在光标后预留的八位字节数。
[in] aAvailableSize
要在光标后分配的八位字节数。
返回值
成功后,系统会指向已分配块中的 PacketBuffer。失败时,NULL

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

将给定的缓冲区复制到适当大小的缓冲区(如果适用)。

此函数是套接字的空操作。

详细信息
参数
[in] aPacket
- 缓冲区或缓冲区链。
返回值
新数据包缓冲区或原始缓冲区