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 iniciador del protocolo Weave Echo. Al igual que el protocolo de ping ICMP, el protocolo Weave Echo se puede usar para probar el funcionamiento y la accesibilidad de un nodo de Weave.

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

Vinculación del cliente

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

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

Modo SendRepeating

El método SendRepeating() se puede utilizar para colocar WeaveEchoClient en modo SendRepeating. En este modo, el objeto del cliente envía una secuencia repetida de mensajes de EchoRequest al par en un intervalo configurado. El modo SendRepeating se puede cancelar llamando 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 configurando el objeto Binding con una dirección de multidifusión IPv6 o una dirección de transmisión de red local IPv4 (255.255.255.255). Cuando el objeto WeaveEchoClient detecta una dirección de multidifusión o transmisión par, entra automáticamente en el modo MultiResponse cuando se envía la EchoRequest.

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

Eventos de la API

Durante su funcionamiento, el objeto WeaveEchoClient llamará a la aplicación para solicitar acciones específicas o enviar notificaciones de eventos importantes. Estas llamadas de eventos de la 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 pueden 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 lo puede llamar durante una devolución de llamada.

Se definen los siguientes eventos de la API:

PreparePayload

El 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 packageBuffer que contenga los datos de la carga útil. Si la aplicación no controla este evento, se enviará automáticamente una EchoRequest con una carga útil de longitud cero. La aplicación NO PUEDE alterar el estado de WeaveEchoClient durante esta devolución de llamada.

RequestSent

Se envió un mensaje EchoRequest al par.

ResponseReceived

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

CommunicationError

Se produjo un error al formar o enviar una EchoRequest, o mientras se esperaba 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ó una 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 Echo en curso porque se realizó una solicitud para enviar otro EchoRequest antes de recibir 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 suceder si la aplicación llama a Send() después de que se envió una EchoRequest, pero antes de que se reciba cualquier respuesta.

Cuando el objeto está en modo de respuesta múltiple, 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 *
Es un puntero a 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
Devuelve un puntero a la función de devolución de llamada de eventos de la API actualmente configurada 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 se encuentra en modo de repetición de envío.
RequestInProgress() const
bool
Muestra true si se envió una EchoRequest y el objeto WeaveEchoClient está esperando una respuesta.
Send(void)
Envía un mensaje de EchoRequest al par.
Send(PacketBuffer *payloadBuf)
Envía un mensaje de EchoRequest al par con una carga útil específica.
SendRepeating(uint32_t sendIntervalMS)
Inicia el envío de una secuencia repetida de mensajes de EchoRequest al par.
SetEventCallback(EventCallback eventCallback)
void
Establece 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 cualquier intercambio de eco en curso y cancela el modo de repetición de envío.

Funciones estáticas públicas

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

Structs

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

Parámetros de entrada para el evento de la API WeaveEchoClient.

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

Parámetros de resultado para el evento WeaveEchoClient de la API.

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 mientras se enviaba una EchoRequest o se esperaba una respuesta.

kEvent_DefaultCheck

Se usa para verificar el manejo correcto de eventos predeterminados en la aplicación.

kEvent_PreparePayload

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

kEvent_RequestAborted

Se anuló un intercambio de Echo en curso porque se realizó una solicitud para iniciar otro intercambio.

kEvent_RequestSent

Se envió un mensaje EchoRequest al par.

kEvent_ResponseReceived

El par recibió un mensaje de EchoResponse.

kEvent_ResponseTimeout

No se recibió una EchoResponse en el tiempo asignado.

Estado

 State
Propiedades
kState_Idle

El objeto de cliente está inactivo.

kState_NotInitialized

No se inicializó el objeto del cliente.

kState_PreparingBinding

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

kState_RequestInProgress

Se envió un mensaje EchoRequest y el objeto del cliente está a la espera de una respuesta.

kState_WaitingToSend

Se llamó a SendRepeating(), y el objeto del cliente está esperando la próxima vez para enviar una EchoRequest.

Atributos públicos

AppState

void * AppState

Es un puntero a 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 

Devuelve un puntero a la función de devolución de llamada de eventos de la API actualmente configurada 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 para preparar el envío de 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 par.
[in] eventCallback
Un puntero para una función a la que el objeto WeaveEchoClient llamará para entregar eventos de la API a la aplicación.
[in] appState
Un puntero a un objeto definido por la aplicación que se pasará de vuelta a la aplicación cada vez que ocurra un evento de API.

IsSendRrepeating

bool IsSendRrepeating() const 

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

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 de EchoRequest al par.

Este método inicia el proceso de envío de un mensaje EchoRequest al nodo par. Si se recibe el mensaje EchoResponse correspondiente, se entregará a la aplicación a través del evento de la API ResponseReceived.

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

Si el objeto Binding no está en el 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 de uno. Por lo tanto, cualquier llamada a Send() mientras haya un envío anterior en la cola generará un solo EchoRequest.

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

Enviar

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

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

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

Cuando se llama a este método, la propiedad del búfer de carga útil suministrada pasa al objeto WeaveEchoClient, que tiene la responsabilidad de liberarlo. Esto es así sin importar si el método se completa correctamente o con un error.

Si el objeto Binding no está en el 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 de uno. Por lo tanto, cualquier llamada a Send() mientras haya un envío anterior en la cola generará un solo EchoRequest.

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

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

SendRepeating

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

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

Este método inicia un proceso repetido de enviar mensajes de EchoRequest al par. A medida que se reciben los mensajes 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 entra en el modo de repetición de envío en el que permanece hasta que se llama a Stop() o se produce un error de Vinculación. Llamar a SendRepeating() varias veces tiene el efecto de restablecer el ciclo de envío y actualizar el intervalo.

El envío inicial de una secuencia ocurre en el momento en que se llama a SendRepeating() o cuando se prepara Binding después de que se llama a SendRepeating() (consulta a continuación). Los envíos posteriores ocurren a partir de ese momento 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 de PreparePayload, para preparar la carga útil del mensaje.

Si el objeto Binding no está 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. Se pausarán los envíos de mensajes repetidos hasta que se complete este proceso. Si falla la preparación de la vinculación a pedido, el WeaveEchoClient dejará de usar el modo de repetición de envío.

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

Establece 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 cualquier intercambio de eco en curso y cancela el modo de repetición de envío.

WeaveEchoClient

 WeaveEchoClient(
  void
)

Funciones estáticas públicas

DefaultEventHandler

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

Controlador predeterminado para eventos de la API WeaveEchoClient.

Las aplicaciones deben llamar a este método para cualquier evento de la API que no reconozcan o no controlen. Los parámetros proporcionados deben ser los mismos que los que pasa 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 del evento que pasa la devolución de llamada del evento
[in] inParam
Referencia de los parámetros del evento de entrada pasados por la devolución de llamada del evento
[in] outParam
Referencia de los parámetros del evento de salida pasados por la devolución de llamada del evento