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 を 1 つ割り当てます。
New(uint16_t aReservedSize)
特定のヘッダー予約サイズで最大合計サイズの PacketBuffer を 1 つ割り当てます。
NewWithAvailableSize(size_t aAvailableSize)
ヘッダーのペイロードにデフォルトの予約サイズ（WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE）で PacketBuffer を割り当て、最初のカーソルポインタの後に追加データ用に少なくとも aAllocSize バイトのスペースを割り当てます。
NewWithAvailableSize(uint16_t aReservedSize, size_t aAvailableSize)
ヘッダー用のペイロードで少なくとも aReservedSize バイトを予約し、最初のカーソルポインタの後に追加データ用に少なくとも aAllocSize バイトのスペースを予約して、PacketBuffer オブジェクトを割り当てます。
RightSize(PacketBuffer *aPacket)
指定されたバッファを、適切なサイズのバッファにコピーします（該当する場合）。

パブリック関数

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 構造に割り当てられたスペースは含まない割り当てのサイズを返します。

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

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
- 現在のバッファが属するバッファ チェーンの先頭。現在のバッファがバッファ チェーンの先頭の場合は NULL になります。

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
)

ペイロードに、デフォルトの最大サイズ（WEAVE_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX）とデフォルトの予約サイズ（WEAVE_SYSTEM_CONFIG_HEADER_RESERVE_SIZE）の PacketBuffer を 1 つ割り当てます。

予約済みサイズ（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）で PacketBuffer を割り当て、最初のカーソルポインタの後に追加データ用に少なくとも aAllocSize バイトのスペースを割り当てます。

この使用方法は、アプリケーション レイヤのメッセージに PacketBuffer を割り当てる場合に最適です。

詳細
パラメータ
[in] aAvailableSize
カーソルの後に割り当てるオクテットの数。
戻り値
成功した場合、割り当てられたブロック内の PacketBuffer へのポインタ。失敗した場合、NULL。*

NewWithAvailableSize

PacketBuffer * NewWithAvailableSize(
  uint16_t aReservedSize,
  size_t aAvailableSize
)

ヘッダー用のペイロードで少なくとも aReservedSize バイトを予約し、最初のカーソルポインタの後に追加データ用に少なくとも aAllocSize バイトのスペースを予約して、PacketBuffer オブジェクトを割り当てます。

詳細
パラメータ
[in] aReservedSize
カーソルの後ろで予約するオクテットの数。
[in] aAvailableSize
カーソルの後に割り当てるオクテットの数。
戻り値
成功した場合、割り当てられたブロック内の PacketBuffer へのポインタ。失敗した場合、NULL。

RightSize

PacketBuffer * RightSize(
  PacketBuffer *aPacket
)

指定されたバッファを、適切なサイズのバッファにコピーします（該当する場合）。

この関数はソケットに対しては機能しません。

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