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.

Riepilogo

La classe WeaveEchoClient implementa il lato iniziatore del protocollo Weave Echo. Analogamente al protocollo ping ICMP, il protocollo Weave Echo può essere utilizzato per testare l'attività e la raggiungibilità di un nodo Weave.

Le applicazioni possono utilizzare la classe WeaveEchoClient per inviare messaggi EchoRequest una tantum o ripetuti a un nodo peer identificato da un oggetto Binding. Esiste una classe corrispondente per rispondere a richieste echo (vedi WeaveEchoServer).

Associazione client

WeaveEchoClient accetta un oggetto Weave Binding utilizzato per identificare e stabilire la comunicazione con il destinatario previsto delle richieste echo. Il Binding può essere configurato e preparato dall'applicazione prima dell'inizializzazione dell'oggetto WeaveEchoClient oppure può essere lasciato non preparato. In questo caso WeaveEchoClient richiederà la preparazione on demand dell'associazione (vedi Binding::RequestPrepare() per maggiori dettagli).

In caso di esito negativo dopo l'entrata nello stato Pronto, verrà richiesta anche la preparazione on demand dell'associazione.

Modalità di invio ripetizione

Il metodo SendRepeating() può essere usato per impostare WeaveEchoClient in modalità SendRipetiing. In questa modalità, l'oggetto client invia una sequenza ripetuta di messaggi EchoRequest al peer a un intervallo configurato. La modalità SendRipetizione può essere annullata chiamando il metodo Stop().

Multicast e broadcast

È possibile utilizzare un oggetto WeaveEchoClient per inviare richieste EchoRequest a più destinatari contemporaneamente configurando l'oggetto Binding con un indirizzo multicast IPv6 o un indirizzo di trasmissione di rete locale IPv4 appropriato (255.255.255.255). Quando l'oggetto WeaveEchoClient rileva un indirizzo peer multicast o broadcast, entra automaticamente in modalità MultiResponse al momento dell'invio dell'EchoRequest.

In questa modalità, l'oggetto continua a ascoltare e recapitare tutti i messaggi EchoResponse in arrivo che arrivano nello stesso scambio. L'oggetto rimane in modalità MultiResponse finché: 1) l'applicazione non chiama Stop() o Send(), 2) in modalità SendRipetiing, arriva il momento di inviare un'altra richiesta o 3) non viene ricevuta alcuna risposta e scade il timeout di ricezione.

Eventi API

Nel corso dell'operazione, l'oggetto WeaveEchoClient chiamerà l'applicazione per richiedere azioni specifiche o inviare notifiche di eventi importanti. Queste chiamate di eventi API vengono effettuate alla funzione di callback attualmente configurata nell'oggetto client. Salvo dove indicato, le applicazioni sono libere di modificare lo stato del client durante un callback di evento. Un'eccezione generale è il metodo Shutdown() dell'oggetto, che potrebbe non essere mai chiamato durante un callback.

Sono definiti i seguenti eventi API:

PreparePayload

WeaveEchoClient sta per generare un messaggio EchoRequest e chiede all'applicazione di fornire un payload. Se un'applicazione lo desidera, potrebbe restituire un nuovo PacketBuffer contenente i dati del payload. Se l'applicazione non gestisce questo evento, verrà inviata automaticamente una richiesta EchoRequest con un payload di lunghezza zero. Durante questo callback, l'applicazione NON POTREBBE modificare lo stato di WeaveEchoClient.

RequestSent

È stato inviato un messaggio EchoRequest al peer.

ResponseReceived

Il peer ha ricevuto un messaggio EchoResponse. Gli argomenti dell'evento contengono il payload della risposta e le meta-informazioni sul messaggio di risposta.

CommunicationError

Si è verificato un errore durante la compilazione o l'invio di una richiesta EchoRequest o l'attesa di una risposta. Esempi di errori che possono verificarsi durante l'attesa di una risposta sono gli errori chiave o la chiusura imprevista di una connessione. Gli argomenti dell'evento contengono il motivo dell'errore.

