Google は、黒人コミュニティのための人種的公平の促進に取り組んでいます。詳細をご覧ください。

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{
  kGetPeerDescription_MaxLength = nl::Weave::kWeavePeerDescription_MaxLength
}
列挙型
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
}
列挙型
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::Weave::Binding::Configuration

Binding オブジェクトを構成して準備するための宣言型インターフェースを提供します。

構造体

nl::Weave::Binding::InEventParam

Binding API イベントにパラメータを入力します。

nl::Weave::Binding::OutEventParam

Binding API イベントにパラメータを出力します。

パブリック タイプ

23

 @23
Properties
kGetPeerDescription_MaxLength

GetPeerDescription() から返される文字列の最大長(NUL 文字を含む)です。

イベント コールバック

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 コンテキストを再構成して、レスポンスのタイムアウトを調整します。

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

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 

ピアとの通信時に使用するデフォルトの 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 の解決完了後などに)アドレス情報を利用できるようになります。バインディングの準備ができたら、バインディングがリセットされるまで、住所の情報を利用できます。

詳細
パラメータ
[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 

IsUnrereableUDPTransport

bool IsUnreliableUDPTransport() const 

IsWRMTransport

bool IsWRMTransport() const 

NewExchangeContext

WEAVE_ERROR NewExchangeContext(
  ExchangeContext *& appExchangeContext
)

バインディングのターゲットであるピアと通信するための新しい Exchange コンテキストを割り当てます。

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

リリース

void Release(
  void
)

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

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

リクエストの準備

WEAVE_ERROR RequestPrepare()

アプリケーションを構成して、バインディングを構成して準備します。

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

このメソッドは、NotConfigured 状態または Failed 状態のバインディングでのみ呼び出すことができます。

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

リセット

void Reset(
  void
)

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

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

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

SetDefaultResponseTimeout

void SetDefaultResponseTimeout(
  uint32_t msec
)

ピアと通信する際に使用するデフォルトの Exchange レスポンス タイムアウトを設定します。

詳細
パラメータ
[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
イベント コールバックによって渡される出力イベント パラメータの参照