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.

Zusammenfassung

Die Klasse WeaveEchoClient implementiert die Initiatorseite des Weave Echo-Protokolls. Ähnlich wie das 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 Binding-Objekt identifiziert wird. Zum Antworten auf Echo-Anfragen ist eine entsprechende Klasse vorhanden (siehe WeaveEchoServer).

Client-Bindung

Der WeaveEchoClient verwendet ein Weave-Binding-Objekt, um den vorgesehenen Empfänger der Echo-Anfragen zu identifizieren und die Kommunikation mit diesem herzustellen. Das Binding kann von der Anwendung vor der Initialisierung des WeaveEchoClient-Objekts konfiguriert und vorbereitet werden. Es kann aber auch nicht vorbereitet werden. In diesem Fall fordert WeaveEchoClient bei Bedarf die Vorbereitung der Bindung an. Weitere Informationen finden Sie unter Binding::RequestPrepare().

Bei Bedarf wird auch die Vorbereitung von Binding angefordert, falls diese nach dem Status „Bereit“ fehlschlägt.

Modus „Wiederholung senden“

Mit der Methode SendRepeating() kann der WeaveEchoClient in den SendRepeating-Modus versetzt werden. In diesem Modus sendet das Clientobjekt in einem konfigurierten Intervall eine sich wiederholende Sequenz von EchoRequest-Nachrichten an den Peer. Der SendRepeating-Modus kann durch Aufrufen der Stop()-Methode abgebrochen werden.

Multicast und Übertragung

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

In diesem Modus wartet das Objekt weiterhin auf alle eingehenden EchoResponse-Nachrichten, die auf derselben Anzeigenplattform eingehen, und stellt sie bereit. Das Objekt bleibt im MultiResponse-Modus, bis die Anwendung Stop() oder Send() aufruft, 2) im SendRepeating-Modus eine weitere Anfrage senden oder 3) keine Antwort eingeht und das Zeitlimit für den Empfang abläuft.

API-Ereignisse

Während seines Betriebs ruft das WeaveEchoClient-Objekt die Anwendung auf, um bestimmte Aktionen anzufordern oder Benachrichtigungen über wichtige Ereignisse zu senden. Diese API-Ereignisaufrufe erfolgen an die aktuell konfigurierte Callback-Funktion des Clientobjekts. Sofern nicht anders angegeben, können Anwendungen den Status des Clients während eines Ereignis-Callbacks ändern. Eine allgemeine Ausnahme ist die Methode Herunterfahren() des Objekts, die während eines Rückrufs möglicherweise nie aufgerufen wird.

Die folgenden API-Ereignisse sind definiert:

PreparePayload

Der WeaveEchoClient ist dabei, eine EchoRequest-Nachricht zu bilden, und fordert von der Anwendung die Bereitstellung einer Nutzlast an. Wenn eine Anwendung es wünscht, kann sie einen neuen PacketBuffer mit den Nutzlastdaten zurückgeben. Wenn die Anwendung dieses Ereignis nicht verarbeitet, wird automatisch ein EchoRequest mit einer Nutzlast der Länge null gesendet. Die Anwendung darf den Status des WeaveEchoClient während dieses Callbacks NICHT ändern.

RequestSent

Eine EchoRequest-Nachricht wurde an den Peer gesendet.

ResponseReceived

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

CommunicationError

Beim Erstellen oder Senden eines EchoRequest oder beim Warten auf eine Antwort ist ein Fehler aufgetreten. Beispiele für Fehler, die beim Warten auf eine Antwort auftreten können, sind wichtige Fehler oder das unerwartete Schließen einer Verbindung. Argumente für das Ereignis enthalten die Fehlerursache.

ResponseTimeout

In der vorgesehenen Zeit ist keine EchoResponse eingegangen. Das Zeitlimit für die Antwort wird durch das Attribut „DefaultResponseTimeout“ im Objekt Binding gesteuert.

RequestAborted

Ein laufender Echo-Austausch wurde abgebrochen, weil vor einer Antwort auf die vorherige Nachricht eine Anfrage zum Senden eines weiteren EchoRequest gesendet wurde. Dies kann im „SendRepeating“-Modus auftreten, wenn der Zeitpunkt zum Senden des nächsten EchoRequest liegt. Dieser Fehler kann auch auftreten, 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.

Konstruktoren und Zerstörer
WeaveEchoClient(void)

Öffentliche Typen
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
} 		enum
State{
  kState_NotInitialized = 0,
  kState_Idle = 1,
  kState_PreparingBinding = 2,
  kState_RequestInProgress = 3,
  kState_WaitingToSend = 4
} 		enum

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