ResponseTimeout

Non è stata ricevuta un'echoResponse nel tempo assegnato. Il timeout della risposta è controllato dalla proprietà DefaultResponseTimeout nell'oggetto Binding.

RequestAborted

Uno scambio Echo in corso è stato interrotto perché è stata fatta una richiesta di inviare un'altra EchoRequest prima di ricevere una risposta al messaggio precedente. Questo può verificarsi in modalità SendRipetizione quando arriva il momento di inviare la successiva EchoRequest. Questo può succedere anche se l'applicazione chiama Send() dopo l'invio di una EchoRequest, ma prima della ricezione di qualsiasi risposta.

Quando l'oggetto è in modalità di risposta multipla, l'evento viene eliminato se è stato ricevuto almeno un messaggio EchoResponse.

Costruttori e distruttori
WeaveEchoClient(void)

Tipi pubblici
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

Attributi pubblici
AppState
void *
Un puntatore ai dati specifici dell'applicazione.

Funzioni pubbliche
GetBinding(void) const
Restituisce un puntatore all'oggetto Binding associato a WeaveEchoClient.
GetEventCallback(void) const
EventCallback
Restituisce un puntatore alla funzione di callback dell'evento API attualmente configurata nell'oggetto WeaveEchoClient.
GetState(void) const
Recupera lo stato attuale dell'oggetto WeaveEchoClient.
Init(Binding *binding, EventCallback eventCallback, void *appState)
Inizializza un oggetto WeaveEchoClient.
IsSendRrepeating() const
bool
Restituisce true se l'oggetto WeaveEchoClient è attualmente in modalità di ripetizione di invio.
RequestInProgress() const
bool
Restituisce true se è stata inviata una EchoRequest e l'oggetto WeaveEchoClient è in attesa di risposta.
Send(void)
Invia un messaggio EchoRequest al peer.
Send(PacketBuffer *payloadBuf)
Invia un messaggio EchoRequest al peer con un payload specifico.
SendRepeating(uint32_t sendIntervalMS)
Avvia l'invio di una sequenza ripetuta di messaggi EchoRequest al peer.
SetEventCallback(EventCallback eventCallback)
void
Imposta la funzione di callback dell'evento API sull'oggetto WeaveEchoClient.
Shutdown(void)
void
Arresta un oggetto WeaveEchoClient inizializzato in precedenza.
Stop(void)
void
Interrompe qualsiasi scambio di eco in corso e annulla la modalità di ripetizione dell'invio.

Funzioni statiche pubbliche
DefaultEventHandler(void *appState, EventType eventType, const InEventParam & inParam, OutEventParam & outParam)
void
Gestore predefinito per gli eventi dell'API WeaveEchoClient.

Structs
nl::Weave::Profiles::Echo_Next::WeaveEchoClient::InEventParam

Parametri di input per l'evento API WeaveEchoClient.

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

Parametri di output per l'evento API WeaveEchoClient.

Tipi pubblici

EventCallback

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

EventType

 EventType
Proprietà
kEvent_CommunicationError

Si è verificato un errore di comunicazione durante l'invio di una richiesta EchoRequest o l'attesa di una risposta.

kEvent_DefaultCheck

Utilizzato per verificare la corretta gestione degli eventi predefiniti nell'applicazione.

kEvent_PreparePayload

L'applicazione deve preparare il payload per la richiesta Echo.

kEvent_RequestAborted

Uno scambio echo in corso è stato interrotto perché è stata fatta una richiesta di avvio di un'altra piattaforma.

kEvent_RequestSent

È stato inviato un messaggio EchoRequest al peer.

kEvent_ResponseReceived

Il peer ha ricevuto un messaggio EchoResponse.

kEvent_ResponseTimeout

