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.

Resumo

A classe WeaveEchoClient implementa o lado do iniciador do protocolo Weave Echo. Semelhante ao protocolo de ping ICMP, o protocolo Weave Echo pode ser usado para testar a atividade e a acessibilidade de um nó do Weave.

Os aplicativos podem usar a classe WeaveEchoClient para enviar mensagens de EchoRequest únicas ou repetidas para um nó de peering identificado por um objeto Binding. Uma classe correspondente existe para responder a solicitações de eco (consulte WeaveEchoServer).

Vinculação do cliente

O WeaveEchoClient usa um objeto Binding do Weave, que é usado para identificar e estabelecer comunicação com o destinatário pretendido das solicitações de eco. A Binding pode ser configurada e preparada pelo aplicativo antes da inicialização do objeto WeaveEchoClient, ou pode ser deixada despreparada. Nesse caso, o WeaveEchoClient vai solicitar a preparação da vinculação sob demanda (consulte Binding::RequestPrepare() para mais detalhes).

A preparação sob demanda da Binding também será solicitada caso ela falhe após ter entrado no estado Ready.

Modo SendRepeating

O método SendRepeating() pode ser usado para colocar o WeaveEchoClient no modo SendRepeating. Neste modo, o objeto cliente envia uma sequência repetida de mensagens de EchoRequest para o ponto em um intervalo configurado. O modo SendRepeating pode ser cancelado chamando o método Stop().

Multicast e transmissão

Um objeto WeaveEchoClient pode ser usado para enviar EchoRequests a vários destinatários simultaneamente configurando o objeto Binding com um endereço multicast IPv6 apropriado ou um endereço de transmissão de rede local IPv4 (255.255.255.255). Quando o objeto WeaveEchoClient detecta um multicast ou um endereço de ponto de transmissão, ele automaticamente entra no modo MultiResponse após o envio da EchoRequest.

Nesse modo, o objeto continua a ouvir e entregar todas as mensagens de EchoResponse recebidas que chegam na mesma troca. O objeto permanece no modo MultiResponse até que: 1) o aplicativo chame Stop() ou Send(), 2) no modo SendRepeating, chegue a hora de enviar outra solicitação ou 3) nenhuma resposta seja recebida e o tempo limite de recebimento expire.

Eventos da API

Durante a operação, o objeto WeaveEchoClient chamará o aplicativo para solicitar ações específicas ou enviar notificações de eventos importantes. Essas chamadas de evento de API são feitas para a função de callback atualmente configurada no objeto do cliente. Exceto quando indicado, os aplicativos podem alterar o estado do cliente durante um callback de evento. Uma exceção geral é o método Shutdown() do objeto, que pode nunca ser chamado durante um callback.

Os seguintes eventos de API estão definidos:

PreparePayload

O WeaveEchoClient está prestes a formar uma mensagem de EchoRequest e solicita que o aplicativo forneça um payload. Se um aplicativo quiser, ele pode retornar um novo PackageBuffer contendo os dados do payload. Se o aplicativo não processar esse evento, uma EchoRequest com carga útil de tamanho zero será enviada automaticamente. O aplicativo NÃO PODE alterar o estado do WeaveEchoClient durante essa chamada de retorno.

RequestSent

Uma mensagem de EchoRequest foi enviada ao par.

ResponseReceived

Uma mensagem de EchoResponse foi recebida do par. Os argumentos para o evento contêm a carga útil da resposta e as metainformações sobre a mensagem de resposta.

CommunicationError

Ocorreu um erro ao formar ou enviar uma EchoRequest ou ao aguardar uma resposta. Exemplos de erros que podem ocorrer ao aguardar uma resposta são erros de chave ou fechamento inesperado de uma conexão. Os argumentos para o evento contêm o motivo do erro.

ResponseTimeout

Um EchoResponse não foi recebido no tempo alocado. O tempo limite de resposta é controlado pela propriedade DefaultResponseTimeout no objeto Binding.

RequestAborted

Uma troca de eco em andamento foi cancelada porque foi feita uma solicitação para enviar outra EchoRequest antes de receber uma resposta para a mensagem anterior. Isso pode surgir no modo SendRepeating quando chega a hora de enviar o próximo EchoRequest. Isso também pode acontecer se o aplicativo chamar Send() depois que um EchoRequest for enviado, mas antes de qualquer resposta ser recebida.

Quando o objeto estiver no modo MultiResponse, o evento será suprimido se pelo menos uma mensagem EchoResponse tiver sido recebida.

Construtores e destruidores

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 *
Um ponteiro para dados específicos do aplicativo.

Funções públicas

