本頁面由 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 目標集區，以及來自標準 C 程式庫堆積的堆積。簡單的例子中，資料緩衝區的大小為 WEAVE_SYSTEM_PACKETBUFFER_SIZE。提供的 Composer 允許使用其他大小的資料緩衝區。

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 *` 在酬載中分配單一 PacketBuffer 的預設大小上限 (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX)，並使用預設保留大小 (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`	- 目前緩衝區所屬緩衝區鏈的標頭。如果目前的緩衝區是緩衝區鏈的中心，可能會是空值。

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
)

在酬載中分配單一 PacketBuffer 的預設大小上限 (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX)，並使用預設保留大小 (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 並透過 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

- 緩衝區或緩衝區鏈結。

傳回

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