Non è stata ricevuta un'echoResponse nel tempo assegnato.

Stato

 State
Proprietà
kState_Idle

L'oggetto client è inattivo.

kState_NotInitialized

L'oggetto client non è inizializzato.

kState_PreparingBinding

L'oggetto client è in attesa che l'associazione sia pronta.

kState_RequestInProgress

È stato inviato un messaggio EchoRequest e l'oggetto client è in attesa di risposta.

kState_WaitingToSend

SendRepeating() è stato chiamato e l'oggetto client è in attesa della successiva invio di una EchoRequest.

Attributi pubblici

AppState

void * AppState

Un puntatore ai dati specifici dell'applicazione.

Funzioni pubbliche

GetBinding

Binding * GetBinding(
  void
) const

Restituisce un puntatore all'oggetto Binding associato a WeaveEchoClient.

GetEventCallback

EventCallback GetEventCallback(
  void
) const

Restituisce un puntatore alla funzione di callback dell'evento API attualmente configurata nell'oggetto WeaveEchoClient.

GetState

State GetState(
  void
) const

Recupera lo stato attuale dell'oggetto WeaveEchoClient.

Init

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

Inizializza un oggetto WeaveEchoClient.

Inizializza un oggetto WeaveEchoClient in preparazione per l'invio di messaggi echo a un peer.

Dettagli
Parametri
[in] binding
Un oggetto Binding utilizzato per stabilire la comunicazione con il nodo peer.
[in] eventCallback
Un puntatore a una funzione che verrà chiamata dall'oggetto WeaveEchoClient per consegnare gli eventi API all'applicazione.
[in] appState
Un puntatore a un oggetto definito dall'applicazione che verrà restituito all'applicazione ogni volta che si verifica un evento API.

IsSendRrepeating

bool IsSendRrepeating() const

Restituisce true se l'oggetto WeaveEchoClient è attualmente in modalità di ripetizione di invio.

RequestInProgress

bool RequestInProgress() const

Restituisce true se è stata inviata una EchoRequest e l'oggetto WeaveEchoClient è in attesa di risposta.

Invia

WEAVE_ERROR Send(
  void
)

Invia un messaggio EchoRequest al peer.

Questo metodo avvia il processo di invio di un messaggio EchoRequest al nodo peer. Se e quando viene ricevuto un messaggio EchoResponse corrispondente, questo verrà inviato all'applicazione tramite l'evento API ResponseReceived.

Quando si forma il messaggio EchoRequest, WeaveEchoClient effettua una richiesta all'applicazione, tramite l'evento API PreparePayload, per preparare il payload del messaggio.

Se l'oggetto Binding non è in stato Pronto quando viene chiamato questo metodo, verrà effettuata una richiesta al metodo Binding::RequestPrepare() per avviare la preparazione on demand. L'operazione di invio verrà quindi messa in coda fino al completamento di questo processo. La profondità massima di questa coda è pari a 1. Di conseguenza, qualsiasi chiamata a Send() mentre è presente un invio precedente in coda comporterà l'invio di una sola richiesta EchoRequest.

La chiamata a Send() mentre WeaveEchoClient è in modalità di ripetizione dell'invio (ad esempio a causa di una precedente chiamata a SendRepeating()) accelera e reimposta il ciclo di invio ma non disattiva la modalità di ripetizione dell'invio per WeaveEchoClient.

Invia

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

Invia un messaggio EchoRequest al peer con un payload specifico.

Questo metodo avvia il processo di invio di un messaggio EchoRequest al nodo peer. I contenuti del buffer di payload fornito verranno inviati al peer come payload del messaggio EchoRequest. Se e quando viene ricevuto un messaggio EchoResponse corrispondente, questo verrà inviato all'applicazione tramite l'evento API ResponseReceived.

Quando viene chiamato questo metodo, la proprietà del buffer di payload fornito passa all'oggetto WeaveEchoClient, che ha la responsabilità di liberarlo. Ciò vale indipendentemente dal fatto che il metodo venga completato correttamente o con un errore.

