nl:: Weave:: System:: PacketBuffer
#include <src/system/SystemPacketBuffer.h>
パケット バッファクラスは、オクテットシリアル化されたデータのパケットを操作するために使用されるコア構造であり、通常は Bluetooth やインターネット プロトコルなどのデータ通信ネットワークのコンテキストで使用されています。
概要
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)
|
バッファのチェーンでデータを使用します。
|
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)とデフォルトの予約済みサイズ(WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE)の単一の PacketBuffer を割り当てます。
|
New(uint16_t aReservedSize)
|
特定のヘッダー予約サイズを含む最大合計サイズの PacketBuffer を 1 つ割り当てます。
|
NewWithAvailableSize(size_t aAvailableSize)
|
ヘッダーのペイロードにデフォルトの予約済みサイズ(WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE)と、初期カーソル ポインタ後の追加データ用の少なくとも
aAllocSize バイトのスペースを持つ PacketBuffer を割り当てます。 |
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
|
ヘッダーのペイロードに
aReservedSize バイト以上予約され、初期カーソル ポインタ後の追加データ用に aAllocSize バイト以上のスペースを持つ PacketBuffer オブジェクトを割り当てます。 |
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
現在の開始位置とバッファサイズから、バッファに収まるデータの最大量(バイト単位)を取得します。
詳細 | |
---|---|
戻り値 |
現在の開始位置に基づいてバッファに収まるバイト数。
|
次へ
PacketBuffer * Next( void ) const
チェーン内の次のバッファへのポインタを取得します。
詳細 | |
---|---|
戻り値 |
チェーン内の次のバッファへのポインタ。チェーンにバッファがない場合、
NULL が返されます。 |
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)とデフォルトの予約済みサイズ(WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE)の単一の PacketBuffer を割り当てます。
予約済みのサイズ(WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE)は、トランスポート レイヤ ヘッダーと、WeaveMessageLayer
と WeaveExchangeLayer
に必要なヘッダーを保持するのに十分な大きさです。
新規
PacketBuffer * New( uint16_t aReservedSize )
特定のヘッダー予約サイズを含む最大合計サイズの PacketBuffer を 1 つ割り当てます。
渡されるパラメータは、割り当てるバッファの全体サイズではなく、さまざまなスタックレイヤからのパケット ヘッダーに対応するためにペイロードの前に予約されたサイズです。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)と、初期カーソル ポインタ後の追加データ用の少なくとも aAllocSize
バイトのスペースを持つ PacketBuffer を割り当てます。
この使用法は、アプリケーション レイヤ メッセージに PacketBuffer を割り当てる場合に最適です。
詳細 | |||
---|---|---|---|
パラメータ |
|
||
戻り値 |
成功した場合、割り当てられたブロック内の PacketBuffer へのポインタ。失敗した場合は、
NULL 。* |
NewWithAvailableSize
PacketBuffer * NewWithAvailableSize( uint16_t aReservedSize, size_t aAvailableSize )
ヘッダーのペイロードに aReservedSize
バイト以上予約され、初期カーソル ポインタ後の追加データ用に aAllocSize
バイト以上のスペースを持つ PacketBuffer オブジェクトを割り当てます。
詳細 | |||||
---|---|---|---|---|---|
パラメータ |
|
||||
戻り値 |
成功した場合、割り当てられたブロック内の PacketBuffer へのポインタ。失敗した場合は、
NULL 。 |
RightSize
PacketBuffer * RightSize( PacketBuffer *aPacket )
必要に応じて、指定されたバッファを適切なサイズのバッファにコピーします。
この関数はソケットに対応していません。
詳細 | |||
---|---|---|---|
パラメータ |
|
||
戻り値 |
新しいパケット バッファ、または
|