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".
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{
|
tipo enumerado |
EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
|
typedefvoid(*
|
EventType{
|
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:: |
Fornece uma interface de estilo declarativo para configurar e preparar um objeto Binding. |
Estruturas |
|
---|---|
nl:: |
Parâmetros de entrada para um evento de API Binding. |
nl:: |
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 |
|
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 |
|
||
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 |
|
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 |
|
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 |
|
||
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 |
|
||||||||
Valores de retorno |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|