nl::Weave::TLV::TLVReader

#include <src/lib/core/WeaveTLV.h>

Weave TLV 形式でエンコードされたデータに対してメモリ効率の高いパーサーを提供します。

まとめ

TLVReader は Weave TLV データ用のフォワード専用「pull スタイル」のパーサーを実装します。TLVReader オブジェクトは、一連の TLV 要素を反復処理し、そのコンテンツを解釈するために使用できるカーソルとして機能します。要素上に配置されると、アプリケーションはリーダーの Get() メソッドを呼び出して、現在の要素のタイプとタグをクエリし、関連する値を抽出します。リーダーから Next() メソッドを使用して、要素間を移動します。

TLVReader オブジェクトは、常に TLV 要素の前後のどちらかに配置されます。最初に初期化されると、TLVReader はエンコードの最初の要素の直前に配置されます。読み取りを開始するには、アプリで Next() メソッドの最初の呼び出しを行い、最初の要素にリーダーを配置する必要があります。コンテナ要素に構造、配列、パスのいずれかが検出されると、OpenContainer() メソッドまたは EnterContainer() メソッドを使って、コンテナの内容を反復処理できます。

リーダーが TLV エンコードの最後、またはコンテナ内の最後の要素に達すると、Next() メソッドから WEAVE_END_OF_TLV エラーを返すことによりアプリケーションにシグナルが送信されます。リーダーは、再初期化されるか、現在のコンテナが終了するまで(CloseContainer() / ExitContainer() を介して)WEAVE_END_OF_TLV を返します。

TLVReader オブジェクトは、固定入力バッファから、または 1 つ以上の PacketBuffer のチェーンから、データを解析できます。さらに、アプリケーションは GetNextBuffer 関数を使用して、任意のソース(ソケットやシリアルポートなど)からリーダーにデータをフィードできます。

継承

直接既知のサブクラス:
nl::Weave::Profiles::DataManagement_Current::CircularEventReader
nl::Weave::TLV::CircularTLVReader

パブリック タイプ

GetNextBufferFunct)(TLVReader &reader, uintptr_t &bufHandle, const uint8_t *&bufStart, uint32_t &bufLen) WEAVE_ERROR(*)
解析する追加の TLV データを取得するために使用できる関数。

パブリック属性

AppData
void *
アプリケーション固有のデータに使用できるポインタ フィールド。
GetNextBuffer
TLVReader オブジェクトの入力データを生成する関数へのポインタ。
ImplicitProfileId
uint32_t
暗黙的にエンコードされたプロファイル タグに使用されるプロファイル ID。

プロテクト属性

mBufEnd
const uint8_t *
mBufHandle
uintptr_t
mContainerType
mControlByte
uint16_t
mElemLenOrVal
uint64_t
mElemTag
uint64_t
mLenRead
uint32_t
mMaxLen
uint32_t
mReadPoint
const uint8_t *

パブリック関数

CloseContainer(TLVReader & containerReader)
OpenContainer() の呼び出し後に TLV コンテナの読み取りを完了します。
DupBytes(uint8_t *& buf, uint32_t & dataLen)
現在のバイトまたは UTF8 文字列の値を含むバッファを割り当てて返します。
DupString(char *& buf)
現在のバイトまたは UTF8 文字列の null 終端値を含むバッファを割り当てて返します。
EnterContainer(TLVType & outerContainerType)
TLV コンテナ要素のメンバーを読み取る TLVReader オブジェクトを準備します。
ExitContainer(TLVType outerContainerType)
TLV コンテナの読み取りを完了し、コンテナの後に要素を読み取るように TLVReader オブジェクトを準備します。
Get(bool & v)
現在の要素の値をブール値のタイプとして取得します。
Get(int8_t & v)
現在の要素の値を 8 ビット符号付き整数として取得します。
Get(int16_t & v)
現在の要素の値を 16 ビット符号付き整数として取得します。
Get(int32_t & v)
現在の要素の値を 32 ビット符号付き整数として取得します。
Get(int64_t & v)
現在の要素の値を 64 ビット符号付き整数として取得します。
Get(uint8_t & v)
現在の要素の値を 8 ビットの符号なし整数として取得します。
Get(uint16_t & v)
現在の要素の値を 16 ビットの符号なし整数として取得します。
Get(uint32_t & v)
現在の要素の値を 32 ビット符号なし整数として取得します。
Get(uint64_t & v)
現在の要素の値を 64 ビット符号なし整数として取得します。
Get(float & v)
Get(double & v)
現在の要素の値を倍精度浮動小数点数として取得します。
GetBufHandle(void) const
uintptr_t
GetBytes(uint8_t *buf, uint32_t bufSize)
現在のバイトまたは UTF8 文字列要素の値を取得します。
GetContainerType(void) const
TLVReader が現在読み取るコンテナのタイプを返します。
GetControlByte(void) const
uint16_t
現在の TLV 要素に関連付けられている制御バイトを返します。
GetDataPtr(const uint8_t *& data)
TLV バイトまたは UTF8 文字列要素の最初のエンコードされたバイトへのポインタを取得します。
GetLength(void) const
uint32_t
現在の TLV 要素に関連付けられているデータの長さを返します。
GetLengthRead(void) const
uint32_t
リーダーが初期化されてから読み取られた合計バイト数を返します。
GetReadPoint(void) const
const uint8_t *
リーダーの現在の位置に対応する、基になる入力バッファ内のポイントを取得します。
GetRemainingLength(void) const
uint32_t
最大読み取り長に達するまで読み取り可能な合計バイト数を返します。
GetString(char *buf, uint32_t bufSize)
現在のバイトまたは UTF8 文字列要素の値を null で終了した文字列として取得します。
GetTag(void) const
uint64_t
現在の TLV 要素に関連付けられているタグを返します。
GetType(void) const
現在の TLV 要素のタイプを返します。
Init(const TLVReader & aReader)
void
別の TLVReader オブジェクトから TLVReader オブジェクトを初期化します。
Init(const uint8_t *data, uint32_t dataLen)
void
単一の入力バッファから読み取る TLVReader オブジェクトを初期化します。
Init(PacketBuffer *buf, uint32_t maxLen)
void
単一の PacketBuffer から読み取る TLVReader オブジェクトを初期化します。
Init(PacketBuffer *buf, uint32_t maxLen, bool allowDiscontiguousBuffers)
void
1 つ以上の PacketBuffer から読み取る TLVReader オブジェクトを初期化します。
Next(void)
TVLReader オブジェクトを、次に読み取る TLV 要素に進めます。
Next(TLVType expectedType, uint64_t expectedTag)
TLVReader オブジェクトを次に読み取る TLV 要素に進め、新しい要素の型とタグをアサートします。
OpenContainer(TLVReader & containerReader)
TLV コンテナ要素のメンバーを読み取る新しい TLVReader オブジェクトを初期化します。
Skip(void)
TLVReader オブジェクトを現在の TLV 要素の直後に移動します。
VerifyEndOfContainer(void)
TVLReader オブジェクトが TLV コンテナの最後にあることを確認します。

