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.

Podsumowanie

Klasa WeaveEchoClient implementuje stronę inicjatora protokołu Weave Echo. Podobnie jak protokół ping ICMP, protokół Weave Echo może być używany do testowania żywotności i osiągalności węzła Weave.

Aplikacje mogą używać klasy WeaveEchoClient do wysyłania jednorazowych lub powtarzających się komunikatów EchoRequest do węzła równorzędnego określonego przez obiekt Binding. Odpowiednia klasa odpowiada na żądania echo (patrz WeaveEchoServer).

Powiązanie z klientem

WeaveEchoClient korzysta z obiektu Weave Binding, który służy do identyfikowania i nawiązywania komunikacji z docelowym odbiorcą żądań echa. Obiekt Binding może zostać skonfigurowany i przygotowany przez aplikację przed zainicjowaniem obiektu WeaveEchoClient. Można go też pozostawić nieprzygotowany, w którym to przypadku WeaveEchoClient poprosi o przygotowanie powiązania na żądanie (szczegóły znajdziesz w sekcji Binding::RequestPrepare()).

W przypadku niepowodzenia po przejściu w stan gotowości wymagane będzie przygotowanie Wiązania na żądanie.

Tryb powtarzania wysyłania

Za pomocą metody SendRepeating() można zastosować metodę WeaveEchoClient w trybie SendRepeating. W tym trybie obiekt klienta wysyła do peera powtarzającą się sekwencję komunikatów EchoRequest w skonfigurowanym przedziale czasu. Tryb SendRepeating można anulować, używając metody Stop().

Multicast i transmisja

Obiekt WeaveEchoClient może być używany do jednoczesnego wysyłania żądań EchoRequest do wielu odbiorców. W tym celu konfiguruj obiekt Binding z odpowiednim adresem multiemisji IPv6 lub adresem rozgłoszeniowym IPv4 (255.255.255.255). Gdy obiekt WeaveEchoClient wykryje multiemisję lub adres peera, automatycznie przechodzi w tryb wielu odpowiedzi po wysłaniu żądania EchoRequest.

W tym trybie obiekt nadal nasłuchuje i dostarcza wszystkie przychodzące wiadomości EchoResponse, które docierają do tej samej wymiany. Obiekt pozostaje w trybie wielu odpowiedzi, dopóki: (1) aplikacja nie wywoła funkcji Stop() lub Send(), 2) w trybie SendRepeating, gdy nadejdzie czas wysłania kolejnego żądania, lub 3) nie zostanie odebrana odpowiedź i upłyną limit czasu odbierania.

Zdarzenia interfejsu API

W trakcie działania obiekt WeaveEchoClient wywołuje aplikację, aby zażądać określonych działań lub dostarczyć powiadomienia o ważnych zdarzeniach. Te wywołania zdarzeń interfejsu API są wysyłane do obecnie skonfigurowanej funkcji wywołania zwrotnego w obiekcie klienta. Aplikacje mogą zmieniać stan klienta podczas wywołania zwrotnego zdarzenia, chyba że wskazano inaczej. Ogólnym wyjątkiem jest metoda Disabledown() obiektu, której nie można nigdy wywołać podczas wywołania zwrotnego.

Zdefiniowano te zdarzenia interfejsu API:

PreparePayload

WeaveEchoClient utworzy komunikat EchoRequest i żąda aplikacji dostarczenia ładunku. W razie potrzeby aplikacja może zwrócić nowy bufor PacketBuffer z danymi ładunku. Jeśli aplikacja nie obsługuje tego zdarzenia, automatycznie zostanie wysłane żądanie EchoRequest z ładunkiem o zerowej długości. Aplikacja NIE MOŻE zmienić stanu WeaveEchoClient podczas tego wywołania zwrotnego.

RequestSent

Wiadomość EchoRequest została wysłana do peera.

ResponseReceived

Odebrano wiadomość echo odpowiedzi od połączenia równorzędnego. Argumenty zdarzenia zawierają ładunek odpowiedzi i metadane dotyczące wiadomości w odpowiedzi.

CommunicationError

Podczas tworzenia lub wysyłania żądania EchoRequest albo podczas oczekiwania na odpowiedź wystąpił błąd. Przykładami błędów, które mogą wystąpić podczas oczekiwania na odpowiedź, są kluczowe błędy lub nieoczekiwane zamknięcie połączenia. Argumenty zdarzenia zawierają przyczynę błędu.

