nl::Weave::System::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_PACKETBUFFER_CAPACITY_MAX) 的单个 PacketBuffer,其中包含默认预留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE)。
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)
将给定的缓冲区复制到大小正确的缓冲区(如果适用)。

公共函数

AddRef

void AddRef(
  void
)

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

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

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

具体说明
参数
[in] aPacket
- 要添加到当前链末尾的数据包缓冲区。

AlignPayload

bool AlignPayload(
  uint16_t aAlignBytes
)

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

根据需要将缓冲区中的载荷向前移动。

具体说明
参数
[in] aAlignBytes
- 指定载荷开始指针的字节数对齐方式。
返回值
如果对齐成功,则为 true;如果缓冲区空间不足,则为 false

AllocSize

size_t AllocSize(
  void
) const 

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

具体说明
返回值
分配大小

AvailableDataLength

uint16_t AvailableDataLength(
  void
) const 

获取在给定当前起始位置和数据长度的情况下可以添加到当前缓冲区的数据字节数。

具体说明
返回值
在指定当前起始位置和数据长度的情况下,适合当前缓冲区的数据长度(以字节为单位)。

CompactHead

void CompactHead(
  void
)

将数据从链中的后续缓冲区移至当前缓冲区,直到填满为止。

只有当前缓冲区会被压缩:当前缓冲区内的数据将移至该缓冲区的前面,从而消除任何保留空间。剩余的可用空间由从链中的后续缓冲区移动的数据来填充,直到当前缓冲区已满。如果链中的后续缓冲区被整个移入当前缓冲区,则系统会将该缓冲区从链中移除并释放。该方法不接受任何参数,不会返回任何结果,也不会失败。

使用

PacketBuffer * Consume(
  uint16_t aConsumeLength
)

使用缓冲区链中的数据。

在缓冲区链中使用数据,先从当前缓冲区开始,然后继续处理链中的其余缓冲区。系统会释放已完全消耗的每个缓冲区,并且该函数会返回包含剩余数据的第一个缓冲区(如果有)。当前缓冲区必须是缓冲区链的头。

具体说明
参数
[in] aConsumeLength
- 当前链中要使用的字节数。
返回值
包含任何剩余数据的当前链中的第一个缓冲区。如果没有剩余数据,则返回 NULL。

ConsumeHead

void ConsumeHead(
  uint16_t aConsumeLength
)

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

在当前缓冲区中的数据起始位置提前指定量(以字节为单位),直到缓冲区中数据的长度。根据摄入的量减少长度和总长度。

具体说明
参数
[in] aConsumeLen
- 当前缓冲区中要消耗的字节数。

DataLength

uint16_t DataLength(
  void
) const 

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

具体说明
返回值
长度,以字节为单位(当前载荷长度)。

DetachTail

PacketBuffer * DetachTail(
  void
)

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

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

具体说明
返回值
当前缓冲区链的尾部,如果当前缓冲区是链中唯一的缓冲区,则返回 NULL。

EnsureReservedSize

bool EnsureReservedSize(
  uint16_t aReservedSize
)

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

确保缓冲区中至少预留了指定数量的预留空间,以便在需要时向前移动缓冲区中的数据,以腾出空间。

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

MaxDataLength

uint16_t MaxDataLength(
  void
) const 

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

具体说明
返回值
在指定当前起始位置缓冲区中适合的字节数。

下一个

PacketBuffer * Next(
  void
) const 

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

具体说明
返回值
指向链中下一个缓冲区的指针。如果链中没有缓冲区,则返回 NULL

ReservedSize

uint16_t ReservedSize(
  void
) const 

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

具体说明
返回值
缓冲区起始位置与当前数据起始位置之间的空间量(以字节为单位)。

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

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

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

具体说明
参数
[in] aNewLen
- 该缓冲区的新长度(以字节为单位)。
[in,out] aChainHead
- 当前缓冲区所属的缓冲区链的头。如果当前缓冲区是缓冲区链的头,则可以为 NULL。

SetStart

void SetStart(
  uint8_t *aNewStart
)

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

具体说明
参数
[in] aNewStart
- 指向新载荷开始位置的指针。将在内部调整 newStart,使其处于 PacketBuffer 链中第一个缓冲区的边界内。

开始

uint8_t * Start(
  void
) const 

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

具体说明
返回值
指向数据开头的指针。

TotalLength

uint16_t TotalLength(
  void
) const 

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

具体说明
返回值
总长度(以八位字节为单位)。

公共静态函数

免费

void Free(
  PacketBuffer *aPacket
)

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

将引用计数减少到当前链中的所有缓冲区。如果引用计数达到 0,相应的缓冲区会根据需要释放或返回到分配池。一般来说,用户应将此方法视为 free() 函数的等效项,并且不要在调用后使用该参数。

具体说明
参数
[in] aPacket
- 要释放的数据包缓冲区。

FreeHead

PacketBuffer * FreeHead(
  PacketBuffer *aPacket
)

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

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

具体说明
参数
[in] aPacket
- 缓冲区链。
返回值
包括输入缓冲区尾部的数据包缓冲区链(可能是 NULL)。

新观看者

PacketBuffer * New(
  void
)

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

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

新观看者

PacketBuffer * New(
  uint16_t aReservedSize
)

分配具有特定标头预留大小的单个总大小上限的 PacketBuffer

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

  • PacketBuffer::New(0):以这种方式调用时,将在不预留任何标头的情况下返回缓冲区,因此调用方可以使用整个载荷。此模式在网络堆栈的较低层特别有用:用户知道载荷将被复制到具有适当标头预留的最终消息中,或者在创建 PacketBuffer(通过 PacketBuffer::AddToEnd() 附加到 PacketBuffer 链)时。 参数
    [in] aReservedSize
    要预留的标头空间量
    返回值
    如果成功,系统会在失败 NULL 时添加一个指向 PacketBuffer 的指针。

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  size_t aAvailableSize
)

在标头的载荷中分配具有默认预留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) 的 PacketBuffer,并且为初始光标指针后的其他数据分配至少 aAllocSize 个字节的空间。

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

具体说明
参数
[in] aAvailableSize
要在游标后分配的八位字节数量。
返回值
成功后,指向已分配块中的 PacketBuffer 的指针。失败时,返回 NULL。*

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

分配一个 PacketBuffer 对象,其中在载荷中为标头预留了至少 aReservedSize 个字节,并且在初始光标指针后预留了至少 aAllocSize 个字节的空间。

具体说明
参数
[in] aReservedSize
要在游标后保留的八位字节数量。
[in] aAvailableSize
要在游标后分配的八位字节数量。
返回值
成功后,指向已分配块中的 PacketBuffer 的指针。失败时,返回 NULL

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

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

对于套接字,此函数是空操作。

具体说明
参数
[in] aPacket
- 缓冲区或缓冲区链。
返回值
新数据包缓冲区或原始缓冲区