Google is committed to advancing racial equity for Black communities. See how.

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

nl::Weave::系統::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

封包緩衝區是用於操控八位元序列化資料封包的架構，通常是透過資料通訊網路 (例如藍牙或網際網路通訊協定) 使用。

總結

在以 LwIP 為基礎的環境中，這個類別是建構在該程式庫中定義的 bubuf 之上。如果缺少 LwIP，Weave 可以提供以購物中心為基礎的實作，或是完全導入深度嵌入裝置的記憶體挑戰。

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

PacketBuffer 物件是參考計數，而 Weave 內的現行使用模式則為「fire-and-forget」。由於封包 (及其基礎的 PacketBuffer 物件) 是透過不同的通訊協定層分派，因此成功層之間的向上呼叫或向下呼叫代表擁有擁有權，而呼叫者應負責釋出緩衝區。當跨圖層呼叫失敗時，釋出緩衝區的責任便取決於呼叫者。

PacketBuffer 類別的新物件會在分配從基礎環境取得的記憶體分配作業開始時初始化，例如從標準 C 程式庫堆積中的 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) 與預設保留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) 的 PacketBuffer。
`New(uint16_t aReservedSize)`	`PacketBuffer *` 分配單一 PacketBuffer 總大小和特定標頭預留大小的大小上限。
`NewWithAvailableSize(size_t aAvailableSize)`	`PacketBuffer *` 分配一個 PacketBuffer，其帶有默認保留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE)。
`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，如果緩衝區空間不足，則傳回 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

取得緩衝區資料的封包總長度。

詳細資料
傳回	以 80 位元組為單位呈現總長度。

公開的靜態函式

免費

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_PACKETBUFFER_CAPACITY_MAX) 與預設保留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) 的 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
)

分配一個 PacketBuffer，其帶有默認保留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE)。

當您為應用程式層訊息分配 PacketBuffer 時，最為適用。

詳細資料

參數

[in] aAvailableSize

遊標後方要分配的八位元數量。

傳回

成功時，指向分配區塊中的 PacketBuffer 指標。失敗時，NULL。*

新可用大小

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

分配 PacketBuffer 物件，該物件中預留的標頭中至少有 aReservedSize 位元組的位元組，以及初始遊標指標之後至少保留 aAllocSize 位元組的額外資料。

詳細資料

參數

`[in] aReservedSize`	遊標後方保留的八位元數量。
`[in] aAvailableSize`	遊標後方要分配的八位元數量。

傳回

成功時，指向分配區塊中的 PacketBuffer 指標。失敗時，NULL。

正確大小

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

將指定的緩衝區複製到適當大小的緩衝區 (如適用)。

這項功能對通訊端而言並非無回應。

詳細資料

參數

[in] aPacket

- 緩衝區或緩衝鏈。

傳回

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