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

nl::Weave::Profiles::Echo_Next::WeaveEchoClient

#include <src/lib/profiles/echo/Next/WeaveEchoClient.h>

Provides the ability to send Weave EchoRequest messages to a peer node and receive
the corresponding EchoResponse messages.

まとめ

WeaveEchoClient クラスは、Weave Echo プロトコルのイニシエータ側を実装します。ICMP ping プロトコルと同様に、Weave Echo プロトコルを使用して、Weave ノードの liveness と ネットワーク到達性をテストします。

アプリケーションは WeaveEchoClient クラスを使用して、Binding オブジェクトによって識別されるピアノードに 1 回限りまたは繰り返しの EchoRequest メッセージを送信できます。エコー リクエストに応答するクラスが存在します(WeaveEchoServer を参照)。

クライアント バインディング

WeaveEchoClient は Weave Binding オブジェクトを受け取ります。このオブジェクトを使用すると、エコー リクエストの対象の受信者との通信を特定して確立できます。WeaveEchoClient オブジェクトの初期化前に、アプリによって Binding を設定および準備できます。準備しない場合は、WeaveEchoClient がオンデマンドでバインディングの準備をリクエストします(詳しくは、Binding::RequestPrepare() をご覧ください)。

Ready 状態になった後にエラーが発生した場合は、Binding のオンデマンド作成もリクエストされます。

繰り返しモードを送信

SendRepeating() メソッドを使用すると、WeaveEchoClient を SendRepeating モードにすることができます。このモードでは、クライアント オブジェクトは設定された間隔でピアに繰り返し EchoRequest メッセージを送信します。SendRepeating モードは、Stop() メソッドを呼び出すことでキャンセルできます。

マルチキャストとブロードキャスト

WeaveEchoClient オブジェクトを使用すると、適切な IPv6 マルチキャスト アドレスまたは IPv4 ローカル ネットワーク ブロードキャスト アドレス(255.255.255.255)で Binding オブジェクトを構成することで、複数の受信者に同時に EchoRequest を送信できます。WeaveEchoClient オブジェクトは、マルチキャストまたはブロードキャストのピアアドレスを検出すると、EchoRequest を送信すると自動的に MultiResponse モードに入ります。

このモードでは、同じエクスチェンジに到着するすべての EchoResponse メッセージをリッスンし、配信します。オブジェクトは、1)アプリケーションが Stop() または Send() を呼び出すか、2)SendRepeating モードで、別のリクエストを送信するまで、または 3)レスポンスが受信されず、受信タイムアウトになるまで、MultiResponse モードのままになります。

API イベント

その動作中に、WeaveEchoClient オブジェクトはアプリケーションを呼び出して、特定のアクションのリクエストや重要なイベントの通知の配信を行います。これらの API イベントの呼び出しは、現在クライアント オブジェクトに設定されているコールバック関数に対して行われます。特に記載のない限り、イベントは、イベント コールバック中にクライアントの状態を自由に変更できます。全体的な例外として、オブジェクトの Shutdown() メソッドが挙げられます。このメソッドは、コールバック中に呼び出すことはできません。

次の API イベントが定義されます。

PreparePayload(準備ペイロード)

WeaveEchoClient は EchoRequest メッセージを形成しようとしているために、アプリケーションにペイロードを提供するようリクエストしています。アプリケーションが必要とする場合は、ペイロード データを含む新しい PacketBuffer を返すことができます。アプリケーションがこのイベントを処理しない場合、長さがゼロの EchoRequest は自動的に送信されます。アプリは、このコールバック中に WeaveEchoClient の状態を変更しても構いません。

リクエスト送信済み

EchoRequest メッセージがピアに送信されました。

ResponseReceived(レスポンスの受信)

ピアから EchoResponse メッセージを受信しました。イベントの引数には、レスポンス ペイロードとレスポンス メッセージに関するメタ情報が含まれます。

通信エラー

