nl:: Weave:: Binding
#include <src/lib/core/WeaveBinding.h>
Captura o alvo 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 "ponto"), além de um conjunto de parâmetros de configuração que descrevem como a comunicação com o ponto deve ocorrer. As vinculações são independentes do protocolo do aplicativo falado entre as duas partes. Assim, eles capturam o "quem" e o "como" de uma comunicação, mas não o "o quê".
Os aplicativos precisam configurar um Binding 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 Trust Messaging e Weave over 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 sessões CASE e PASE, além de chaves de grupos de aplicativos. A interface para configurar uma Binding usa um estilo de API declarativa que permite que os aplicativos declarem os próprios requisitos para a comunicação em termos simples.
Consulte a documentação de Binding::Configuration para ver mais detalhes.
Preparação
Antes da comunicação ocorrer, uma Binding precisa ser "preparada". O ato de preparar uma Vinculação envolve estabelecer o estado necessário para a comunicação. Isso pode incluir ações como resolver o endereço de rede do peering, estabelecer uma conexão de rede e negociar chaves de segurança. Depois de configurado pelo aplicativo, a classe Binding cuida de todas as etapas necessárias para se preparar para a comunicação, fazendo um callback para o aplicativo quando o processo é concluído. Dessa forma, as vinculações escondem a mecânica de comunicação, permitindo que os aplicativos se concentrem nas interações de alto nível.
Comunicação
Depois que um Binding é preparado, ele fica pronto 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 de Weave. O contexto da troca resultante vem pré-configurado para comunicação, permitindo que o aplicativo inicie imediatamente uma troca do Weave com o peering. O aplicativo pode continuar solicitando contextos de troca de Binding até que a Binding seja encerrada ou até que algum evento, por exemplo, uma falha de rede, encerre o canal de comunicação subjacente.
Mudanças no estado de vinculação
Durante o uso, uma Binding entrega eventos de API para o aplicativo, informando sobre mudanças no estado do Binding. Por exemplo, quando a preparação é bem-sucedida, o aplicativo recebe um evento informando que a Binding está pronta para uso. Da mesma forma, se o canal de comunicação subjacente falhar, um evento será entregue ao aplicativo informando que Binding não está mais no estado "ready".
Os eventos da API são entregues ao aplicativo por meio de uma função de callback de evento fornecida quando a Binding é alocada.
Duração da vinculação
As vinculações são contadas para permitir o uso compartilhado entre vários componentes de software. Quando uma Vinculação é alocada, uma referência única a ela é criada. O aplicativo é responsável por lançar essa referência em algum momento no futuro, de modo que a Binding fique livre para reutilização subsequente.
Quando um aplicativo termina de usar uma Binding, ele pode chamar Close() na vinculação. Isso libera a referência do aplicativo para a Binding e bloqueia todas as outras entregas de eventos da API. Quando a última referência a uma Binding é liberada, ela é automaticamente fechada.
Tipos públicos |
|
---|---|
@23{
|
enum |
EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
|
typedefvoid(*
|
EventType{
|
enum |
State
|
enum |
Atributos públicos |
|
---|---|
AppState
|
void *
|
Funções públicas |
|
---|---|
AddRef(void)
|
void
Reserve uma referência para o objeto de vinculação.
|
AdjustResponseTimeout(ExchangeContext *apExchangeContext) const
|
Reconfigure um Contexto do Exchange para ajustar o tempo limite de resposta.
|
AllocateRightSizedBuffer(PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize)
|
|
BeginConfiguration()
|
Ser 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
|
Recebe o objeto de conexão do Weave associado à vinculação.
|
GetDefaultResponseTimeout() const
|
uint32_t
Encontre o tempo limite padrão de resposta da troca a ser usado ao se comunicar com o peering.
|
GetDefaultWRMPConfig(void) const
|
const WRMPConfig &
Recebe a configuração padrão do WRMP a ser usada na comunicação com o peering.
|
GetEncryptionType(void) const
|
uint8_t
Recupera o tipo de criptografia da mensagem a ser usado ao criptografar mensagens de/para o peering.
|
GetEventCallback() const
|
EventCallback
Acessa a função que será chamada quando um evento de API ocorrer para Binding.
|
GetExchangeManager() const
|
|
GetKeyId(void) const
|
uint32_t
Recupere o ID da chave de criptografia de mensagem que será usada ao criptografar mensagens de/para o ponto.
|
GetLogId(void) const
|
uint16_t
Consiga um ID exclusivo para a vinculação.
|
GetMaxWeavePayloadSize(const System::PacketBuffer *msgBuf)
|
uint32_t
Extrai o tamanho máximo do payload do Weave que pode caber dentro do PacketBuffer fornecido.
|
GetPeerDescription(char *buf, uint32_t bufSize) const
|
void
Constrói 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 do endereço IP do peering, se disponíveis.
|
GetPeerNodeId(void) const
|
uint64_t
Recupera o ID do nó do peering de vinculação.
|
GetProtocolLayerCallback(EventCallback & callback, void *& state) const
|
void
|
GetState(void) const
|
State
Recupera o estado atual da vinculação.
|
IsAuthenticMessageFromPeer(const WeaveMessageInfo *msgInfo)
|
bool
Determine se uma mensagem recebida específica é do peering configurado e está 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 peering que é o destino da vinculação.
|
Release(void)
|
void
Liberar uma referência ao objeto de vinculação.
|
RequestPrepare()
|
Solicite que o aplicativo configure e prepare a Binding.
|
Reset(void)
|
void
Redefina a vinculação de volta para um estado não configurado.
|
SetDefaultResponseTimeout(uint32_t msec)
|
void
Defina o tempo limite padrão de resposta da troca a ser usado ao se comunicar com o peering.
|
SetDefaultWRMPConfig(const WRMPConfig & wrmpConfig)
|
void
Defina a configuração padrão do WRMP a ser usada na comunicação com o peering.
|
SetEventCallback(EventCallback aEventCallback)
|
void
Defina a função definida pelo aplicativo a ser chamada quando ocorrer um evento de API para Binding.
|
SetProtocolLayerCallback(EventCallback callback, void *state)
|
void
Defina uma função de callback de evento para o código da camada de protocolo usando Binding 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.
|
Aulas |
|
---|---|
nl:: |
Fornece uma interface de estilo declarativo para configurar e preparar um objeto Binding. |
Estruturas |
|
---|---|
nl:: |
Parâmetros de entrada para um evento da API Binding. |
nl:: |
Parâmetros de saída para um evento da API Binding. |
Tipos públicos
@23
@23
Propriedades | |
---|---|
kGetPeerDescription_MaxLength
|
Comprimento máximo da string (incluindo o caractere NUL) retornado por GetPeerDescription(). |
EventCallback
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 peering. |
kEvent_BindingReady
|
A ação de preparar na vinculação foi bem-sucedida, e a vinculação agora pode ser usada para se comunicar com o peering. |
kEvent_ConnectionEstablished
|
A conexão do Weave solicitada foi estabelecida. |
kEvent_DefaultCheck
|
Usado para verificar o gerenciamento correto de eventos padrão no aplicativo. |
kEvent_PASEParametersRequested
|
É necessário que o aplicativo forneça parâmetros que serão usados durante o estabelecimento da sessão PASE. |
kEvent_PrepareFailed
|
Falha na ação de preparação na vinculação. |
kEvent_PrepareRequested
|
O aplicativo precisa configurar e preparar a vinculação para uso pela pilha de rede. |
kEvent_TAKEParametersRequested
|
É solicitado que o aplicativo forneça parâmetros que serão usados durante o estabelecimento da sessão Take. |
Estado
State
Atributos públicos
AppState
void * AppState
Funções públicas
AddRef
void AddRef( void )
Reserve uma referência para o objeto de vinculação.
AdjustResponseTimeout
WEAVE_ERROR AdjustResponseTimeout( ExchangeContext *apExchangeContext ) const
Reconfigure um Contexto do Exchange para ajustar o tempo limite de resposta.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
AllocateRightSizedBuffer
WEAVE_ERROR AllocateRightSizedBuffer( PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize )
BeginConfiguration
Configuration BeginConfiguration()
Ser o processo de configuração da Binding.
Os aplicativos precisam chamar BeginConfiguration() para configurar o Binding antes de prepará-lo para a comunicação com o peering.
Detalhes | |
---|---|
Retorna |
Um objeto Binding::Configuration que pode ser usado para configurar a vinculação.
|
CanBePrepared
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 Fechado. Todas as ações de preparação em andamento para a vinculação são canceladas, e todos os recursos de comunicação externa mantidos 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
Recebe 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
Encontre o tempo limite padrão de resposta da troca a ser usado ao se comunicar com o peering.
Detalhes | |
---|---|
Retorna |
Tempo limite de resposta em ms.
|
GetDefaultWRMPConfig
const WRMPConfig & GetDefaultWRMPConfig( void ) const
Recebe a configuração padrão do WRMP a ser usada na comunicação com o peering.
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 da mensagem a ser usado ao criptografar mensagens de/para o peering.
GetEventCallback
EventCallback GetEventCallback() const
Acessa a função que será chamada quando um evento de API ocorrer para Binding.
Detalhes | |
---|---|
Retorna |
Um ponteiro para a função de callback.
|
GetExchangeManager
WeaveExchangeManager * GetExchangeManager() const
GetKeyId
uint32_t GetKeyId( void ) const
Recupere o ID da chave de criptografia de mensagem que será usada ao criptografar mensagens de/para o ponto.
GetLogId
uint16_t GetLogId( void ) const
Consiga um ID exclusivo para a vinculação.
GetMaxWeavePayloadSize
uint32_t GetMaxWeavePayloadSize( const System::PacketBuffer *msgBuf )
Extrai o tamanho máximo do payload do Weave que pode caber dentro do PacketBuffer fornecido.
Para UDP, incluindo UDP com WRM, o tamanho máximo de payload retornado garantirá que a mensagem Weave resultante não ultrapasse a MTU do UDP configurada.
Além disso, esse método garante que o payload do Weave não sobrecarregue o PackageBuffer fornecido.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
||
Retorna |
O tamanho máximo do payload do Weave.
|
GetPeerDescription
void GetPeerDescription( char *buf, uint32_t bufSize ) const
Constrói 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 do endereço IP do peering, se disponíveis.
A disponibilidade das informações do endereço IP do peering depende do estado e da configuração da vinculação. As informações de endereço IP só estão disponíveis ao usar 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ó ficam 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 são disponibilizadas quando a preparação do endereço é concluída (por exemplo, após a conclusão da resolução de DNS). Depois que a Binding estiver pronta, 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
Recupera o ID do nó do peering de vinculação.
Válida somente depois que o objeto de vinculação tiver sido preparado.
Detalhes | |
---|---|
Retorna |
Entrelaçar o ID do nó do peering
|
GetProtocolLayerCallback
void GetProtocolLayerCallback( EventCallback & callback, void *& state ) const
GetState
State GetState( void ) const
Recupera o estado atual da vinculação.
Detalhes | |
---|---|
Retorna |
O estado de vinculação.
|
IsAuthenticMessageFromPeer
bool IsAuthenticMessageFromPeer( const WeaveMessageInfo *msgInfo )
Determine se uma mensagem recebida específica é do peering configurado e está devidamente autenticada.
Esse método confirma os seguintes detalhes sobre a mensagem fornecida:
- A mensagem foi originada do nó de peering da vinculação
- A mensagem foi recebida com o mesmo tipo de transporte da vinculação. Se a mensagem foi recebida por uma conexão, o método também confirmará se 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 foi projetado para ser usado em protocolos como o WDM, em que os pares podem iniciar trocas espontaneamente de volta para o nó local após uma troca inicial do nó para o peering. Nesses casos, o método permite que o nó local confirme que a mensagem não solicitada de entrada foi enviada pelo ponto associado. Obviamente, para vinculações configuradas sem o uso de criptografia de mensagens, essa declaração não oferece valor do ponto de vista da segurança. Ele apenas confirma que o ID do nó do remetente e os tipos de transporte correspondem.
Se a vinculação não estiver no estado Ready, esse método sempre retornará "false".
Detalhes | |||
---|---|---|---|
Parâmetros |
|
||
Retorna |
Verdadeiro se a mensagem for autêntica do colega.
|
IsConnectionTransport
bool IsConnectionTransport() const
IsPreparing
bool IsPreparing( void ) const
Detalhes | |
---|---|
Retorna |
Verdadeiro se a Binding estiver sendo preparada no momento.
|
IsReady
bool IsReady( void ) const
Detalhes | |
---|---|
Retorna |
Verdadeiro se Binding estiver no estado "Pronto".
|
IsUDPTransport
bool IsUDPTransport() const
IsUnreliableUDPTransport
bool IsUnreliableUDPTransport() const
IsWRMTransport
bool IsWRMTransport() const
NewExchangeContext
WEAVE_ERROR NewExchangeContext( ExchangeContext *& appExchangeContext )
Aloque um novo contexto do Exchange para se comunicar com o peering que é o destino da vinculação.
Detalhes | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parâmetros |
|
||||||||
Valores de retorno |
|
Versão
void Release( void )
Liberar uma referência ao 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 Binding.
O código de camada do protocolo pode usar esse método em uma Binding que não foi configurada, ou falhou, para acionar um evento para o 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 "NotConfigured" ou "Com falha".
Se o aplicativo não for compatível com a configuração/preparação sob demanda de vinculações, o método falhará com WEAVE_ERROR_NOT_IMPLEMENTED.
Redefinir
void Reset( void )
Redefina a vinculação de volta 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 externa 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 )
Defina o tempo limite padrão de resposta da troca a ser usado ao se comunicar com o peering.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
SetDefaultWRMPConfig
void SetDefaultWRMPConfig( const WRMPConfig & wrmpConfig )
Defina a configuração padrão do WRMP a ser usada na comunicação com o peering.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
SetEventCallback
void SetEventCallback( EventCallback aEventCallback )
Defina a função definida pelo aplicativo a ser chamada quando ocorrer um evento de API para Binding.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
SetProtocolLayerCallback
void SetProtocolLayerCallback( EventCallback callback, void *state )
Defina uma função de callback de evento para o código da camada de protocolo usando Binding em nome de um aplicativo.
Essa função será chamada junto com a função de callback definida pelo aplicativo quando os eventos da API ocorrerem para Binding.
Detalhes | |||||
---|---|---|---|---|---|
Parâmetros |
|
Funções estáticas públicas
DefaultEventHandler
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 eventos da API que não reconhecerem ou manipularem. Os parâmetros fornecidos precisam ser iguais aos passados pela vinculação à função do manipulador de eventos do aplicativo.
Detalhes | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parâmetros |
|