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 通訊協定的起始者。Weave Echo 通訊協定與 ICMP 連線偵測 (ping) 通訊協定類似,可用來測試 Weave 節點的有效性和可連性。

應用程式可以使用 WeaveEchoClient 類別傳送一次性或重複 EchoRequest 訊息至 Binding 物件指定的對等節點。存在對應類別來回應回應要求 (請參閱 WeaveEchoServer)。

用戶端繫結

WeaveEchoClient 會使用 Weave Binding 物件,用於識別 echo 要求的特定收件者並建立通訊。在 WeaveEchoClient 物件初始化之前,應用程式便可設定及準備 Binding,也可以取消準備,在這種情況下,WeaveEchoClient 會要求預先準備繫結 (詳情請參閱 Binding::RequestPrepare())。

在進入「就緒」狀態後,系統也會要求繫結的隨選準備作業失敗。

傳送重複模式

SendRepeating() 方法可將 WeaveEchoClient 進入 SendRepeating 模式。在這個模式中,用戶端物件會按照設定的時間間隔,將重複的 EchoRequest 訊息序列傳送給對等互連。您可以呼叫 Stop() 方法,取消 SendRepeating 模式。

多點傳播與廣播

您可以使用 WeaveEchoClient 物件,為 Binding 物件設定適當的 IPv6 多點傳播位址或 IPv4 區域網路廣播位址 (255.255.255.255),藉此將 EchoRequests 物件同時傳送給多位收件者。當 WeaveEchoClient 物件偵測到多點傳送或廣播對等位址時,就會在傳送 EchoRequest 時自動進入多回應模式。

在這個模式下,物件會繼續監聽及傳送同一個交換下所收到的所有 EchoResponse 訊息。除非:1) 應用程式在 SendRepeating 模式下呼叫 Stop()Send(),以及 2) 傳送其他要求的時間,或 3) 未收到回應且接收逾時。

API 事件

在作業期間,WeaveEchoClient 物件會呼叫應用程式以要求特定動作或傳送重要事件通知。這些 API 事件呼叫會呼叫用戶端物件目前設定的回呼函式。除非另有註明,否則應用程式可以在事件回呼期間變更用戶端的狀態。整體例外是物件的 Shutdown() 方法,該方法可能無法在回呼期間呼叫。

下列 API 事件的定義如下:

PreparePayload

WeaveEchoClient 即將形成 EchoRequest 訊息,並要求應用程式提供酬載。應用程式如有需要,可能會傳回包含酬載資料的新 PacketBuffer。如果應用程式未處理這個事件,系統會自動傳送酬載為零長度的 EchoRequest 。在這個回呼期間,應用程式「不得」變更 WeaveEchoClient 的狀態。

RequestSent

EchoRequest 訊息已傳送給對等互連。

ResponseReceived

收到來自對等點的 EchoResponse 訊息。事件的引數包含關於回應訊息的回應酬載和中繼資訊。

CommunicationError

形成或傳送 EchoRequest 時發生錯誤,或是等待回應時發生錯誤。等待回應時可能發生的錯誤,例如關鍵錯誤或非預期的連線關閉。事件引數包含錯誤原因。

ResponseTimeout

未在指定時間內收到 EchoResponse。回應逾時取決於 Binding 物件的 DefaultResponseTimeout 屬性。

RequestAborted

由於系統要求在收到先前訊息的回應前傳送其他 EchoRequest,因此已取消執行中的 Echo 交換作業。在 SendRepeating 模式下,可能會發生這種情形,進而傳送下一個 EchoRequest。如果應用程式在傳送 EchoRequest 後,但在收到任何回應之前就呼叫 Send(),也可能會發生這種情況。

當物件處於多回應模式時,如果收到至少一則 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 事件。

公開類型

EventCallback

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

EventType

 EventType
屬性
kEvent_CommunicationError

傳送 EchoRequest 或等待回應時發生通訊錯誤。

kEvent_DefaultCheck

用於驗證應用程式中正確的預設事件處理方式。

kEvent_PreparePayload

系統會要求該應用程式準備 Echo 要求的酬載。

kEvent_RequestAborted

由於有人提出啟動其他交易的要求,因此處理中的 Echo 交換作業已取消。

kEvent_RequestSent

EchoRequest 訊息已傳送給對等互連。

kEvent_ResponseReceived

收到來自對等點的 EchoResponse 訊息。

kEvent_ResponseTimeout

未在指定時間內收到 EchoResponse。

狀態

 State
屬性
kState_Idle

用戶端物件處於閒置狀態。

kState_NotInitialized

Client 物件未初始化。

kState_PreparingBinding

用戶端物件正在等候繫結準備就緒。

kState_RequestInProgress

EchoRequest 訊息已送出,用戶端物件正在等候回應。

kState_WaitingToSend

呼叫 SendRepeating() 後,用戶端物件正在等候下次傳送 EchoRequest。

公開屬性

AppState

