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

此页面由 Cloud Translation API 翻译。

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)`	`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_PACKETBUFFER_CAPACITY_MAX) 的单个 PacketBuffer 和默认预留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE)。
`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 *` 如果适用，将给定的缓冲区复制到适当大小的缓冲区。

公共函数

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 结构分配的空间。

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

详细信息
返回值	分配的大小

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) 足以容纳传输层标头以及 WeaveMessageLayer 和 WeaveExchangeLayer 所需的标头。

新

PacketBuffer * New(
  uint16_t aReservedSize
)

分配具有最大总大小的单个 PacketBuffer 和特定标头预留大小。

传入的参数是在载荷之前预留的大小，以容纳来自不同堆栈层的数据包标头，而不是要分配的缓冲区的总大小。缓冲区 WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX 的大小，未在调用中指定。

PacketBuffer::New(0)：以这种方式调用时，系统将返回缓冲区，而不预留任何标头，因此整个载荷可供调用方使用。在用户知道有效负载将被复制到具有适当标头预留的最终消息中时，或在创建通过 PacketBuffer::AddToEnd() 附加到 PacketBuffer 链的 PacketBuffer 时，此模式在网络堆栈的较低层特别有用。参数

[in] aReservedSize

要预留的标头空间大小。

退货

如果成功，则在失败时返回指向 PacketBuffer 的指针 NULL。

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

- 缓冲区或缓冲区链。

返回值

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