nl::Weave::Profile::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.

Fazit

Die Klasse WeaveEchoClient implementiert die Initiatorenseite des Weave-Echo-Protokolls. Ähnlich wie beim ICMP-Ping-Protokoll kann das Weave-Echo-Protokoll verwendet werden, um die Aktivität und Erreichbarkeit eines Weave-Knotens zu testen.

Anwendungen können die Klasse WeaveEchoClient verwenden, um einmalige oder wiederkehrende EchoRequest-Nachrichten an einen Peer-Knoten zu senden, der durch ein Bindungsobjekt identifiziert wird. Für die Antwort auf Echo-Anfragen ist eine entsprechende Klasse vorhanden (siehe WeaveEchoServer).

Clientbindung

WeaveEchoClient verwendet ein Weave-Bindungsobjekt, das verwendet wird, um die Kommunikation mit dem vorgesehenen Empfänger der Echo-Anfragen zu ermitteln und herzustellen. Die Bindung kann von der Anwendung vor der Initialisierung des WeaveEchoClient-Objekts konfiguriert und vorbereitet werden oder sie kann nicht vorbereitet werden. In diesem Fall fordert WeaveEchoClient bei Bedarf die Vorbereitung der Bindung an (siehe Bindung::RequestPrepare()).

Eine On-Demand-Vorbereitung der Bindung wird ebenfalls angefordert, wenn sie im Status „Bereit“ fehlschlägt.

Wiederkehrender Modus

Die SendRepeating()-Methode kann verwendet werden, um den WeaveEchoClient in den Sendewiederholungsmodus zu versetzen. In diesem Modus sendet das Clientobjekt in regelmäßigen Abständen eine wiederkehrende Echoanfrage-Nachricht an den Peer. Der Modus „Wiederholen“ kann mit der Methode Stop() abgebrochen werden.

Multicast und Übertragung

Ein WeaveEchoClient-Objekt kann verwendet werden, um EchoRequest-Anfragen an mehrere Empfänger gleichzeitig zu senden. Dazu wird das Bindungsobjekt mit einer geeigneten IPv6-Multicast-Adresse oder einer lokalen IPv4-Broadcast-Adresse (255.255.255.255) konfiguriert. Wenn das WeaveEchoClient-Objekt eine Multicast- oder Broadcast-Peer-Adresse erkennt, wechselt es beim Senden des EchoRequest automatisch in den MultiResponse-Modus.

In diesem Modus wartet das Objekt weiter auf alle eingehenden EchoResponse-Nachrichten, die auf demselben Exchange eingehen. Das Objekt bleibt im MultiResponse-Modus, bis: 1) die Anwendung Stop() oder Send() aufruft, 2) im Modus „Sendewiederholung“ wechselt, eine neue Anfrage gesendet wird oder 3) keine Antwort empfangen wird und das Zeitlimit für den Empfang abläuft.

API-Ereignisse

Während dessen Vorgang ruft das Objekt WeaveEchoClient die Anwendung auf, um bestimmte Aktionen anzufordern oder Benachrichtigungen über wichtige Ereignisse zu senden. Diese API-Ereignisaufrufe werden an die aktuell konfigurierte Callback-Funktion im Clientobjekt gesendet. Sofern nicht anders angegeben, können Anwendungen den Status des Clients während eines Ereignis-Callbacks ändern. Eine Ausnahme ist die H()-Methode für Objekte, die nie während eines Callbacks aufgerufen werden kann.

Die folgenden API-Ereignisse sind definiert:

Nutzlast

WeaveEchoClient beginnt mit der Erstellung einer EchoRequest-Nachricht und fordert die Anwendung an, eine Nutzlast bereitzustellen. Eine Anwendung kann einen neuen PacketBuffer mit den Nutzlastdaten zurückgeben, wenn dies erwünscht ist. Wenn die Anwendung dieses Ereignis nicht verarbeitet, wird automatisch ein EchoRequest mit Nutzlast null Länge gesendet. Die Anwendung darf den Status von WeaveEchoClient während dieses Callbacks NICHT ändern.

Anfrage gesendet

Eine EchoRequest-Nachricht wurde an den Peer gesendet.

Antwort erhalten

Vom Peer wurde eine EchoResponse-Nachricht empfangen. Argumente für das Ereignis enthalten die Nutzlast der Antwort und Metainformationen zur Antwortnachricht.

Kommunikationsfehler

