nl:: Weave:: TLV:: TLVUpdater
#include <src/lib/core/WeaveTLV.h>
TLV エンコードの要素を編集、追加、削除するための統合されたリーダー / ライター インターフェースを提供します。
概要
TLVUpdater は、TLVReader オブジェクトと TLVWriter オブジェクトを結合したもので、エンコード内のデータの編集/削除や、TLV エンコードへの新しい要素の追加を行うためのインターフェース メソッドを提供します。TLVUpdater オブジェクトは基本的に 2 つのカーソルのように機能します。1 つは既存のエンコードの読み取り用、もう 1 つは書き込み用(既存のデータのコピーまたは新しいデータの書き込み)です。
意味的には、TLVUpdater オブジェクトは、TLVReader と TLVWriter の結合体のように機能します。TLVUpdater メソッドの意味は、TLVReader/TLVWriter の同様の名前を持つものと同じです。セマンティクスに違いがある場合は、WeaveTLVUpdater.cpp の関数のコメント セクションに違いが明記されています。
TLVUpdater の PutBytes() メソッドと PutString() メソッドについて特に重要な点の 1 つに、オーバーフローが発生したときに要素ヘッダーのみが書き込まれ、エンコードが破損した状態のままとなる可能性があることです。アプリケーションは GetRemainingFreeLength() を呼び出して、エンコードを書き込むのにほぼ十分な空き領域があることを確認できます。GetRemainingFreeLength() は利用可能な空きバイト数のみを通知し、書き込まれるエンコードされたデータの長さをアプリケーションが把握する方法はないことに注意してください。オーバーフローが発生すると、PutBytes() と PutString() はどちらも呼び出し元に WEAVE_ERROR_BUFFER_TOO_SMALL を返します。
また、Next() メソッドはオーバーロードされ、現在の要素をスキップするとともに、内部リーダーを次の要素に進めます。すでにエンコードされた要素をスキップするには、新しい解放されたスペースを考慮して内部ライターの空き領域状態変数を変更する必要があるため(スキップすることで利用可能になります)、アプリケーションは、値を書き戻さない Get() メソッドの後でアップデータで Next() を呼び出す必要があります(現在の要素をスキップするのと同じです)。
パブリック関数 |
|
---|---|
CopyElement(TLVReader & reader)
|
|
CopyElement(uint64_t tag, TLVReader & reader)
|
|
DupBytes(uint8_t *& buf, uint32_t & dataLen)
|
|
DupString(char *& buf)
|
|
EndContainer(TLVType outerContainerType)
|
|
EnterContainer(TLVType & outerContainerType)
|
コンテナの要素を読み取るための TLVUpdater オブジェクトを作成します。
|
ExitContainer(TLVType outerContainerType)
|
|
Finalize(void)
|
|
Get(bool & v)
|
|
Get(int8_t & v)
|
|
Get(int16_t & v)
|
|
Get(int32_t & v)
|
|
Get(int64_t & v)
|
|
Get(uint8_t & v)
|
|
Get(uint16_t & v)
|
|
Get(uint32_t & v)
|
|
Get(uint64_t & v)
|
|
Get(float & v)
|
|
Get(double & v)
|
|
GetBytes(uint8_t *buf, uint32_t bufSize)
|
|
GetContainerType(void) const
|
|
GetDataPtr(const uint8_t *& data)
|
|
GetImplicitProfileId(void)
|
uint32_t
|
GetLength(void) const
|
uint32_t
|
GetLengthRead(void) const
|
uint32_t
|
GetLengthWritten(void)
|
uint32_t
|
GetReader(TLVReader & containerReader)
|
void
|
GetRemainingFreeLength(void)
|
uint32_t
|
GetRemainingLength(void) const
|
uint32_t
|
GetString(char *buf, uint32_t bufSize)
|
|
GetTag(void) const
|
uint64_t
|
GetType(void) const
|
|
Init(uint8_t *buf, uint32_t dataLen, uint32_t maxLen)
|
TLVUpdater オブジェクトを初期化して単一の入力バッファを編集します。
|
Init(TLVReader & aReader, uint32_t freeLen)
|
TLVReader を使用して TLVUpdater オブジェクトを初期化します。
|
Move(void)
|
|
MoveUntilEnd(void)
|
void
TLVUpdater の現在の読み取りポイントから入力 TLV バッファの終わりまで、すべてを出力に移動します。
|
Next(void)
|
現在の要素をスキップして、TLVUpdater オブジェクトを入力 TLV の次の要素に進む。
|
Put(uint64_t tag, int8_t v)
|
|
Put(uint64_t tag, int16_t v)
|
|
Put(uint64_t tag, int32_t v)
|
|
Put(uint64_t tag, int64_t v)
|
|
Put(uint64_t tag, uint8_t v)
|
|
Put(uint64_t tag, uint16_t v)
|
|
Put(uint64_t tag, uint32_t v)
|
|
Put(uint64_t tag, uint64_t v)
|
|
Put(uint64_t tag, int8_t v, bool preserveSize)
|
|
Put(uint64_t tag, int16_t v, bool preserveSize)
|
|
Put(uint64_t tag, int32_t v, bool preserveSize)
|
|
Put(uint64_t tag, int64_t v, bool preserveSize)
|
|
Put(uint64_t tag, uint8_t v, bool preserveSize)
|
|
Put(uint64_t tag, uint16_t v, bool preserveSize)
|
|
Put(uint64_t tag, uint32_t v, bool preserveSize)
|
|
Put(uint64_t tag, uint64_t v, bool preserveSize)
|
|
Put(uint64_t tag, float v)
|
|
Put(uint64_t tag, double v)
|
|
PutBoolean(uint64_t tag, bool v)
|
|
PutBytes(uint64_t tag, const uint8_t *buf, uint32_t len)
|
|
PutNull(uint64_t tag)
|
|
PutString(uint64_t tag, const char *buf)
|
|
PutString(uint64_t tag, const char *buf, uint32_t len)
|
|
SetImplicitProfileId(uint32_t profileId)
|
void
TLVUpdater オブジェクトの暗黙的なプロファイル ID を設定します。
|
StartContainer(uint64_t tag, TLVType containerType, TLVType & outerContainerType)
|
|
VerifyEndOfContainer(void)
|
パブリック関数
CopyElement
WEAVE_ERROR CopyElement( TLVReader & reader )
CopyElement
WEAVE_ERROR CopyElement( uint64_t tag, TLVReader & reader )
DupBytes
WEAVE_ERROR DupBytes( uint8_t *& buf, uint32_t & dataLen )
DupString
WEAVE_ERROR DupString( char *& buf )
EndContainer
WEAVE_ERROR EndContainer( TLVType outerContainerType )
EnterContainer
WEAVE_ERROR EnterContainer( TLVType & outerContainerType )
コンテナの要素を読み取るための TLVUpdater オブジェクトを作成します。
また、出力 TLV において、コンテナ オブジェクトの開始をエンコードします。
EnterContainer() メソッドは、現在の TLVUpdater オブジェクトを用意して、TLV コンテナのメンバー要素(構造体、配列、またはパス)の読み取りを開始します。EnterContainer() アプリケーションを呼び出すたびに、対応する ExitContainer() 呼び出しを行う必要があります。
EnterContainer() が呼び出されたら、TLVUpdater のリーダーをコンテナ要素上に配置する必要があります。このメソッドは、コンテナの読み取り中にアップデータのコンテキストを保存するために使用される TLVType 値への参照を引数として受け取ります。
EnterContainer() メソッドが戻ると、アップデータはコンテナの最初のメンバーの前に配置されます。Next() を繰り返し呼び出すと、コレクションの最後に到達するまでアップデータの処理が進められ、終了時点に達した時点で WEAVE_END_OF_TLV が返されます。
アプリケーションでコンテナの読み取りが完了したら、ExitContainer() メソッドを呼び出して、コンテナ以降の要素の読み取りを続行できます。
詳細 | |||||||
---|---|---|---|---|---|---|---|
パラメータ |
|
||||||
戻り値 |
|
ExitContainer
WEAVE_ERROR ExitContainer( TLVType outerContainerType )
TLV コンテナ要素の読み取りを完了し、出力 TLV 内の TLV 要素の終了をエンコードします。
ExitContainer() メソッドは、EnterContainer() 呼び出しの後、TLVUpdater オブジェクトの状態を復元します。EnterContainer() アプリケーションを呼び出すたびに、対応する ExitContainer() を呼び出して、EnterContainer() メソッドから返されたコンテキスト値を渡す必要があります。
ExitContainer() が返されると、TLVUpdater リーダーが入力 TLV 内のコンテナに続く最初の要素の直前に配置されます。この時点から、アプリケーションは Next() を呼び出して残りの要素を進められるようになります。
EnterContainer() が呼び出されると、基盤となるコンテナ内のすべての要素が読み取られたかどうかにかかわらず、任意の時点でアップデータで ExitContainer() を呼び出すことができます。また、コンテナ内のすべての要素を読み取る前に ExitContainer() を呼び出すと、更新されたコンテナが出力 TLV で切り捨てられることに注意してください。
詳細 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
パラメータ |
|
||||||||||
戻り値 |
|
ファイナライズ
WEAVE_ERROR Finalize( void )
Get
WEAVE_ERROR Get( bool & v )
Get
WEAVE_ERROR Get( int8_t & v )
Get
WEAVE_ERROR Get( int16_t & v )
Get
WEAVE_ERROR Get( int32_t & v )
Get
WEAVE_ERROR Get( int64_t & v )
Get
WEAVE_ERROR Get( uint8_t & v )
Get
WEAVE_ERROR Get( uint16_t & v )
Get
WEAVE_ERROR Get( uint32_t & v )
Get
WEAVE_ERROR Get( uint64_t & v )
Get
WEAVE_ERROR Get( float & v )
Get
WEAVE_ERROR Get( double & v )
GetBytes
WEAVE_ERROR GetBytes( uint8_t *buf, uint32_t bufSize )
GetContainerType
TLVType GetContainerType( void ) const
GetDataPtr
WEAVE_ERROR GetDataPtr( const uint8_t *& data )
GetImplicitProfileId
uint32_t GetImplicitProfileId( void )
GetLength
uint32_t GetLength( void ) const
GetLengthRead
uint32_t GetLengthRead( void ) const
GetLengthWritten
uint32_t GetLengthWritten( void )
GetReader
void GetReader( TLVReader & containerReader )
GetRemainingFreeLength
uint32_t GetRemainingFreeLength( void )
GetRemainingLength
uint32_t GetRemainingLength( void ) const
GetString
WEAVE_ERROR GetString( char *buf, uint32_t bufSize )
GetTag
uint64_t GetTag( void ) const
GetType
TLVType GetType( void ) const
init
WEAVE_ERROR Init( uint8_t *buf, uint32_t dataLen, uint32_t maxLen )
TLVUpdater オブジェクトを初期化して単一の入力バッファを編集します。
このメソッドを呼び出すと、バッファ内の TLV データがバッファの末尾に移動され、この再配置されたバッファでプライベート TLVReader オブジェクトが初期化されます。プライベートの TLVWriter オブジェクトも、最初に使用可能な空き領域で初期化されます。アプリケーションでは、TLVUpdater オブジェクトを使用して TLV データを解析し、既存の要素の変更や削除、エンコードに新しい要素を追加できます。
詳細 | |||||||
---|---|---|---|---|---|---|---|
パラメータ |
|
||||||
戻り値 |
|
init
WEAVE_ERROR Init( TLVReader & aReader, uint32_t freeLen )
TLVReader を使用して TLVUpdater オブジェクトを初期化します。
このメソッドを呼び出すと、TLVReader によってポイントされるバッファ内の TLV データが、現在の読み取りポイントからバッファの最後に移動されます。新しいプライベート TLVReader オブジェクトがこの新しい場所から読み取るように初期化され、新しいプライベート TLVWriter オブジェクトが解放されたバッファ領域に書き込むように初期化されます。
TLVReader がすでに要素上に配置されている場合は、まずその要素の先頭にバックオフされます。また、このバッキングはコンテナ要素でも適切に機能します。つまり、TLVReader が EnterContainer() の呼び出しにすでに使用されている場合、バックオフする必要はありません。ただし、TLVReader がコンテナ要素に配置されていて、EnterContainer() がまだ呼び出されていない場合、TLVReader オブジェクトはコンテナのヘッドの先頭にバックオフされます。
入力された TLVReader オブジェクトは、戻る前に破棄されるため、アプリは戻り時にそれを使用してはなりません。
詳細 | |||||||
---|---|---|---|---|---|---|---|
パラメータ |
|
||||||
戻り値 |
|
移動
WEAVE_ERROR Move( void )
入力 TLV から現在の要素を出力 TLV にコピーします。
Move() メソッドは、TLVUpdater のリーダーが配置されている現在の要素を TLVUpdater のライターにコピーします。このメソッドを呼び出す前に、アプリケーションは Next() を呼び出して、TLVUpdater のリーダーを要素上に配置する必要があります。TLVReader::Next() メソッドと同様に、呼び出しの時点でリーダーがコンテナ要素に置かれていた場合は、コンテナのすべてのメンバーがコピーされます。リーダーがどの要素にも配置されていない場合、このメソッドを呼び出しても変化はありません。
詳細 | |||||||||
---|---|---|---|---|---|---|---|---|---|
戻り値 |
|
MoveUntilEnd
void MoveUntilEnd( void )
TLVUpdater の現在の読み取りポイントから入力 TLV バッファの終わりまで、すべてを出力に移動します。
このメソッドでは、TLVUpdater の現在の読み取りポイントからリーダー バッファの末尾までのすべてを、TLVUpdater のライターに移動できます。
次へ
WEAVE_ERROR Next( void )
現在の要素をスキップして、TLVUpdater オブジェクトを入力 TLV の次の要素に進む。
Next() メソッドは、入力 TLV の現在の要素をスキップし、TLVUpdater のリーダーを同じ包含コンテキストに存在する次の要素に進めます。特に、リーダーが TLV エンコードの最も外側にあるレベルにある場合、Next() を呼び出すと、次の最上位の要素に進めます。リーダーが TLV コンテナ要素(構造、配列、パス)内にある場合、Next() を呼び出すと、コンテナの次のメンバー要素に進みます。
Next() は、リーダーの動きを現在のコンテインメント コンテキストに制限するため、リーダーがコンテナ要素上に置かれたときに Next() を呼び出すと、コンテナの上に移動し、コンテナ後の最初の要素に到達するまでメンバー要素(およびネストされたコンテナのメンバー)はスキップされます。
特定の包含コンテキスト内にそれ以上要素がない場合、Next() メソッドは WEAVE_END_OF_TLV エラーを返し、リーダーの位置は変更されません。
詳細 | |||||
---|---|---|---|---|---|
戻り値 |
|
データに
WEAVE_ERROR Put( uint64_t tag, int8_t v )
データに
WEAVE_ERROR Put( uint64_t tag, int16_t v )
データに
WEAVE_ERROR Put( uint64_t tag, int32_t v )
データに
WEAVE_ERROR Put( uint64_t tag, int64_t v )
データに
WEAVE_ERROR Put( uint64_t tag, uint8_t v )
データに
WEAVE_ERROR Put( uint64_t tag, uint16_t v )
データに
WEAVE_ERROR Put( uint64_t tag, uint32_t v )
データに
WEAVE_ERROR Put( uint64_t tag, uint64_t v )
データに
WEAVE_ERROR Put( uint64_t tag, int8_t v, bool preserveSize )
データに
WEAVE_ERROR Put( uint64_t tag, int16_t v, bool preserveSize )
データに
WEAVE_ERROR Put( uint64_t tag, int32_t v, bool preserveSize )
データに
WEAVE_ERROR Put( uint64_t tag, int64_t v, bool preserveSize )
データに
WEAVE_ERROR Put( uint64_t tag, uint8_t v, bool preserveSize )
データに
WEAVE_ERROR Put( uint64_t tag, uint16_t v, bool preserveSize )
データに
WEAVE_ERROR Put( uint64_t tag, uint32_t v, bool preserveSize )
データに
WEAVE_ERROR Put( uint64_t tag, uint64_t v, bool preserveSize )
データに
WEAVE_ERROR Put( uint64_t tag, float v )
データに
WEAVE_ERROR Put( uint64_t tag, double v )
PutBoolean
WEAVE_ERROR PutBoolean( uint64_t tag, bool v )
PutBytes
WEAVE_ERROR PutBytes( uint64_t tag, const uint8_t *buf, uint32_t len )
PutNull
WEAVE_ERROR PutNull( uint64_t tag )
PutString
WEAVE_ERROR PutString( uint64_t tag, const char *buf )
PutString
WEAVE_ERROR PutString( uint64_t tag, const char *buf, uint32_t len )
SetImplicitProfileId
void SetImplicitProfileId( uint32_t profileId )
TLVUpdater オブジェクトの暗黙的なプロファイル ID を設定します。
このメソッドは、TLVUpdater オブジェクトに暗黙的なプロファイル ID を設定します。アップデータで新しい要素のエンコードを求められ、新しい要素に関連付けられたタグのプロファイル ID が profileId
の値と一致すると、アップデータは暗黙的にタグをエンコードするため、プロセス内でプロファイル ID は省略されます。
詳細 | |||
---|---|---|---|
パラメータ |
|
StartContainer
WEAVE_ERROR StartContainer( uint64_t tag, TLVType containerType, TLVType & outerContainerType )