nl :: Tecer:: Obrigatório
#include <src/lib/core/WeaveBinding.h>
Captura o alvo pretendido de uma comunicação Weave e informações de configuração associadas.
Resumo
Um objeto Binding identifica o alvo pretendido de uma comunicação Weave (também conhecido como "par"), junto com um conjunto de parâmetros de configuração que descreve como a comunicação com o par deve ocorrer. As ligações são independentes do protocolo do aplicativo falado entre as duas partes. Como tal, eles capturam o "quem" e o "como" de uma comunicação, mas não o "o quê".
Os aplicativos devem configurar um Binding com parâmetros específicos para o tipo de canal de comunicação desejado. As ligações fornecem suporte para uma variedade de transportes de rede, incluindo TCP, UDP, UDP com Weave Reliable 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 e chaves de grupo de aplicativos. A interface para configurar um Binding usa um estilo de API declarativo que permite aos aplicativos declarar seus requisitos para a comunicação em termos simples.
Consulte a documentação de Binding :: Configuration para obter mais detalhes.
Preparação
Antes de ocorrer a comunicação, uma Vinculação deve ser "preparada". O ato de preparar uma Ligação envolve o estabelecimento do estado necessário para que a comunicação ocorra. Isso pode incluir coisas como: resolver o endereço de rede do par, estabelecer uma conexão de rede e negociar chaves de segurança. Uma vez configurado pelo aplicativo, o Binding cuida de todas as etapas necessárias para se preparar para a comunicação, retornando ao aplicativo quando o processo for concluído. Desta forma, os Bindings ocultam a mecânica da comunicação, permitindo que os aplicativos se concentrem nas interações de alto nível.
Comunicação
Assim que uma Encadernação for preparada, ela estará pronta para uso. Nesse estado, os aplicativos (ou mais comumente, o código da camada de protocolo trabalhando em nome de um aplicativo) solicitam que o Binding aloque um contexto de troca do Weave. O contexto de troca resultante vem pré-configurado para comunicação, permitindo que o aplicativo inicie imediatamente uma troca Weave com o par. O aplicativo pode continuar a solicitar contextos de troca do Binding até que o Binding seja fechado ou algum evento, por exemplo, uma falha de rede, termine o canal de comunicação subjacente.
Alterações de estado de ligação
Durante seu uso, um Binding entregará eventos de API ao aplicativo informando-o sobre as mudanças no estado do Binding . Por exemplo, quando a preparação for bem-sucedida, o aplicativo receberá um evento informando que o Binding está pronto para uso. Da mesma forma, se o canal de comunicação subjacente falhar, um evento será entregue ao aplicativo informando que o Binding não está mais no estado pronto.
Os eventos da API são entregues ao aplicativo por meio de uma função de retorno de chamada de evento fornecida quando o Binding é alocado.
Tempo de vida obrigatório
As ligações são contadas por referência para permitir o uso compartilhado entre vários componentes de software. Quando uma vinculação é alocada, uma única referência à vinculação é criada. O aplicativo é responsável por liberar essa referência em algum momento no futuro, de forma que a Ligação esteja livre para reutilização subsequente.
Quando um aplicativo é feito com um Binding, ele pode chamar Close () no binding. Isso libera a referência do aplicativo ao Binding e bloqueia todas as entregas futuras de eventos de API. Quando a última referência a uma ligação for liberada, ela será fechada automaticamente.
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 ao objeto de ligação. |
AdjustResponseTimeout ( ExchangeContext *apExchangeContext) const | Reconfigure um Exchange Context existente para ajustar o tempo limite de resposta. |
AllocateRightSizedBuffer (PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize) | |
BeginConfiguration () | Sendo o processo de configuração do Binding . |
CanBePrepared (void) const | bool |
Close (void) | void Feche o objeto de ligação e libere uma referência. |
GetConnection () const | Obtenha o objeto de conexão Weave associado à ligação. |
GetDefaultResponseTimeout () const | uint32_t Obtenha o tempo limite de resposta de troca padrão a ser usado ao se comunicar com o par. |
GetDefaultWRMPConfig (void) const | const WRMPConfig & Obtenha a configuração WRMP padrão a ser usada ao se comunicar com o par. |
GetEncryptionType (void) const | uint8_t Recupere o tipo de criptografia da mensagem a ser usado ao criptografar mensagens de / para o par. |
GetEventCallback () const | EventCallback Obtenha a função que será chamada quando ocorrer um evento de API para o Binding . |
GetExchangeManager () const | |
GetKeyId (void) const | uint32_t Recupere o id da chave de criptografia da mensagem a ser usada ao criptografar mensagens de / para o par. |
GetLogId (void) const | uint16_t Obtenha uma identificação exclusiva para a ligação. |
GetMaxWeavePayloadSize (const System::PacketBuffer *msgBuf) | uint32_t Obtenha o tamanho máximo de carga útil 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 mesmo nível e suas 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 par, se disponível. |
GetPeerNodeId (void) const | uint64_t Recupere o id do nó do par de ligação. |
GetProtocolLayerCallback (EventCallback & callback, void *& state) const | void |
GetState (void) const | State Recupere o estado atual da ligação. |
IsAuthenticMessageFromPeer (const WeaveMessageInfo *msgInfo) | bool Determine se uma determinada mensagem recebida é do par 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 de Troca para se comunicar com o par que é o destino da ligação. |
Release (void) | void Libere uma referência ao objeto de ligação. |
RequestPrepare () | Solicite o aplicativo para configurar e preparar o Binding . |
Reset (void) | void Redefina a ligação de volta para um estado não configurado. |
SetDefaultResponseTimeout (uint32_t msec) | void Defina o tempo limite de resposta de troca padrão a ser usado ao se comunicar com o par. |
SetDefaultWRMPConfig (const WRMPConfig & wrmpConfig) | void Defina a configuração WRMP padrão a ser usada ao se comunicar com o par. |
SetEventCallback (EventCallback aEventCallback) | void Configure a função definida pelo aplicativo a ser chamada quando ocorrer um evento de API para o Binding . |
SetProtocolLayerCallback (EventCallback callback, void *state) | void Defina uma função de retorno de chamada de evento para o código da camada de protocolo usando o Binding em nome de um aplicativo. |
Funções estáticas públicas | |
---|---|
DefaultEventHandler (void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam) | void Manipulador padrão para vincular eventos de API. |
Aulas | |
---|---|
nl :: Weave :: Binding :: Configuration | Fornece uma interface de estilo declarativo para configurar e preparar um objeto Binding . |
Structs | |
---|---|
nl :: Weave :: Binding :: InEventParam | Parâmetros de entrada para um evento Binding API. |
nl :: Weave :: Binding :: OutEventParam | Parâmetros de saída para um evento Binding API. |
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)
Tipo de evento
EventType
Estado
State
Atributos públicos
AppState
void * AppState
Funções públicas
AddRef
void AddRef( void )
Reserve uma referência ao objeto de ligação.
AdjustResponseTimeout
WEAVE_ERROR AdjustResponseTimeout( ExchangeContext *apExchangeContext ) const
Reconfigure um Exchange Context existente 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()
Sendo o processo de configuração do Binding .
Os aplicativos devem chamar BeginConfiguration () para configurar o Binding antes de prepará-lo para se comunicar com o par.
Detalhes | |
---|---|
Devoluções | 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 ligaçã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 tornar-se zero.
GetConnection
WeaveConnection * GetConnection() const
Obtenha o objeto de conexão Weave associado à ligação.
Detalhes | |
---|---|
Devoluções | Um ponteiro para um objeto WeaveConnection ou NULL se não houver conexão associada à vinculação. |
GetDefaultResponseTimeout
uint32_t GetDefaultResponseTimeout() const
Obtenha o tempo limite de resposta de troca padrão a ser usado ao se comunicar com o par.
Detalhes | |
---|---|
Devoluções | Tempo limite de resposta em ms. |
GetDefaultWRMPConfig
const WRMPConfig & GetDefaultWRMPConfig( void ) const
Obtenha a configuração WRMP padrão a ser usada ao se comunicar com o par.
Detalhes | |
---|---|
Devoluções | Uma referência a uma estrutura WRMPConfig contendo os valores de configuração padrão. |
GetEncryptionType
uint8_t GetEncryptionType( void ) const
Recupere o tipo de criptografia da mensagem a ser usado ao criptografar mensagens de / para o par.
GetEventCallback
EventCallback GetEventCallback() const
Obtenha a função que será chamada quando ocorrer um evento de API para o Binding .
Detalhes | |
---|---|
Devoluções | Um ponteiro para a função de retorno de chamada. |
GetExchangeManager
WeaveExchangeManager * GetExchangeManager() const
GetKeyId
uint32_t GetKeyId( void ) const
Recupere o id da chave de criptografia da mensagem a ser usada ao criptografar mensagens de / para o par.
GetLogId
uint16_t GetLogId( void ) const
Obtenha uma identificação exclusiva para a ligação.
GetMaxWeavePayloadSize
uint32_t GetMaxWeavePayloadSize( const System::PacketBuffer *msgBuf )
Obtenha o tamanho máximo de carga útil do Weave que pode caber dentro do PacketBuffer fornecido.
Para UDP, incluindo UDP com WRM, o tamanho máximo de carga retornado garantirá que a mensagem Weave resultante não irá estourar o UDP MTU configurado.
Além disso, esse método garantirá que a carga útil do Weave não sobrecarregue o PacketBuffer fornecido.
Detalhes | |||
---|---|---|---|
Parâmetros |
| ||
Devoluções | O tamanho máximo da carga útil do Weave. |
GetPeerDescription
void GetPeerDescription( char *buf, uint32_t bufSize ) const
Constrói uma string que descreve o nó de mesmo nível e suas 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 par, se disponível.
A disponibilidade das informações do endereço IP do ponto depende do estado e da configuração da ligação. As informações de endereço IP estão disponíveis apenas 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ó estarão disponíveis se tiverem sido definidas expressamente pelo aplicativo durante a configuração. Durante a fase de preparação, as informações do endereço estarão disponíveis quando a preparação do endereço for concluída (por exemplo, após a conclusão da resolução DNS). Depois que a vinculação estiver pronta, as informações de endereço permanecerão disponíveis até que a vinculação seja redefinida.
Detalhes | |||||||
---|---|---|---|---|---|---|---|
Parâmetros |
|
GetPeerNodeId
uint64_t GetPeerNodeId( void ) const
Recupere o id do nó do par de ligação.
Válido apenas quando o objeto de ligação for preparado.
Detalhes | |
---|---|
Devoluções | ID do nó de tecer do par |
GetProtocolLayerCallback
void GetProtocolLayerCallback( EventCallback & callback, void *& state ) const
GetState
State GetState( void ) const
Recupere o estado atual da ligação.
Detalhes | |
---|---|
Devoluções | O estado de ligação. |
IsAuthenticMessageFromPeer
bool IsAuthenticMessageFromPeer( const WeaveMessageInfo *msgInfo )
Determine se uma determinada mensagem de entrada é do par configurado e está devidamente autenticada.
Este método confirma os seguintes detalhes sobre a mensagem fornecida:
- A mensagem originada do nó par da ligação
- A mensagem foi recebida pelo mesmo tipo de transporte da ligação. Se a mensagem foi recebida por meio de uma conexão, o método também confirma que a mensagem foi recebida por meio da conexão exata associada à ligação.
- A chave e o tipo de criptografia usados para criptografar a mensagem correspondem àqueles configurados na ligação. Para ligações configuradas sem o uso de segurança, o método confirma que a mensagem recebida NÃO está criptografada.
Este método deve ser usado em protocolos como o WDM, onde os pares podem iniciar espontaneamente as trocas de volta para o nó local após uma troca inicial do nó para o par. Nesses casos, o método permite que o nó local confirme que a mensagem não solicitada recebida foi enviada pelo par associado. (Obviamente, para Bindings configurados sem o uso de criptografia de mensagem, essa afirmação não fornece nenhum valor de uma perspectiva de segurança. Ela apenas confirma que o id do nó remetente e os tipos de transporte correspondem.)
Observe que, se a ligação não estiver no estado Pronto, esse método sempre retornará falso.
Detalhes | |||
---|---|---|---|
Parâmetros |
| ||
Devoluções | Verdadeiro se a mensagem for autenticamente do par. |
IsConnectionTransport
bool IsConnectionTransport() const
Está preparando
bool IsPreparing( void ) const
Detalhes | |
---|---|
Devoluções | Verdadeiro se a Ligação estiver sendo preparada no momento. |
Está pronto
bool IsReady( void ) const
Detalhes | |
---|---|
Devoluções | Verdadeiro se a Ligação 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 de Troca para se comunicar com o par que é o destino da ligação.
Detalhes | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parâmetros |
| ||||||||
Valores Retornados |
|
Liberação
void Release( void )
Libere uma referência ao objeto de ligaçã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 o aplicativo para configurar e preparar o Binding .
O código da camada de protocolo pode usar este método em um Binding que não foi configurado, ou falhou, para acionar um evento para o aplicativo (kEvent_PrepareRequested) solicitando que ele configure e prepare o binding para uso.
Este método só pode ser chamado em Bindings nos estados NotConfigured ou Failed.
Se o aplicativo não suportar configuração / preparação sob demanda de Bindings, o método falhará com WEAVE_ERROR_NOT_IMPLEMENTED.
Redefinir
void Reset( void )
Redefina a ligaçã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 mantidos pela vinculação são liberados. Reset () coloca a ligação no estado Desconfigurado, após o qual 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 de resposta de troca padrão a ser usado ao se comunicar com o par.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
SetDefaultWRMPConfig
void SetDefaultWRMPConfig( const WRMPConfig & wrmpConfig )
Defina a configuração WRMP padrão a ser usada ao se comunicar com o par.
Detalhes | |||
---|---|---|---|
Parâmetros |
|
SetEventCallback
void SetEventCallback( EventCallback aEventCallback )
Configure a função definida pelo aplicativo a ser chamada quando ocorrer um evento de API para o Binding .
Detalhes | |||
---|---|---|---|
Parâmetros |
|
SetProtocolLayerCallback
void SetProtocolLayerCallback( EventCallback callback, void *state )
Defina uma função de retorno de chamada de evento para o código da camada de protocolo usando o Binding em nome de um aplicativo.
Essa função será chamada além da função de retorno de chamada definida pelo aplicativo quando ocorrerem eventos de API para o Binding .
Detalhes | |||||
---|---|---|---|---|---|
Parâmetros |
|
Funções estáticas públicas
DefaultEventHandler
void DefaultEventHandler( void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam )
Manipulador padrão para vincular eventos de API.
Os aplicativos são obrigados a chamar esse método para quaisquer eventos de API que eles não reconhecem ou manipulam. Os parâmetros fornecidos devem ser iguais aos passados pela vinculação à função de manipulador de eventos do aplicativo.
Detalhes | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parâmetros |
|