プロテクト関数

ClearElementState(void)
void
TLVReader の状態をクリアします。
ElementType(void) const
TLVElementType
これは、mControlByte から TLVElementType を返すプライベート メソッドです。
EnsureData(WEAVE_ERROR noDataErr)
GetElementHeadLength(uint8_t & elemHeadBytes) const
これは、TLV 要素ヘッドの長さの計算に使用されるプライベート メソッドです。
IsContainerOpen(void) const
bool
ReadData(uint8_t *buf, uint32_t len)
ReadElement(void)
ReadTag(TLVTagControl tagControl, const uint8_t *& p)
uint64_t
SetContainerOpen(bool aContainerOpen)
void
SkipData(void)
現在の TLV に含まれるデータをすべて宛先バッファなしで読み取ってスキップします。
SkipToEndOfContainer(void)
VerifyElement(void)

保護された静的関数

FailGetNextBuffer(TLVReader & reader, uintptr_t & bufHandle, const uint8_t *& bufStart, uint32_t & bufLen)
GetNextPacketBuffer(TLVReader & reader, uintptr_t & bufHandle, const uint8_t *& bufStart, uint32_t & bufLen)

パブリック タイプ

GetNextBufferFunct

WEAVE_ERROR(* GetNextBufferFunct)(TLVReader &reader, uintptr_t &bufHandle, const uint8_t *&bufStart, uint32_t &bufLen)

解析する追加の TLV データを取得するために使用できる関数。

このタイプの関数は、入力データを TLVReader にフィードするために使用します。呼び出されると、この関数によって追加データが生成され、リーダーがこれ以上データが利用できないことが解析またはシグナルされます。

詳細
パラメータ
[in] reader
入力データをリクエストしている TLVReader オブジェクトへの参照。
[in,out] bufHandle
関数が呼び出し間でコンテキスト データを保存するために使用できる uintptr_t 値への参照。この値は、最初の呼び出しの前に 0 に初期化されます。
[in,out] bufStart
データポインタへの参照。関数の開始時に、bufStart は、リーダーが消費した最後の TLV データバイトを超える 1 バイトを指します。終了時に、bufStart は解析対象の新しい TLV データの最初のバイトを指すことが想定されます。新しいポインタ値は、以前使用したデータと同じバッファに収めることも、まったく新しいバッファを指すこともできます。
[out] bufLen
関数が返す TLV データバイト数に設定される符号なし整数への参照。入力 TLV データの最後に達した場合、この関数はこの値を 0 に設定します。
戻り値
WEAVE_NO_ERROR
関数によって TLV データが正常に生成された場合、または入力データの最後に達した場合(この場合は bufLen を 0 に設定する必要があります)。
other
関数がリクエスト データを生成できないというエラーが発生したことを示す、その他の Weave またはプラットフォーム固有のエラーコード。

パブリック属性

アプリデータ

void * AppData

アプリケーション固有のデータに使用できるポインタ フィールド。

GetNextBuffer

GetNextBufferFunct GetNextBuffer

TLVReader オブジェクトの入力データを生成する関数へのポインタ。

NULL(デフォルト値)に設定すると、読み取りデータは入力データがそれ以上提供されないものとみなされます。

GetNextBuffer は、アプリケーションがいつでも設定できますが、通常はリーダーの初期化時に設定されます。

GetNextBuffer 関数の実装について詳しくは、GetNextBufferFunct 型の定義をご覧ください。

暗黙的なプロファイル ID

uint32_t ImplicitProfileId

暗黙的にエンコードされたプロファイル タグに使用されるプロファイル ID。

リーダーでは、暗黙的にエンコードされたプロファイル固有のタグが検出されると、ImplicitProfileId プロパティの値がタグの想定プロファイル ID として使用されます。

