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)
|
在緩衝區鏈中取用資料。
|
ConsumeHead(uint16_t aConsumeLength)
|
void
調整目前的緩衝區,指出耗用的資料量。
|
DataLength(void) const
|
uint16_t
取得封包緩衝區中的資料長度 (以位元組為單位)。
|
DetachTail(void)
|
從緩衝區中卸離目前的緩衝區,然後將指標傳回至其餘的緩衝區。
|
EnsureReservedSize(uint16_t aReservedSize)
|
bool
確保緩衝區至少擁有指定的保留空間。
|
MaxDataLength(void) const
|
uint16_t
根據目前的開始位置和緩衝區大小,取得緩衝區空間上限 (以位元組為單位)。
|
Next(void) const
|
取得鏈結中的下一個緩衝區指標。
|
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)
|
釋放鏈結中的第一個緩衝區,並傳回指向其餘緩衝區的指標。
|
New(void)
|
在酬載中分配預設大小上限 (WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX) 的單一 PacketBuffer,並採用預設保留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE)。
|
New(uint16_t aReservedSize)
|
搭配特定標頭保留大小,配置總大小上限的單一 PacketBuffer。
|
NewWithAvailableSize(size_t aAvailableSize)
|
在酬載中為標頭分配預設保留大小 (WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE) 的 PacketBuffer,以及在初始遊標指標之後至少為其他資料分配
aAllocSize 位元組的空間。 |
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
|
|
RightSize(PacketBuffer *aPacket)
|
在適用情況下,將指定的緩衝區複製到適當大小的緩衝區。
|
公用函式
AddRef
void AddRef( void )
增加目前緩衝區的參照計數。
AddToEnd
void AddToEnd( PacketBuffer *aPacket )
將指定的封包緩衝區新增至緩衝區鏈結的尾端,據此調整鏈結中每個緩衝區的總長度。
詳細說明 | |||
---|---|---|---|
參數 |
|
AlignPayload
bool AlignPayload( uint16_t aAlignBytes )
讓緩衝區酬載按照指定的位元組邊界對齊。
視需要將緩衝區中的酬載往前移動。
詳細說明 | |||
---|---|---|---|
參數 |
|
||
傳回 |
true 表示成功對齊,如果緩衝區空間不足,則為 false 。 |
AllocSize
size_t AllocSize( void ) const
傳回分配大小 (包括保留和酬載資料空間),但不包含為 PacketBuffer 結構配置的空間。
詳細說明 | |
---|---|
傳回 |
分配的規模大小
|
AvailableDataLength
uint16_t AvailableDataLength( void ) const
取得根據目前的開始位置和資料長度,在目前緩衝區中新增的資料位元組數。
詳細說明 | |
---|---|
傳回 |
根據目前的起始位置和資料長度,顯示目前緩衝區的資料長度 (以位元組為單位)。
|
CompactHead
void CompactHead( void )
將鏈結中後續緩衝區的資料移至目前的緩衝區,直到空間已滿為止。
只有目前的緩衝區會經過壓縮:目前緩衝區中的資料將移至緩衝區的前方,無需保留任何保留空間。剩餘的可用空間會填滿從鏈結中後續緩衝區移動的資料,直到目前緩衝區已滿為止。如果鏈結中的後續緩衝區完整移至目前的緩衝區,系統就會從鏈結中移除並釋放該緩衝區。這個方法沒有參數,不會傳回任何結果,也無法失敗。
取用
PacketBuffer * Consume( uint16_t aConsumeLength )
在緩衝區鏈中取用資料。
在從目前緩衝區開始的緩衝區鏈中取用資料,然後繼續完成鏈結中剩餘的緩衝區。每個完全消耗的緩衝區都會釋放,且函式會傳回包含剩餘資料的第一個緩衝區 (若有)。目前的緩衝區必須是緩衝區鏈結的標頭。
詳細說明 | |||
---|---|---|---|
參數 |
|
||
傳回 |
來自目前鏈結的第一個緩衝區,包含剩餘資料。如果沒有任何資料,就會傳回 NULL。
|
ConsumeHead
void ConsumeHead( uint16_t aConsumeLength )
調整目前的緩衝區,指出耗用的資料量。
根據指定的資料量 (以位元組為單位),從緩衝區中的資料長度提高資料在目前緩衝區中的起始位置。按照耗用量降低影片長度和總長度。
詳細說明 | |||
---|---|---|---|
參數 |
|
DataLength
uint16_t DataLength( void ) const
取得封包緩衝區中的資料長度 (以位元組為單位)。
詳細說明 | |
---|---|
傳回 |
長度,以位元組為單位 (目前酬載長度)。
|
DetachTail
PacketBuffer * DetachTail( void )
從緩衝區中卸離目前的緩衝區,然後將指標傳回至其餘的緩衝區。
目前的緩衝區必須是鏈結的標頭。
詳細說明 | |
---|---|
傳回 |
目前緩衝區鏈結的尾部;如果目前緩衝區是鏈結中唯一的緩衝區,則傳回 NULL。
|
EnsureReservedSize
bool EnsureReservedSize( uint16_t aReservedSize )
確保緩衝區至少擁有指定的保留空間。
請確保緩衝區至少擁有指定空間的保留空間,可將緩衝區中的資料往前移動,以便視需要騰出空間。
詳細說明 | |||
---|---|---|---|
參數 |
|
||
傳回 |
如果要求的保留大小可用,則為
true ;如果緩衝區空間不足,則為 false 。 |
MaxDataLength
uint16_t MaxDataLength( void ) const
根據目前的開始位置和緩衝區大小,取得緩衝區空間上限 (以位元組為單位)。
詳細說明 | |
---|---|
傳回 |
根據目前的起始位置,緩衝區所含的位元組數。
|
ReservedSize
uint16_t ReservedSize( void ) const
取得目前緩衝區內,從緩衝區開始和目前資料開始位置之間的位元組數。
詳細說明 | |
---|---|
傳回 |
緩衝區開始和目前資料開始位置之間的空間量 (以位元組為單位)。
|
SetDataLength
void SetDataLength( uint16_t aNewLen, PacketBuffer *aChainHead )
設定緩衝區中的資料長度 (以位元組為單位),並據此調整總長度。
函式會設定緩衝區中的資料長度 (以位元組為單位),並適當調整總長度。如果緩衝區不是緩衝區鏈結的標頭 (常見情況:呼叫端在呼叫較高層之前,呼叫端會將資料新增至 PacketBuffer 鏈結中的最後一個緩衝區),則必須傳入 aChainHead,以便適當調整每個緩衝區的總長度 (在目前緩衝區之前)。
詳細說明 | |||||
---|---|---|---|---|---|
參數 |
|
SetStart
void SetStart( uint8_t *aNewStart )
設定緩衝區中的起始資料,並據此調整長度和總長度。
詳細說明 | |||
---|---|---|---|
參數 |
|
開始
uint8_t * Start( void ) const
取得緩衝區中資料開頭的指標。
詳細說明 | |
---|---|
傳回 |
指向資料開頭
|
TotalLength
uint16_t TotalLength( void ) const
取得緩衝區鏈中封包資料的總長度。
詳細說明 | |
---|---|
傳回 |
總長度 (八位元)
|
公開的靜態函式
免費
void Free( PacketBuffer *aPacket )
釋放鏈結中的所有封包緩衝區。
將目前鏈結中所有緩衝區的參照計數減少。如果參考次數達到 0,系統就會視情況釋出或傳回至配置集區。根據規則,使用者應將這個方法視為相當於 free()
函式,而不是呼叫後的引數。
詳細說明 | |||
---|---|---|---|
參數 |
|
FreeHead
PacketBuffer * FreeHead( PacketBuffer *aPacket )
釋放鏈結中的第一個緩衝區,並傳回指向其餘緩衝區的指標。
* @note When the buffer chain is referenced by multiple callers,
FreeHead() 會卸離頭部,但不會強制取消分配頭緩衝區。
詳細說明 | |||
---|---|---|---|
參數 |
|
||
傳回 |
由輸入緩衝區的尾部組成 (可能為
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 時,最適合使用這種用法。
詳細說明 | |||
---|---|---|---|
參數 |
|
||
傳回 |
成功時,指標指向分配區塊中的 PacketBuffer。失敗時,
NULL 。*。 |
NewWithAvailableSize
PacketBuffer * NewWithAvailableSize( uint16_t aReservedSize, size_t aAvailableSize )
為 PacketBuffer 物件分配在標頭的酬載中保留至少 aReservedSize
個位元組,在初始遊標指標後方至少保留 aAllocSize
位元組的空間。
詳細說明 | |||||
---|---|---|---|---|---|
參數 |
|
||||
傳回 |
成功時,指標指向分配區塊中的 PacketBuffer。失敗時,
NULL 。 |
RightSize
PacketBuffer * RightSize( PacketBuffer *aPacket )
在適用情況下,將指定的緩衝區複製到適當大小的緩衝區。
此函式為通訊端的免人工管理。
詳細說明 | |||
---|---|---|---|
參數 |
|
||
傳回 |
新的封包緩衝區或原始緩衝區
|