Beim Erstellen oder Senden eines EchoRequest-Fehlers oder beim Warten auf eine Antwort ist ein Fehler aufgetreten. Zu den Fehlern, die beim Warten auf eine Antwort auftreten können, gehören entscheidende Fehler oder unerwartetes Schließen einer Verbindung. Argumente für das Ereignis enthalten den Fehlergrund.

Zeitüberschreitung der Antwort

Es wurde keine EchoResponse empfangen. Das Zeitlimit für Antworten wird vom Attribut „DefaultResponseTimeout“ für das Objekt Bindung festgelegt.

Anfrage abgebrochen

Ein laufender Echo-Austausch wurde abgebrochen, weil eine Anfrage zum Senden eines weiteren EchoRequest gestellt wurde, bevor eine Antwort auf die vorherige Nachricht empfangen wurde. Dieser Fehler kann im Modus „RepeatRepeating“ auftreten, wenn die Zeit ansteht, das nächste EchoRequest-Objekt zu senden. Das kann auch vorkommen, wenn die Anwendung Send() aufruft, nachdem ein EchoRequest gesendet wurde, aber bevor eine Antwort empfangen wurde.

Wenn sich das Objekt im MultiResponse-Modus befindet, wird das Ereignis unterdrückt, wenn mindestens eine EchoResponse-Nachricht empfangen wurde.

Konstrukteur und Zerstörer
WeaveEchoClient(void)

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

Öffentliche Attribute
AppState
void *
Ein Hinweis auf anwendungsspezifische Daten.

Öffentliche Funktionen
GetBinding(void) const
Gibt einen Zeiger auf das Bindungsobjekt zurück, das mit dem WeaveEchoClient verknüpft ist.
GetEventCallback(void) const
EventCallback
Gibt einen Zeiger auf die API-Ereignis-Callback-Funktion zurück, die derzeit für das WeaveEchoClient-Objekt konfiguriert ist.
GetState(void) const
Rufen Sie den aktuellen Status des WeaveEchoClient-Objekts ab.
Init(Binding *binding, EventCallback eventCallback, void *appState)
Initialisiere ein WeaveEchoClient-Objekt.
IsSendRrepeating() const
bool
Gibt „true“ zurück, wenn sich das WeaveEchoClient-Objekt derzeit im Sendewiederholmodus-Modus befindet.
RequestInProgress() const
bool
Gibt „true“ zurück, wenn ein EchoRequest gesendet wurde und das WeaveEchoClient-Objekt auf eine Antwort wartet.
Send(void)
Sende eine EchoRequest-Nachricht an den Peer.
Send(PacketBuffer *payloadBuf)
Eine EchoRequest-Nachricht mit einer bestimmten Nutzlast an den Peer senden.
SendRepeating(uint32_t sendIntervalMS)
Senden Sie eine wiederkehrende Sequenz von EchoRequest-Nachrichten an den Peer.
SetEventCallback(EventCallback eventCallback)
void
Legt die API-Ereignis-Callback-Funktion für das WeaveEchoClient-Objekt fest.
Shutdown(void)
void
Herunterfahren eines zuvor initialisierten WeaveEchoClient-Objekts
Stop(void)
void
Beendet den Echo-Austausch und der Vorgang „Wiederholen“ wird abgebrochen.

Öffentliche statische Funktionen
DefaultEventHandler(void *appState, EventType eventType, const InEventParam & inParam, OutEventParam & outParam)
void
Standard-Handler für WeaveEchoClient-API-Ereignisse.

Strebenklemmen
nl::Weave::Profile::Echo_Next::WeaveEchoClient::InEventParam

Eingabeparameter für das API-Ereignis WeaveEchoClient

nl::Weave::Profile::Echo_Next::WeaveEchoClient::OutEventParam

Ausgabeparameter an das API-Ereignis WeaveEchoClient.

Öffentliche Typen

Ereignis-Callback

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

EventType

 EventType
Attribute
kEvent_CommunicationError

Ein Kommunikationsfehler ist aufgetreten, während ein EchoRequest gesendet oder auf eine Antwort gewartet wurde.

kEvent_DefaultCheck

Wird verwendet, um die korrekte standardmäßige Ereignisverarbeitung in der Anwendung zu prüfen.

kEvent_PreparePayload

Die Anwendung wird aufgefordert, die Nutzlast für die Echo-Anfrage vorzubereiten.

kEvent_RequestAborted

Ein laufenden Echo-Austausch wurde abgebrochen, weil eine neue Anfrage gesendet wurde.

kEvent_RequestSent

Eine EchoRequest-Nachricht wurde an den Peer gesendet.

kEvent_ResponseReceived

Vom Peer wurde eine EchoResponse-Nachricht empfangen.