ResponseTimeout

Nie otrzymano odpowiedzi echo w przydzielonym czasie. Czas oczekiwania na odpowiedź jest określany przez właściwość DefaultResponseTimeout w obiekcie Binding.

RequestAborted

Działająca wymiana Echo została przerwana, ponieważ zanim otrzymano odpowiedź na poprzednią wiadomość, wysłano żądanie o wysłanie innego żądania EchoRequest. Może się to zdarzyć w trybie SendRepeating, gdy nadejdzie czas wysłania następnego żądania EchoRequest. Ten problem może też wystąpić, jeśli aplikacja wywoła funkcję Send() po wysłaniu żądania EchoRequest, ale przed otrzymaniem odpowiedzi.

Gdy obiekt jest w trybie wielu odpowiedzi, zdarzenie jest pomijane, jeśli otrzymano co najmniej 1 komunikat EchoResponse.

Konstruktory i niszczyciele
WeaveEchoClient(void)

Typy publiczne
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 | typ wyliczeniowy
State{
  kState_NotInitialized = 0,
  kState_Idle = 1,
  kState_PreparingBinding = 2,
  kState_RequestInProgress = 3,
  kState_WaitingToSend = 4
} 		enum | typ wyliczeniowy

Atrybuty publiczne
AppState
void *
wskaźnik do danych związanych z aplikacją,

Funkcje publiczne
GetBinding(void) const
Zwraca wskaźnik do obiektu Binding powiązanego z identyfikatorem WeaveEchoClient.
GetEventCallback(void) const
EventCallback
Zwraca wskaźnik do funkcji wywołania zwrotnego zdarzenia interfejsu API, która jest obecnie skonfigurowana w obiekcie WeaveEchoClient.
GetState(void) const
Pobierz bieżący stan obiektu WeaveEchoClient.
Init(Binding *binding, EventCallback eventCallback, void *appState)
Zainicjuj obiekt WeaveEchoClient.
IsSendRrepeating() const
bool
Zwraca wartość „prawda”, jeśli obiekt WeaveEchoClient jest obecnie w trybie powtarzania wysyłania.
RequestInProgress() const
bool
Zwraca wartość „prawda”, jeśli żądanie EchoRequest zostało wysłane, a obiekt WeaveEchoClient oczekuje na odpowiedź.
Send(void)
Wyślij wiadomość EchoRequest do peera.
Send(PacketBuffer *payloadBuf)
Wyślij do peera wiadomość EchoRequest z określonym ładunkiem.
SendRepeating(uint32_t sendIntervalMS)
Zainicjuj wysyłanie do peera cyklicznej sekwencji wiadomości EchoRequest.
SetEventCallback(EventCallback eventCallback)
void
Ustawia funkcję wywołania zwrotnego zdarzenia interfejsu API w obiekcie WeaveEchoClient.
Shutdown(void)
void
Wyłącz wcześniej zainicjowany obiekt WeaveEchoClient.
Stop(void)
void
Zatrzymuje trwającą wymianę echa i anuluje tryb powtarzania wysyłania.

Publiczne funkcje statyczne
DefaultEventHandler(void *appState, EventType eventType, const InEventParam & inParam, OutEventParam & outParam)
void
Domyślny moduł obsługi zdarzeń interfejsu API WeaveEchoClient.

Struktura
nl::Weave::Profiles::Echo_Next::WeaveEchoClient::InEventParam

Parametry wejściowe zdarzenia interfejsu API WeaveEchoClient.

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

Parametry wyjściowe do zdarzenia interfejsu API WeaveEchoClient.

Typy publiczne

EventCallback

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

EventType

 EventType
Właściwości
kEvent_CommunicationError

Podczas wysyłania żądania EchoRequest lub oczekiwania na odpowiedź wystąpił błąd komunikacji.

kEvent_DefaultCheck

Służy do weryfikacji prawidłowej domyślnej obsługi zdarzeń w aplikacji.

kEvent_PreparePayload

Aplikacja ma przygotować ładunek na żądanie echo.

kEvent_RequestAborted

Działająca wymiana Echo została przerwana, ponieważ wysłano żądanie o rozpoczęcie kolejnej.

kEvent_RequestSent

Wiadomość EchoRequest została wysłana do peera.

kEvent_ResponseReceived

Odebrano wiadomość echo odpowiedzi od połączenia równorzędnego.

kEvent_ResponseTimeout

