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.

Resumen

La clase WeaveEchoClient implementa el lado del iniciador del protocolo Echo de Weave. Al igual que el protocolo ping ICMP, el protocolo Echo de Weave puede usarse para probar el funcionamiento y la accesibilidad de un nodo de Weave.

Las aplicaciones pueden usar la clase WeaveEchoClient para enviar mensajes EchoRequest únicos o repetidos a un nodo par identificado por un objeto Binding. Existe una clase correspondiente para responder a las solicitudes de echo (consulta WeaveEchoServer).

Vinculación de cliente

WeaveEchoClient toma un objeto Binding de Weave que se usa para identificar y establecer la comunicación con el destinatario previsto de las solicitudes de echo. La aplicación puede configurar y preparar la Vinculación antes de la inicialización del objeto WeaveEchoClient, o bien puede dejarse sin preparar, en cuyo caso WeaveEchoClient solicitará la preparación a pedido de la vinculación (consulta Vinculación::RequestPrepare() para obtener más detalles).

La preparación a pedido de la Vinculación también se solicitará en caso de que falle después de ingresar al estado Listo.

Modo de repetición de llamadas

El método SendRepeating() se puede usar para colocar WeaveEchoClient en el modo SendRepeating. En este modo, el objeto del cliente envía una secuencia repetitiva de mensajes EchoRequest al par en un intervalo configurado. Para cancelar el modo SendRepeating, llama al método Stop().

Multidifusión y emisión

Se puede usar un objeto WeaveEchoClient para enviar EchoRequests a varios destinatarios de forma simultánea. Para ello, se configura el objeto Binding con una dirección de multidifusión IPv6 o IPv4 local (255.255.255.255). Cuando el objeto WeaveEchoClient detecta una dirección de par de transmisión o multidifusión, ingresa automáticamente al modo MultiResponse cuando se envía la EchoRequest.

En este modo, el objeto continúa escuchando y entregando todos los mensajes EchoResponse entrantes que lleguen al mismo intercambio. El objeto permanece en modo MultiResponse hasta que 1) la aplicación llame a Stop() o Send(), 2) en el modo SendRepeating, llegue el momento de enviar otra solicitud o 3) no se reciba ninguna respuesta y se venza el tiempo de espera de la recepción.

Eventos de la API

Durante el transcurso de su operación, el objeto WeaveEchoClient llamará a la aplicación para solicitar acciones específicas o entregar notificaciones de eventos importantes. Estas llamadas de eventos de API se realizan a la función de devolución de llamada configurada actualmente en el objeto de cliente. Excepto cuando se indique lo contrario, las aplicaciones tienen la libertad de alterar el estado del cliente durante una devolución de llamada de evento. Una excepción general es el método Shutdown() del objeto, al que nunca se puede llamar durante una devolución de llamada.

Se definen los siguientes eventos de la API:

PreparePayload

WeaveEchoClient está a punto de formar un mensaje EchoRequest y solicita a la aplicación que proporcione una carga útil. Si una aplicación lo desea, puede mostrar un nuevo PacketBuffer que contenga los datos de carga útil. Si la aplicación no controla este evento, se enviará automáticamente una EchoRequest con una carga útil de longitud cero. Es posible que la aplicación NO altere el estado de WeaveEchoClient durante esta devolución de llamada.

RequestSent

Se envió un mensaje EchoRequest al par.

ResponseReceived

Se recibió un mensaje EchoResponse del par. Los argumentos del evento contienen la carga útil de la respuesta y la metainformación sobre el mensaje de respuesta.

CommunicationError

Se ha producido un error durante la formación o el envío de una EchoRequest, o mientras se espera una respuesta. Algunos ejemplos de errores que pueden ocurrir mientras se espera una respuesta son los errores clave o el cierre inesperado de una conexión. Los argumentos del evento contienen el motivo del error.

ResponseTimeout

No se recibió EchoResponse en el tiempo asignado. El tiempo de espera de respuesta se controla mediante la propiedad DefaultResponseTimeout en el objeto Binding.

RequestAborted

Se anuló un intercambio de Echo en curso porque se solicitó enviar otra EchoRequest antes de que se recibiera una respuesta al mensaje anterior. Esto puede surgir en el modo SendRepeating cuando llega el momento de enviar la siguiente EchoRequest. Esto también puede ocurrir si la aplicación llama a Send() después de que se haya enviado una EchoRequest, pero antes de que se reciba cualquier respuesta.

Cuando el objeto está en modo MultiResponse, el evento se suprime si se recibió al menos un mensaje EchoResponse.

Constructores y destructores

WeaveEchoClient(void)

Tipos públicos

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

Atributos públicos

AppState
void *
Un puntero para datos específicos de la aplicación.

Funciones públicas

