Google 致力于为黑人社区推动种族平等。查看具体举措。

此页面由 Cloud Translation API 翻译。

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)`	`PacketBuffer *` 消耗缓冲区链中的数据。
`ConsumeHead(uint16_t aConsumeLength)`	`void` 调整当前缓冲区以指示已用的数据量。
`DataLength(void) const`	`uint16_t` 获取数据包缓冲区中数据的长度（以字节为单位）。
`DetachTail(void)`	`PacketBuffer *` 将当前缓冲区与其链分离，并返回一个指向其余缓冲区的指针。
`EnsureReservedSize(uint16_t aReservedSize)`	`bool` 确保缓冲区具有至少指定数量的预留空间。
`MaxDataLength(void) const`	`uint16_t` 根据当前起始位置和缓冲区大小，获取可存放在缓冲区中的数据的最大量（以字节为单位）。
`Next(void) const`	`PacketBuffer *` 获取链中下一个缓冲区的指针。
`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)`	`PacketBuffer *` 释放链中的第一个缓冲区，并返回一个指向其余缓冲区的指针。
`New(void)`	`PacketBuffer *` 在载荷中分配具有默认预留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) 的默认大小上限 (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) 的单个 PacketBuffer。
`New(uint16_t aReservedSize)`	`PacketBuffer *` 根据总标头大小分配单个总大小的 PacketBuffer。
`NewWithAvailableSize(size_t aAvailableSize)`	`PacketBuffer *` 在标头的负载中分配具有默认预留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) 的 PacketBuffer，并在初始光标指针后分配至少 `aAllocSize` 字节的空间来存储额外数据。
`NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)`	`PacketBuffer *` 分配一个 PacketBuffer 对象，为有效负载预留至少 `aReservedSize` 字节的标头空间，并在初始光标指针后为其他数据预留至少 `aAllocSize` 字节的空间。
`RightSize(PacketBuffer *aPacket)`	`PacketBuffer *` 将给定的缓冲区复制到适当大小的缓冲区（如果适用）。

公共函数

添加引用

void AddRef(
  void
)

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

添加到结束日期

void AddToEnd(
  PacketBuffer *aPacket
)

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

详细信息

参数

[in] aPacket

- 要添加到当前链路末尾的数据包缓冲区。

对齐载荷

bool AlignPayload(
  uint16_t aAlignBytes
)

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

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

详细信息

参数

[in] aAlignBytes

- 指定载荷开始指针的字节数对齐。

返回值

如果对齐成功，则返回 true；如果缓冲区中没有足够的空间，则返回 false。

分配大小

size_t AllocSize(
  void
) const

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

注意：分配大小等于或大于 aAllocSize 参数 Create 方法）。

详细信息
返回值	分配大小

可用数据长度

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) 足够大，可容纳传输层标头以及 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 时，这种用法最为合适。

详细信息

参数

[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

- 缓冲区或缓冲区链。

返回值

新数据包缓冲区或原始缓冲区