Nie otrzymano odpowiedzi echo w przydzielonym czasie.

Stan

 State
Właściwości
kState_Idle

Obiekt klienta jest nieaktywny.

kState_NotInitialized

Obiekt klienta nie został zainicjowany.

kState_PreparingBinding

Obiekt klienta czeka na przygotowanie powiązania.

kState_RequestInProgress

Wysłano komunikat EchoRequest, a obiekt klienta czeka na odpowiedź.

kState_WaitingToSend

Wywołano funkcję SendRepeating(), a obiekt klienta czeka na kolejny raz na wysłanie echoRequest.

Atrybuty publiczne

AppState

void * AppState

wskaźnik do danych związanych z aplikacją,

Funkcje publiczne

GetBinding

Binding * GetBinding(
  void
) const

Zwraca wskaźnik do obiektu Binding powiązanego z identyfikatorem WeaveEchoClient.

GetEventCallback

EventCallback GetEventCallback(
  void
) const

Zwraca wskaźnik do funkcji wywołania zwrotnego zdarzenia interfejsu API, która jest obecnie skonfigurowana w obiekcie WeaveEchoClient.

GetState

State GetState(
  void
) const

Pobierz bieżący stan obiektu WeaveEchoClient.

Init

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

Zainicjuj obiekt WeaveEchoClient.

Zainicjuj obiekt WeaveEchoClient w ramach przygotowań do wysłania wiadomości echo do peera.

Szczegóły
Parametry
[in] binding
Obiekt Binding, który będzie używany do nawiązywania komunikacji z węzłem równorzędnym.
[in] eventCallback
Wskaźnik do funkcji, która będzie wywoływana przez obiekt WeaveEchoClient w celu dostarczenia zdarzeń interfejsu API do aplikacji.
[in] appState
Wskaźnik do obiektu zdefiniowanego przez aplikację, który będzie przekazywany z powrotem do aplikacji za każdym razem, gdy wystąpi zdarzenie interfejsu API.

IsSendRrepeating

bool IsSendRrepeating() const

Zwraca wartość „prawda”, jeśli obiekt WeaveEchoClient jest obecnie w trybie powtarzania wysyłania.

RequestInProgress

bool RequestInProgress() const

Zwraca wartość „prawda”, jeśli żądanie EchoRequest zostało wysłane, a obiekt WeaveEchoClient oczekuje na odpowiedź.

Wyślij

WEAVE_ERROR Send(
  void
)

Wyślij wiadomość EchoRequest do peera.

Ta metoda inicjuje proces wysyłania komunikatu EchoRequest do węzła równorzędnego. Po otrzymaniu odpowiedniego komunikatu EchoResponse zostanie on dostarczony do aplikacji przez zdarzenie ResponseReceived API.

Podczas tworzenia komunikatu EchoRequest WeaveEchoClient wysyła do aplikacji żądanie za pomocą zdarzenia PreparePayload API, aby przygotować ładunek wiadomości.

Jeśli obiekt Binding nie jest w stanie gotowości, gdy ta metoda jest wywoływana, do metody Binding::RequestPrepare() zostanie wysłane żądanie rozpoczęcia przygotowywania na żądanie. Operacja wysyłania trafi do kolejki do momentu jej zakończenia. Maksymalna głębokość tej kolejki to 1. Dlatego każde wywołanie Send() w czasie, gdy w kolejce istnieje wcześniejsze wysyłanie, spowoduje wysłanie tylko jednego żądania EchoRequest.

Wywołanie Send(), gdy WeaveEchoClient jest w trybie powtarzania wysyłania (np. ze względu na poprzednie wywołanie funkcji SendRepeating()), ma skutek przyspieszenia i zresetowania cyklu wysyłania, ale nie wyłącza trybu powtarzania wysyłania przez WeaveEchoClient.

Wyślij

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

Wyślij do peera wiadomość EchoRequest z określonym ładunkiem.

Ta metoda inicjuje proces wysyłania komunikatu EchoRequest do węzła równorzędnego. Zawartość dostarczonego bufora ładunku zostanie wysłana do połączenia równorzędnego jako ładunek komunikatu EchoRequest. Po otrzymaniu odpowiedniego komunikatu EchoResponse zostanie on dostarczony do aplikacji przez zdarzenie ResponseReceived API.

Po wywołaniu tej metody własność dostarczonego bufora ładunku jest przekazywana do obiektu WeaveEchoClient, który jest odpowiedzialny za jego zwolnienie. Dzieje się tak niezależnie od tego, czy metoda zakończy się pomyślnie, czy z błędem.

