Google は、黒人コミュニティのための人種的公平の促進に取り組んでいます。詳細をご覧ください。

nl::Weave::System::PacketBuffer

#include <src/system/SystemPacketBuffer.h>

パケット バッファクラスは、オクテットシリアル化データのパケットを操作するために使用されるコア構造であり、通常は Bluetooth やインターネット プロトコルなどのデータ通信ネットワークのコンテキストで使用されます。

まとめ

LwIP ベースの環境では、このクラスは、そのライブラリで定義された pbuf 構造上に構築されます。Weave には LwIP がない場合、malloc ベースの実装や、ディープ 埋め込みデバイスのメモリの問題に最も近いプールベースの実装が用意されています。

階層化されたネットワーク スタックで使用される多くの同様の構造と同様に、PacketBuffer クラスは、構成可能な通信スタックの各レイヤでプロトコル ヘッダーのスペースを予約するメカニズムを備えています。詳しくは、PacketBuffer::New() と LwIP のドキュメントをご覧ください。

PacketBuffer オブジェクトは参照カウントされ、Weave の一般的な使用モードは「fire-and-forget」です。パケット(およびその基になる 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)の単一の 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)
PacketBuffer オブジェクトを、ヘッダーのペイロードに少なくとも aReservedSize バイト、最初のカーソル ポインタの後にある追加のデータに aAllocSize バイト以上確保します。
RightSize(PacketBuffer *aPacket)
必要に応じて、指定されたバッファを適切なサイズのバッファにコピーします。

パブリック関数

AddRef

void AddRef(
  void
)

現在のバッファの参照数をインクリメントします。

AddToEnd

void AddToEnd(
  PacketBuffer *aPacket
)

指定されたパケット バッファをバッファ チェーンの末尾に追加し、それに応じてチェーン内の各バッファの合計長を調整します。

詳細
パラメータ
[in] aPacket
- 現在のチェーンの末尾に追加されるパケット バッファ。

AlignPayload(整列ペイロード)

bool AlignPayload(
  uint16_t aAlignBytes
)

バッファ ペイロードを指定されたバイト境界に揃えます。

必要に応じて、バッファ内のペイロードを前方に移動します。

詳細
パラメータ
[in] aAlignBytes
- ペイロード開始ポインタのバイト数を指定します。
戻り値
アライメントが成功した場合は true、バッファに十分なスペースがない場合は false

割り当てサイズ

size_t AllocSize(
  void
) const 

予約サイズとペイロードのデータスペースを含む割り当てのサイズを返しますが、PacketBuffer 構造に割り当てられたスペースは含まれません。

詳細
戻り値
割り当てのサイズ

利用可能なデータ長

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

MaxDataLength

uint16_t MaxDataLength(
  void
) const 

現在の開始位置とバッファサイズを考慮して、バッファに収まるデータの最大量(バイト)を取得します。

詳細
戻り値
現在の開始位置を考慮してバッファに収まるバイト数。

次へ

PacketBuffer * Next(
  void
) const 

チェーン内の次のバッファへのポインタを取得します。

詳細
戻り値
チェーン内の次のバッファへのポインタ。チェーンにバッファがない場合、NULL が返されます。

予約済みサイズ

uint16_t ReservedSize(
  void
) const 

バッファの先頭から現在のデータの開始位置までの現在のバッファ内のバイト数を取得します。

詳細
戻り値
バッファの開始時点と現在のデータの開始位置の間のスペースの量(バイト単位)。

SetDataLength

void SetDataLength(
  uint16_t aNewLen,
  PacketBuffer *aChainHead
)

バッファ内のデータの長さをバイト単位で設定し、それに応じて合計長を調整します。

この関数は、バッファ内のデータの長さをバイト単位で設定し、合計長を適切に調整します。バッファがバッファ チェーンの先頭でない場合(一般的には、呼び出し元が上位レイヤを呼び出す前に、PacketBuffer チェーンの最後のバッファにデータを追加します)、aBufferHead を渡して、現在のバッファの前に各バッファの合計長を適切に調整する必要があります。

詳細
パラメータ
[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 

バッファ チェーン内のパケットデータの合計長を取得します。

詳細
戻り値
オクテットで示した、全長

静的パブリック関数

無料

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 の場合もあります)。

New

PacketBuffer * New(
  void
)

デフォルトの最大サイズ(WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX)の単一の PacketBuffer をペイロードにデフォルトの予約サイズ(WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE)で割り当てます。

予約済みのサイズ(WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE)は、トランスポート レイヤのヘッダーと、WeaveMessageLayer および WeaveExchangeLayer で必要なヘッダーを保持するのに十分な大きさです。

New

PacketBuffer * New(
  uint16_t aReservedSize
)

最大合計サイズの単一の PacketBuffer を、特定のヘッダー予約サイズで割り当てます。

渡されるパラメータは、さまざまなバッファレイヤからのパケット ヘッダーに対応できるように、ペイロードの前に予約されているサイズであり、割り当てるバッファ全体のサイズではありません。バッファのサイズ WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX(呼び出しで指定しません)。

  • PacketBuffer::New(0) : この形式で呼び出されると、ヘッダーが予約されていないバッファが返されます。したがって、呼び出し元はペイロード全体を使用できます。このパターンは、ペイロードが適切なヘッダーの予約で最終メッセージにコピーされることをユーザーが知っている場合、または PacketBuffer::AddToEnd() を介して PacketBuffer のチェーンに追加される PacketBuffer を作成する場合に、ネットワーク スタックの下位レイヤで特に役立ちます。 パラメータ
    [in] aReservedSize
    予約するヘッダーのスペース。
    返品
    成功すると、失敗時に NULLPacketBuffer へのポインタ。

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

サイズ

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

必要に応じて、指定されたバッファを適切なサイズのバッファにコピーします。

この関数はソケットに対して no-op です。

詳細
パラメータ
[in] aPacket
- バッファまたはバッファ チェーン
戻り値
新しいパケット バッファまたは元のバッファ