デフォルトでは、ImplicitProfileId プロパティは kProfileIdNotSpecified に設定されています。暗黙的にエンコードされたタグを含む TLV をデコードする場合、アプリはそのようなタグを持つ TLV 要素を読み取る前に、ImplicitProfileId を設定する必要があります。適切なプロファイル ID は通常、話されているアプリケーションまたはプロトコルのコンテキストによって異なります。

ImplicitProfileId が kProfileIdNotSpecified に設定されている間に暗黙的にエンコードされたタグが検出されると、リーダーは WEAVE_ERROR_UNKNOWN_IMPLICIT_TLV_TAG エラーを返します。

プロテクト属性

mBufEnd

const uint8_t * mBufEnd

mBufHandle

uintptr_t mBufHandle

mContainerType

TLVType mContainerType

mControlByte

uint16_t mControlByte

memlemLenOrVal

uint64_t mElemLenOrVal

モバイルタグ

uint64_t mElemTag

mLenRead

uint32_t mLenRead

mMaxLen

uint32_t mMaxLen

mReadPoint

const uint8_t * mReadPoint

パブリック関数

コンテナを閉じる

WEAVE_ERROR CloseContainer(
  TLVReader & containerReader
)

OpenContainer() の呼び出し後に TLV コンテナの読み取りを完了します。

CloseContainer() メソッドは、OpenContainer() を呼び出した後、親の TLVReader オブジェクトの状態を復元します。OpenContainer() アプリケーションへの呼び出しごとに、対応する CloseContainer() を呼び出し、両方のメソッドに同じコンテナ リーダーへの参照を渡す必要があります。

CloseContainer() が返されると、親リーダーはコンテナに続く最初の要素の直前に配置されます。この時点から、アプリケーションは Next() メソッドを使用して、残りの要素を進めることができます。

アプリケーションは、基盤となるコンテナ内のすべての要素が読み取られたかどうかにかかわらず、いつでも親リーダーで閉じる CloseContainer() を呼び出すことができます。CloseContainer() が呼び出されたら、アプリケーションはコンテナ リーダーを「初期化済み」と見なし、再初期化しない限り使用しません。

詳細
パラメータ
[in] containerReader
OpenContainer() メソッドに提供された TLVReader オブジェクトへの参照。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_INCORRECT_STATE
リーダーで OpenContainer() が呼び出されていない場合、またはコンテナ リーダーが OpenContainer() メソッドに渡されたものと一致しない場合。
WEAVE_ERROR_TLV_UNDERRUN
基盤となる TLV エンコードが途中で終了した場合。
WEAVE_ERROR_INVALID_TLV_ELEMENT
リーダーが無効な、またはサポートされていない TLV 要素タイプを検出した場合。
WEAVE_ERROR_INVALID_TLV_TAG
読者が無効なコンテキストで TLV タグを検出した場合。
other
設定された GetNextBuffer() 関数によって返されるその他の Weave またはプラットフォームのエラーコード。GetNextBuffer が NULL でない場合にのみ可能です。

DupBytes

WEAVE_ERROR DupBytes(
  uint8_t *& buf,
  uint32_t & dataLen
)

現在のバイトまたは UTF8 文字列の値を含むバッファを割り当てて返します。

このメソッドはバッファを作成し、現在の位置のバイトまたは UTF-8 文字列要素に関連付けられたデータのコピーを返します。バッファのメモリは malloc() で取得され、不要になったら呼び出し元によって free() で解放する必要があります。

詳細
パラメータ
[out] buf
dataLen バイトのヒープ割り当てバッファが成功時に割り当てられるポインタへの参照。
[out] dataLen
成功時の buf のサイズ(バイト単位)のストレージへの参照。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_WRONG_TLV_TYPE
現在の要素が TLV バイトまたは UTF8 文字列でない場合、またはリーダーが要素に配置されていない場合。
WEAVE_ERROR_NO_MEMORY
出力バッファにメモリを割り当てられなかった場合。
WEAVE_ERROR_TLV_UNDERRUN
基盤となる TLV エンコードが途中で終了した場合。
WEAVE_ERROR_UNSUPPORTED_WEAVE_FEATURE
ターゲット プラットフォームが malloc() と free() をサポートしていない場合。
other
設定された GetNextBuffer() 関数によって返されるその他の Weave またはプラットフォームのエラーコード。GetNextBuffer が NULL でない場合にのみ可能です。

文字列

WEAVE_ERROR DupString(
  char *& buf
)

現在のバイトまたは UTF8 文字列の null 終端値を含むバッファを割り当てて返します。

このメソッドはバッファを作成し、現在の位置にあるバイトまたは UTF-8 文字列要素に関連付けられたデータの null 終端コピーを返します。バッファのメモリは malloc() で取得され、不要になったら呼び出し元によって free() で解放する必要があります。

詳細
パラメータ
[out] buf
成功したときにヒープ割り当てバッファが割り当てられるポインタへの参照。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_WRONG_TLV_TYPE
現在の要素が TLV バイトまたは UTF8 文字列でない場合、またはリーダーが要素に配置されていない場合。
WEAVE_ERROR_NO_MEMORY
出力バッファにメモリを割り当てられなかった場合。
WEAVE_ERROR_TLV_UNDERRUN
基盤となる TLV エンコードが途中で終了した場合。
WEAVE_ERROR_UNSUPPORTED_WEAVE_FEATURE
ターゲット プラットフォームが malloc() と free() をサポートしていない場合。
other
設定された GetNextBuffer() 関数によって返されるその他の Weave またはプラットフォームのエラーコード。GetNextBuffer が NULL でない場合にのみ可能です。

EnterContainer

