本頁面由 Cloud Translation API 翻譯而成。

nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

封包緩衝區類別是用於操控八位元序列化資料的封包的核心結構，通常位於資料通訊網路 (例如藍牙或網際網路通訊協定) 內。

摘要

在 LwIP 型環境中，這個類別是以該程式庫中定義的 pbuf 結構為基礎。在沒有 LwIP 的情況下，Weave 會提供 Malloc 型實作，或採用集區式實作，近乎嵌入深度嵌入裝置的記憶體挑戰。

PacketBuffer 類別像是在分層網路堆疊中使用的許多類似結構，可提供在可設定通訊堆疊中各層保留通訊協定標頭空間的機制。詳情請參閱 PacketBuffer::New() 和 LwIP 說明文件。

PacketBuffer 物件會列入參照計算，而 Weave 中的主要使用模式為「fire-and-forget」。封包 (及其基礎 PacketBuffer 物件) 是透過多個通訊協定層來分派，因此不同層之間的成功向上呼叫或向下呼叫僅表示擁有權轉移，而呼叫端則負責釋放緩衝區。跨層呼叫失敗時，應負責釋出緩衝區並與呼叫端繼續保留。

PacketBuffer 類別的新物件會在從基礎環境取得的記憶體配置 (例如來自內部緩衝區集區的 LwIP pbuf 目標集區) 開始時初始化。在此簡單的情況下，資料緩衝區的大小為 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

要保留的標頭空間

傳回

成功時，在失敗 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

- 緩衝區或緩衝區鏈結。

傳回

新的封包緩衝區或原始緩衝區