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. Come il 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 alle richieste echo (vedi WeaveEchoServer).

Associazione client

WeaveEchoClient accetta un oggetto Binding Weave, che viene utilizzato per identificare e stabilire una 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, nel qual caso WeaveEchoClient richiederà la preparazione on demand dell'associazione (per i dettagli, vedi Binding::RequestPrepare()).

Verrà richiesta anche la preparazione on demand dell'associazione nel caso in cui l'operazione non vada a buon fine dopo il passaggio allo stato Pronto.

Modalità ripetizione invio

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

Multicast e trasmissione

Un oggetto WeaveEchoClient può essere utilizzato per inviare EchoRequests a più destinatari contemporaneamente configurando l'oggetto Binding con un indirizzo di trasmissione 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 all'invio dell'EchoRequest.

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

Eventi API

Nel corso delle sue operazioni, 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 il callback di un evento. Un'eccezione generale è il metodo Shutdown() dell'oggetto, che non può mai essere chiamato durante un callback.

Vengono definiti i seguenti eventi API:

PreparePayload

WeaveEchoClient sta per formare un messaggio EchoRequest e richiede all'applicazione di fornire un payload. Se un'applicazione lo desidera, può restituire un nuovo PacketBuffer contenente i dati del payload. Se l'applicazione non gestisce questo evento, verrà inviato automaticamente un EchoRequest con un payload di lunghezza zero. L'applicazione POTREBBE NON modificare lo stato di WeaveEchoClient durante questo callback.

RequestSent

È stato inviato un messaggio EchoRequest al peer.

ResponseReceived

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

CommunicationError

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

ResponseTimeout

Non è stato ricevuto un EchoResponse nel tempo previsto. Il timeout della risposta è controllato dalla proprietà predefinitaResponseTimeout nell'oggetto Binding.

RequestAborted

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

Quando l'oggetto è in modalità MultiResponse, l'evento viene soppresso 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 è stato inviato un EchoRequest e l'oggetto WeaveEchoClient è in attesa di risposta.
Send(void)
Invia un messaggio EchoRequest al collega.
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 collega.
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 di invio.

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

Strutture
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 EchoRequest o l'attesa di una risposta.

kEvent_DefaultCheck

Utilizzato per verificare la corretta gestione predefinita degli eventi 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 effettuata una richiesta di avvio di un altro scambio.

kEvent_RequestSent

È stato inviato un messaggio EchoRequest al peer.

kEvent_ResponseReceived

È stato ricevuto un messaggio EchoResponse dal peer.

kEvent_ResponseTimeout

Non è stato ricevuto un EchoResponse nel tempo previsto.

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() è stata chiamata e l'oggetto client attende che la prossima volta invii 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.

Inizia

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

Inizializza un oggetto WeaveEchoClient.

Inizializza un oggetto WeaveEchoClient in vista dell'invio di messaggi eco a un peer.

Dettagli
Parametri
[in] binding
Un oggetto Binding che verrà utilizzato per stabilire la comunicazione con il nodo peer.
[in] eventCallback
Un puntatore a una funzione che verrà chiamata dall'oggetto WeaveEchoClient per inviare eventi API all'applicazione.
[in] appState
Un puntatore a un oggetto definito dall'applicazione che verrà passato nuovamente 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 è stato inviato un EchoRequest e l'oggetto WeaveEchoClient è in attesa di risposta.

Invia

WEAVE_ERROR Send(
  void
)

Invia un messaggio EchoRequest al collega.

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à consegnato all'applicazione tramite l'evento API ResponseReceived.

Durante la creazione del messaggio EchoRequest, WeaveEchoClient invia 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à inviata una richiesta al metodo Binding::RequestPrepare() per avviare la preparazione on demand. L'operazione di invio verrà quindi messa in coda fino al completamento del processo. La profondità massima di questa coda è uno. Pertanto, qualsiasi chiamata a Send() mentre è presente un invio precedente in coda comporterà l'invio di una singola EchoRequest.

La chiamata a Send() mentre WeaveEchoClient è in modalità di ripetizione di invio (ossia a causa di una precedente chiamata a SendRepeating()) ha l'effetto di accelerare e reimpostare il ciclo di invio, ma non fa uscire WeaveEchoClient dalla modalità di ripetizione di invio.

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 del payload fornito verranno inviati al peer come payload del messaggio EchoRequest. Se e quando viene ricevuto un messaggio EchoResponse corrispondente, questo verrà consegnato all'applicazione tramite l'evento API ResponseReceived.

Al momento della chiamata di questo metodo, la proprietà del buffer del payload fornito passa all'oggetto WeaveEchoClient, che ha la responsabilità di liberarlo. Questo 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à inviata una richiesta al metodo Binding::RequestPrepare() per avviare la preparazione on demand. L'operazione di invio verrà quindi messa in coda fino al completamento del processo. La profondità massima di questa coda è uno. Pertanto, qualsiasi chiamata a Send() mentre è presente un invio precedente in coda comporterà l'invio di una singola EchoRequest.

La chiamata a Send() mentre WeaveEchoClient è in modalità di ripetizione di invio (ossia a causa di una precedente chiamata a SendRepeating()) ha l'effetto di accelerare e reimpostare il ciclo di invio, ma non fa uscire WeaveEchoClient dalla modalità di ripetizione di invio.

Dettagli
Parametri
[in] payloadBuf
Un oggetto PacketBuffer contenente i dati del 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 collega.

Questo metodo avvia un processo ripetuto di invio dei 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 di invio in cui rimane finché non viene chiamato Stop() o non si verifica un errore 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 chiamata SendRepeating() oppure ogni volta che l'Binding diventa pronta dopo la chiamata di SendRepeating() (vedi di seguito). Gli invii successivi avvengono successivamente all'intervallo specificato.

Ogni volta che si verifica un invio, WeaveEchoClient invia una richiesta all'applicazione tramite l'evento API PreparePayload per preparare il payload del messaggio.

Se l'oggetto Binding non è in stato Pronto quando è il momento di inviare un messaggio, verrà inviata una richiesta al metodo Binding::RequestPrepare() per avviare la preparazione on demand. Eventuali ulteriori invii di messaggi ripetuti verranno messi in pausa fino al completamento del processo. Un errore durante la preparazione di Binding on demand farà sì che WeaveEchoClient abbandoni la modalità di ripetizione di 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() è stato chiamato in precedenza.

Interrompi

void Stop(
  void
)

Interrompe qualsiasi scambio di eco in corso e annulla la modalità di ripetizione di 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 tutti gli eventi API che non riconoscono o non gestiscono. I parametri forniti devono essere gli stessi passati dall'oggetto client alla funzione gestore di eventi dell'applicazione.

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