WEAVE_ERROR EnterContainer(
  TLVType & outerContainerType
)

TLV コンテナ要素のメンバーを読み取る TLVReader オブジェクトを準備します。

EnterContainer() メソッドは現在の TLVReader オブジェクトを準備して、TLV コンテナのメンバー要素(構造、配列、パス)の読み取りを開始します。アプリケーションが EnterContainer() を呼び出すたびに、それに応じて ExitContainer() を呼び出す必要があります。

EnterContainer() が呼び出された場合、読み取るコンテナ要素に TLVReader オブジェクトを配置する必要があります。このメソッドは、コンテナの読み取り中にリーダーのコンテキストを保存するために、TLVType 値への参照を引数として受け取ります。

EnterContainer() メソッドが返されると、リーダーはコンテナの最初のメンバーの直前に配置されます。Next() を繰り返し呼び出すと、リーダーはコレクションのメンバーまで移動し、最後まで到達すると WEAVE_END_OF_TLV を返します。

アプリケーションがコンテナの読み取りを終了したら、コンテナの終了後に要素を終了するために、ExitContainer() メソッドを呼び出すことができます。

詳細
パラメータ
[out] outerContainerType
リーダーのコンテキストを受け取る TLVType 値への参照。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_INCORRECT_STATE
現在の要素がコンテナ要素に配置されていない場合。

ExitContainer

WEAVE_ERROR ExitContainer(
  TLVType outerContainerType
)

TLV コンテナの読み取りを完了し、コンテナの後に要素を読み取るように TLVReader オブジェクトを準備します。

ExitContainer() メソッドは、EnterContainer() を呼び出した後、TLVReader オブジェクトの状態を復元します。EnterContainer() アプリケーションへの呼び出しごとに、それに応じて ExitContainer() を呼び出し、EnterContainer() メソッドで返されるコンテキスト値を渡す必要があります。

ExitContainer() が返されると、リーダーはコンテナに続く最初の要素の直前に配置されます。この時点から、アプリケーションは Next() メソッドを使用して、残りの要素を進めることができます。

EnterContainer() が呼び出されると、アプリケーションは、基盤となるコンテナ内のすべての要素が読み取られたかどうかにかかわらず、リーダーで ExitContainer() を呼び出すことができます。

詳細
パラメータ
[in] outerContainerType
EnterContainer() メソッドで返された TLVType の値です。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_INCORRECT_STATE
リーダーで OpenContainer() が呼び出されていない場合、またはコンテナ リーダーが OpenContainer() メソッドに渡されたものと一致しない場合。
WEAVE_ERROR_TLV_UNDERRUN
基盤となる TLV エンコードが途中で終了した場合。
WEAVE_ERROR_INVALID_TLV_ELEMENT
リーダーが無効な、またはサポートされていない TLV 要素タイプを検出した場合。
WEAVE_ERROR_INVALID_TLV_TAG
読者が無効なコンテキストで TLV タグを検出した場合。
other
設定された GetNextBuffer() 関数によって返されるその他の Weave またはプラットフォームのエラーコード。GetNextBuffer が NULL でない場合にのみ可能です。

Get

WEAVE_ERROR Get(
  bool & v
)

現在の要素の値をブール値のタイプとして取得します。

詳細
パラメータ
[out] v
現在の TLV 要素に関連付けられている値を受け取ります。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_WRONG_TLV_TYPE
現在の要素が TLV ブール値型でない場合、または要素にリーダーが配置されていない場合。

Get

WEAVE_ERROR Get(
  int8_t & v
)

現在の要素の値を 8 ビット符号付き整数として取得します。

エンコードされた整数値が出力データ型より大きい場合、結果の値は切り捨てられます。

詳細
パラメータ
[out] v
現在の TLV 要素に関連付けられている値を受け取ります。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_WRONG_TLV_TYPE
現在の要素が TLV 整数型(符号付きまたは符号なし)でない場合、またはリーダー上に要素を配置していない場合。

Get

WEAVE_ERROR Get(
  int16_t & v
)

現在の要素の値を 16 ビット符号付き整数として取得します。

エンコードされた整数値が出力データ型より大きい場合、結果の値は切り捨てられます。

詳細
パラメータ
[out] v
現在の TLV 要素に関連付けられている値を受け取ります。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_WRONG_TLV_TYPE
現在の要素が TLV 整数型(符号付きまたは符号なし)でない場合、またはリーダー上に要素を配置していない場合。

Get

WEAVE_ERROR Get(
  int32_t & v
)

現在の要素の値を 32 ビット符号付き整数として取得します。

エンコードされた整数値が出力データ型より大きい場合、結果の値は切り捨てられます。

詳細
パラメータ
[out] v
現在の TLV 要素に関連付けられている値を受け取ります。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_WRONG_TLV_TYPE
現在の要素が TLV 整数型(符号付きまたは符号なし)でない場合、またはリーダー上に要素を配置していない場合。

Get

WEAVE_ERROR Get(
  int64_t & v
)

現在の要素の値を 64 ビット符号付き整数として取得します。

エンコードされた整数値が出力データ型より大きい場合、結果の値は切り捨てられます。

詳細
パラメータ
[out] v
現在の TLV 要素に関連付けられている値を受け取ります。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_WRONG_TLV_TYPE
現在の要素が TLV 整数型(符号付きまたは符号なし)でない場合、またはリーダー上に要素を配置していない場合。

Get

WEAVE_ERROR Get(
  uint8_t & v
)

現在の要素の値を 8 ビットの符号なし整数として取得します。

