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
)

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

詳細
パラメータ
[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 を割り当てます。

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

新規

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 を割り当てる場合に最適です。

詳細
パラメータ
[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
バッファチェーンです。
戻り値
新しいパケット バッファ、または