nl::Weave::設定檔::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 節點的即時性和可連性。

應用程式可以使用 WeaveEchoClient 類別，將一次性或重複的 EchoRequest 訊息傳送至由 binding 物件識別的對等節點。有對應的類別可回應 echo 要求 (請參閱 WeaveEchoServer)。

用戶端 繫結

WeaveEchoClient 會使用 Weave binding 物件，用於識別回應以及與回呼要求中預定的收件者之間的通訊內容。應用程式可在初始化 WeaveEchoClient 物件之前設定及準備 binding，或是設為不準備，在此情況下，WeaveEchoClient 會要求對繫結進行隨選準備 (詳情請參閱 binding::RequestPrepare())。

如果「繫結」在「就緒」狀態失敗時，系統也會提出隨選要求。

重複傳送模式

您可以利用 SendRepeating() 方法將 WeaveEchoClient 設為 SendRepeating 模式。在這個模式下，用戶端物件會依照指定的間隔，將重複的 EchoRequest 訊息序列傳送至對等點。如要停止傳送重複傳送模式，請呼叫 Stop() 方法。

多播和廣播

WeaveEchoClient 物件可用來設定 繫結 物件並搭配適當的 IPv6 多播位址或 IPv4 本機網路廣播位址 (255.255.255.255.255.255.255)。當 WeaveEchoClient 物件偵測到多點傳送或廣播對等點位址時，它會在傳送 EchoRequest 時自動進入 MultiResponse 模式。

在這個模式下，物件會監聽並傳送所有接收到相同廣告交易平台的 EchoResponse 訊息。在等待

API 事件

在作業過程中，WeaveEchoClient 物件會呼叫應用程式，要求執行特定動作或傳送重要事件的通知。這些 API 事件呼叫會呼叫用戶端物件上已設定的回呼函式。除非另有註明，否則在事件回呼期間，應用程式可以免費變更用戶端的狀態。

下列 API 事件的定義如下：

準備酬載

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

已傳送要求

已傳送 EchoRequest 訊息給同事。

已收到回應

已收到同事傳送的 EchoResponse 訊息。事件的引數包含回應酬載，以及回應訊息的中繼資訊。

通訊錯誤

建立或傳送 EchoRequest 或等待回應時發生錯誤。等待回應期間可能出現的錯誤示例包括關鍵錯誤或連線中斷。事件的引數包含錯誤原因。

回應逾時

未在指定時間內收到 EchoResponse。回應逾時是由 繫結物件上的 DefaultResponseTimeout 屬性控制。

要求已中止

由於收到一封郵件，且在收到前一則訊息的回應之前已傳送另一個 EchoRequest 要求，因此處理中的 Echo Exchange 作業已取消。當傳送時間來傳送下一個 EchoRequest 時，可能會發生於 SendRepeating 模式中。如果應用程式在系統收到 EchoRequest 後，在收到任何回應之前呼叫 Send()，也可能會發生這種情形。

當物件處於 MultiResponse 模式時，如果收到至少一則 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 相關的 繫結 指標。
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

 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

用戶端物件未初始化。
kState_PreparingBinding

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

已傳送 EchoRequest 訊息，用戶端物件正在等待回應。
kState_WaitingToSend

已呼叫 SendRepeating()，用戶端物件正在等待下一次傳送 EchoRequest。

公開屬性

應用程式狀態

void * AppState

應用程式專屬資料的指標。

公開函式

取得繫結

Binding * GetBinding(
  void
) const

傳回指向與 WeaveEchoClient 相關的 繫結 指標。

取得事件回呼

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
指向 WeaveEchoClient 物件會呼叫的函式，用來將 API 事件傳送至應用程式。
[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 物件未處於就緒狀態，系統會向 binding::RequestPrepare() 方法發出要求，以便進行隨選準備。傳送作業會排入佇列，直到這項程序完成為止。這個佇列的最大深度為 1。因此，如果佇列中有先前的傳送，則任何對 Send() 的呼叫都會產生一個，且只會傳送一個 EchoRequest。

只要在 WeaveEchoClient 處於傳送傳送模式時呼叫 Send() (亦即先前曾呼叫 SendRepeating() 時)，即能加快及重設傳送週期，但不將 WeaveEchoClient 從傳送重複移除。

傳送

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

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

這個方法會啟動將 EchoRequest 訊息傳送至對等節點的程序。將提供的酬載緩衝區內容以 EchoRequest 訊息的酬載的形式傳送給對等端。當系統收到相對應的 EchoResponse 訊息時，會透過 ResponseReceived API 事件將訊息傳送至應用程式。

呼叫這個方法後，所提供酬載緩衝區的擁有權會傳送到 WeaveEchoClient 物件，由此負責釋出。不論該方法是否成功完成或是發生錯誤，都是如此。

如果呼叫這個方法時，如果 binding 物件未處於就緒狀態，系統會向 binding::RequestPrepare() 方法發出要求，以便進行隨選準備。傳送作業會排入佇列，直到這項程序完成為止。這個佇列的最大深度為 1。因此，如果佇列中有先前的傳送，則任何對 Send() 的呼叫都會產生一個，且只會傳送一個 EchoRequest。

只要在 WeaveEchoClient 處於傳送傳送模式時呼叫 Send() (亦即先前曾呼叫 SendRepeating() 時)，即能加快及重設傳送週期，但不將 WeaveEchoClient 從傳送重複移除。

詳細資料
參數
[in] payloadBuf
內含要傳送給對等點的酬載資料的 PacketBuffer 物件。無論在何種情況下，這個緩衝區的擁有權都會傳送至 WeaveEchoClient 物件。

重複傳送

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

開始傳送對等的 EchoRequest 訊息序列至對等點。

這個方法會重複傳送 EchoRequest 訊息給同事。接收到對等點傳送 EchoResponse 訊息時，系統會透過 ResponseReceived API 事件將訊息傳送到應用程式。

當呼叫 SendRepeating() 時，WeaveEchoClient 會進入傳送重複模式，直到呼叫 Stop() 或發生繫結錯誤為止。多次呼叫 SendRepeating() 可重設傳送週期及更新時間間隔。

序列的初始發送在 SendRepeating() 被呼叫，或者每次 繫結在 SendRepeating() 被訂購後就為時間（見下文）。後續的傳送時間則會在指定的時間間隔之後發生。

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

如果在建立訊息時，如果 binding 物件未處於就緒狀態，系統會向 binding::RequestPrepare() 方法發出要求，以便準備隨選。在你重複傳送相同訊息後，系統會暫停傳送重複的訊息。如果隨選繫結失敗，WeaveEchoClient 就會停止傳送重寫模式。

設定事件回呼

void SetEventCallback(
  EventCallback eventCallback
)

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

停用

void Shutdown(
  void
)

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

請注意，只有在先前已呼叫 Init() 方法時，才能呼叫這個方法。

停止

void Stop(
  void
)

停止進行中的 Echo 交換作業，並取消傳送重複模式。

WeaveEchoClient

 WeaveEchoClient(
  void
)

公開的靜態函式

預設事件處理常式

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

WeaveEchoClient API 事件的預設處理常式。

如果應用程式無法辨識或處理任何 API 事件，則必須呼叫這個方法。提供的參數必須與用戶端物件傳送至應用程式事件處理常式函式的參數相同。

詳細資料
參數
[in] appState
指向與用戶端物件相關聯的應用程式定義狀態指標。
[in] eventType
事件回呼傳送的事件 ID
[in] inParam
事件回呼傳送的輸入事件參數參考資料
[in] outParam
事件回呼傳送的輸出事件參數參考資料