エンコードされた整数値が出力データ型より大きい場合、結果の値は切り捨てられます。同様に、エンコードされた整数値が負の場合、その値は符号なしに変換されます。

詳細
パラメータ
[out] v
現在の TLV 要素に関連付けられている値を受け取ります。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_WRONG_TLV_TYPE
現在の要素が TLV 整数型(符号付きまたは符号なし)でない場合、またはリーダー上に要素を配置していない場合。

Get

WEAVE_ERROR Get(
  uint16_t & v
)

現在の要素の値を 16 ビットの符号なし整数として取得します。

エンコードされた整数値が出力データ型より大きい場合、結果の値は切り捨てられます。同様に、エンコードされた整数値が負の場合、その値は符号なしに変換されます。

詳細
パラメータ
[out] v
現在の TLV 要素に関連付けられている値を受け取ります。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_WRONG_TLV_TYPE
現在の要素が TLV 整数型(符号付きまたは符号なし)でない場合、またはリーダー上に要素を配置していない場合。

Get

WEAVE_ERROR Get(
  uint32_t & v
)

現在の要素の値を 32 ビット符号なし整数として取得します。

エンコードされた整数値が出力データ型より大きい場合、結果の値は切り捨てられます。同様に、エンコードされた整数値が負の場合、その値は符号なしに変換されます。

詳細
パラメータ
[out] v
現在の TLV 要素に関連付けられている値を受け取ります。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_WRONG_TLV_TYPE
現在の要素が TLV 整数型(符号付きまたは符号なし)でない場合、またはリーダー上に要素を配置していない場合。

Get

WEAVE_ERROR Get(
  uint64_t & v
)

現在の要素の値を 64 ビット符号なし整数として取得します。

エンコードされた整数値が負の場合、その値は符号なしに変換されます。

詳細
パラメータ
[out] v
現在の TLV 要素に関連付けられている値を受け取ります。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_WRONG_TLV_TYPE
現在の要素が TLV 整数型(符号付きまたは符号なし)でない場合、またはリーダー上に要素を配置していない場合。

Get

WEAVE_ERROR Get(
  float & v
)

Get

WEAVE_ERROR Get(
  double & v
)

現在の要素の値を倍精度浮動小数点数として取得します。

詳細
パラメータ
[out] v
現在の TLV 要素に関連付けられている値を受け取ります。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_WRONG_TLV_TYPE
現在の要素が TLV 浮動小数点型でない場合、またはリーダーが要素に配置されていない場合。

GetBufHandle

uintptr_t GetBufHandle(
  void
) const 

GetBytes

WEAVE_ERROR GetBytes(
  uint8_t *buf,
  uint32_t bufSize
)

現在のバイトまたは UTF8 文字列要素の値を取得します。

必要な入力バッファサイズを決定するには、GetBytes() を呼び出す前に GetLength() メソッドを呼び出します。

詳細
パラメータ
[in] buf
文字列データを受け取るバッファへのポインタ。
[in] bufSize
buf が指すバッファのサイズ(バイト単位)。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_WRONG_TLV_TYPE
現在の要素が TLV バイトまたは UTF8 文字列でない場合、またはリーダーが要素に配置されていない場合。
WEAVE_ERROR_BUFFER_TOO_SMALL
指定されたバッファが小さすぎて、現在の要素に関連付けられたデータを保持できない場合。
WEAVE_ERROR_TLV_UNDERRUN
基盤となる TLV エンコードが途中で終了した場合。
other
設定された GetNextBuffer() 関数によって返されるその他の Weave またはプラットフォームのエラーコード。GetNextBuffer が NULL でない場合にのみ可能です。

GetContainerType

TLVType GetContainerType(
  void
) const 

TLVReader が現在読み取るコンテナのタイプを返します。

GetContainerType() メソッドは、TLVReader が読み取る TLV コンテナのタイプを返します。TLVReaderTLV エンコードの最も外側のレベル(最も外側の TLV 要素の前後にあるなど)に配置されている場合、このメソッドは kTLVType_NotSpecified を返します。

詳細
戻り値
現在のコンテナの TLVType。TLVReader がコンテナ内に配置されていない場合は kTLVType_NotSpecified です。

GetControlByte

uint16_t GetControlByte(
  void
) const 

現在の TLV 要素に関連付けられている制御バイトを返します。

コントロール バイトのことを誰も知る必要がなく、TLV の内部実装のみがアクセスできるのが理想的です。それでも、コントロール バイトにアクセスできれば、TLVDebug ユーティリティTLV バッファの内容をかなり出力するときにタグ コントロール バイトをデコードしようとする)によるデバッグに役立ちます。

詳細
戻り値
現在の TLV 要素に関連付けられている制御バイトを含む符号なし整数。リーダーが要素に配置されていない場合、kTLVControlByte_NotSpecified が返されます。

GetDataPtr

WEAVE_ERROR GetDataPtr(
  const uint8_t *& data
)

TLV バイトまたは UTF8 文字列要素の最初のエンコードされたバイトへのポインタを取得します。

このメソッドは、基盤となる入力バッファ内のエンコードされた文字列値を直接ポインタに返します。成功するには、文字列値全体が 1 つのバッファ内に存在している必要があります。それ以外の場合、メソッドは WEAVE_ERROR_TLV_UNDERRUN を返します。そのため、不連続な複数のバッファからデータを読み取る場合、メソッドの使用は制限されます。