Öffentliche Funktionen
GetBinding(void) const
Gibt einen Zeiger auf das Binding-Objekt zurück, das WeaveEchoClient zugeordnet ist.
GetEventCallback(void) const
EventCallback
Gibt einen Verweis auf die Callback-Funktion für API-Ereignisse zurück, die derzeit auf dem WeaveEchoClient-Objekt konfiguriert ist.
GetState(void) const
Rufen Sie den aktuellen Status des Objekts WeaveEchoClient ab.
Init(Binding *binding, EventCallback eventCallback, void *appState)
Initialisieren Sie ein WeaveEchoClient-Objekt.
IsSendRrepeating() const
bool
Gibt "true" zurück, wenn sich das WeaveEchoClient-Objekt derzeit im Modus "Sendewiederholung" befindet.
RequestInProgress() const
bool
Gibt "true" zurück, wenn ein EchoRequest gesendet wurde und das WeaveEchoClient-Objekt auf eine Antwort wartet.
Send(void)
Senden Sie eine EchoRequest-Nachricht an den Peer.
Send(PacketBuffer *payloadBuf)
Eine EchoRequest-Nachricht mit einer bestimmten Nutzlast an den Peer senden.
SendRepeating(uint32_t sendIntervalMS)
Initiieren Sie das Senden einer sich wiederholenden Sequenz von EchoRequest-Nachrichten an den Peer.
SetEventCallback(EventCallback eventCallback)
void
Legt die Callback-Funktion des API-Ereignisses für das WeaveEchoClient-Objekt fest.
Shutdown(void)
void
Fahren Sie ein zuvor initialisiertes WeaveEchoClient-Objekt herunter.
Stop(void)
void
Beendet einen laufenden Echo-Austausch und bricht den Sendewiederholungsmodus ab.

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

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

Eingabeparameter für das API-Ereignis WeaveEchoClient

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

Ausgabeparameter für das API-Ereignis WeaveEchoClient

Öffentliche Typen

EventCallback

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

EventType

 EventType
Attribute
kEvent_CommunicationError

Beim Senden eines EchoRequest oder beim Warten auf eine Antwort ist ein Kommunikationsfehler aufgetreten.

kEvent_DefaultCheck

Wird verwendet, um die korrekte Verarbeitung von Standardereignissen in der Anwendung zu überprüfen.

kEvent_PreparePayload

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

kEvent_RequestAborted

Ein laufender Echo-Austausch wurde abgebrochen, weil eine Anfrage zum Starten eines weiteren Austauschs gestellt wurde.

kEvent_RequestSent

Eine EchoRequest-Nachricht wurde an den Peer gesendet.

kEvent_ResponseReceived

Vom Peer wurde eine EchoResponse-Nachricht empfangen.

kEvent_ResponseTimeout

In der vorgesehenen Zeit ist keine EchoResponse eingegangen.

Status

 State
Attribute
kState_Idle

Das Clientobjekt ist inaktiv.

kState_NotInitialized

Das Clientobjekt wurde 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 Clientobjekt wartet auf das nächste Mal, um ein EchoRequest zu senden.

Öffentliche Attribute

AppState

void * AppState

Ein Zeiger auf anwendungsspezifische Daten.

Öffentliche Funktionen

GetBinding

Binding * GetBinding(
  void
) const

Gibt einen Zeiger auf das Binding-Objekt zurück, das WeaveEchoClient zugeordnet ist.

GetEventCallback

EventCallback GetEventCallback(
  void
) const

Gibt einen Verweis auf die Callback-Funktion für API-Ereignisse zurück, die derzeit auf dem WeaveEchoClient-Objekt konfiguriert ist.

GetState

State GetState(
  void
) const

Rufen Sie den aktuellen Status des Objekts WeaveEchoClient ab.

Init

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

Initialisieren Sie ein WeaveEchoClient-Objekt.

Initialisieren Sie ein WeaveEchoClient-Objekt zur Vorbereitung des Sendens von Echo-Nachrichten an einen Peer.

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

IsSendRrepeating

bool IsSendRrepeating() const

Gibt "true" zurück, wenn sich das WeaveEchoClient-Objekt derzeit im Modus "Sendewiederholung" befindet.

RequestInProgress

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
)

Senden Sie eine EchoRequest-Nachricht an den Peer.

Diese Methode initiiert das Senden einer EchoRequest-Nachricht an den Peer-Knoten. Wenn eine entsprechende EchoResponse-Nachricht eingeht, wird diese über das API-Ereignis ResponseReceived an die Anwendung übermittelt.

Bei der Erstellung der EchoRequest-Nachricht stellt der WeaveEchoClient über das PreparePayload API-Ereignis eine Anfrage an die Anwendung, um die Nutzlast der Nachricht vorzubereiten.

Wenn sich das Objekt Binding beim Aufruf dieser Methode nicht im Status „Bereit“ befindet, wird eine Anfrage an die Methode Binding::RequestPrepare() gesendet, um die Vorbereitung auf Anfrage zu initiieren. Der Sendevorgang wird dann in die Warteschlange gestellt, bis dieser Vorgang abgeschlossen ist. Die maximale Tiefe dieser Warteschlange beträgt eins. Daher führt jeder Aufruf von Send() zu einer vorherigen Sendung in der Warteschlange dazu, dass nur ein einziger EchoRequest gesendet wird.