EchoRequest の作成中または送信中、またはレスポンスの待機中にエラーが発生しました。レスポンスを待機している間に発生する可能性のあるエラーの例としては、キーエラーや予期しない接続の切断があります。イベントの引数にエラーの理由が含まれています。

ResponseTimeout(レスポンスのタイムアウト)

割り当てられた時間内に EchoResponse を受信しませんでした。レスポンス タイムアウトは、Binding オブジェクトの DefaultResponseTimeout プロパティによって制御されます。

リクエストを中止しました

進行中の Echo 交換は、前のメッセージに対するレスポンスを受信する前に別の EchoRequest を送信するようにリクエストされているため、中止されました。これは、次の EchoRequest を送信する時間になると、SendRepeating モードで発生する可能性があります。また、EchoRequest が送信された後でレスポンスが受信される前に、アプリケーションが Send() を呼び出した場合にも発生します。

オブジェクトが MultiResponse モードの場合、少なくとも 1 つの EchoResponse メッセージが受信されると、イベントは抑制されます。

コンストラクタとデストラクタ

WeaveEchoClient(void)

パブリック タイプ

EventCallback)(void *appState, EventType eventType, const InEventParam &inParam, OutEventParam &outParam) typedef
void(*
EventType{
  kEvent_PreparePayload = 1,
  kEvent_RequestSent = 2,
  kEvent_ResponseReceived = 3,
  kEvent_CommunicationError = 4,
  kEvent_ResponseTimeout = 5,
  kEvent_RequestAborted = 6,
  kEvent_DefaultCheck = 100
}
列挙型
State{
  kState_NotInitialized = 0,
  kState_Idle = 1,
  kState_PreparingBinding = 2,
  kState_RequestInProgress = 3,
  kState_WaitingToSend = 4
}
列挙型

パブリック属性

AppState
void *
アプリケーション固有のデータへのポインタ。

パブリック関数

GetBinding(void) const
WeaveEchoClient に関連付けられた Binding オブジェクトへのポインタを返します。
GetEventCallback(void) const
EventCallback
現在 WeaveEchoClient オブジェクトに構成されている API イベント コールバック関数へのポインタを返します。
GetState(void) const
WeaveEchoClient オブジェクトの現在の状態を取得します。
Init(Binding *binding, EventCallback eventCallback, void *appState)
WeaveEchoClient オブジェクトを初期化します。
IsSendRrepeating() const
bool
WeaveEchoClient オブジェクトが現在、送信繰り返しモードになっている場合、true を返します。
RequestInProgress() const
bool
EchoRequest が送信され、WeaveEchoClient オブジェクトがレスポンスを待機している場合に true を返します。
Send(void)
ピアに EchoRequest メッセージを送信します。
Send(PacketBuffer *payloadBuf)
特定のペイロードを含むピアに EchoRequest メッセージを送信します。
SendRepeating(uint32_t sendIntervalMS)
ピアへの EchoRequest メッセージの繰り返しシーケンスを送信します。
SetEventCallback(EventCallback eventCallback)
void
WeaveEchoClient オブジェクトに API イベント コールバック関数を設定します。
Shutdown(void)
void
以前に初期化した WeaveEchoClient オブジェクトをシャットダウンします。
Stop(void)
void
進行中の Echo の交換を停止し、送信の繰り返しモードをキャンセルします。

静的パブリック関数

DefaultEventHandler(void *appState, EventType eventType, const InEventParam & inParam, OutEventParam & outParam)
void
WeaveEchoClient API イベントのデフォルト ハンドラ。

構造体

nl::Weave::Profiles::Echo_Next::WeaveEchoClient::InEventParam

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

nl::Weave::Profiles::Echo_Next::WeaveEchoClient::OutEventParam

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

パブリック タイプ

イベント コールバック

void(* EventCallback)(void *appState, EventType eventType, const InEventParam &inParam, OutEventParam &outParam)

イベントタイプ

 EventType
Properties
kEvent_CommunicationError

EchoRequest の送信中または応答の待機中に通信エラーが発生しました。

kEvent_DefaultCheck

アプリケーションのデフォルトのイベント処理が正しく行われていることを確認するために使用されます。

kEvent_PreparePayload

アプリケーションに、Echo リクエストのペイロードを準備するようにリクエストします。

kEvent_RequestAborted

別のエクスチェンジを開始するリクエストが行われたため、進行中の Echo エクスチェンジは中止されました。

kEvent_RequestSent

EchoRequest メッセージがピアに送信されました。

kEvent_ResponseReceived

ピアから EchoResponse メッセージを受信しました。

kEvent_ResponseTimeout

割り当てられた時間内に EchoResponse を受信しませんでした。

状態

 State
Properties
kState_Idle

クライアント オブジェクトはアイドル状態です。

kState_NotInitialized

クライアント オブジェクトは初期化されません。

kState_PreparingBinding

クライアント オブジェクトは、バインディングの準備が完了するのを待機しています。

kState_RequestInProgress

EchoRequest メッセージを送信し、クライアント オブジェクトが応答を待機しています。

kState_WaitingToSend

SendRepeating() が呼び出され、クライアント オブジェクトが次回 EchoRequest を送信するのを待機しています。

パブリック属性

アプリの状態

void * AppState

アプリケーション固有のデータへのポインタ。

パブリック関数

バインディングの取得

Binding * GetBinding(
  void
) const 

WeaveEchoClient に関連付けられた Binding オブジェクトへのポインタを返します。

GetEventCallback

EventCallback GetEventCallback(
  void
) const 

現在 WeaveEchoClient オブジェクトに構成されている API イベント コールバック関数へのポインタを返します。

GetState

State GetState(
  void
) const 

WeaveEchoClient オブジェクトの現在の状態を取得します。

init

WEAVE_ERROR Init(
  Binding *binding,
  EventCallback eventCallback,
  void *appState
)

WeaveEchoClient オブジェクトを初期化します。

ピアにエコー メッセージを送信する前に、WeaveEchoClient オブジェクトを初期化します。

詳細
パラメータ
[in] binding
ピアノードとの通信を確立するために使用される Binding オブジェクト。
[in] eventCallback
API イベントをアプリケーションに配信するために WeaveEchoClient オブジェクトによって呼び出される関数へのポインタ。
[in] appState
API イベントが発生するたびにアプリケーションに返されるアプリケーション定義オブジェクトへのポインタ。

IsSendRRepeating

bool IsSendRrepeating() const 

WeaveEchoClient オブジェクトが現在、送信繰り返しモードになっている場合、true を返します。

リクエストの進行状況

bool RequestInProgress() const 

EchoRequest が送信され、WeaveEchoClient オブジェクトがレスポンスを待機している場合に true を返します。

送信

WEAVE_ERROR Send(
  void
)

ピアに EchoRequest メッセージを送信します。

このメソッドは、ピアノードに EchoRequest メッセージを送信するプロセスを開始します。対応する EchoResponse メッセージを受信すると、そのメッセージは ResponseReceived API イベントを介してアプリケーションに配信されます。

EchoRequest メッセージを作成するときに、WeaveEchoClient は PreparePayload API のイベントを介してアプリケーションにリクエストを送信し、メッセージのペイロードを準備します。

このメソッドが呼び出されたときに Binding オブジェクトが Ready 状態でない場合、Binding::RequestPrepare() メソッドに対してリクエストが行われ、オンデマンドでの準備が開始します。この処理が完了するまで、送信操作はキューに入れられます。このキューの最大深度は 1 です。そのため、キュー内に前回の送信がある場合に Send() を呼び出すと、EchoRequest は 1 つしか送信されません。

WeaveEchoClient が送信繰り返しモードのとき(たとえば、前の SendRepeating() の呼び出しのため)に Send() を呼び出すと、送信サイクルを加速してリセットできますが、WeaveEchoClient を送信送信モードから除外することはできません。

送信

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

特定のペイロードを含むピアに EchoRequest メッセージを送信します。

このメソッドは、ピアノードに EchoRequest メッセージを送信するプロセスを開始します。指定したペイロード バッファの内容が、EchoRequest メッセージのペイロードとしてピアに送信されます。対応する EchoResponse メッセージを受信すると、そのメッセージは ResponseReceived API イベントを介してアプリケーションに配信されます。

このメソッドを呼び出すと、ペイロード バッファの所有権は WeaveEchoClient オブジェクトに渡され、このオブジェクトにより解放されます。これは、メソッドが正常に完了したかどうか、またはエラーがあったかどうかに関係なく当てはまります。

このメソッドが呼び出されたときに Binding オブジェクトが Ready 状態でない場合、Binding::RequestPrepare() メソッドに対してリクエストが行われ、オンデマンドでの準備が開始します。送信が完了するまで、この処理はキューに追加されます。このキューの最大深度は 1 です。そのため、キュー内に前回の送信がある場合に Send() を呼び出すと、EchoRequest は 1 つしか送信されません。

WeaveEchoClient が送信繰り返しモードのとき(たとえば、前の SendRepeating() の呼び出しのため)に Send() を呼び出すと、送信サイクルを加速してリセットできますが、WeaveEchoClient を送信送信モードから除外することはできません。

詳細
パラメータ
[in] payloadBuf
ピアに送信されるペイロード データを含む PacketBuffer オブジェクト。このバッファの所有権は、すべての場合に WeaveEchoClient オブジェクトに渡されます。

繰り返し送信

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

ピアへの EchoRequest メッセージの繰り返しシーケンスを送信します。

このメソッドは、ピアに EchoRequest メッセージを送信する繰り返しプロセスを開始します。EchoResponse のメッセージはピアから受信されると、ResponseReceived API イベントを介してアプリケーションに送信されます。

SendRepeating() が呼び出されると、WeaveEchoClientStop() が呼び出されるか、Binding エラーが発生するまで送信繰り返しモードになります。SendRepeating() を複数回呼び出すと、送信サイクルがリセットされ、間隔が更新されます。

シーケンスの最初の送信は、SendRepeating() が呼び出されたとき、または SendRepeating() が呼び出された後に Binding の準備ができたときに発生します(下記参照)。その後の送信は、指定された間隔で行われます。

送信が発生するたびに、WeaveEchoClient は PreparePayload API のイベントを介してアプリケーションにリクエストを送信し、メッセージのペイロードを準備します。

メッセージの送信時に Binding オブジェクトが Ready 状態でない場合、Binding::RequestPrepare() メソッドに対してリクエストが行われ、オンデマンドでの準備が開始します。このプロセスを繰り返すと、メッセージの送信は一時停止されます。オンデマンドのバインディングの準備中にエラーが発生すると、WeaveEchoClient は送信の繰り返しモードを終了します。

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

WeaveEchoClient オブジェクトに API イベント コールバック関数を設定します。

シャットダウン

void Shutdown(
  void
)

以前に初期化した WeaveEchoClient オブジェクトをシャットダウンします。

このメソッドは、以前に Init() メソッドが呼び出された場合にのみ呼び出すことができます。

Stop

void Stop(
  void
)

進行中の Echo の交換を停止し、送信の繰り返しモードをキャンセルします。

WeaveEchoClient

 WeaveEchoClient(
  void
)

静的パブリック関数

DefaultEventHandler

void DefaultEventHandler(
  void *appState,
  EventType eventType,
  const InEventParam & inParam,
  OutEventParam & outParam
)

WeaveEchoClient API イベントのデフォルト ハンドラ。

アプリケーションは、認識または処理しない API イベントでこのメソッドを呼び出す必要があります。指定するパラメータは、クライアント オブジェクトからアプリケーションのイベント ハンドラ関数に渡されるパラメータと同じにする必要があります。

詳細
パラメータ
[in] appState
クライアント オブジェクトに関連付けられたアプリケーション定義の状態情報へのポインタ。
[in] eventType
イベント コールバックが渡すイベント ID
[in] inParam
イベント コールバックによって渡される入力イベント パラメータの参照
[in] outParam
イベント コールバックによって渡される出力イベント パラメータの参照