GetBinding(void) const
Retorna um ponteiro para o objeto Binding associado ao WeaveEchoClient.
GetEventCallback(void) const
EventCallback
Retorna um ponteiro para a função de callback do evento da API configurada no momento no objeto WeaveEchoClient.
GetState(void) const
Recupere o estado atual do objeto WeaveEchoClient.
Init(Binding *binding, EventCallback eventCallback, void *appState)
Inicialize um objeto WeaveEchoClient.
IsSendRrepeating() const
bool
Retorna verdadeiro se o objeto WeaveEchoClient estiver no modo de repetição de envio.
RequestInProgress() const
bool
Retorna verdadeiro se um EchoRequest tiver sido enviado e o objeto WeaveEchoClient estiver aguardando uma resposta.
Send(void)
Envie uma mensagem de EchoRequest ao par.
Send(PacketBuffer *payloadBuf)
Envie uma mensagem EchoRequest ao par com um payload específico.
SendRepeating(uint32_t sendIntervalMS)
Comece a enviar uma sequência repetida de mensagens de EchoRequest para o contato.
SetEventCallback(EventCallback eventCallback)
void
Define a função de retorno de chamada do evento da API no objeto WeaveEchoClient.
Shutdown(void)
void
Encerra um objeto WeaveEchoClient inicializado anteriormente.
Stop(void)
void
Interrompe qualquer troca de eco em andamento e cancela o modo de repetição de envio.

Funções estáticas públicas

DefaultEventHandler(void *appState, EventType eventType, const InEventParam & inParam, OutEventParam & outParam)
void
Manipulador padrão para eventos da API WeaveEchoClient.

Estruturas

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

Parâmetros de entrada para o evento da API WeaveEchoClient.

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

Parâmetros de saída para o evento da API WeaveEchoClient.

Tipos públicos

EventCallback

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

EventType

 EventType
Propriedades
kEvent_CommunicationError

Ocorreu um erro de comunicação ao enviar uma EchoRequest ou esperar uma resposta.

kEvent_DefaultCheck

Usado para verificar o tratamento correto do evento padrão no aplicativo.

kEvent_PreparePayload

O aplicativo é solicitado a preparar o payload para a solicitação de eco.

kEvent_RequestAborted

Uma troca de eco em andamento foi cancelada porque foi feita uma solicitação para iniciar outra troca.

kEvent_RequestSent

Uma mensagem de EchoRequest foi enviada ao par.

kEvent_ResponseReceived

Uma mensagem de EchoResponse foi recebida do par.

kEvent_ResponseTimeout

Um EchoResponse não foi recebido no tempo alocado.

Estado

 State
Propriedades
kState_Idle

O objeto do cliente está inativo.

kState_NotInitialized

O objeto do cliente não foi inicializado.

kState_PreparingBinding

O objeto cliente está aguardando a vinculação ficar pronta.

kState_RequestInProgress

Uma mensagem EchoRequest foi enviada e o objeto do cliente está aguardando uma resposta.

kState_WaitingToSend

SendRepeating() foi chamado, e o objeto do cliente está esperando pela próxima vez para enviar uma EchoRequest.

Atributos públicos

AppState

void * AppState

Um ponteiro para dados específicos do aplicativo.

Funções públicas

GetBinding

Binding * GetBinding(
  void
) const 

Retorna um ponteiro para o objeto Binding associado ao WeaveEchoClient.

GetEventCallback

EventCallback GetEventCallback(
  void
) const 

Retorna um ponteiro para a função de callback do evento da API configurada no momento no objeto WeaveEchoClient.

GetState

State GetState(
  void
) const 

Recupere o estado atual do objeto WeaveEchoClient.

Init

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

Inicialize um objeto WeaveEchoClient.

Inicialize um objeto WeaveEchoClient como preparação para enviar mensagens de eco a um peer.

Detalhes
Parâmetros
[in] binding
Um objeto Binding que será usado para estabelecer comunicação com o nó de peering.
[in] eventCallback
Um ponteiro para uma função que será chamada pelo objeto WeaveEchoClient para entregar eventos de API ao aplicativo.
[in] appState
Um ponteiro para um objeto definido pelo aplicativo que será passado de volta para o aplicativo sempre que ocorrer um evento da API.

IsSendRrepeating

bool IsSendRrepeating() const 

Retorna verdadeiro se o objeto WeaveEchoClient estiver no modo de repetição de envio.

RequestInProgress

bool RequestInProgress() const 

Retorna verdadeiro se um EchoRequest tiver sido enviado e o objeto WeaveEchoClient estiver aguardando uma resposta.

Enviar

WEAVE_ERROR Send(
  void
)

Envie uma mensagem de EchoRequest ao par.

Esse método inicia o processo de envio de uma mensagem de EchoRequest para o nó de peering. Se e quando uma mensagem EchoResponse correspondente for recebida, ela será entregue ao aplicativo por meio do evento ResponseReceived API.

Ao formar a mensagem EchoRequest, o WeaveEchoClient faz uma solicitação ao aplicativo, por meio do evento da API PreparePayload, para preparar o payload da mensagem.

