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 beim ICMP-Ping-Protokoll kann mit dem Weave Echo-Protokoll die Aktivität und Erreichbarkeit eines Weave-Knotens getestet werden.

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. Für die Beantwortung von Echo-Anfragen ist eine entsprechende Klasse vorhanden (siehe WeaveEchoServer).

Client-Bindung

Der WeaveEchoClient verwendet ein Weave Binding-Objekt, mit dem die Kommunikation mit dem beabsichtigten Empfänger der Echo-Anfragen hergestellt wird. Die Binding kann von der Anwendung vor der Initialisierung des WeaveEchoClient-Objekts konfiguriert und vorbereitet werden. Sie kann aber auch nicht vorbereitet werden. In diesem Fall fordert der WeaveEchoClient eine On-Demand-Vorbereitung der Bindung an. Weitere Informationen finden Sie unter Binding::RequestPrepare().

Die On-Demand-Vorbereitung der Binding wird auch angefordert, wenn sie nach dem Wechsel in den Status „Bereit“ fehlschlägt.

Modus „SendRepeating“ (SendenWiederholungsmodus)

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

Multicast und Broadcast

Mit einem WeaveEchoClient-Objekt können EchoRequests gleichzeitig an mehrere Empfänger gesendet werden. Dazu wird das Binding-Objekt mit einer geeigneten IPv6-Multicast-Adresse oder einer lokalen IPv4-Netzwerkadresse (255.255.255.255) konfiguriert. Wenn das Objekt WeaveEchoClient eine Multicast- oder Broadcast-Peer-Adresse erkennt, wechselt es beim Senden der EchoRequest automatisch in den MultiResponse-Modus.

In diesem Modus überwacht das Objekt weiterhin alle eingehenden EchoResponse-Nachrichten, die auf demselben Exchange eingehen, und stellt diese zu. Das Objekt bleibt im MultiResponse-Modus, bis: 1) die Anwendung Stop() oder Send() aufruft, 2) im SendRepeating-Modus arbeitet, die Zeit zum Senden einer weiteren Anfrage gekommen ist oder 3) keine Antwort eingeht und das Zeitlimit für den Empfang abläuft.

API-Ereignisse

Während des Betriebs ruft das Objekt WeaveEchoClient die Anwendung auf, um bestimmte Aktionen anzufordern oder Benachrichtigungen über wichtige Ereignisse zu senden. Diese API-Ereignisaufrufe erfolgen an die aktuell konfigurierte Callback-Funktion auf dem Clientobjekt. Sofern nicht anders angegeben, können Anwendungen den Status des Clients während eines Ereignisrückrufs ändern. Eine allgemeine Ausnahme ist die Methode Shutdown() des Objekts, die während eines Rückrufs niemals aufgerufen werden kann.

Die folgenden API-Ereignisse sind definiert:

PreparePayload

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

RequestSent

Eine EchoRequest-Nachricht wurde an den Peer gesendet.

ResponseReceived

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

CommunicationError

Beim Erstellen oder Senden einer 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

Es ist keine EchoResponse in der vorgesehenen Zeit eingegangen. Das Antwortzeitlimit wird über die Property „DefaultResponseTimeout“ im Objekt Binding gesteuert.

RequestAborted

Ein laufender Echo-Austausch wurde abgebrochen, weil eine Anfrage zum Senden eines weiteren EchoRequest gesendet wurde, bevor eine Antwort auf die vorherige Nachricht eingegangen ist. Dies kann im SendRepeating-Modus auftreten, wenn die Zeit für das Senden des nächsten EchoRequest gekommen ist. 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 mit WeaveEchoClient verknüpft ist.
GetEventCallback(void) const
EventCallback
Gibt einen Zeiger auf die API-Ereignis-Callback-Funktion zurück, die aktuell 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)
Initialisieren Sie ein WeaveEchoClient-Objekt.
IsSendRrepeating() const
bool
Gibt "true" zurück, wenn sich das Objekt WeaveEchoClient derzeit im Modus zum Wiederholen von Nachrichten befindet.
RequestInProgress() const
bool
Gibt "true" zurück, wenn ein EchoRequest gesendet wurde und das Objekt WeaveEchoClient 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 API-Ereignis-Callback-Funktion für das WeaveEchoClient-Objekt fest.
Shutdown(void)
void
Fahren Sie ein zuvor initialisiertes WeaveEchoClient-Objekt herunter.
Stop(void)
void
Beendet jeglichen Echo-Austausch und bricht den Modus für wiederholte Senden 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 einer 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 prüfen.

kEvent_PreparePayload

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

kEvent_RequestAborted

Ein laufender Echo-Austausch wurde abgebrochen, da eine Anfrage zum Starten eines neuen Austauschs gesendet wurde.

kEvent_RequestSent

Eine EchoRequest-Nachricht wurde an den Peer gesendet.

kEvent_ResponseReceived

Der Peer hat eine EchoResponse-Nachricht empfangen.

kEvent_ResponseTimeout

Es ist keine EchoResponse in der vorgesehenen Zeit eingegangen.

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 wird.

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 einen 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 mit WeaveEchoClient verknüpft ist.

GetEventCallback

EventCallback GetEventCallback(
  void
) const

Gibt einen Zeiger auf die API-Ereignis-Callback-Funktion zurück, die aktuell 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
)

Initialisieren Sie ein WeaveEchoClient-Objekt.

Initialisieren Sie ein WeaveEchoClient-Objekt, um das Senden von Echo-Nachrichten an einen Peer vorzubereiten.

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