Wenn Send() aufgerufen wird, während sich WeaveEchoClient im Sendewiederholungsmodus befindet (d.h. aufgrund eines vorherigen Aufrufs von SendRepeating()), wird der Sendezyklus beschleunigt und zurückgesetzt, der WeaveEchoClient wird jedoch nicht aus dem Sendewiederholungsmodus genommen.

Senden

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

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

Diese Methode initiiert das Senden einer EchoRequest-Nachricht an den Peer-Knoten. Der Inhalt des bereitgestellten Nutzlastpuffers wird als Nutzlast der EchoRequest-Nachricht an den Peer gesendet. Wenn eine entsprechende EchoResponse-Nachricht eingeht, wird diese über das API-Ereignis ResponseReceived an die Anwendung übermittelt.

Nach dem Aufruf dieser Methode übergibt das Eigentumsrecht am bereitgestellten Nutzlastpuffer an das Objekt WeaveEchoClient, das die Verantwortung für dessen Freigabe hat. Dies gilt unabhängig davon, ob die Methode erfolgreich abgeschlossen wurde oder mit einem Fehler.

Wenn sich das Objekt Binding beim Aufruf dieser Methode nicht im Status „Bereit“ befindet, wird eine Anfrage an die Methode Binding::RequestPrepare() gesendet, um die Vorbereitung auf Anfrage zu initiieren. Der Sendevorgang wird dann in die Warteschlange gestellt, bis dieser Vorgang abgeschlossen ist. Die maximale Tiefe dieser Warteschlange beträgt eins. Daher führt jeder Aufruf von Send() zu einer vorherigen Sendung in der Warteschlange dazu, dass nur ein einziger EchoRequest gesendet wird.

Wenn Send() aufgerufen wird, während sich WeaveEchoClient im Sendewiederholungsmodus befindet (d.h. aufgrund eines vorherigen Aufrufs von SendRepeating()), wird der Sendezyklus beschleunigt und zurückgesetzt, der WeaveEchoClient wird jedoch nicht aus dem Sendewiederholungsmodus genommen.

Details
Parameter
[in] payloadBuf
Ein PacketBuffer-Objekt mit Nutzlastdaten, die an den Peer gesendet werden sollen. Die Eigentumsrechte für diesen Puffer gehen in allen Fällen an das WeaveEchoClient-Objekt über.

SendRepeating

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

Initiieren Sie das Senden einer sich wiederholenden Sequenz von EchoRequest-Nachrichten an den Peer.

Diese Methode initiiert einen sich wiederholenden Prozess zum Senden von EchoRequest-Nachrichten an den Peer. Wenn EchoResponse-Nachrichten vom Peer empfangen werden, werden sie über das API-Ereignis ResponseReceived an die Anwendung gesendet.

Wenn SendRepeating() aufgerufen wird, wechselt der WeaveEchoClient in den Sendewiederholungsmodus, in dem er so lange bleibt, bis Stop() aufgerufen wird oder ein Binding-Fehler auftritt. Durch mehrfaches Aufrufen von SendRepeating() wird der Sendezyklus zurückgesetzt und das Intervall aktualisiert.

Der erste Sende einer Sequenz erfolgt beim Aufruf von SendRepeating() oder wenn Binding nach dem Aufruf von SendRepeating() bereit wird (siehe unten). Die nachfolgenden Sendevorgänge erfolgen im festgelegten Intervall.

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

Wenn das Objekt Binding beim Senden einer Nachricht nicht den Status „Bereit“ hat, wird eine Anfrage an die Methode Binding::RequestPrepare() gesendet, um die Vorbereitung auf Anfrage zu starten. Weitere wiederholte Nachrichten werden pausiert, bis dieser Vorgang abgeschlossen ist. Ein Fehler bei der Vorbereitung der On-Demand-Bindung führt dazu, dass WeaveEchoClient den Sendewiederholungsmodus beendet.

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

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

Herunterfahren

void Shutdown(
  void
)

Fahren Sie ein zuvor initialisiertes WeaveEchoClient-Objekt herunter.

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

Beenden

void Stop(
  void
)

Beendet einen laufenden Echo-Austausch und bricht den Sendewiederholungsmodus ab.

WeaveEchoClient

 WeaveEchoClient(
  void
)

Öffentliche statische Funktionen

DefaultEventHandler

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

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

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

Details
Parameter
[in] appState
Ein Zeiger auf anwendungsdefinierte Statusinformationen, die dem Clientobjekt zugeordnet sind.
[in] eventType
Vom Ereignis-Callback übergebene Ereignis-ID
[in] inParam
Referenz der Eingabeereignisparameter, die vom Ereignis-Callback übergeben werden
[in] outParam
Referenz der Ausgabeereignisparameter, die vom Ereignis-Callback übergeben werden