Se o objeto Binding não estiver no estado Ready quando esse método for chamado, uma solicitação será feita ao método Binding::RequestPrepare() para iniciar a preparação sob demanda. A operação de envio ficará, então, na fila até a conclusão do processo. A profundidade máxima desta fila é um. Assim, qualquer chamada para Send() enquanto houver um envio anterior na fila resultará no envio de apenas um único EchoRequest.

Chamar Send() enquanto o WeaveEchoClient estiver no modo de repetição de envio (por exemplo, devido a uma chamada anterior para SendRepeating()) tem o efeito de acelerar e redefinir o ciclo de envio, mas não tira o WeaveEchoClient do modo de repetição de envio.

Enviar

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

Envie uma mensagem EchoRequest ao par com um payload específico.

Esse método inicia o processo de envio de uma mensagem de EchoRequest para o nó de peering. O conteúdo do buffer de payload fornecido será enviado ao terminal como o payload da mensagem EchoRequest. Se e quando uma mensagem EchoResponse correspondente for recebida, ela será entregue ao aplicativo por meio do evento ResponseReceived API.

Ao chamar esse método, a propriedade do buffer de payload fornecido passa para o objeto WeaveEchoClient, que tem a responsabilidade de liberá-lo. Isso ocorre independentemente de o método ser concluído com sucesso ou com um erro.

Se o objeto Binding não estiver no estado Ready quando esse método for chamado, uma solicitação será feita ao método Binding::RequestPrepare() para iniciar a preparação sob demanda. A operação de envio será colocada na fila até que esse processo seja concluído. A profundidade máxima desta fila é um. Assim, qualquer chamada para Send() enquanto houver um envio anterior na fila resultará no envio de apenas um único EchoRequest.

Chamar Send() enquanto o WeaveEchoClient estiver no modo de repetição de envio (por exemplo, devido a uma chamada anterior para SendRepeating()) tem o efeito de acelerar e redefinir o ciclo de envio, mas não tira o WeaveEchoClient do modo de repetição de envio.

Detalhes
Parâmetros
[in] payloadBuf
Um objeto PackageBuffer contendo dados de payload a serem enviados ao peering. A propriedade desse buffer é passada para o objeto WeaveEchoClient em todos os casos.

SendRepeating

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

Comece a enviar uma sequência repetida de mensagens de EchoRequest para o contato.

Esse método inicia um processo repetido de envio de mensagens de EchoRequest para o par. À medida que as mensagens de EchoResponse são recebidas do terminal, elas são entregues ao aplicativo por meio do evento ResponseReceived da API.

Quando SendRepeating() é chamado, o WeaveEchoClient entra no modo de repetição de envio, que permanece até que Stop() seja chamado ou até que ocorra um erro Binding. Chamar SendRepeating() várias vezes resulta na redefinição do ciclo de envio e na atualização do intervalo.

O envio inicial de uma sequência ocorre no momento em que SendRepeating() é chamado ou sempre que Binding fica pronto depois que SendRepeating() é chamado (confira abaixo). Os envios subsequentes ocorrem posteriormente no intervalo especificado.

Sempre que ocorre um envio, o WeaveEchoClient faz uma solicitação ao aplicativo, por meio do evento da API PreparePayload, para preparar o payload da mensagem.

Se o objeto Binding não estiver no estado Ready quando chegar a hora de enviar uma mensagem, uma solicitação será feita ao método Binding::RequestPrepare() para iniciar a preparação sob demanda. O envio repetido de mensagens será pausado até a conclusão do processo. Uma falha durante a preparação de Binding sob demanda fará com que o WeaveEchoClient saia do modo de repetição de envio.

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

Define a função de retorno de chamada do evento da API no objeto WeaveEchoClient.

Encerramento

void Shutdown(
  void
)

Encerra um objeto WeaveEchoClient inicializado anteriormente.

Observe que esse método só poderá ser chamado se o método Init() já tiver sido chamado anteriormente.

Parar

void Stop(
  void
)

Interrompe qualquer troca de eco em andamento e cancela o modo de repetição de envio.

WeaveEchoClient

 WeaveEchoClient(
  void
)

Funções estáticas públicas

DefaultEventHandler

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

Manipulador padrão para eventos da API WeaveEchoClient.

Os aplicativos precisam chamar esse método para qualquer evento da API que não reconheçam ou não consigam processar. Os parâmetros fornecidos precisam ser os mesmos passados pelo objeto do cliente para a função de manipulador de eventos do aplicativo.

Detalhes
Parâmetros
[in] appState
Um ponteiro para informações de estado definidas pelo aplicativo associadas ao objeto cliente.
[in] eventType
ID do evento transmitido pelo callback do evento
[in] inParam
Referência dos parâmetros do evento de entrada transmitidos pelo callback do evento
[in] outParam
Referência dos parâmetros do evento de saída transmitidos pelo callback do evento