kEvent_ResponseTimeout

Es wurde keine EchoResponse empfangen.

Status

 State
Attribute
kState_Idle

Das Clientobjekt ist inaktiv.

kState_NotInitialized

Das Clientobjekt ist nicht initialisiert.

kState_PreparingBinding

Das Clientobjekt wartet darauf, dass die Bindung bereit ist.

kState_RequestInProgress

Eine EchoRequest-Nachricht wurde gesendet und das Clientobjekt wartet auf eine Antwort.

kState_WaitingToSend

SendRepeating() wurde aufgerufen und das Client-Objekt wartet auf das nächste Senden eines EchoRequest.

Öffentliche Attribute

App-Status

void * AppState

Ein Hinweis auf anwendungsspezifische Daten.

Öffentliche Funktionen

GetBindung

Binding * GetBinding(
  void
) const

Gibt einen Zeiger auf das Bindungsobjekt zurück, das mit dem WeaveEchoClient verknüpft ist.

GetEventCallback

EventCallback GetEventCallback(
  void
) const

Gibt einen Zeiger auf die API-Ereignis-Callback-Funktion zurück, die derzeit für das WeaveEchoClient-Objekt konfiguriert ist.

GetState

State GetState(
  void
) const

Rufen Sie den aktuellen Status des WeaveEchoClient-Objekts ab.

Init

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

Initialisiere ein WeaveEchoClient-Objekt.

Initialisieren Sie ein WeaveEchoClient-Objekt, um Echo-Nachrichten an einen Peer zu senden.

Details
Parameter
[in] binding
Ein Bindungsobjekt, das zur Kommunikation mit dem Peer-Knoten verwendet wird.
[in] eventCallback
Ein Zeiger auf eine Funktion, die vom Objekt WeaveEchoClient aufgerufen wird, um API-Ereignisse an die Anwendung zu senden.
[in] appState
Ein Zeiger auf ein anwendungsdefiniertes Objekt, das bei jedem API-Ereignis an die Anwendung zurückgegeben wird.

IsSendRwiederkehrend

bool IsSendRrepeating() const

Gibt „true“ zurück, wenn sich das WeaveEchoClient-Objekt derzeit im Sendewiederholmodus-Modus befindet.

Anfrage in Bearbeitung

bool RequestInProgress() const

Gibt „true“ zurück, wenn ein EchoRequest gesendet wurde und das WeaveEchoClient-Objekt auf eine Antwort wartet.

Senden

WEAVE_ERROR Send(
  void
)

Sende eine EchoRequest-Nachricht an den Peer.

Mit dieser Methode wird eine EchoRequest-Nachricht an den Peer-Knoten gesendet. Wenn und wann eine entsprechende EchoResponse-Nachricht eingeht, wird sie über das ResponseReceived API-Ereignis an die Anwendung gesendet.

Beim Erstellen der EchoRequest-Nachricht stellt WeaveEchoClient über das PreparePayload API-Ereignis eine Anfrage zur Vorbereitung der Nutzlast der Nachricht bereit.

Wenn sich das Bindungsobjekt beim Aufrufen dieser Methode nicht im Status „Bereit“ befindet, wird eine Anfrage an die Methode Bindung::RequestPrepare() gestellt, um die On-Demand-Vorbereitung zu initiieren. Der Vorgang wird dann in die Warteschlange gestellt, bis der Vorgang abgeschlossen ist. Die maximale Tiefe dieser Warteschlange ist eins. Beim Aufrufen von Send() in der Warteschlange wird somit nur ein EchoRequest gesendet.

Wenn Send() aufgerufen wird, während sich WeaveEchoClient im Modus zum Senden von Wiederholungen befindet (d.h. aufgrund eines früheren Aufrufs von SendRepeating()), beschleunigt und zurückgesetzt sich der Sendezyklus, verlässt aber WeaveEchoClient nicht aus dem Modus „Wiederholen“.

Senden

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

Eine EchoRequest-Nachricht mit einer bestimmten Nutzlast an den Peer senden.

Mit dieser Methode wird eine EchoRequest-Nachricht an den Peer-Knoten gesendet. Der Inhalt des bereitgestellten Nutzlastzwischenspeichers wird als Nutzlast der EchoRequest-Nachricht an den Peer gesendet. Wenn und wann eine entsprechende EchoResponse-Nachricht eingeht, wird sie über das ResponseReceived API-Ereignis an die Anwendung gesendet.