詳細
パラメータ
[out] data
基になる文字列データへのポインタを受け取る const ポインタへの参照です。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_WRONG_TLV_TYPE
現在の要素が TLV バイトまたは UTF8 文字列でない場合、またはリーダーが要素に配置されていない場合。
WEAVE_ERROR_TLV_UNDERRUN
基盤となる TLV エンコードが途中で終了した場合、または現在の文字列要素の値が連続する 1 つのバッファに含まれていない場合。
other
設定された GetNextBuffer() 関数によって返されるその他の Weave またはプラットフォームのエラーコード。GetNextBuffer が NULL でない場合にのみ可能です。

GetLength

uint32_t GetLength(
  void
) const 

現在の TLV 要素に関連付けられているデータの長さを返します。

データ長は UTF8 文字列型またはバイト文字列型の要素にのみ適用されます。UTF8 文字列の場合、返される値は文字列ではなく、文字列のバイト数です。

詳細
戻り値
現在の TLV 要素に関連するデータの長さ(バイト単位)。現在の要素が UTF8 文字列またはバイト文字列でない場合、またはリーダーが要素に配置されていない場合は 0。

GetLengthRead

uint32_t GetLengthRead(
  void
) const 

リーダーが初期化されてから読み取られた合計バイト数を返します。

詳細
戻り値
リーダーが初期化されてから読み取られた合計バイト数。

GetReadPoint

const uint8_t * GetReadPoint(
  void
) const 

リーダーの現在の位置に対応する、基になる入力バッファ内のポイントを取得します。

詳細
戻り値
リーダーの現在の位置に対応する、基盤となる入力バッファへのポインタ。

GetRemainingLength

uint32_t GetRemainingLength(
  void
) const 

最大読み取り長に達するまで読み取り可能な合計バイト数を返します。

詳細
戻り値
最大読み取り長に達するまで読み取り可能な合計バイト数。

GetString

WEAVE_ERROR GetString(
  char *buf,
  uint32_t bufSize
)

現在のバイトまたは UTF8 文字列要素の値を null で終了した文字列として取得します。

必要な入力バッファサイズを決定するには、GetLength() メソッドを呼び出してから、GetBytes() を呼び出します。入力バッファは、null 文字を格納するための文字列長より少なくとも 1 バイト大きい必要があります。

詳細
パラメータ
[in] buf
バイト文字列データを受け取るバッファへのポインタ。
[in] bufSize
buf が指すバッファのサイズ(バイト単位)。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_WRONG_TLV_TYPE
現在の要素が TLV バイトまたは UTF8 文字列でない場合、またはリーダーが要素に配置されていない場合。
WEAVE_ERROR_BUFFER_TOO_SMALL
指定されたバッファが小さすぎて、現在の要素に関連付けられたデータを保持できない場合。
WEAVE_ERROR_TLV_UNDERRUN
基盤となる TLV エンコードが途中で終了した場合。
other
設定された GetNextBuffer() 関数によって返されるその他の Weave またはプラットフォームのエラーコード。GetNextBuffer が NULL でない場合にのみ可能です。

GetTag

uint64_t GetTag(
  void
) const 

現在の TLV 要素に関連付けられているタグを返します。

GetTag() で返された値は、タグ ユーティリティ関数(IsProfileTag()IsContextTag()ProfileIdFromTag() など)と合わせて使用することにより、タグのタイプを判別したり、さまざまなタグ フィールド値を抽出したりすることができます。

詳細
戻り値
現在の TLV 要素に関連付けられているタグに関する情報を含む符号なし整数。

GetType

TLVType GetType(
  void
) const 

現在の TLV 要素のタイプを返します。

詳細
戻り値
現在の TLV 要素のデータ型を記述する TLVType の値。リーダーが TLV 要素に配置されていない場合、戻り値は kTLVType_NotSpecified になります。

init

void Init(
  const TLVReader & aReader
)

別の TLVReader オブジェクトから TLVReader オブジェクトを初期化します。

詳細
パラメータ
[in] aReader
初期化元の TLVReader の読み取り専用参照。

init

void Init(
  const uint8_t *data,
  uint32_t dataLen
)

単一の入力バッファから読み取る TLVReader オブジェクトを初期化します。

詳細
パラメータ
[in] data
解析される TLV データを含むバッファへのポインタ。
[in] dataLen
解析される TLV データの長さ。

init

void Init(
  PacketBuffer *buf,
  uint32_t maxLen
)

単一の PacketBuffer から読み取る TLVReader オブジェクトを初期化します。

解析はバッファの開始位置(buf->DataStart())から始まり、バッファ内のデータの末尾(buf->Datalen() で表される)まで、または maxLen バイトが解析されるまで継続します。

詳細
パラメータ
[in] buf
解析される TLV データを含む PacketBuffer へのポインタ。
[in] maxLen
解析する最大バイト数。デフォルトは入力バッファ内のデータ量です。

init

void Init(
  PacketBuffer *buf,
  uint32_t maxLen,
  bool allowDiscontiguousBuffers
)

1 つ以上の PacketBuffer から読み取る TLVReader オブジェクトを初期化します。

解析は、最初のバッファの開始位置(buf->DataStart())から始まります。allowDiscontiguousBuffers が true の場合、リーダーは Next() ポインタによってリンクされたバッファのチェーンを進行します。解析は、バッファ チェーン内のすべてのデータが使用されるか(buf->Datalen() で示されます)、maxLen バイトが解析されるまで継続します。