GetBinding(void) const
Muestra un puntero al objeto Binding asociado con WeaveEchoClient.
GetEventCallback(void) const
EventCallback
Muestra un puntero a la función de devolución de llamada del evento de la API configurada actualmente en el objeto WeaveEchoClient.
GetState(void) const
Recupera el estado actual del objeto WeaveEchoClient.
Init(Binding *binding, EventCallback eventCallback, void *appState)
Inicializa un objeto WeaveEchoClient.
IsSendRrepeating() const
bool
Muestra true si el objeto WeaveEchoClient está actualmente en modo de envío-repetición.
RequestInProgress() const
bool
Muestra true si se envió una EchoRequest y el objeto WeaveEchoClient está esperando una respuesta.
Send(void)
Envía un mensaje EchoRequest al par.
Send(PacketBuffer *payloadBuf)
Envía un mensaje EchoRequest al par con una carga útil específica.
SendRepeating(uint32_t sendIntervalMS)
Inicia el envío de una secuencia repetitiva de mensajes EchoRequest al par.
SetEventCallback(EventCallback eventCallback)
void
Configura la función de devolución de llamada del evento de la API en el objeto WeaveEchoClient.
Shutdown(void)
void
Cierra un objeto WeaveEchoClient inicializado con anterioridad.
Stop(void)
void
Detiene los intercambios de eco en curso y cancela el modo de envío y repetición.

Funciones estáticas públicas

DefaultEventHandler(void *appState, EventType eventType, const InEventParam & inParam, OutEventParam & outParam)
void
Controlador predeterminado para los eventos de la API de WeaveEchoClient.

Structs

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

Los parámetros de entrada para el evento de la API de WeaveEchoClient.

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

Muestra los parámetros para el evento de la API WeaveEchoClient.

Tipos públicos

EventCallback

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

EventType

 EventType
Propiedades
kEvent_CommunicationError

Se produjo un error de comunicación al enviar una EchoRequest o esperar una respuesta.

kEvent_DefaultCheck

Se usa para verificar la correcta administración predeterminada de los eventos en la aplicación.

kEvent_PreparePayload

Se solicita a la aplicación que prepare la carga útil para la solicitud de Echo.

kEvent_RequestAborted

Se anuló un intercambio de eco en curso porque se solicitó iniciar otro intercambio.

kEvent_RequestSent

Se envió un mensaje EchoRequest al par.

kEvent_ResponseReceived

Se recibió un mensaje EchoResponse del par.

kEvent_ResponseTimeout

No se recibió EchoResponse en el tiempo asignado.

Estado

 State
Propiedades
kState_Idle

El objeto del cliente está inactivo.

kState_NotInitialized

No se inicializó el objeto de cliente.

kState_PreparingBinding

El objeto del cliente está esperando que la vinculación esté lista.

kState_RequestInProgress

Se envió un mensaje EchoRequest y el objeto del cliente está esperando una respuesta.

kState_WaitingToSend

Se llamó a SendRepeating() y el objeto del cliente está esperando la próxima vez que se envíe una EchoRequest.

Atributos públicos

AppState

void * AppState

Un puntero para datos específicos de la aplicación.

Funciones públicas

GetBinding

Binding * GetBinding(
  void
) const 

Muestra un puntero al objeto Binding asociado con WeaveEchoClient.

GetEventCallback

EventCallback GetEventCallback(
  void
) const 

Muestra un puntero a la función de devolución de llamada del evento de la API configurada actualmente en el objeto WeaveEchoClient.

GetState

State GetState(
  void
) const 

Recupera el estado actual del objeto WeaveEchoClient.

Init

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

Inicializa un objeto WeaveEchoClient.

Inicializa un objeto WeaveEchoClient en preparación para enviar mensajes de eco a un par.

Detalles
Parámetros
[in] binding
Un objeto Binding que se usará para establecer la comunicación con el nodo de intercambio de tráfico.
[in] eventCallback
Un puntero a una función que llamará el objeto WeaveEchoClient para entregar eventos de API a la aplicación.
[in] appState
Un puntero a un objeto definido por la aplicación que se enviará de vuelta a la aplicación cada vez que ocurra un evento de la API.

IsSendRrepeating

bool IsSendRrepeating() const 

Muestra true si el objeto WeaveEchoClient está actualmente en modo de envío-repetición.

RequestInProgress

bool RequestInProgress() const 

Muestra true si se envió una EchoRequest y el objeto WeaveEchoClient está esperando una respuesta.

Enviar

WEAVE_ERROR Send(
  void
)

Envía un mensaje EchoRequest al par.

Este método inicia el proceso de enviar un mensaje EchoRequest al nodo de intercambio de tráfico. Si se recibe el mensaje EchoResponse correspondiente, se enviará a la aplicación a través del evento de la API ResponseReceived.

Cuando se forma el mensaje EchoRequest, WeaveEchoClient envía una solicitud a la aplicación a través del evento de la API PreparePayload para preparar la carga útil del mensaje.

