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)
|
|
RightSize(PacketBuffer *aPacket)
|
将给定的缓冲区复制到适当大小的缓冲区(如果适用)。
|
公共函数
添加引用
void AddRef( void )
递增当前缓冲区的引用计数。
添加到结束日期
void AddToEnd( PacketBuffer *aPacket )
将给定的数据包缓冲区添加到缓冲区链的末尾,并相应地调整链中每个缓冲区的总长度。
详细信息 | |||
---|---|---|---|
参数 |
|
对齐载荷
bool AlignPayload( uint16_t aAlignBytes )
在指定字节边界上对齐缓冲区载荷。
如有必要,将缓冲区中的载荷向前移动。
详细信息 | |||
---|---|---|---|
参数 |
|
||
返回值 |
如果对齐成功,则返回
true ;如果缓冲区中没有足够的空间,则返回 false 。 |
可用数据长度
uint16_t AvailableDataLength( void ) const
根据当前起始位置和数据长度,获取可添加到当前缓冲区的数据字节数。
详细信息 | |
---|---|
返回值 |
根据当前起始位置和数据长度,适合当前缓冲区的数据长度(以字节为单位)。
|
紧凑型
void CompactHead( void )
将链中后续缓冲区中的数据移至当前缓冲区中,直至该缓冲区已满。
只有当前缓冲区会压缩:当前缓冲区中的数据会移动到缓冲区前端,从而消除所有预留空间。剩余的可用空间填充自链中后续缓冲区的数据,直到当前缓冲区已满。如果链中的后续缓冲区被整个移至当前缓冲区,则会将其从链中移除并释放。该方法不使用任何参数,不返回任何结果,并且不会失败。
使用
PacketBuffer * Consume( uint16_t aConsumeLength )
消耗缓冲区链中的数据。
消耗缓冲区缓冲区中的数据(从当前缓冲区开始,并继续执行链中的剩余缓冲区)。每个已完全用尽的缓冲区都将被释放,并且函数会返回包含剩余数据的第一个缓冲区(如果有)。当前缓冲区必须是缓冲区链的头。
详细信息 | |||
---|---|---|---|
参数 |
|
||
返回值 |
来自当前链的第一个包含任何剩余数据的缓冲区。如果没有剩余数据,则返回 NULL。
|
消耗头像
void ConsumeHead( uint16_t aConsumeLength )
调整当前缓冲区以指示已用的数据量。
使当前缓冲区中的数据起始位置按指定的量(以字节为单位)提高,直至缓冲区中的数据长度达到上限。按长度减少长度和总长度。
详细信息 | |||
---|---|---|---|
参数 |
|
数据长度
uint16_t DataLength( void ) const
获取数据包缓冲区中数据的长度(以字节为单位)。
详细信息 | |
---|---|
返回值 |
以字节为单位的长度(当前载荷长度)。
|
分离式
PacketBuffer * DetachTail( void )
将当前缓冲区与其链分离,并返回一个指向其余缓冲区的指针。
当前缓冲区必须是链的头部。
详细信息 | |
---|---|
返回值 |
当前缓冲区链的尾部;如果当前缓冲区是链中唯一的缓冲区,则为 NULL。
|
确保预留的规模
bool EnsureReservedSize( uint16_t aReservedSize )
确保缓冲区具有至少指定数量的预留空间。
如有必要,请确保缓冲区至少预留指定量的缓冲区空间来移动数据,以腾出空间。
详细信息 | |||
---|---|---|---|
参数 |
|
||
返回值 |
如果请求的预留大小可用,则返回
true ;如果缓冲区中没有足够的空间,则返回 false 。 |
最大数据长度
uint16_t MaxDataLength( void ) const
根据当前起始位置和缓冲区大小,获取可存放在缓冲区中的数据的最大量(以字节为单位)。
详细信息 | |
---|---|
返回值 |
给定当前起始位置时可放入缓冲区的字节数。
|
预留尺寸
uint16_t ReservedSize( void ) const
获取缓冲区缓冲区和当前数据起始位置之间当前缓冲区内的字节数。
详细信息 | |
---|---|
返回值 |
缓冲区起始位置与当前数据起始位置之间的空间量(以字节为单位)。
|
设置数据长度
void SetDataLength( uint16_t aNewLen, PacketBuffer *aChainHead )
设置缓冲区中数据的长度(以字节为单位),并相应地调整总长度。
此函数设置缓冲区中数据的长度(以字节为单位),并适当调整总长度。如果该缓冲区不是缓冲区链的头(常见情况:调用方在调用较高层之前将数据添加到 PacketBuffer 链中的最后一个缓冲区),必须传入 aChainHead,以便在当前缓冲区之前适当地调整每个缓冲区的总长度。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
开始
void SetStart( uint8_t *aNewStart )
设置缓冲区中的起始数据,并相应地调整长度和总长度。
详细信息 | |||
---|---|---|---|
参数 |
|
开始
uint8_t * Start( void ) const
获取指向缓冲区中数据起始位置的指针。
详细信息 | |
---|---|
返回值 |
指针指向数据的开头。
|
总长度
uint16_t TotalLength( void ) const
获取缓冲区链中数据包数据的总长度。
详细信息 | |
---|---|
返回值 |
总长度(以八位字节为单位)。
|
公共静态函数
免费
void Free( PacketBuffer *aPacket )
释放链中的所有数据包缓冲区。
将引用计数减少到当前链中的所有缓冲区。如果引用计数达到 0,则系统将相应地释放相应的缓冲区或将其返回到分配池。一般来讲,用户应将此方法视为与 free()
函数等效,而不是在调用后使用该参数。
详细信息 | |||
---|---|---|---|
参数 |
|
自由头
PacketBuffer * FreeHead( PacketBuffer *aPacket )
释放链中的第一个缓冲区,并返回一个指向其余缓冲区的指针。
* @note When the buffer chain is referenced by multiple callers,
FreeHead()` 会分离头部,但不会强制取消分配头部缓冲区。
详细信息 | |||
---|---|---|---|
参数 |
|
||
返回值 |
由输入缓冲区尾部(可能是
NULL )组成的数据包缓冲区链。 |
新建
PacketBuffer * New( void )
在载荷中分配具有默认预留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) 的默认大小上限 (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) 的单个 PacketBuffer。
预留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) 足够大,可容纳传输层标头以及 WeaveMessageLayer
和 WeaveExchangeLayer
所需的标头。
新建
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 时,这种用法最为合适。
详细信息 | |||
---|---|---|---|
参数 |
|
||
返回值 |
成功后,系统会指向已分配块中的 PacketBuffer。失败时,
NULL 。* |
有新尺寸
PacketBuffer * NewWithAvailableSize( uint16_t aReservedSize, size_t aAvailableSize )
分配一个 PacketBuffer 对象,为有效负载预留至少 aReservedSize
字节的标头空间,并在初始光标指针后为其他数据预留至少 aAllocSize
字节的空间。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
||||
返回值 |
成功后,系统会指向已分配块中的 PacketBuffer。失败时,
NULL 。 |
RightSize
PacketBuffer * RightSize( PacketBuffer *aPacket )
将给定的缓冲区复制到适当大小的缓冲区(如果适用)。
此函数是套接字的空操作。
详细信息 | |||
---|---|---|---|
参数 |
|
||
返回值 |
新数据包缓冲区或原始缓冲区
|