詳細
パラメータ
[in] buf
解析される TLV データを含む PacketBuffer へのポインタ。
[in] maxLen
解析する最大バイト数。デフォルトでは、入力バッファ チェーン内のデータの合計量になります。
[in] allowDiscontiguousBuffers
true の場合、現在のバッファ内のすべてのデータが消費されたら、チェーン内の次のバッファに進みます。false の場合は、初期バッファの最後に解析を停止します。

次へ

WEAVE_ERROR Next(
  void
)

TVLReader オブジェクトを、次に読み取る TLV 要素に進めます。

Next() メソッドは、同じ包含コンテキストに存在する TLV エンコードの次の要素にリーダー オブジェクトを配置します。特に、リーダーが TLV エンコードの最も外側のレベルに配置されている場合、Next() を呼び出すと、リーダーが次に最上位にある要素に移動されます。リーダーが TLV コンテナ要素(構造、配列、パス)内に配置されている場合、Next() を呼び出すと、リーダーをコンテナの次のメンバー要素に移動させることができます。

Next() では、リーダーの動きを現在のコンテインメント コンテキストに制限しているため、リーダーをコンテナ要素に配置する際に Next() を呼び出すと、コンテナよりに移動し、そのメンバー要素(およびネストされたコンテナのメンバー)はコンテナより後の最初の要素に到達するまでスキップされます。

特定のコンテインメント コンテキスト内に要素が他にない場合、Next() メソッドは WEAVE_END_OF_TLV エラーを返し、リーダーの位置は変更されません。

詳細
戻り値
WEAVE_NO_ERROR
新しい要素にリーダーが配置されたかどうか。
WEAVE_END_OF_TLV
他に利用できる要素がない場合。
WEAVE_ERROR_TLV_UNDERRUN
基盤となる TLV エンコードが途中で終了した場合。
WEAVE_ERROR_INVALID_TLV_ELEMENT
リーダーが無効な、またはサポートされていない TLV 要素タイプを検出した場合。
WEAVE_ERROR_INVALID_TLV_TAG
読者が無効なコンテキストで TLV タグを検出した場合。
WEAVE_ERROR_UNKNOWN_IMPLICIT_TLV_TAG
暗黙的にエンコードされた TLV タグを検出した場合(対応するプロファイル ID は不明)。
other
設定された GetNextBuffer() 関数によって返されるその他の Weave またはプラットフォームのエラーコード。GetNextBuffer が NULL でない場合にのみ可能です。

次へ

WEAVE_ERROR Next(
  TLVType expectedType,
  uint64_t expectedTag
)

TLVReader オブジェクトを次に読み取る TLV 要素に進め、新しい要素の型とタグをアサートします。

Next(TLVType を期待されるタイプ, uint64_t を期待されるタグ) メソッドは便利なメソッドです。これは Next() と同じ動作をしますが、新しい TLV 要素のタイプとタグが、指定された引数と一致することを確認します。

詳細
パラメータ
[in] expectedType
次の要素に想定されるデータ型。
[in] expectedTag
次の要素に想定されるタグ。
戻り値
WEAVE_NO_ERROR
新しい要素にリーダーが配置されたかどうか。
WEAVE_END_OF_TLV
他に利用できる要素がない場合。
WEAVE_ERROR_WRONG_TLV_TYPE
新しい要素の型が expectedType 引数の値と一致しない場合。
WEAVE_ERROR_UNEXPECTED_TLV_ELEMENT
新しい要素に関連付けられたタグが expectedTag 引数の値と一致しない場合。
WEAVE_ERROR_TLV_UNDERRUN
基盤となる TLV エンコードが途中で終了した場合。
WEAVE_ERROR_INVALID_TLV_ELEMENT
リーダーが無効な、またはサポートされていない TLV 要素タイプを検出した場合。
WEAVE_ERROR_INVALID_TLV_TAG
読者が無効なコンテキストで TLV タグを検出した場合。
other
設定された GetNextBuffer() 関数によって返されるその他の Weave またはプラットフォームのエラーコード。GetNextBuffer が NULL でない場合にのみ可能です。

OpenContainer

WEAVE_ERROR OpenContainer(
  TLVReader & containerReader
)

TLV コンテナ要素のメンバーを読み取る新しい TLVReader オブジェクトを初期化します。

OpenContainer() メソッドは、TLV コンテナのメンバー要素(構造、配列、またはパス)を読み取るための新しい TLVReader オブジェクトを初期化します。OpenContainer() が呼び出されたら、読み取るコンテナ要素に現在の TLVReader オブジェクトを配置する必要があります。このメソッドは、コンテナを読み取るために初期化される新しいリーダーへの参照を、唯一の引数として受け取ります。このリーダーはコンテナ リーダーと呼ばれ、OpenContainer() が呼び出されるリーダーは親リーダーと呼ばれます。

OpenContainer() メソッドが返されると、コンテナ リーダーはコンテナの最初のメンバーの直前に配置されます。コンテナ リーダーで Next() を呼び出すと、最後まで到達するまでコレクションのメンバーが移動し、その時点でリーダーは WEAVE_END_OF_TLV を返します。

コンテナ リーダーが開いている間、アプリケーションは親リーダーの呼び出しや状態の変更はできません。アプリケーションがコンテナ リーダーの使用を終了したら、親リーダーで CloseContainer() を呼び出し、コンテナ リーダーを引数として渡してアプリケーションを閉じる必要があります。アプリケーションは、基盤となるコンテナに含まれるすべての要素を読み取るかどうかにかかわらず、いつでもコンテナ リーダーを閉じることができます。コンテナ リーダーを閉じた後も、アプリケーションは親リーダーを引き続き使用できます。

