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{
  kGetPeerDescription_MaxLength = nl::Weave::kWeavePeerDescription_MaxLength
}
enum
EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam) typedef
void(*
EventType{
  kEvent_ConnectionEstablished = 1,
  kEvent_BindingReady = 2,
  kEvent_PrepareFailed = 3,
  kEvent_BindingFailed = 4,
  kEvent_PrepareRequested = 5,
  kEvent_PASEParametersRequested = 6,
  kEvent_TAKEParametersRequested = 7,
  kEvent_DefaultCheck = 100
}
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::Weave::Binding::Configuration

Binding オブジェクトの設定と準備を行うための宣言型スタイルのインターフェースを提供します。

構造体

nl::Weave::Binding::InEventParam

Binding API イベントへの入力パラメータ。

nl::Weave::Binding::OutEventParam

Binding API イベントへの出力パラメータ。

パブリック タイプ

@23

 @23
プロパティ
kGetPeerDescription_MaxLength

GetPeerDescription() によって返される文字列(NUL 文字を含む)の最大長。

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 コンテキストを再構成して応答タイムアウトを調整する。

詳細
パラメータ
[in] apExchangeContext
再構成する Exchange Context オブジェクトへのポインタ

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 

ピアとの通信時に使用するデフォルトの WRMP 構成を取得します。

詳細
戻り値
デフォルトの構成値を含む WRMPConfig 構造体への参照。

GetEncryptionType

uint8_t GetEncryptionType(
  void
) const 

ピアとのメッセージの暗号化に使用するメッセージ暗号化タイプを取得します。

GetEventCallback

EventCallback GetEventCallback() const 

Binding に対して API イベントが発生したときに呼び出される関数を取得します。

詳細
戻り値
コールバック関数へのポインタ。

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 をオーバーフローすることがなくなります。

詳細
パラメータ
[in] msgBuf
メッセージ ペイロードの書き込み先となる PacketBuffer へのポインタ。
戻り値
Weave ペイロードの最大サイズ。

GetPeerDescription

void GetPeerDescription(
  char *buf,
  uint32_t bufSize
) const 

ピアノードとそれに関連付けられたアドレス / 接続情報を記述する文字列を作成します。

詳細
パラメータ
[in] buf
文字列を書き込むバッファへのポインタ。指定するバッファは少なくとも kGetPeerDescription_MaxLength 以上にする必要があります。小さいバッファが指定された場合、文字列が収まるように切り捨てられます。いずれの場合も、出力には NUL 終了文字が含まれます。
[in] bufSize
buf が指すバッファのサイズ。

GetPeerIPAddress

void GetPeerIPAddress(
  nl::Inet::IPAddress & address,
  uint16_t & port,
  InterfaceId & interfaceId
) const 

ピアの IP アドレス情報を取得します(利用可能な場合)。

ピアの IP アドレス情報が利用可能かどうかは、バインディングの状態と構成によって異なります。IP アドレス情報は、IP ベースのトランスポート(TCP、UDP、WRMP を使用した UDP)を使用している場合にのみ使用できます。準備を開始する前に、アドレス情報は、構成時にアプリケーションによって明示的に設定されている場合にのみ利用できます。準備フェーズでは、アドレスの準備が完了したとき(DNS の解決が完了した後など)にアドレス情報を使用できるようになります。Binding が準備できると、Binding がリセットされるまでアドレス情報が利用可能のままになります。

詳細
パラメータ
[out] address
ピアの IP アドレスを受け取る IPAddress オブジェクトへの参照。ピアの IP アドレス情報を取得できない場合、この値は IPAddress::Any に設定されます。
[out] port
ピアのポート番号を受け取る整数への参照。ピアの IP アドレス情報を取得できない場合、この値は未定義になります。
[out] interfaceId
ピアに到達可能なネットワーク インターフェースの ID を受け取る整数の参照。ピアの IP アドレス情報を取得できない場合、この値は未定義になります。

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 を返します。

詳細
パラメータ
[in] msgInfo
受信メッセージの Weave メッセージ情報。
戻り値
メッセージがピアから送信されたものである場合は true。

IsConnectionTransport

bool IsConnectionTransport() const 

IsPreparing

bool IsPreparing(
  void
) const 

詳細
戻り値
Binding が現在準備中の場合は true。

IsReady

bool IsReady(
  void
) const 

詳細
戻り値
Binding が Ready 状態の場合は true。

IsUDPTransport

bool IsUDPTransport() const 

IsUnreliableUDPTransport

bool IsUnreliableUDPTransport() const 

IsWRMTransport

bool IsWRMTransport() const 

NewExchangeContext

WEAVE_ERROR NewExchangeContext(
  ExchangeContext *& appExchangeContext
)

バインディングの対象となるピアと通信するために、新しい Exchange コンテキストを割り振る。

詳細
パラメータ
[out] appExchangeContext
新しく割り当てられた Exchange Context オブジェクトを受け取るポインタへの参照。メソッドが失敗すると、ポインタは NULL に設定されます。
戻り値
WEAVE_NO_ERROR
交換コンテキストが正常に割り当てられたかどうか。
WEAVE_ERROR_NO_MEMORY
交換コンテキストの割り当てに使用できるメモリがなかった場合。
WEAVE_ERROR_INCORRECT_STATE
バインディングが Ready 状態でない場合。
other
バインディングの構成に基づく交換コンテキストの構成に関連するその他のエラー。

リリース

void Release(
  void
)

バインディング オブジェクトへの参照を解放します。

バインディング オブジェクトへの参照がなくなると、バインディングは閉じて解放されます。

RequestPrepare

WEAVE_ERROR RequestPrepare()

アプリケーションに、Binding の構成と準備をリクエストします。

プロトコル レイヤコードは、構成されていない、または失敗した Binding でこのメソッドを使用して、使用するバインディングの構成と準備をリクエストしているアプリ(kEvent_PrepareRequested)に対してイベントをトリガーできます。

このメソッドは、NotConfigured または Failed 状態の Binding でのみ呼び出すことができます。

アプリケーションでバインディングのオンデマンド構成/準備がサポートされていない場合、メソッドは WEAVE_ERROR_NOT_IMPLEMENTED で失敗します。

リセット

void Reset(
  void
)

バインディングを未設定の状態にリセットします。

Reset() が呼び出されると、進行中のバインディングの準備アクションがすべてキャンセルされ、バインディングが保持しているすべての外部通信リソースが解放されます。Reset() が、バインディングを「未設定」の状態にします。その後、再度構成して準備できるようになります。

Reset() は、バインディングの参照数を変更しません。

SetDefaultResponseTimeout

void SetDefaultResponseTimeout(
  uint32_t msec
)

ピアとの通信時に使用するデフォルトの交換応答タイムアウトを設定します。

詳細
パラメータ
[in] timeout
新しいレスポンスのタイムアウト(ミリ秒単位)。

SetDefaultWRMPConfig

void SetDefaultWRMPConfig(
  const WRMPConfig & wrmpConfig
)

ピアとの通信時に使用するデフォルトの WRMP 構成を設定します。

詳細
パラメータ
[in] aWRMPConfig
新しいデフォルト構成を含む WRMPConfig 構造体への参照。

SetEventCallback

void SetEventCallback(
  EventCallback aEventCallback
)

Binding に対して API イベントが発生したときに呼び出すアプリケーション定義関数を設定します。

詳細
パラメータ
[in] aEventCallback
コールバック関数へのポインタ。

SetProtocolLayerCallback

void SetProtocolLayerCallback(
  EventCallback callback,
  void *state
)

アプリの代わりに Binding を使用して、プロトコル レイヤコードのイベント コールバック関数を設定します。

この関数は、Binding に対して API イベントが発生したときに、アプリケーション定義のコールバック関数に加えて呼び出されます。

詳細
パラメータ
[in] callback
コールバック関数へのポインタ。
[in] state
プロトコル レイヤのコールバックが発生したときにプロトコル レイヤのコードに渡される状態オブジェクトへのポインタ。

静的パブリック関数

DefaultEventHandler

void DefaultEventHandler(
  void *apAppState,
  EventType aEvent,
  const InEventParam & aInParam,
  OutEventParam & aOutParam
)

API イベントをバインドするためのデフォルト ハンドラ。

アプリケーションで認識または処理できない API イベントがある場合は、このメソッドを呼び出す必要があります。指定するパラメータは、アプリケーションのイベント ハンドラ関数へのバインディングによって渡されるパラメータと同じである必要があります。

詳細
パラメータ
[in] apAppState
バインディングに関連付けられたアプリケーション定義の状態情報へのポインタ。
[in] aEvent
イベント コールバックによって渡されたイベント ID
[in] aInParam
イベント コールバックによって渡される入力イベント パラメータの参照
[in] aOutParam
イベント コールバックによって渡される出力イベント パラメータの参照