IsSendRrepeating

bool IsSendRrepeating() const

Gibt "true" zurück, wenn sich das Objekt WeaveEchoClient derzeit im Modus zum Wiederholen von Nachrichten befindet.

RequestInProgress

bool RequestInProgress() const

Gibt "true" zurück, wenn ein EchoRequest gesendet wurde und das Objekt WeaveEchoClient 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 und wenn eine entsprechende EchoResponse-Nachricht empfangen wird, wird diese über das ResponseReceived API-Ereignis an die Anwendung gesendet.

Beim Erstellen der EchoRequest-Nachricht sendet der WeaveEchoClient über das PreparePayload API-Ereignis eine Anfrage an die Anwendung, um die Nutzlast der Nachricht vorzubereiten.

Befindet sich das Objekt Binding beim Aufruf dieser Methode nicht im Status „Bereit“, wird eine Anfrage an die Methode Binding::RequestPrepare() gesendet, um die On-Demand-Vorbereitung zu starten. Der Sendevorgang wird dann in die Warteschlange gestellt, bis dieser Prozess abgeschlossen ist. Die maximale Tiefe dieser Warteschlange beträgt eins. Somit führt jeder Aufruf von Send() während eines vorherigen Sendevorgangs in der Warteschlange dazu, dass nur ein einziger EchoRequest gesendet wird.

Durch das Aufrufen von Send(), während sich der WeaveEchoClient im Sendewiederholungsmodus befindet (z.B. aufgrund eines vorherigen Aufrufs von SendRepeating()), wird der Sendezyklus beschleunigt und zurückgesetzt, der WeaveEchoClient jedoch nicht deaktiviert.

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 Nutzlastzwischenspeichers wird als Nutzlast der EchoRequest-Nachricht an den Peer gesendet. Wenn und wenn eine entsprechende EchoResponse-Nachricht empfangen wird, wird diese über das ResponseReceived API-Ereignis an die Anwendung gesendet.

Nach dem Aufrufen dieser Methode wird das Eigentum an dem bereitgestellten Nutzlastzwischenspeicher an das Objekt WeaveEchoClient übergeben, das für seine Freigabe verantwortlich ist. Dies gilt unabhängig davon, ob die Methode erfolgreich abgeschlossen wird oder ein Fehler aufgetreten ist.

Befindet sich das Objekt Binding beim Aufruf dieser Methode nicht im Status „Bereit“, wird eine Anfrage an die Methode Binding::RequestPrepare() gesendet, um die On-Demand-Vorbereitung zu starten. Der Sendevorgang wird dann in die Warteschlange gestellt, bis dieser Vorgang abgeschlossen ist. Die maximale Tiefe dieser Warteschlange beträgt eins. Somit führt jeder Aufruf von Send() während eines vorherigen Sendevorgangs in der Warteschlange dazu, dass nur ein einziger EchoRequest gesendet wird.

Durch das Aufrufen von Send(), während sich der WeaveEchoClient im Sendewiederholungsmodus befindet (z.B. aufgrund eines vorherigen Aufrufs von SendRepeating()), wird der Sendezyklus beschleunigt und zurückgesetzt, der WeaveEchoClient wird jedoch nicht deaktiviert.

Details
Parameter
[in] payloadBuf
Ein PacketBuffer-Objekt mit Nutzlastdaten, die an den Peer gesendet werden sollen. Die Inhaberschaft an diesem Zwischenspeicher geht in allen Fällen auf das Objekt WeaveEchoClient ü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 das wiederholte Senden von EchoRequest-Nachrichten an den Peer. Wenn EchoResponse-Nachrichten vom Peer empfangen werden, werden sie der Anwendung über das ResponseReceived API-Ereignis zugestellt.

Beim Aufruf von SendRepeating() wechselt der WeaveEchoClient in einen Sendewiederholungsmodus. Dieser bleibt so lange bestehen, bis Stop() aufgerufen wird oder ein Binding-Fehler auftritt. Wenn Sie SendRepeating() mehrmals aufrufen, wird der Sendezyklus zurückgesetzt und das Intervall aktualisiert.

Das erste Senden einer Sequenz erfolgt, wenn SendRepeating() aufgerufen wird oder wann immer die Binding bereit wird, nachdem SendRepeating() aufgerufen wurde (siehe unten). Die nachfolgenden Sendevorgänge finden im angegebenen Intervall statt.

Jedes Mal, wenn eine Nachricht gesendet wird, stellt der WeaveEchoClient über das PreparePayload API-Ereignis eine Anfrage an die Anwendung, um die Nutzlast der Nachricht vorzubereiten.

Wenn das Objekt Binding zum Senden einer Nachricht nicht im Status „Bereit“ ist, wird eine Anfrage an die Methode Binding::RequestPrepare() gesendet, um die On-Demand-Vorbereitung zu starten. Weitere wiederholte Nachrichtenübermittlungen werden pausiert, bis dieser Vorgang abgeschlossen ist. Ein Fehler bei der Vorbereitung des On-Demand-Binding führt dazu, dass der WeaveEchoClient den Modus „Senden und Wiederholen“ verlässt.

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

Legt die API-Ereignis-Callback-Funktion 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 die Init()-Methode zuvor aufgerufen wurde.

Beenden

void Stop(
  void
)

Beendet jeglichen Echo-Austausch und bricht den Modus für wiederholte Senden 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 angegebenen Parameter müssen denen entsprechen, die vom Clientobjekt an die Ereignis-Handler-Funktion der Anwendung übergeben werden.

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