Se l'oggetto Binding non è in stato Pronto quando viene chiamato questo metodo, verrà effettuata una richiesta al metodo Binding::RequestPrepare() per avviare la preparazione on demand. L'operazione di invio verrà quindi messa in coda fino al completamento di questo processo. La profondità massima di questa coda è pari a 1. Di conseguenza, qualsiasi chiamata a Send() mentre è presente un'invio precedente in coda comporterà l'invio di una sola richiesta EchoRequest.

La chiamata a Send() mentre WeaveEchoClient è in modalità di ripetizione dell'invio (ad esempio a causa di una precedente chiamata a SendRepeating()) accelera e reimposta il ciclo di invio ma non disattiva la modalità di ripetizione dell'invio per WeaveEchoClient.

Dettagli
Parametri
[in] payloadBuf
Un oggetto PacketBuffer contenente dati di payload da inviare al peer. La proprietà di questo buffer passa in tutti i casi all'oggetto WeaveEchoClient.

SendRepeating

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

Avvia l'invio di una sequenza ripetuta di messaggi EchoRequest al peer.

Questo metodo avvia un processo ripetuto di invio di messaggi EchoRequest al peer. Quando i messaggi EchoResponse vengono ricevuti dal peer, vengono recapitati all'applicazione tramite l'evento API ResponseReceived.

Quando viene chiamato SendRepeating(), WeaveEchoClient entra in modalità di ripetizione dell'invio in cui rimane fino alla chiamata di Stop() o fino al verificarsi di un errore di Binding. Chiamare SendRepeating() più volte ha l'effetto di reimpostare il ciclo di invio e aggiornare l'intervallo.

L'invio iniziale di una sequenza avviene nel momento in cui viene chiamato SendRepeating() o quando Binding diventa pronto dopo la chiamata di SendRepeating() (vedi sotto). Gli invii successivi avvengono successivamente all'intervallo specificato.

Ogni volta che viene inviato un messaggio, WeaveEchoClient effettua una richiesta all'applicazione tramite l'evento API PreparePayload per preparare il payload del messaggio.

Se l'oggetto Binding non è in stato Pronto quando arriva il momento di inviare un messaggio, verrà effettuata una richiesta al metodo Binding::RequestPrepare() per avviare la preparazione on demand. Ulteriori invii di messaggi ripetuti saranno messi in pausa fino al completamento di questo processo. In caso di errore durante la preparazione di Binding on demand, WeaveEchoClient uscirà dalla modalità di ripetizione dell'invio.

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

Imposta la funzione di callback dell'evento API sull'oggetto WeaveEchoClient.

Arresto

void Shutdown(
  void
)

Arresta un oggetto WeaveEchoClient inizializzato in precedenza.

Tieni presente che questo metodo può essere chiamato solo se il metodo Init() è già stato richiamato in precedenza.

Interrompi

void Stop(
  void
)

Interrompe qualsiasi scambio di eco in corso e annulla la modalità di ripetizione dell'invio.

WeaveEchoClient

 WeaveEchoClient(
  void
)

Funzioni statiche pubbliche

DefaultEventHandler

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

Gestore predefinito per gli eventi dell'API WeaveEchoClient.

Le applicazioni devono chiamare questo metodo per eventuali eventi API che non riconoscono o non gestiscono. I parametri forniti devono essere uguali a quelli trasmessi dall'oggetto client alla funzione di gestore di eventi dell'applicazione.

Dettagli
Parametri
[in] appState
Un puntatore alle informazioni sullo stato definite dall'applicazione associate all'oggetto client.
[in] eventType
ID evento passato dal callback dell'evento
[in] inParam
Riferimento dei parametri evento di input passati dal callback evento
[in] outParam
Riferimento dei parametri evento di output passati dal callback evento