コンテナ リーダーは、親リーダーからさまざまな構成プロパティを継承します。サポートしているものは次のとおりです。

  • 暗黙的プロファイル ID(ImplicitProfileId)
  • アプリケーション データ ポインタ(AppData)
  • GetNextBuffer 関数ポインタ

詳細
パラメータ
[out] containerReader
現在のコンテナ要素のメンバーを読み取るために初期化される TLVReader オブジェクトへの参照。指定されたオブジェクトに関連付けられたデータはすべて上書きされます。
戻り値
WEAVE_NO_ERROR
メソッドが成功した場合。
WEAVE_ERROR_INCORRECT_STATE
現在の要素がコンテナ要素に配置されていない場合。

スキップ

WEAVE_ERROR Skip(
  void
)

TLVReader オブジェクトを現在の TLV 要素の直後に移動します。

Skip() メソッドは、現在の TLV 要素の直後にリーダー オブジェクトを配置して、後続の Next() の呼び出しでリーダーを次の要素に進めます。Next() と同様、リーダーが呼び出し時にコンテナ要素上に配置されている場合、コンテナのメンバーはスキップされます。リーダーがどの要素にも配置されていない場合は、その位置は変更されません。

詳細
戻り値
WEAVE_NO_ERROR
新しい要素にリーダーが配置されたかどうか。
WEAVE_END_OF_TLV
他に利用できる要素がない場合。
WEAVE_ERROR_TLV_UNDERRUN
基盤となる TLV エンコードが途中で終了した場合。
WEAVE_ERROR_INVALID_TLV_ELEMENT
リーダーが無効な、またはサポートされていない TLV 要素タイプを検出した場合。
WEAVE_ERROR_INVALID_TLV_TAG
読者が無効なコンテキストで TLV タグを検出した場合。
other
設定された GetNextBuffer() 関数によって返されるその他の Weave またはプラットフォームのエラーコード。GetNextBuffer が NULL でない場合にのみ可能です。

コンテナの確認を確認する

WEAVE_ERROR VerifyEndOfContainer(
  void
)

TVLReader オブジェクトが TLV コンテナの最後にあることを確認します。

VerifyEndOfContainer() メソッドは、現在の TLV コンテナ内に読み込まれる TLV 要素がないことを確認します。これは、Next() を呼び出して戻り値 WEAVE_END_OF_TLV をチェックする場合と同等の便利なメソッドです。

詳細
戻り値
WEAVE_NO_ERROR
読み取られる TLV 要素が他にない場合。
WEAVE_ERROR_UNEXPECTED_TLV_ELEMENT
コレクションに別の TLV 要素が見つかった場合。
WEAVE_ERROR_TLV_UNDERRUN
基盤となる TLV エンコードが途中で終了した場合。
WEAVE_ERROR_INVALID_TLV_ELEMENT
リーダーが無効な、またはサポートされていない TLV 要素タイプを検出した場合。
WEAVE_ERROR_INVALID_TLV_TAG
読者が無効なコンテキストで TLV タグを検出した場合。
other
設定された GetNextBuffer() 関数によって返されるその他の Weave またはプラットフォームのエラーコード。GetNextBuffer が NULL でない場合にのみ可能です。

プロテクト関数

ClearElementState

void ClearElementState(
  void
)

TLVReader の状態をクリアします。

このメソッドは、最初の TLV の前、TLV 間、または最後の TLV の後ろにリーダーを配置するために使用されます。

ElementType

TLVElementType ElementType(
  void
) const 

これは、mControlByte から TLVElementType を返すプライベート メソッドです。

データの確保

WEAVE_ERROR EnsureData(
  WEAVE_ERROR noDataErr
)

GetElementHeadLength

WEAVE_ERROR GetElementHeadLength(
  uint8_t & elemHeadBytes
) const 

これは、TLV 要素ヘッドの長さの計算に使用されるプライベート メソッドです。

IsContainerOpen

bool IsContainerOpen(
  void
) const 

読み取りデータ

WEAVE_ERROR ReadData(
  uint8_t *buf,
  uint32_t len
)

ReadElement

WEAVE_ERROR ReadElement(
  void
)

ReadTag

uint64_t ReadTag(
  TLVTagControl tagControl,
  const uint8_t *& p
)

コンテナを設定

void SetContainerOpen(
  bool aContainerOpen
)

データをスキップ

WEAVE_ERROR SkipData(
  void
)

現在の TLV に含まれるデータをすべて宛先バッファなしで読み取ってスキップします。

詳細
戻り値
WEAVE_NO_ERROR
データの最後にリーダーが正常に配置されたかどうか。
other
設定された GetNextBuffer() 関数によって返されるその他の Weave またはプラットフォームのエラーコード。GetNextBuffer が NULL でない場合にのみ可能です。

SkipToEndOfContainer

WEAVE_ERROR SkipToEndOfContainer(
  void
)

VerifyElement

WEAVE_ERROR VerifyElement(
  void
)

保護された静的関数

FailGetNextBuffer

WEAVE_ERROR FailGetNextBuffer(
  TLVReader & reader,
  uintptr_t & bufHandle,
  const uint8_t *& bufStart,
  uint32_t & bufLen
)

GetNextPacketBuffer

WEAVE_ERROR GetNextPacketBuffer(
  TLVReader & reader,
  uintptr_t & bufHandle,
  const uint8_t *& bufStart,
  uint32_t & bufLen
)