Jeśli obiekt Binding nie jest w stanie gotowości, gdy ta metoda jest wywoływana, do metody Binding::RequestPrepare() zostanie wysłane żądanie rozpoczęcia przygotowywania na żądanie. Operacja wysyłania trafi do kolejki do momentu jej zakończenia. Maksymalna głębokość tej kolejki to 1. Dlatego każde wywołanie Send() w czasie, gdy w kolejce istnieje wcześniejsze wysyłanie, spowoduje wysłanie tylko jednego żądania EchoRequest.

Wywołanie Send(), gdy WeaveEchoClient jest w trybie powtarzania wysyłania (np. ze względu na poprzednie wywołanie funkcji SendRepeating()), ma skutek przyspieszenia i zresetowania cyklu wysyłania, ale nie wyłącza trybu powtarzania wysyłania przez WeaveEchoClient.

Szczegóły
Parametry
[in] payloadBuf
Obiekt PacketBuffer zawierający dane ładunku, które należy wysłać do peera. We wszystkich przypadkach własność tego bufora jest przekazywana do obiektu WeaveEchoClient.

SendRepeating

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

Zainicjuj wysyłanie do peera cyklicznej sekwencji wiadomości EchoRequest.

Ta metoda inicjuje powtarzający się proces wysyłania wiadomości EchoRequest do peera. Komunikaty EchoResponse są odbierane od peera, a są one dostarczane do aplikacji przez zdarzenie ResponseReceived API.

Po wywołaniu funkcji SendRepeating() element WeaveEchoClient przechodzi w tryb powtarzania wysyłania, w którym pozostaje do czasu wywołania funkcji Stop() lub wystąpienia błędu Wiązania. Wielokrotne wywołanie funkcji SendRepeating() spowoduje zresetowanie cyklu wysyłania i zmianę interwału.

Początkowe wysłanie sekwencji następuje w momencie wywołania funkcji SendRepeating() lub za każdym razem, gdy element Binding będzie gotowy po wywołaniu funkcji SendRepeating() (patrz poniżej). Kolejne operacje wysyłania będą następować po upływie określonego czasu.

Za każdym razem, gdy następuje wysłanie, WeaveEchoClient wysyła żądanie do aplikacji za pomocą zdarzenia PreparePayload API, aby przygotować ładunek wiadomości.

Jeśli obiekt Binding nie jest w stanie gotowości podczas wysyłania wiadomości, do metody Binding::RequestPrepare() zostanie wysłane żądanie rozpoczęcia przygotowywania na żądanie. Do czasu zakończenia tego procesu kolejne wysyłanie wiadomości będzie wstrzymane. Błąd podczas przygotowywania wiązania na żądanie spowoduje, że WeaveEchoClient opuści tryb powtarzania wysyłania.

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

Ustawia funkcję wywołania zwrotnego zdarzenia interfejsu API w obiekcie WeaveEchoClient.

Wyłączono

void Shutdown(
  void
)

Wyłącz wcześniej zainicjowany obiekt WeaveEchoClient.

Pamiętaj, że tę metodę można wywołać tylko wtedy, gdy metoda Init() została wywołana wcześniej.

Zatrzymaj

void Stop(
  void
)

Zatrzymuje trwającą wymianę echa i anuluje tryb powtarzania wysyłania.

WeaveEchoClient

 WeaveEchoClient(
  void
)

Publiczne funkcje statyczne

DefaultEventHandler

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

Domyślny moduł obsługi zdarzeń interfejsu API WeaveEchoClient.

Aplikacje muszą wywoływać tę metodę w przypadku wszystkich zdarzeń interfejsu API, których nie rozpoznają ani nie obsługują. Podane parametry muszą być takie same jak te przekazywane przez obiekt kliencki do funkcji obsługi zdarzeń aplikacji.

Szczegóły
Parametry
[in] appState
Wskaźnik do informacji o stanie określonych przez aplikację powiązanych z obiektem klienta.
[in] eventType
Identyfikator zdarzenia przekazany przez wywołanie zwrotne zdarzenia
[in] inParam
Odniesienie do parametrów wejściowych zdarzeń przekazywanych przez wywołanie zwrotne zdarzenia
[in] outParam
Odniesienie do parametrów zdarzenia wyjściowego przekazywanych przez wywołanie zwrotne zdarzenia