Beim Aufrufen dieser Methode wird die Eigentümerschaft des bereitgestellten Nutzlastpuffers an das WeaveEchoClient-Objekt übergeben, das für die Freigabe verantwortlich ist. Dies gilt unabhängig davon, ob die Methode erfolgreich abgeschlossen wurde oder ob ein Fehler aufgetreten ist.

Wenn sich das Bindungsobjekt beim Aufrufen dieser Methode nicht im Status „Bereit“ befindet, wird eine Anfrage an die Methode Bindung::RequestPrepare() gestellt, um die On-Demand-Vorbereitung zu initiieren. Der Vorgang wird dann in die Warteschlange gestellt, bis der Vorgang abgeschlossen ist. Die maximale Tiefe dieser Warteschlange ist eins. Beim Aufrufen von Send() in der Warteschlange wird somit nur ein EchoRequest gesendet.

Wenn Send() aufgerufen wird, während sich WeaveEchoClient im Modus zum Senden von Wiederholungen befindet (d.h. aufgrund eines früheren Aufrufs von SendRepeating()), beschleunigt und zurückgesetzt sich der Sendezyklus, verlässt aber WeaveEchoClient nicht aus dem Modus „Wiederholen“.

Details
Parameter
[in] payloadBuf
Ein PacketBuffer-Objekt, das Nutzlastdaten enthält, die an den Peer gesendet werden sollen. Die Eigentümerschaft dieses Zwischenspeichers wird in allen Fällen an das WeaveEchoClient-Objekt übergeben.

Wiederkehrende senden

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

Senden Sie eine wiederkehrende Sequenz von EchoRequest-Nachrichten an den Peer.

Mit dieser Methode wird ein sich wiederholender Prozess gestartet, bei dem EchoRequest-Nachrichten an den Peer gesendet werden. Wenn EchoResponse-Nachrichten vom Peer empfangen werden, werden sie über das ResponseReceived API-Ereignis an die Anwendung gesendet.

Wenn SendRepeating() aufgerufen wird, wechselt WeaveEchoClient in den Sendewiederholmodus-Modus, in dem es verbleibt, bis Stop() aufgerufen wird oder ein Bindung-Fehler auftritt. Wenn Sie SendRepeating() mehrmals aufrufen, wird der Sendezyklus zurückgesetzt und das Intervall wird aktualisiert.

Das erste Senden einer Sequenz erfolgt, wenn SendRepeating() aufgerufen wird oder wenn Bindung bereit ist, nachdem SendRepeating() aufgerufen wird (siehe unten). Nachfolgende danach erfolgen im angegebenen Intervall.

Bei jedem Senden sendet WeaveEchoClient über das PreparePayload API-Ereignis eine Anfrage an die Anwendung, um die Nutzlast der Nachricht vorzubereiten.

Wenn sich das Bindungsobjekt beim Senden einer Nachricht nicht im Status „Bereit“ befindet, wird eine Anfrage an die Methode Bindung::RequestPrepare() gestellt, um die On-Demand-Vorbereitung zu initiieren. Weitere wiederkehrende Nachrichten werden pausiert, bis dieser Vorgang abgeschlossen ist. Wenn die Bindung on-demand nicht vorbereitet wird, verlässt WeaveEchoClient den Modus „Wiederholen“.

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

Legt die API-Ereignis-Callback-Funktion für das WeaveEchoClient-Objekt fest.

Heruntergefahren

void Shutdown(
  void
)

Herunterfahren eines zuvor initialisierten WeaveEchoClient-Objekts

Diese Methode kann nur aufgerufen werden, wenn die Methode Init() zuvor aufgerufen wurde.

Beenden

void Stop(
  void
)

Beendet den Echo-Austausch und der Vorgang „Wiederholen“ wird abgebrochen.

Logo: WeaveEchoClient

 WeaveEchoClient(
  void
)

Öffentliche statische Funktionen

Standard-EventHandler

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

Standard-Handler für WeaveEchoClient-API-Ereignisse.

Die Anwendungen müssen diese Methode für alle API-Ereignisse aufrufen, die sie nicht erkennen oder verarbeiten. Die bereitgestellten Parameter müssen mit den Parametern übereinstimmen, die vom Clientobjekt an die Ereignis-Handler-Funktion übergeben werden.

Details
Parameter
[in] appState
Ein Zeiger auf anwendungsspezifische Statusinformationen, die mit dem Clientobjekt verknüpft sind.
[in] eventType
Vom Ereignis-Callback übergebene Ereignis-ID
[in] inParam
Referenz der vom Ereignis-Callback übergebenen Eingabeereignisparameter
[in] outParam
Verweis auf die Ereignisparameter, die vom Ereignis-Callback übergeben werden