nl:: Weave:: バインディング
#include <src/lib/core/WeaveBinding.h>
Weave 通信の意図されたターゲットと関連する構成情報をキャプチャします。
まとめ
Binding オブジェクトは、Weave 通信(または「ピア」とも呼ばれます)の意図されるターゲットと、ピアとの通信方法を示す一連の構成パラメータを識別します。バインディングは、両者間で行われるアプリケーション プロトコルとは無関係です。つまり、「コミュニケーション」の「人物」と「方法」は測定されますが、「何を」は取得されません。
アプリは、目的の通信チャネルのタイプに固有のパラメータを使用して、バインディングを構成する必要があります。バインディングは、TCP、UDP、Weave Reliable Messaging を使用した UDP、Weave over BLE(WoBLE)など、さまざまなネットワーク トランスポートをサポートします。また、当事者間で送信されたメッセージを保護するために、特定のセキュリティ メカニズムを使用するようリクエストすることもできます。これには、CASE セッション、PASE セッション、アプリケーション グループ キーが含まれます。バインディングを設定するインターフェースでは、宣言型の API スタイルを使用して、通信の要件を簡単な言葉で表現できます。
詳細については、Binding::Configuration のドキュメントをご覧ください。
準備
コミュニケーションを行う前に、バインディングを「準備」する必要があります。バインディングの準備とは、通信を行うために必要な状態を確立することです。たとえば、ピアのネットワーク アドレスの解決、ネットワーク接続の確立、セキュリティ キーの交渉などです。アプリによって構成されると、バインディングによって通信の準備に必要なすべてのステップが処理され、プロセスが完了するとアプリケーションにコールバックします。このように、バインディングは通信の仕組みを隠すため、アプリケーションは大まかなやり取りに集中できます。
コミュニケーション
バインディングの準備が整ったら、使用できるようになります。この状態では、アプリ(より一般的には、アプリケーションの代わりに動作するプロトコル レイヤ コード)が Weave 交換コンテキストを割り当てるために Binding をリクエストします。その結果、交換コンテキストは通信用に事前構成されているため、アプリによりピアとの Weave 交換をすぐに開始できます。アプリは、Binding が閉じられるか、なんらかのイベント(ネットワークの障害など)が基盤となる通信チャネルを終了するまで、Binding に交換コンテキストを要求し続けることができます。
バインディング状態の変更
使用している間、Binding は API イベントをアプリケーションに送信し、Binding の状態の変化を知らせます。たとえば、準備が成功すると、アプリは、バインディングの準備ができたことを通知するイベントを受け取ります。同様に、基盤となる通信チャネルで障害が発生すると、バインディングが準備完了状態ではなくなったことをアプリケーションが通知します。
API イベントは、Binding に割り当てられたときに提供されるイベント コールバック関数を介してアプリケーションに配信されます。
Binding ライフタイム
バインディングは、複数のソフトウェア コンポーネント間で共有可能な参照としてカウントします。Binding が割り当てられると、バインディングへの単一の参照が作成されます。後で再利用できるように Binding が無料になるように、ある時点でこの参照をリリースする責任はアプリケーションにあります。
バインディングを使用してアプリケーションが完了すると、バインディングで Close() を呼び出すことができます。これにより、アプリケーションのバインディングへの参照が解放され、それ以降は API イベントの配信がすべてブロックされます。Binding への最後の参照が解放されると、バインディングは自動的に閉じられます。
パブリック タイプ |
|
---|---|
@23{
|
列挙型 |
EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
|
typedefvoid(*
|
EventType{
|
列挙型 |
State
|
列挙型 |
パブリック属性 |
|
---|---|
AppState
|
void *
|
パブリック関数 |
|
---|---|
AddRef(void)
|
void
バインディング オブジェクトへの参照を予約します。
|
AdjustResponseTimeout(ExchangeContext *apExchangeContext) const
|
既存の Exchange コンテキストを再構成して、レスポンスのタイムアウトを調整します。
|
AllocateRightSizedBuffer(PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize)
|
|
BeginConfiguration()
|
Binding を構成するプロセス。
|
CanBePrepared(void) const
|
bool
|
Close(void)
|
void
バインディング オブジェクトを閉じて、参照を解放します。
|
GetConnection() const
|
バインディングに関連付けられた Weave 接続オブジェクトを取得します。
|
GetDefaultResponseTimeout() const
|
uint32_t
ピアと通信する際に使用するデフォルトの Exchange レスポンス タイムアウトを取得します。
|
GetDefaultWRMPConfig(void) const
|
const WRMPConfig &
ピアとの通信時に使用するデフォルトの WRMP 構成を取得します。
|
GetEncryptionType(void) const
|
uint8_t
ピアとの間でメッセージを暗号化する際に使用するメッセージ暗号化タイプを取得します。
|
GetEventCallback() const
|
EventCallback
Binding で API イベントが発生したときに呼び出される関数を取得します。
|
GetExchangeManager() const
|
|
GetKeyId(void) const
|
uint32_t
ピアとの間でメッセージを暗号化する際に使用するメッセージ暗号鍵の ID を取得します。
|
GetLogId(void) const
|
uint16_t
バインディングの一意の ID を取得します。
|
GetMaxWeavePayloadSize(const System::PacketBuffer *msgBuf)
|
uint32_t
指定された PacketBuffer に収まる Weave ペイロードの最大サイズを取得します。
|
GetPeerDescription(char *buf, uint32_t bufSize) const
|
void
ピアノードとそれに関連付けられたアドレス / 接続情報を記述する文字列を作成します。
|
GetPeerIPAddress(nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId) const
|
void
ピアの IP アドレス情報を取得します(ある場合)。
|
GetPeerNodeId(void) const
|
uint64_t
バインディング ピアのノード ID を取得します。
|
GetProtocolLayerCallback(EventCallback & callback, void *& state) const
|
void
|
GetState(void) const
|
State
バインディングの現在の状態を取得します。
|
IsAuthenticMessageFromPeer(const WeaveMessageInfo *msgInfo)
|
bool
特定のピアが設定したピアから送信され、適切に認証されているかどうかを確認します。
|
IsConnectionTransport() const
|
bool
|
IsPreparing(void) const
|
bool
|
IsReady(void) const
|
bool
|
IsUDPTransport() const
|
bool
|
IsUnreliableUDPTransport() const
|
bool
|
IsWRMTransport() const
|
bool
|
NewExchangeContext(ExchangeContext *& appExchangeContext)
|
バインディングのターゲットであるピアと通信するための新しい Exchange コンテキストを割り当てます。
|
Release(void)
|
void
バインディング オブジェクトへの参照を解放します。
|
RequestPrepare()
|
アプリケーションを構成して、バインディングを構成して準備します。
|
Reset(void)
|
void
バインディングを未構成の状態にリセットします。
|
SetDefaultResponseTimeout(uint32_t msec)
|
void
ピアと通信する際に使用するデフォルトの Exchange レスポンス タイムアウトを設定します。
|
SetDefaultWRMPConfig(const WRMPConfig & wrmpConfig)
|
void
ピアとの通信時に使用するデフォルトの WRMP 構成を設定します。
|
SetEventCallback(EventCallback aEventCallback)
|
void
Binding で API イベントが発生したときに呼び出されるアプリケーション定義関数を設定します。
|
SetProtocolLayerCallback(EventCallback callback, void *state)
|
void
アプリに代わって Binding を使用して、プロトコル レイヤコードのイベント コールバック関数を設定します。
|
静的パブリック関数 |
|
---|---|
DefaultEventHandler(void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam)
|
void
API イベントをバインドするデフォルト ハンドラ。
|
クラス |
|
---|---|
nl:: |
Binding オブジェクトを構成して準備するための宣言型インターフェースを提供します。 |
構造体 |
|
---|---|
nl:: |
Binding API イベントにパラメータを入力します。 |
nl:: |
Binding API イベントにパラメータを出力します。 |
パブリック タイプ
イベント コールバック
void(* EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
イベントタイプ
EventType
Properties | |
---|---|
kEvent_BindingFailed
|
バインディングが失敗し、ピアとの通信に使用できなくなりました。 |
kEvent_BindingReady
|
バインディングの準備アクションが成功したため、バインディングをピアとの通信に使用できるようになりました。 |
kEvent_ConnectionEstablished
|
リクエストされた Weave 接続は確立されました。 |
kEvent_DefaultCheck
|
アプリケーションのデフォルトのイベント処理が正しく行われていることを確認するために使用されます。 |
kEvent_PASEParametersRequested
|
PASE セッションの確立で使用するパラメータを、アプリケーションがリクエストします。 |
kEvent_PrepareFailed
|
バインディングの準備アクションが失敗しました。 |
kEvent_PrepareRequested
|
アプリは、ネットワーク スタックで使用するバインディングを構成して準備するようリクエストされます。 |
kEvent_TAKEParametersRequested
|
アプリケーションは、TAKE セッションの確立で使用するパラメータを指定する必要があります。 |
状態
State
パブリック属性
アプリの状態
void * AppState
パブリック関数
AddRef
void AddRef( void )
バインディング オブジェクトへの参照を予約します。
AdjustResponseTimeout を使用する
WEAVE_ERROR AdjustResponseTimeout( ExchangeContext *apExchangeContext ) const
既存の Exchange コンテキストを再構成して、レスポンスのタイムアウトを調整します。
詳細 | |||
---|---|---|---|
パラメータ |
|
RightSizedBuffer を割り当て
WEAVE_ERROR AllocateRightSizedBuffer( PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize )
構成の開始
Configuration BeginConfiguration()
Binding を構成するプロセス。
アプリは、ピアと通信する準備をする前に、BeginConfiguration() を呼び出してバインディングを構成する必要があります。
詳細 | |
---|---|
戻り値 |
バインディングの構成に使用できる Binding::Configuration オブジェクト。
|
準備可能
bool CanBePrepared( void ) const
閉じる
void Close( void )
バインディング オブジェクトを閉じて、参照を解放します。
このメソッドが呼び出されると、バインディングが「終了」状態になります。バインディングで進行中の準備アクションがすべてキャンセルされ、バインディングによって保持されているすべての外部通信リソースが解放されます。
Close() を呼び出すと、バインディングに関連付けられた参照数が減り、参照数がゼロになるとオブジェクトが解放されます。
GetConnection
WeaveConnection * GetConnection() const
バインディングに関連付けられた Weave 接続オブジェクトを取得します。
詳細 | |
---|---|
戻り値 |
WeaveConnection オブジェクトへのポインタ。バインディングに関連付けられた接続がない場合は NULL。
|
GetDefaultResponseTimeout が指定されている
uint32_t GetDefaultResponseTimeout() const
ピアと通信する際に使用するデフォルトの Exchange レスポンス タイムアウトを取得します。
詳細 | |
---|---|
戻り値 |
レスポンス タイムアウト(ミリ秒単位)
|
GetDefaultWRMPConfig
const WRMPConfig & GetDefaultWRMPConfig( void ) const
GetEncryptionType
uint8_t GetEncryptionType( void ) const
ピアとの間でメッセージを暗号化する際に使用するメッセージ暗号化タイプを取得します。
GetEventCallback
EventCallback GetEventCallback() const
GetExchangeManager
WeaveExchangeManager * GetExchangeManager() const
GetKeyId
uint32_t GetKeyId( void ) const
ピアとの間でメッセージを暗号化する際に使用するメッセージ暗号鍵の ID を取得します。
GetLogId
uint16_t GetLogId( void ) const
バインディングの一意の ID を取得します。
GetMaxWeavePayloadSize
uint32_t GetMaxWeavePayloadSize( const System::PacketBuffer *msgBuf )
指定された PacketBuffer に収まる Weave ペイロードの最大サイズを取得します。
UDP(WRM を使用する UDP を含む)の場合、返される最大ペイロード サイズによって、生成される Weave メッセージが構成済みの UDP MTU をオーバーフローしなくなります。
さらに、このメソッドは Weave ペイロードによって指定された PacketBuffer をオーバーフローしないようにします。
詳細 | |||
---|---|---|---|
パラメータ |
|
||
戻り値 |
Weave ペイロードの最大サイズ。
|
GetPeerDescription
void GetPeerDescription( char *buf, uint32_t bufSize ) const
ピアノードとそれに関連付けられたアドレス / 接続情報を記述する文字列を作成します。
詳細 | |||||
---|---|---|---|---|---|
パラメータ |
|
GetPeerIPAddress
void GetPeerIPAddress( nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId ) const
ピアの IP アドレス情報を取得します(ある場合)。
ピアの IP アドレス情報を使用できるかどうかは、バインディングの状態と構成によって異なります。IP アドレス情報は、IP ベースのトランスポート(TCP、UDP、WRMP による UDP)を使用する場合にのみ使用できます。準備を開始する前に、住所情報が設定時にアプリケーションによって明示的に設定されている場合にのみ表示されます。準備フェーズでは、アドレスの準備が完了すると(DNS の解決完了後などに)アドレス情報を利用できるようになります。バインディングの準備ができたら、バインディングがリセットされるまで、住所の情報を利用できます。
詳細 | |||||||
---|---|---|---|---|---|---|---|
パラメータ |
|
GetPeerNodeId
uint64_t GetPeerNodeId( void ) const
バインディング ピアのノード ID を取得します。
バインディング オブジェクトを準備する場合にのみ有効です。
詳細 | |
---|---|
戻り値 |
ピアの Weave ノード ID
|
GetProtocolLayerCallback の使用
void GetProtocolLayerCallback( EventCallback & callback, void *& state ) const
GetState
State GetState( void ) const
バインディングの現在の状態を取得します。
詳細 | |
---|---|
戻り値 |
バインディングの状態。
|
IsAuthenticMessageFromPeer
bool IsAuthenticMessageFromPeer( const WeaveMessageInfo *msgInfo )
特定のピアが設定したピアから送信され、適切に認証されているかどうかを確認します。
このメソッドは、指定されたメッセージに関する以下の詳細を確認します。
- バインディングのピアノードから送信されたメッセージ
- メッセージはバインディングと同じトランスポート タイプで受信されました。接続を介してメッセージが受信された場合、このメソッドは、バインディングに関連付けられた正確な接続を介してメッセージが受信されたことも確認します。
- メッセージの暗号化に使用される暗号鍵とタイプが、バインディングで構成されたものと一致する。セキュリティを使用せずに構成されているバインディングの場合、受信メッセージが暗号化されていないことが確認されます。
この方法は、ノードからピアへの最初の交換の後、ピアが自発的にローカルノードへの交換を開始できる WDM などのプロトコルで使用することを目的としています。そのような場合、このメソッドを使用すると、受信する迷惑メールが関連付けられたピアによって送信されたことをローカルノードが確認できます。(もちろん、メッセージ暗号化を使用せずに構成されたバインディングの場合、セキュリティの観点からは、このアサーションには価値がありません。送信者ノード ID とトランスポート タイプが一致していることを確認するだけです)。
バインディングが Ready 状態でない場合、このメソッドは常に false を返します。
詳細 | |||
---|---|---|---|
パラメータ |
|
||
戻り値 |
メールがピアからのものである場合、true。
|
IsConnectionTransport
bool IsConnectionTransport() const
IsUDPTransport
bool IsUDPTransport() const
IsUnrereableUDPTransport
bool IsUnreliableUDPTransport() const
IsWRMTransport
bool IsWRMTransport() const
NewExchangeContext
WEAVE_ERROR NewExchangeContext( ExchangeContext *& appExchangeContext )
バインディングのターゲットであるピアと通信するための新しい Exchange コンテキストを割り当てます。
詳細 | |||||||||
---|---|---|---|---|---|---|---|---|---|
パラメータ |
|
||||||||
戻り値 |
|
リリース
void Release( void )
バインディング オブジェクトへの参照を解放します。
バインディング オブジェクトへの参照がなくなると、バインディングは閉じられ、解放されます。
リクエストの準備
WEAVE_ERROR RequestPrepare()
アプリケーションを構成して、バインディングを構成して準備します。
プロトコル レイヤのコードでは、このメソッドが設定(または失敗)していない Binding でこのメソッドを使用し、アプリケーション(kEvent_PrepareRequested)に対してイベントをトリガーして、バインディングの設定と準備をリクエストできます。
このメソッドは、NotConfigured 状態または Failed 状態のバインディングでのみ呼び出すことができます。
アプリケーションがバインディングのオンデマンド構成や準備をサポートしていない場合、メソッドは WEAVE_ERROR_NOT_IMPLEMENTED で失敗します。
リセット
void Reset( void )
SetDefaultResponseTimeout
void SetDefaultResponseTimeout( uint32_t msec )
ピアと通信する際に使用するデフォルトの Exchange レスポンス タイムアウトを設定します。
詳細 | |||
---|---|---|---|
パラメータ |
|
SetDefaultWRMPConfig
void SetDefaultWRMPConfig( const WRMPConfig & wrmpConfig )
SetEventCallback
void SetEventCallback( EventCallback aEventCallback )
SetProtocolLayerCallback
void SetProtocolLayerCallback( EventCallback callback, void *state )
静的パブリック関数
DefaultEventHandler
void DefaultEventHandler( void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam )
API イベントをバインドするデフォルト ハンドラ。
アプリケーションは、認識または処理しない API イベントでこのメソッドを呼び出す必要があります。指定するパラメータは、アプリのイベント ハンドラ関数へのバインディングから渡されたパラメータと同じでなければなりません。
詳細 | |||||||||
---|---|---|---|---|---|---|---|---|---|
パラメータ |
|