Si el objeto Binding no está en estado Listo cuando se llama a este método, se realizará una solicitud al método Binding::RequestPrepare() para iniciar la preparación a pedido. La operación de envío se pondrá en cola hasta que se complete este proceso. La profundidad máxima de esta cola es una. Por lo tanto, cualquier llamada a Send() mientras haya un envío anterior en la cola hará que solo se envíe una EchoRequest.

Llamar a Send() mientras WeaveEchoClient está en modo de envío-repetición (es decir, debido a una llamada anterior a SendRepeating()) tiene el efecto de acelerar y restablecer el ciclo de envío, pero no quita a WeaveEchoClient del modo de envío-repetición.

Enviar

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

Envía un mensaje EchoRequest al par con una carga útil específica.

Este método inicia el proceso de enviar un mensaje EchoRequest al nodo de intercambio de tráfico. El contenido del búfer de la carga útil suministrado se enviará al par como la carga útil del mensaje EchoRequest. Si se recibe el mensaje EchoResponse correspondiente, se enviará a la aplicación a través del evento de la API ResponseReceived.

Después de llamar a este método, la propiedad del búfer de la carga útil suministrado pasa al objeto WeaveEchoClient, que tiene la responsabilidad de liberarlo. Esto es así sin importar si el método se completa de forma correcta o con un error.

Si el objeto Binding no está en estado Listo cuando se llama a este método, se realizará una solicitud al método Binding::RequestPrepare() para iniciar la preparación a pedido. La operación de envío se pondrá en cola hasta que se complete este proceso. La profundidad máxima de esta cola es una. Por lo tanto, cualquier llamada a Send() mientras haya un envío anterior en la cola hará que solo se envíe una EchoRequest.

Llamar a Send() mientras WeaveEchoClient está en modo de envío-repetición (es decir, debido a una llamada anterior a SendRepeating()) tiene el efecto de acelerar y restablecer el ciclo de envío, pero no quita a WeaveEchoClient del modo de envío-repetición.

Detalles
Parámetros
[in] payloadBuf
Un objeto PacketBuffer que contiene datos de carga útil que se enviarán al par. La propiedad de este búfer se pasa al objeto WeaveEchoClient en todos los casos.

SendRepeating

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

Inicia el envío de una secuencia repetitiva de mensajes EchoRequest al par.

Este método inicia un proceso recurrente de envío de mensajes EchoRequest al par. A medida que se reciben mensajes de EchoResponse del par, se entregan a la aplicación a través del evento de la API ResponseReceived.

Cuando se llama a SendRepeating(), el WeaveEchoClient ingresa al modo de envío y repetición, en el que permanece hasta que se llama a Stop() o se produce un error de vinculación. Si llamas a SendRepeating() varias veces, se restablecerá el ciclo de envío y se actualizará el intervalo.

El envío inicial de una secuencia se produce cuando se llama a SendRepeating() o cuando la Binding queda lista después de llamar a SendRepeating() (consulta a continuación). Los envíos posteriores se realizarán en el intervalo especificado.

Cada vez que se produce un envío, WeaveEchoClient realiza una solicitud a la aplicación a través del evento de la API PreparePayload, para preparar la carga útil del mensaje.

Si el objeto Binding no está en estado Listo cuando llegue el momento de enviar un mensaje, se realizará una solicitud al método Binding::RequestPrepare() para iniciar la preparación a pedido. Los demás envíos de mensajes repetidos se detendrán hasta que se complete este proceso. Una falla durante la preparación de la vinculación a pedido provocará que WeaveEchoClient salga del modo de envío-repetición.

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

Configura la función de devolución de llamada del evento de la API en el objeto WeaveEchoClient.

Cierre

void Shutdown(
  void
)

Cierra un objeto WeaveEchoClient inicializado con anterioridad.

Ten en cuenta que solo se puede llamar a este método si se llamó al método Init() anteriormente.

Detener

void Stop(
  void
)

Detiene los intercambios de eco en curso y cancela el modo de envío y repetición.

WeaveEchoClient

 WeaveEchoClient(
  void
)

Funciones estáticas públicas

DefaultEventHandler

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

Controlador predeterminado para los eventos de la API de WeaveEchoClient.

Se requiere que las aplicaciones llamen a este método para cualquier evento de API que no reconozcan o no manejen. Los parámetros proporcionados deben ser los mismos que pasó el objeto del cliente a la función del controlador de eventos de la aplicación.

Detalles
Parámetros
[in] appState
Un puntero para la información de estado definida por la aplicación asociada con el objeto de cliente.
[in] eventType
ID de evento que pasa la devolución de llamada del evento
[in] inParam
Referencia de parámetros de eventos de entrada pasados por la devolución de llamada de eventos
[in] outParam
Referencia de parámetros de eventos de salida pasados por la devolución de llamada del evento