nl:: Weave:: Binding
#include <src/lib/core/WeaveBinding.h>
Weave 通信の意図されたターゲットと関連する構成情報をキャプチャします。
概要
Binding オブジェクトは、Weave 通信の意図されたターゲット(「ピア」とも呼ばれます)と、ピアとの通信を行う方法を説明する一連の構成パラメータを識別します。バインディングは、2 つの当事者間で行われるアプリケーション プロトコルとは関係ありません。したがって、コミュニケーションの「誰が」と「どのように」は捉えることができ、コミュニケーションの「何」は捕捉されません。
アプリは、目的の通信チャネルのタイプに固有のパラメータを使用してバインディングを構成する必要があります。バインディングは、TCP、UDP、UDP(Weave Reliable Messaging)、Weave over BLE(WoBLE)など、さまざまなネットワーク トランスポートをサポートします。アプリは、当事者間で送信されるメッセージを保護するために、特定のセキュリティ メカニズムの使用をリクエストすることもできます。これには、CASE と PASE セッション、アプリケーション グループ キーが含まれます。バインディングを構成するインターフェースでは、宣言型 API スタイルを使用して、アプリが通信の要件をわかりやすい言葉で記述できます。
詳しくは、Binding::Configuration のドキュメントをご覧ください。
準備
コミュニケーションの前に、Binding を「準備」する必要があります。Binding を準備する作業には、通信を行うために必要な状態を確立することが含まれます。たとえば、ピアのネットワーク アドレスの解決、ネットワーク接続を確立、セキュリティ キーのネゴシエーションなどを行います。アプリによって設定されると、Binding は通信の準備に必要なすべてのステップを処理し、プロセスが完了したらアプリにコールバックします。このように、バインディングによって通信の仕組みが隠されているため、アプリは高度なインタラクションに集中できます。
コミュニケーション
Binding が準備されると、使用可能になります。この状態では、アプリケーション(より一般的には、アプリケーションに代わって動作するプロトコル レイヤ コード)が Binding をリクエストし、Weave エクスチェンジ コンテキストを割り当てます。その結果として生じる交換コンテキストは通信用に事前構成され、アプリケーションはピアとの Weave 交換を直ちに開始できます。アプリケーションは、Binding が閉じられるか、ネットワーク障害などのイベントによって基盤となる通信チャネルを終了するまで、Binding から交換コンテキストをリクエストし続けることができます。
バインディング状態の変更
Binding は使用の過程で、アプリケーションに API イベントを配信し、Binding の状態の変化を通知します。たとえば、準備が成功すると、アプリは Binding が使用可能になったことを通知するイベントを受け取ります。同様に、基盤となる通信チャネルで障害が発生した場合、Binding が準備完了状態ではなくなったことを通知するイベントがアプリケーションに送信されます。
API イベントは、Binding が割り当てられたときに提供されるイベント コールバック関数を介してアプリに配信されます。
バインディングの有効期間
バインディングは、複数のソフトウェア コンポーネント間での共有使用を可能にするために参照カウントされます。Binding が割り当てられると、バインディングへの単一の参照が作成されます。アプリケーションは、将来のある時点でこの参照を解放し、Binding がその後再利用できるように解放する責任を負います。
アプリで Binding の処理が完了すると、そのバインディングで Close() を呼び出すことができます。これにより、バインディングへの参照が解放され、それ以降の API イベントの配信がすべてブロックされます。Binding への最後の参照が解放されると、それは自動的に閉じられます。
パブリック タイプ |
|
---|---|
@23{
|
enum |
EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
|
typedefvoid(*
|
EventType{
|
enum |
State
|
enum |
パブリック属性 |
|
---|---|
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
ピアとの通信時に使用するデフォルトの交換応答タイムアウトを取得します。
|
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()
|
アプリケーションに、Binding の構成と準備をリクエストします。
|
Reset(void)
|
void
バインディングを未設定の状態にリセットします。
|
SetDefaultResponseTimeout(uint32_t msec)
|
void
ピアとの通信時に使用するデフォルトの交換応答タイムアウトを設定します。
|
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 イベントへの出力パラメータ。 |
パブリック タイプ
EventCallback
void(* EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
EventType
EventType
プロパティ | |
---|---|
kEvent_BindingFailed
|
バインディングに失敗したため、ピアとの通信に使用できなくなりました。 |
kEvent_BindingReady
|
バインディングの準備アクションに成功し、バインディングを使用してピアと通信できるようになりました。 |
kEvent_ConnectionEstablished
|
リクエストされた Weave 接続が確立されました。 |
kEvent_DefaultCheck
|
アプリケーションのデフォルトのイベント処理の正確性を検証するために使用されます。 |
kEvent_PASEParametersRequested
|
アプリケーションは、PAASE セッションの確立中に使用するパラメータを提供するようにリクエストされます。 |
kEvent_PrepareFailed
|
バインディングの準備アクションが失敗しました。 |
kEvent_PrepareRequested
|
アプリケーションは、ネットワーク スタックで使用するバインディングを構成して準備するようにリクエストされます。 |
kEvent_TAKEParametersRequested
|
アプリケーションは、TAKE セッションの確立時に使用されるパラメータを提供するようにリクエストされます。 |
状態
State
パブリック属性
AppState
void * AppState
パブリック関数
AddRef
void AddRef( void )
バインディング オブジェクトへの参照を予約します。
AdjustResponseTimeout
WEAVE_ERROR AdjustResponseTimeout( ExchangeContext *apExchangeContext ) const
既存の Exchange コンテキストを再構成して応答タイムアウトを調整する。
詳細 | |||
---|---|---|---|
パラメータ |
|
AllocateRightSizedBuffer
WEAVE_ERROR AllocateRightSizedBuffer( PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize )
BeginConfiguration
Configuration BeginConfiguration()
Binding を構成するプロセスである。
アプリは、ピアとの通信の準備をする前に BeginConfiguration() を呼び出して Binding を構成する必要があります。
詳細 | |
---|---|
戻り値 |
バインディングの構成に使用できる Binding::Configuration オブジェクト。
|
CanBePrepared
bool CanBePrepared( void ) const
閉じる
void Close( void )
バインディング オブジェクトを閉じて参照を解放します。
このメソッドが呼び出されると、バインディングがクローズ状態になります。進行中のバインディングの準備アクションはすべてキャンセルされ、バインディングが保持している外部通信リソースはすべて解放されます。
Close() を呼び出すと、バインディングに関連付けられた参照カウントが減少し、参照カウントがゼロになるとオブジェクトを解放します。
GetConnection
WeaveConnection * GetConnection() const
バインディングに関連付けられている Weave 接続オブジェクトを取得します。
詳細 | |
---|---|
戻り値 |
WeaveConnection オブジェクトへのポインタ。バインディングに関連付けられた接続がない場合は NULL。
|
GetDefaultResponseTimeout
uint32_t GetDefaultResponseTimeout() const
ピアとの通信時に使用するデフォルトの交換応答タイムアウトを取得します。
詳細 | |
---|---|
戻り値 |
レスポンスのタイムアウト(ミリ秒単位)。
|
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 の解決が完了した後など)にアドレス情報を使用できるようになります。Binding が準備できると、Binding がリセットされるまでアドレス情報が利用可能のままになります。
詳細 | |||||||
---|---|---|---|---|---|---|---|
パラメータ |
|
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
IsUnreliableUDPTransport
bool IsUnreliableUDPTransport() const
IsWRMTransport
bool IsWRMTransport() const
NewExchangeContext
WEAVE_ERROR NewExchangeContext( ExchangeContext *& appExchangeContext )
バインディングの対象となるピアと通信するために、新しい Exchange コンテキストを割り振る。
詳細 | |||||||||
---|---|---|---|---|---|---|---|---|---|
パラメータ |
|
||||||||
戻り値 |
|
リリース
void Release( void )
バインディング オブジェクトへの参照を解放します。
バインディング オブジェクトへの参照がなくなると、バインディングは閉じて解放されます。
RequestPrepare
WEAVE_ERROR RequestPrepare()
アプリケーションに、Binding の構成と準備をリクエストします。
プロトコル レイヤコードは、構成されていない、または失敗した Binding でこのメソッドを使用して、使用するバインディングの構成と準備をリクエストしているアプリ(kEvent_PrepareRequested)に対してイベントをトリガーできます。
このメソッドは、NotConfigured または Failed 状態の Binding でのみ呼び出すことができます。
アプリケーションでバインディングのオンデマンド構成/準備がサポートされていない場合、メソッドは WEAVE_ERROR_NOT_IMPLEMENTED で失敗します。
リセット
void Reset( void )
SetDefaultResponseTimeout
void SetDefaultResponseTimeout( uint32_t msec )
ピアとの通信時に使用するデフォルトの交換応答タイムアウトを設定します。
詳細 | |||
---|---|---|---|
パラメータ |
|
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 イベントがある場合は、このメソッドを呼び出す必要があります。指定するパラメータは、アプリケーションのイベント ハンドラ関数へのバインディングによって渡されるパラメータと同じである必要があります。
詳細 | |||||||||
---|---|---|---|---|---|---|---|---|---|
パラメータ |
|