void * AppState

應用程式特定資料的指標。

公用函式

GetBinding

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 物件,以準備將 echo 訊息傳送給對等點。

詳細說明
參數
[in] binding
繫結物件,用來建立與對等互連節點的通訊。
[in] eventCallback
指向一個函式指標,該函式會由 WeaveEchoClient 物件呼叫,以便將 API 事件提供給應用程式。
[in] appState
應用程式定義物件的指標。每當發生 API 事件時,這個物件就會傳回應用程式。

IsSendRrepeating

bool IsSendRrepeating() const 

如果 WeaveEchoClient 物件目前處於傳送重複模式,則傳回 true。

RequestInProgress

bool RequestInProgress() const 

如果已傳送 EchoRequest 且 WeaveEchoClient 物件正在等待回應,則傳回 true。

傳送

WEAVE_ERROR Send(
  void
)

傳送 EchoRequest 訊息給對等互連。

這個方法會啟動傳送 EchoRequest 訊息至對等互連節點的程序。如果收到相應的 EchoResponse 訊息,就會透過 ResponseReceived API 事件傳送至您的應用程式。

建立 EchoRequest 訊息時,WeaveEchoClient 會透過 PreparePayload API 事件向應用程式發出要求,以便準備訊息的酬載。

呼叫此方法時,如果 Binding 物件未處於「就緒」狀態,則會傳送要求至 Binding::RequestPrepare() 方法,以啟動隨選準備程序。傳送作業將排入佇列,直到這項程序完成為止。這個佇列的最大深度為 1。因此,如果佇列中仍有傳送先前傳送的內容,對 Send() 進行任何呼叫,系統只會傳送單一 EchoRequest 通知。

WeaveEchoClient 處於傳送重複模式時 (也就是由於先前的呼叫 SendRepeating()),呼叫 Send() 可能會加速及重設傳送週期,但不會讓 WeaveEchoClient 退出傳送重複模式。

傳送

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

將 EchoRequest 訊息傳送至含有特定酬載的對等點。

這個方法會啟動傳送 EchoRequest 訊息至對等互連節點的程序。所提供酬載緩衝區的內容會做為 EchoRequest 訊息的酬載傳送至對等互連。如果收到相應的 EchoResponse 訊息,就會透過 ResponseReceived API 事件傳送至您的應用程式。

呼叫此方法後,所提供酬載緩衝區的擁有權會傳遞至 WeaveEchoClient 物件,該物件有責任釋出該緩衝區。無論方法是否順利完成或有錯誤,都是如此。

呼叫此方法時,如果 Binding 物件未處於「就緒」狀態,則會傳送要求至 Binding::RequestPrepare() 方法,以啟動隨選準備作業。傳送作業接著會排入佇列,直到這項程序完成為止。這個佇列的最大深度為 1。因此,如果佇列中仍有傳送先前傳送的內容,對 Send() 進行任何呼叫,系統只會傳送單一 EchoRequest 通知。

WeaveEchoClient 處於傳送重複模式時 (也就是由於先前的呼叫 SendRepeating()),呼叫 Send() 可能會加速及重設傳送週期,但不會讓 WeaveEchoClient 退出傳送重複模式。

詳細說明
參數
[in] payloadBuf
包含要傳送至對等點的酬載資料的 PacketBuffer 物件。在任何情況下,這個緩衝區的擁有權都會傳遞至 WeaveEchoClient 物件。

SendRepeating

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

傳送重複的 EchoRequest 訊息序列至對等點。

這個方法會啟動重複的程序,將 EchoRequest 訊息傳送給對等互連。從對等點收到 EchoResponse 訊息,就會透過 ResponseReceived API 事件傳送至您的應用程式。

呼叫 SendRepeating() 時,WeaveEchoClient 會進入傳送重複模式,直到呼叫 Stop() 或發生 Binding 錯誤。多次呼叫 SendRepeating() 會造成重設傳送週期並更新間隔。

系統會在呼叫 SendRepeating() 時,或在呼叫 SendRepeating() 之後 (請見下文) 時,完成 Binding 的初始傳送作業。後續的傳送時間則會在特定的時間間隔後發生。

每次傳送時,WeaveEchoClient 會透過 PreparePayload API 事件向應用程式發出要求,準備訊息的酬載。

在傳送訊息時,如果 Binding 物件並未處於「就緒」狀態,則會傳送要求至 Binding::RequestPrepare() 方法,以便啟動隨選準備作業。重複傳送的訊息會暫停傳送,直到這項程序完成為止。在隨選繫結準備期間發生錯誤,WeaveEchoClient 會離開傳送重複模式。

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

WeaveEchoClient 物件上設定 API 事件回呼函式。

關機

void Shutdown(
  void
)

關閉先前初始化的 WeaveEchoClient 物件。

請注意,您必須先呼叫 Init() 方法,才能呼叫此方法。

停止

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
由事件回呼傳遞的輸出事件參數參考資料