nl::Tratado:Vinculação

#include <src/lib/core/WeaveBinding.h>

Captura o destino pretendido de uma comunicação do Weave e informações de configuração associadas.

Resumo

Um objeto Binding identifica o destino pretendido de uma comunicação do Weave (também conhecido como " peers") com um conjunto de parâmetros de configuração que descrevem como a comunicação com o par precisa ocorrer. As vinculações são independentes do protocolo de aplicativo falado entre as duas partes. Dessa forma, eles capturam o "quem" e o "como" de uma comunicação, mas não o "o que".

Configuration

Os aplicativos precisam configurar uma Vinculação com parâmetros específicos para o tipo de canal de comunicação desejado. As vinculações fornecem suporte para uma variedade de transportes de rede, incluindo TCP, UDP, UDP com Weave Trusted Messaging e Weave via BLE (WoBLE). Os aplicativos também podem solicitar o uso de mecanismos de segurança específicos para proteger as mensagens enviadas entre as partes. Isso inclui as sessões CASE e PASE e as chaves do grupo de aplicativos. A interface para configurar uma Vinculação usa um estilo de API declarativa que permite que os aplicativos declarem os requisitos de comunicação em termos simples.

Consulte a documentação de Binding::Configuração para mais detalhes.

preparação

Antes da comunicação, uma Binding precisa ser "prepared." O ato de preparar uma vinculação envolve estabelecer o estado necessário para a comunicação. Isso pode incluir, por exemplo: resolver o endereço de rede do terminal, estabelecer uma conexão de rede e negociar chaves de segurança. Depois de configurado pelo aplicativo, a Binding cuida de todas as etapas necessárias para se preparar para a comunicação, chamando o app novamente quando o processo é concluído. Dessa forma, as vinculações ocultam a mecânica da comunicação, permitindo que os aplicativos se concentrem nas interações de alto nível.

Comunicação

Depois que uma Binding for preparada, ela estará pronta para uso. Nesse estado, os aplicativos ou, mais comumente, o código da camada de protocolo que funciona em nome de um aplicativo solicitam a Binding para alocar um contexto de troca do Weave. O contexto de troca resultante vem pré-configurado para comunicação, permitindo que o app inicie imediatamente uma troca do Weave com o par. O aplicativo pode continuar a solicitar contextos de troca da Vinculação até que a Vinculação seja encerrada ou algum evento, como uma falha de rede, encerre o canal de comunicação subjacente.

Alterações no estado Binding

Durante o uso, uma Binding enviará eventos de API ao aplicativo, informando-as sobre as alterações no estado da vinculação. Por exemplo, quando a preparação for bem-sucedida, o aplicativo receberá um evento informando que a Binding está pronta para uso. Da mesma forma, se o canal de comunicação subjacente falhar, um evento será enviado ao aplicativo informando que a vinculação não estará mais no estado pronto.

Os eventos de API são entregues ao aplicativo por meio de uma função de retorno de chamada de evento fornecida quando a Binding é alocada.

Ciclo de vida de Binding

As vinculações são contadas para permitir o uso compartilhado em vários componentes de software. Quando uma Vinculação é alocada, uma única referência a ela é criada. O aplicativo será responsável por lançar essa referência em algum momento do futuro, de modo que a Binding seja gratuita para a reutilização subsequente.

Quando um aplicativo terminar de usar uma Binding, poderá chamar Close() na vinculação. Isso libera a referência do aplicativo à Binding e bloqueia todas as entregas adicionais de eventos de API. Quando a última referência a uma Binding for liberada, ela será fechada automaticamente.

Tipos públicos

@23{
  kGetPeerDescription_MaxLength = nl::Weave::kWeavePeerDescription_MaxLength
}
tipo enumerado
EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam) typedef
void(*
EventType{
  kEvent_ConnectionEstablished = 1,
  kEvent_BindingReady = 2,
  kEvent_PrepareFailed = 3,
  kEvent_BindingFailed = 4,
  kEvent_PrepareRequested = 5,
  kEvent_PASEParametersRequested = 6,
  kEvent_TAKEParametersRequested = 7,
  kEvent_DefaultCheck = 100
}
tipo enumerado
State tipo enumerado

Atributos públicos

AppState
void *

Funções públicas

AddRef(void)
void
Reserve uma referência ao objeto de vinculação.
AdjustResponseTimeout(ExchangeContext *apExchangeContext) const
Reconfigure um Contexto do Exchange existente para ajustar o tempo limite de resposta.
AllocateRightSizedBuffer(PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize)
BeginConfiguration()
O processo de configuração da Binding.
CanBePrepared(void) const
bool
Close(void)
void
Feche o objeto de vinculação e libere uma referência.
GetConnection() const
Receba o objeto de conexão do Weave associado à vinculação.
GetDefaultResponseTimeout() const
uint32_t
Receber o tempo limite padrão de resposta da troca a ser usado na comunicação com o par.
GetDefaultWRMPConfig(void) const
const WRMPConfig &
Recebe a configuração WRMP padrão a ser usada na comunicação com o par.
GetEncryptionType(void) const
uint8_t
Recupera o tipo de criptografia de mensagem a ser usado ao criptografar mensagens de/para o par.
GetEventCallback() const
EventCallback
Encontre a função que será chamada quando ocorrer um evento da API para a Binding.
GetExchangeManager() const
GetKeyId(void) const
uint32_t
Recupere o ID da chave de criptografia de mensagens a ser usada ao criptografar mensagens de/para o par.
GetLogId(void) const
uint16_t
Receba um ID exclusivo para a vinculação.
GetMaxWeavePayloadSize(const System::PacketBuffer *msgBuf)
uint32_t
Receber o tamanho máximo do payload do Weave que cabe dentro do PackageBuffer fornecido.
GetPeerDescription(char *buf, uint32_t bufSize) const
void
Cria uma string que descreve o nó de peering e as informações de endereço / conexão associadas.
GetPeerIPAddress(nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId) const
void
Recupere as informações de endereço IP do terminal, se disponível.
GetPeerNodeId(void) const
uint64_t
Recupere o ID do nó do peering de vinculação.
GetProtocolLayerCallback(EventCallback & callback, void *& state) const
void
GetState(void) const
State
Recuperar o estado atual da vinculação.
IsAuthenticMessageFromPeer(const WeaveMessageInfo *msgInfo)
bool
Determinar se uma mensagem recebida específica é do par configurado e devidamente autenticada.
IsConnectionTransport() const
bool
IsPreparing(void) const
bool
IsReady(void) const
bool
IsUDPTransport() const
bool
IsUnreliableUDPTransport() const
bool
IsWRMTransport() const
bool
NewExchangeContext(ExchangeContext *& appExchangeContext)
Aloque um novo contexto do Exchange para se comunicar com o par que é o destino da vinculação.
Release(void)
void
Libere uma referência para o objeto de vinculação.
RequestPrepare()
Solicite que o aplicativo configure e prepare a Vinculação.
Reset(void)
void
Redefina a vinculação para um estado não configurado.
SetDefaultResponseTimeout(uint32_t msec)
void
Define o tempo limite padrão de resposta da troca a ser usado na comunicação com o par.
SetDefaultWRMPConfig(const WRMPConfig & wrmpConfig)
void
Defina a configuração WRMP padrão a ser usada na comunicação com o par.
SetEventCallback(EventCallback aEventCallback)
void
Defina a função definida pelo aplicativo a ser chamada quando ocorrer um evento da API para a Vinculação.
SetProtocolLayerCallback(EventCallback callback, void *state)
void
Defina uma função de retorno de chamada para o código da camada de protocolo usando a vinculação em nome de um aplicativo.

Funções estáticas públicas

DefaultEventHandler(void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam)
void
Gerenciador padrão para vincular eventos da API.

Classes

nl::Weave::Binding::Configuração

Fornece uma interface de estilo declarativo para configurar e preparar um objeto Binding.

Estruturas

nl::Weave::Binding::InEventParam

Parâmetros de entrada para um evento de API Binding.

nl::Weave::Binding::OutEventParam

Parâmetros de saída para um evento de API Binding.

Tipos públicos

@23

 @23
Propriedades
kGetPeerDescription_MaxLength

Tamanho máximo da string (incluindo o caractere NUL) retornado por GetPeerDescription().

Callback de evento

void(* EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)

EventType

 EventType
Propriedades
kEvent_BindingFailed

A vinculação falhou e não pode mais ser usada para se comunicar com o par.

kEvent_BindingReady

A ação de preparação da vinculação foi bem-sucedida, e ela agora pode ser usada para se comunicar com o par.

kEvent_ConnectionEstablished

A conexão Weave solicitada foi estabelecida.

kEvent_DefaultCheck

Usado para verificar o gerenciamento correto de eventos padrão no aplicativo.

kEvent_PASEParametersRequested

É solicitado que o aplicativo forneça parâmetros para serem usados durante o estabelecimento da sessão PASE.

kEvent_PrepareFailed

Falha na ação de preparação da vinculação.

kEvent_PrepareRequested

É solicitado que o aplicativo configure e prepare a vinculação para uso pela pilha de rede.

kEvent_TAKEParametersRequested

O app é solicitado a fornecer parâmetros que serão usados durante o estabelecimento da sessão Grab.

Estado

 State

Atributos públicos

Estado do aplicativo

void * AppState

Funções públicas

Adicionar referência

void AddRef(
  void
)

Reserve uma referência ao objeto de vinculação.

AdjustResponseTimeout

WEAVE_ERROR AdjustResponseTimeout(
  ExchangeContext *apExchangeContext
) const 

Reconfigure um Contexto do Exchange existente para ajustar o tempo limite de resposta.

Detalhes
Parâmetros
[in] apExchangeContext
Um ponteiro para um objeto de contexto do Exchange a ser reconfigurado

Alocar RightRightSizedBuffer

WEAVE_ERROR AllocateRightSizedBuffer(
  PacketBuffer *& buf,
  const uint32_t desiredSize,
  const uint32_t minSize,
  uint32_t & outMaxPayloadSize
)

BeginConfiguration

Configuration BeginConfiguration()

O processo de configuração da Binding.

Os aplicativos precisam chamar BeginConfiguration() para configurar a Binding antes de prepará-la para se comunicar com o par.

Detalhes
Retorna
Um objeto Binding::Configuration que pode ser usado para configurar a vinculação.

Prepare-se

bool CanBePrepared(
  void
) const 

Fechar

void Close(
  void
)

Feche o objeto de vinculação e libere uma referência.

Quando chamado, esse método faz com que a vinculação entre no estado "Closed". Todas as ações de preparação em andamento para a vinculação são canceladas, e todos os recursos externos de comunicação retidos pela vinculação são liberados.

Chamar Close() diminui a contagem de referência associada à vinculação, liberando o objeto se a contagem de referência se tornar zero.

GetConnection

WeaveConnection * GetConnection() const 

Receba o objeto de conexão do Weave associado à vinculação.

Detalhes
Retorna
Um ponteiro para um objeto WeaveConnection ou NULL se não houver conexão associada à vinculação.

GetDefaultResponseTimeout

uint32_t GetDefaultResponseTimeout() const 

Receber o tempo limite padrão de resposta da troca a ser usado na comunicação com o par.

Detalhes
Retorna
Tempo limite de resposta em ms.

GetDefaultWRMPConfig.

const WRMPConfig & GetDefaultWRMPConfig(
  void
) const 

Recebe a configuração WRMP padrão a ser usada na comunicação com o par.

Detalhes
Retorna
Uma referência a uma estrutura WRMPConfig que contém os valores de configuração padrão.

GetEncryptionType

uint8_t GetEncryptionType(
  void
) const 

Recupera o tipo de criptografia de mensagem a ser usado ao criptografar mensagens de/para o par.

GetEventCallback

EventCallback GetEventCallback() const 

Encontre a função que será chamada quando ocorrer um evento da API para a Binding.

Detalhes
Retorna
Um ponteiro para a função de callback.

GetManagerManager.

WeaveExchangeManager * GetExchangeManager() const 

GetKeyId.

uint32_t GetKeyId(
  void
) const 

Recupere o ID da chave de criptografia de mensagens a ser usada ao criptografar mensagens de/para o par.

GetLogId.

uint16_t GetLogId(
  void
) const 

Receba um ID exclusivo para a vinculação.

GetMaxWeavePayloadSize

uint32_t GetMaxWeavePayloadSize(
  const System::PacketBuffer *msgBuf
)

Receber o tamanho máximo do payload do Weave que cabe dentro do PackageBuffer fornecido.

Para o UDP, incluindo o UDP com WRM, o tamanho máximo do payload retornado garantirá que a mensagem do Weave resultante não transborde a MTU UDP configurada.

Além disso, esse método garantirá que o payload do Weave não ultrapasse o PackageBuffer fornecido.

Detalhes
Parâmetros
[in] msgBuf
Um ponteiro para o PackageBuffer onde o payload da mensagem será gravado.
Retorna
O tamanho máximo de payload do Weave.

GetPeerDescription

void GetPeerDescription(
  char *buf,
  uint32_t bufSize
) const 

Cria uma string que descreve o nó de peering e as informações de endereço / conexão associadas.

Detalhes
Parâmetros
[in] buf
Um ponteiro para um buffer em que a string precisa ser gravada. O buffer fornecido deve ser pelo menos tão grande quanto o kGetPeerDescription_MaxLength. Se um buffer menor for fornecido, a string será truncada. A saída incluirá um caractere de encerramento NUL em todos os casos.
[in] bufSize
O tamanho do buffer apontado por buf.

GetPeerIPAddress

void GetPeerIPAddress(
  nl::Inet::IPAddress & address,
  uint16_t & port,
  InterfaceId & interfaceId
) const 

Recupere as informações de endereço IP do terminal, se disponível.

A disponibilidade das informações de endereço IP do terminal depende do estado e da configuração da vinculação. As informações de endereço IP só estão disponíveis quando se usa um transporte baseado em IP (TCP, UDP ou UDP com WRMP). Antes do início da preparação, as informações de endereço só estarão disponíveis se tiverem sido definidas expressamente pelo aplicativo durante a configuração. Durante a fase de preparação, as informações de endereço estão disponíveis quando a preparação de endereço é concluída (por exemplo, após a conclusão da resolução de DNS). Depois que o Binding estiver pronto, as informações de endereço permanecerão disponíveis até que a Binding seja redefinida.

Detalhes
Parâmetros
[out] address
Uma referência a um objeto IPAddress que receberá o endereço IP do terminal. Se as informações de endereço IP dos apps semelhantes estiverem indisponíveis, esse valor será definido como IPAddress::Any.
[out] port
Uma referência a um número inteiro que receberá o número de porta de peering. Se as informações de endereço IP do terminal não estiverem disponíveis, esse valor será indefinido.
[out] interfaceId
Uma referência a um número inteiro que receberá o ID da interface de rede por meio da qual o peer pode ser acessado. Se as informações de endereço IP do terminal não estiverem disponíveis, esse valor será indefinido.

GetPeerNodeId

uint64_t GetPeerNodeId(
  void
) const 

Recupere o ID do nó do peering de vinculação.

Válido apenas após o objeto de vinculação ter sido preparado.

Detalhes
Retorna
Criar ID de nó de peering

GetProtocolLayerCallback

void GetProtocolLayerCallback(
  EventCallback & callback,
  void *& state
) const 

GetState (link em inglês)

State GetState(
  void
) const 

Recuperar o estado atual da vinculação.

Detalhes
Retorna
O estado de vinculação.

IsAuthenticMessageFromPeer

bool IsAuthenticMessageFromPeer(
  const WeaveMessageInfo *msgInfo
)

Determinar se uma mensagem recebida específica é do par configurado e devidamente autenticada.

Esse método confirma os seguintes detalhes sobre a mensagem fornecida:

  • A mensagem é originada do nó de peering da vinculação
  • A mensagem foi recebida pelo mesmo tipo de transporte que a vinculação. Se a mensagem foi recebida em uma conexão, o método também confirma que a mensagem foi recebida pela conexão exata associada à vinculação.
  • A chave e o tipo de criptografia usados para criptografar a mensagem correspondem aos que foram configurados na vinculação. Para vinculações configuradas sem o uso de segurança, o método confirma que a mensagem recebida NÃO é criptografada.

Esse método deve ser usado em protocolos como o WDM, em que os peerings podem iniciar espontaneamente as trocas de volta ao nó local após uma troca inicial do nó para o par. Nesses casos, o método permite que o nó local confirme se a mensagem não solicitada recebida foi enviada pelo par associado. É claro que, para as vinculações configuradas sem o uso de criptografia de mensagens, essa declaração não fornece valor de uma perspectiva de segurança. Ela apenas confirma que o ID do nó do remetente e os tipos de transporte são correspondentes.

Se a vinculação não estiver no estado "Pronto", esse método sempre retornará "false".

Detalhes
Parâmetros
[in] msgInfo
As informações da mensagem do Weave para a mensagem recebida.
Retorna
Verdadeiro se a mensagem for autêntica com o par.

IsConnectionTransport

bool IsConnectionTransport() const 

Está se preparando

bool IsPreparing(
  void
) const 

Detalhes
Retorna
Verdadeiro se a vinculação estiver sendo preparada.

IsReady

bool IsReady(
  void
) const 

Detalhes
Retorna
Verdadeiro se a Vinculação estiver no estado "Pronto".

Transporte isUDP

bool IsUDPTransport() const 

IsUnreliableUDPTransport

bool IsUnreliableUDPTransport() const 

IsWRMTransport

bool IsWRMTransport() const 

NovoContexto

WEAVE_ERROR NewExchangeContext(
  ExchangeContext *& appExchangeContext
)

Aloque um novo contexto do Exchange para se comunicar com o par que é o destino da vinculação.

Detalhes
Parâmetros
[out] appExchangeContext
Uma referência a um ponteiro que receberá o objeto de contexto do Exchange recém-alocado. O ponteiro será definido como NULL caso o método falhe.
Valores de retorno
WEAVE_NO_ERROR
Se o contexto da troca foi alocado com sucesso.
WEAVE_ERROR_NO_MEMORY
Se nenhuma memória estiver disponível para alocar o contexto de troca.
WEAVE_ERROR_INCORRECT_STATE
Se a vinculação não estiver no estado "Pronto".
other
Outros erros relacionados à configuração do contexto de troca com base na configuração da vinculação.

Versão

void Release(
  void
)

Libere uma referência para o objeto de vinculação.

Se não houver mais referências ao objeto de vinculação, a vinculação será fechada e liberada.

RequestPrepare

WEAVE_ERROR RequestPrepare()

Solicite que o aplicativo configure e prepare a Vinculação.

O código da camada do protocolo pode usar este método em uma Binding que não foi configurada ou falhou para acionar um evento no aplicativo (kEvent_PrepareRequested), solicitando que ele configure e prepare a vinculação para uso.

Esse método só pode ser chamado em "Vinculações" nos estados "Não configurado" ou "Falha".

Se o aplicativo não for compatível com a configuração/preparação sob demanda de Bindings, o método falhará com WEAVE_ERROR_NOT_IMPLEMENTED.

Redefinir

void Reset(
  void
)

Redefina a vinculação para um estado não configurado.

Quando Reset() é chamado, todas as ações de preparação em andamento para a vinculação são canceladas, e todos os recursos de comunicação externos retidos pela vinculação são liberados. Reset() coloca a vinculação no estado Não configurado. Depois disso, ela pode ser configurada e preparada novamente.

Reset() não altera a contagem de referência da vinculação.

SetDefaultResponseTimeout

void SetDefaultResponseTimeout(
  uint32_t msec
)

Define o tempo limite padrão de resposta da troca a ser usado na comunicação com o par.

Detalhes
Parâmetros
[in] timeout
O novo tempo limite de resposta em ms.

SetDefaultWRMPConfig.

void SetDefaultWRMPConfig(
  const WRMPConfig & wrmpConfig
)

Defina a configuração WRMP padrão a ser usada na comunicação com o par.

Detalhes
Parâmetros
[in] aWRMPConfig
Uma referência a uma estrutura WRMPConfig que contém a nova configuração padrão.

SetEventCallback

void SetEventCallback(
  EventCallback aEventCallback
)

Defina a função definida pelo aplicativo a ser chamada quando ocorrer um evento da API para a Vinculação.

Detalhes
Parâmetros
[in] aEventCallback
Um ponteiro para a função de callback.

SetProtocolLayerCallback

void SetProtocolLayerCallback(
  EventCallback callback,
  void *state
)

Defina uma função de retorno de chamada para o código da camada de protocolo usando a vinculação em nome de um aplicativo.

Essa função será chamada além da função de callback definida pelo aplicativo quando ocorrerem eventos de API para a Binding.

Detalhes
Parâmetros
[in] callback
Um ponteiro para a função de callback.
[in] state
Um ponteiro para um objeto de estado que será fornecido ao código da camada de protocolos quando um callback de camada de protocolo ocorrer.

Funções estáticas públicas

Gerenciador de eventos padrão

void DefaultEventHandler(
  void *apAppState,
  EventType aEvent,
  const InEventParam & aInParam,
  OutEventParam & aOutParam
)

Gerenciador padrão para vincular eventos da API.

Os aplicativos precisam chamar esse método para quaisquer eventos de API que não reconheçam ou manipulem. Os parâmetros fornecidos precisam ser os mesmos transmitidos pela vinculação à função de manipulador de eventos do aplicativo.

Detalhes
Parâmetros
[in] apAppState
Um ponteiro para informações de estado definidas pelo aplicativo associadas à vinculação.
[in] aEvent
Código do evento transmitido pelo callback do evento
[in] aInParam
Referência de parâmetros de eventos de entrada transmitidos pelo callback do evento
[in] aOutParam
Referência de parâmetros de eventos de saída transmitidos pelo callback do evento