nl :: Tejido:: Unión
#include <src/lib/core/WeaveBinding.h>
Captura el objetivo previsto de una comunicación Weave y la información de configuración asociada.
Resumen
A Binding identifica objeto al objetivo pretendido de una comunicación de la armadura (también conocida como la "pares"), además de un conjunto de parámetros de configuración que describe cómo la comunicación con el interlocutor debe tener lugar. Los enlaces son independientes del protocolo de aplicación que se habla entre las dos partes. Como tales, capturan el "quién" y el "cómo" de una comunicación, pero no el "qué".
Las solicitudes deben configurar una unión con parámetros específicos para el tipo de canal de comunicación deseada. Los enlaces brindan soporte para una variedad de transportes de red, incluidos TCP, UDP, UDP con Weave Reliable Messaging y Weave over BLE (WoBLE). Las aplicaciones también pueden solicitar el uso de mecanismos de seguridad específicos para proteger los mensajes enviados entre las partes. Estos incluyen sesiones CASE y PASE, y claves de grupo de aplicaciones. La interfaz para la configuración de una unión utiliza un estilo declarativo API que permite a las aplicaciones afirman sus requisitos para la comunicación en términos simples.
Consulte la documentación de Encuadernación :: Configuración para más detalles.
Preparación
Antes de la comunicación que tiene lugar, una unión debe ser "preparado". El acto de la preparación de una encuadernación consiste en establecer el estado necesario para la comunicación tenga lugar. Esto puede incluir cosas como: resolver la dirección de red del par, establecer una conexión de red y negociar claves de seguridad. Una vez configurada la aplicación, la unión se encarga de todos los pasos necesarios para prepararse para la comunicación, volver a llamar a la aplicación cuando el proceso se haya completado. De esta manera, los Bindings ocultan la mecánica de la comunicación, permitiendo que las aplicaciones se concentren en las interacciones de alto nivel.
Comunicación
Una vez que una encuadernación ha sido preparado se hace listo para su uso. En este estado, las aplicaciones (o más comúnmente, el código de capa de protocolo de trabajo en nombre de una aplicación) solicitan al Encuadernación para asignar un contexto de cambio de la armadura. El contexto de intercambio resultante viene preconfigurado para la comunicación, lo que permite que la aplicación inicie inmediatamente un intercambio de Weave con el par. La aplicación puede continuar a contextos de cambio solicitud de la unión hasta que la unión está cerrada, o algún evento, por ejemplo, un fallo de red, termina el canal de comunicación subyacente.
Encuadernación Cambios de estado
En el transcurso de su uso, una unión entregará sucesos de API a la aplicación informándole de los cambios en la unión estatal 's. Por ejemplo, cuando la preparación tiene éxito, la aplicación recibirá un evento informándole de que la encuadernación está listo para su uso. Del mismo modo, si falla el canal de comunicación subyacente, un evento se entrega a la aplicación informándole de que la unión ya no está en el estado listo es.
Sucesos de API se entregan a la aplicación a través de una función de evento de devolución de llamada suministrada cuando la unión se asigna.
unión de por vida
La unión se cuentan referencia para permitir el uso compartido a través de múltiples componentes de software. Cuando una unión se asigna, se crea una sola referencia a la unión. La aplicación es responsable de la liberación de esta referencia en algún momento en el futuro, de forma que la encuadernación es libre para su posterior reutilización.
Cuando una aplicación se realiza con una unión que puede llamar a Close () en la unión. Esto libera la referencia de la aplicación de las Encuadernación y bloquea toda nueva entrega de sucesos de API. Cuando la última referencia a una encuadernación se libera, se cierra automáticamente.
Tipos públicos | |
---|---|
@23 { | enumeración |
EventCallback )(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam) | typedefvoid(* |
EventType { | enumeración |
State | enumeración |
Atributos públicos | |
---|---|
AppState | void * |
Funciones publicas | |
---|---|
AddRef (void) | void Reserve una referencia al objeto vinculante. |
AdjustResponseTimeout ( ExchangeContext *apExchangeContext) const | Vuelva a configurar un contexto de Exchange existente para ajustar el tiempo de espera de respuesta. |
AllocateRightSizedBuffer (PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize) | |
BeginConfiguration () | Siendo el proceso de configuración de la encuadernación . |
CanBePrepared (void) const | bool |
Close (void) | void Cierre el objeto de enlace y libere una referencia. |
GetConnection () const | Obtenga el objeto de conexión Weave asociado con el enlace. |
GetDefaultResponseTimeout () const | uint32_t Obtenga el tiempo de espera de respuesta de intercambio predeterminado que se utilizará al comunicarse con el par. |
GetDefaultWRMPConfig (void) const | const WRMPConfig & Obtenga la configuración WRMP predeterminada que se utilizará al comunicarse con el par. |
GetEncryptionType (void) const | uint8_t Recupere el tipo de cifrado de mensajes que se utilizará al cifrar mensajes hacia / desde el par. |
GetEventCallback () const | EventCallback Obtener la función que se llamará cuando se produce un evento API para la encuadernación . |
GetExchangeManager () const | |
GetKeyId (void) const | uint32_t Recupere la identificación de la clave de cifrado de mensajes que se utilizará al cifrar mensajes hacia / desde el par. |
GetLogId (void) const | uint16_t Obtenga una identificación única para el enlace. |
GetMaxWeavePayloadSize (const System::PacketBuffer *msgBuf) | uint32_t Obtenga el tamaño máximo de carga útil de Weave que puede caber dentro del PacketBuffer suministrado. |
GetPeerDescription (char *buf, uint32_t bufSize) const | void Construye una cadena que describe el nodo par y su dirección / información de conexión asociada. |
GetPeerIPAddress ( nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId) const | void Recupere la información de la dirección IP del par, si está disponible. |
GetPeerNodeId (void) const | uint64_t Recupere el ID de nodo del par vinculante. |
GetProtocolLayerCallback (EventCallback & callback, void *& state) const | void |
GetState (void) const | State Recupere el estado actual del enlace. |
IsAuthenticMessageFromPeer (const WeaveMessageInfo *msgInfo) | bool Determine si un mensaje entrante en particular proviene del par configurado y está debidamente autenticado. |
IsConnectionTransport () const | bool |
IsPreparing (void) const | bool |
IsReady (void) const | bool |
IsUDPTransport () const | bool |
IsUnreliableUDPTransport () const | bool |
IsWRMTransport () const | bool |
NewExchangeContext ( ExchangeContext *& appExchangeContext) | Asigne un nuevo contexto de Exchange para comunicarse con el par que es el destino del enlace. |
Release (void) | void Suelte una referencia al objeto vinculante. |
RequestPrepare () | Solicitar la aplicación para configurar y preparar la encuadernación . |
Reset (void) | void Restablezca el enlace a un estado no configurado. |
SetDefaultResponseTimeout (uint32_t msec) | void Establezca el tiempo de espera de respuesta de intercambio predeterminado que se utilizará al comunicarse con el par. |
SetDefaultWRMPConfig (const WRMPConfig & wrmpConfig) | void Establezca la configuración WRMP predeterminada que se utilizará al comunicarse con el par. |
SetEventCallback (EventCallback aEventCallback) | void Ajuste la función definida por la aplicación que se llamará cuando se produce un evento API para la encuadernación . |
SetProtocolLayerCallback (EventCallback callback, void *state) | void Establecer una función de devolución de llamada de evento para el código de capa de protocolo utilizando la unión en nombre de una aplicación. |
Funciones estáticas públicas | |
---|---|
DefaultEventHandler (void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam) | void Controlador predeterminado para vincular eventos de API. |
Clases | |
---|---|
nl :: :: Armadura Encuadernación :: Configuración | Proporciona una interfaz de estilo declarativo para configurar y preparar una encuadernación objeto. |
Estructuras | |
---|---|
nl :: :: Armadura Encuadernación :: InEventParam | Los parámetros de entrada a una encuadernación de eventos del API. |
nl :: :: Armadura Encuadernación :: OutEventParam | Los parámetros de salida a una encuadernación de eventos del API. |
Tipos públicos
@ 23
@23
Propiedades | |
---|---|
kGetPeerDescription_MaxLength | Longitud máxima de cadena (incluyendo el carácter NUL) devuelto por GetPeerDescription () . |
EventCallback
void(* EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
Tipo de evento
EventType
Expresar
State
Atributos públicos
AppState
void * AppState
Funciones publicas
AddRef
void AddRef( void )
Reserve una referencia al objeto vinculante.
AdjustResponseTimeout
WEAVE_ERROR AdjustResponseTimeout( ExchangeContext *apExchangeContext ) const
Vuelva a configurar un contexto de Exchange existente para ajustar el tiempo de espera de respuesta.
Detalles | |||
---|---|---|---|
Parámetros |
|
AllocateRightSizedBuffer
WEAVE_ERROR AllocateRightSizedBuffer( PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize )
BeginConfiguration
Configuration BeginConfiguration()
Siendo el proceso de configuración de la encuadernación .
Las aplicaciones deben llamar BeginConfiguration () para configurar la unión antes de prepararlo para la comunicación con los pares.
Detalles | |
---|---|
Devoluciones | Un Encuadernación :: Configuración de objeto que se puede utilizar para configurar la unión. |
CanBePrepared
bool CanBePrepared( void ) const
Cerca
void Close( void )
Cierre el objeto de enlace y libere una referencia.
Cuando se llama, este método hace que el enlace entre en el estado Cerrado. Se cancelan todas las acciones de preparación en curso para el enlace y se liberan todos los recursos de comunicaciones externas que tiene el enlace.
Llamar a Close () decrementa el contador de referencia asociada con la unión, liberando el objeto si el recuento de referencia se convierte en cero.
GetConnection
WeaveConnection * GetConnection() const
Obtenga el objeto de conexión Weave asociado con el enlace.
Detalles | |
---|---|
Devoluciones | Un puntero a una WeaveConnection objeto, o NULL si no hay conexión asociada con la unión. |
GetDefaultResponseTimeout
uint32_t GetDefaultResponseTimeout() const
Obtenga el tiempo de espera de respuesta de intercambio predeterminado que se utilizará al comunicarse con el par.
Detalles | |
---|---|
Devoluciones | Tiempo de espera de respuesta en ms. |
GetDefaultWRMPConfig
const WRMPConfig & GetDefaultWRMPConfig( void ) const
Obtenga la configuración WRMP predeterminada que se utilizará al comunicarse con el par.
Detalles | |
---|---|
Devoluciones | Una referencia a un WRMPConfig estructura que contiene los valores de configuración por defecto. |
GetEncryptionType
uint8_t GetEncryptionType( void ) const
Recupere el tipo de cifrado de mensajes que se utilizará al cifrar mensajes hacia / desde el par.
GetEventCallback
EventCallback GetEventCallback() const
Obtener la función que se llamará cuando se produce un evento API para la encuadernación .
Detalles | |
---|---|
Devoluciones | Un puntero a la función de devolución de llamada. |
GetExchangeManager
WeaveExchangeManager * GetExchangeManager() const
GetKeyId
uint32_t GetKeyId( void ) const
Recupere la identificación de la clave de cifrado de mensajes que se utilizará al cifrar mensajes hacia / desde el par.
GetLogId
uint16_t GetLogId( void ) const
Obtenga una identificación única para el enlace.
GetMaxWeavePayloadSize
uint32_t GetMaxWeavePayloadSize( const System::PacketBuffer *msgBuf )
Obtenga el tamaño máximo de carga útil de Weave que puede caber dentro del PacketBuffer suministrado.
Para UDP, incluido UDP con WRM, el tamaño máximo de carga útil devuelto garantizará que el mensaje Weave resultante no desborde la MTU UDP configurada.
Además, este método garantizará que la carga útil de Weave no desborde el PacketBuffer suministrado.
Detalles | |||
---|---|---|---|
Parámetros |
| ||
Devoluciones | El tamaño máximo de carga útil de Weave. |
GetPeerDescription
void GetPeerDescription( char *buf, uint32_t bufSize ) const
Construye una cadena que describe el nodo par y su dirección / información de conexión asociada.
Detalles | |||||
---|---|---|---|---|---|
Parámetros |
|
GetPeerIPAddress
void GetPeerIPAddress( nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId ) const
Recupere la información de la dirección IP del par, si está disponible.
La disponibilidad de la información de la dirección IP del par depende del estado y la configuración del enlace. La información de la dirección IP solo está disponible cuando se utiliza un transporte basado en IP (TCP, UDP o UDP con WRMP). Antes del inicio de la preparación, la información de dirección solo está disponible si la aplicación la ha configurado expresamente durante la configuración. Durante la fase de preparación, la información de la dirección está disponible cuando se completa la preparación de la dirección (por ejemplo, después de que se haya completado la resolución de DNS). Después de la encuadernación está listo, la información de dirección permanece disponible hasta que la unión se pone a cero.
Detalles | |||||||
---|---|---|---|---|---|---|---|
Parámetros |
|
GetPeerNodeId
uint64_t GetPeerNodeId( void ) const
Recupere el ID de nodo del par vinculante.
Solo válido una vez que se ha preparado el objeto vinculante
Detalles | |
---|---|
Devoluciones | ID de nodo de tejido del par |
GetProtocolLayerCallback
void GetProtocolLayerCallback( EventCallback & callback, void *& state ) const
GetState
State GetState( void ) const
Recupere el estado actual del enlace.
Detalles | |
---|---|
Devoluciones | El estado vinculante. |
IsAuthenticMessageFromPeer
bool IsAuthenticMessageFromPeer( const WeaveMessageInfo *msgInfo )
Determine si un mensaje entrante en particular proviene del par configurado y está debidamente autenticado.
Este método confirma los siguientes detalles sobre el mensaje dado:
- El mensaje se originó en el nodo par del enlace.
- El mensaje se recibió a través del mismo tipo de transporte que el enlace. Si el mensaje se recibió a través de una conexión, el método también confirma que el mensaje se recibió a través de la conexión exacta asociada con el enlace.
- La clave de cifrado y el tipo utilizados para cifrar el mensaje coinciden con los configurados en el enlace. Para enlaces configurados sin el uso de seguridad, el método confirma que el mensaje entrante NO está encriptado.
Este método está destinado a ser utilizado en protocolos como WDM donde los pares pueden iniciar intercambios de forma espontánea hacia el nodo local después de un intercambio inicial del nodo al par. En tales casos, el método permite que el nodo local confirme que el par asociado envió el mensaje no solicitado entrante. (Por supuesto, para los enlaces configurados sin el uso de cifrado de mensajes, esta afirmación no proporciona ningún valor desde una perspectiva de seguridad. Simplemente confirma que el ID del nodo remitente y los tipos de transporte coinciden).
Tenga en cuenta que si el enlace no está en el estado Listo, este método siempre devolverá falso.
Detalles | |||
---|---|---|---|
Parámetros |
| ||
Devoluciones | Verdadero si el mensaje es auténticamente del par. |
IsConnectionTransport
bool IsConnectionTransport() const
Está preparando
bool IsPreparing( void ) const
Detalles | |
---|---|
Devoluciones | Es cierto que si el Binding se está preparando actualmente. |
Está listo
bool IsReady( void ) const
Detalles | |
---|---|
Devoluciones | Es cierto que si el encuadernación es en el estado Preparado. |
IsUDPTransporte
bool IsUDPTransport() const
No es confiableUDPTransport
bool IsUnreliableUDPTransport() const
IsWRMTransport
bool IsWRMTransport() const
NewExchangeContext
WEAVE_ERROR NewExchangeContext( ExchangeContext *& appExchangeContext )
Asigne un nuevo contexto de Exchange para comunicarse con el par que es el destino del enlace.
Detalles | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parámetros |
| ||||||||
Valores devueltos |
|
Lanzamiento
void Release( void )
Suelte una referencia al objeto vinculante.
Si no hay más referencias al objeto de enlace, el enlace se cierra y se libera.
SolicitarPreparar
WEAVE_ERROR RequestPrepare()
Solicitar la aplicación para configurar y preparar la encuadernación .
Código de la capa de protocolo puede utilizar este método en una unión que no se ha configurado, o ha fallado, para desencadenar un evento para la aplicación (kEvent_PrepareRequested) solicitando que configurar y preparar la unión para su uso.
Este método solo se puede llamar en Bindings en los estados NotConfigured o Failed.
Si la aplicación no admite la configuración / preparación bajo demanda de enlaces, el método fallará con WEAVE_ERROR_NOT_IMPLEMENTED.
Reiniciar
void Reset( void )
Restablezca el enlace a un estado no configurado.
Cuando Reset () se llama, ninguna en curso preparar acciones para la unión son canceladas y todos los recursos de comunicación externa en poder de la unión se liberan. Reset () coloca la unión en el estado no configurado, después de lo cual se puede configurar y se preparó de nuevo.
Reset () no altera el cómputo de referencia de la unión.
SetDefaultResponseTimeout
void SetDefaultResponseTimeout( uint32_t msec )
Establezca el tiempo de espera de respuesta de intercambio predeterminado que se utilizará al comunicarse con el par.
Detalles | |||
---|---|---|---|
Parámetros |
|
SetDefaultWRMPConfig
void SetDefaultWRMPConfig( const WRMPConfig & wrmpConfig )
Establezca la configuración WRMP predeterminada que se utilizará al comunicarse con el par.
Detalles | |||
---|---|---|---|
Parámetros |
|
SetEventCallback
void SetEventCallback( EventCallback aEventCallback )
Ajuste la función definida por la aplicación que se llamará cuando se produce un evento API para la encuadernación .
Detalles | |||
---|---|---|---|
Parámetros |
|
SetProtocolLayerCallback
void SetProtocolLayerCallback( EventCallback callback, void *state )
Establecer una función de devolución de llamada de evento para el código de capa de protocolo utilizando la unión en nombre de una aplicación.
Esta función se llama, además de la función de devolución de llamada definido por la aplicación cuando los eventos de la API se producen para la encuadernación .
Detalles | |||||
---|---|---|---|---|---|
Parámetros |
|
Funciones estáticas públicas
DefaultEventHandler
void DefaultEventHandler( void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam )
Controlador predeterminado para vincular eventos de API.
Las aplicaciones deben llamar a este método para cualquier evento de API que no reconozcan o manejen. Los parámetros suministrados deben ser los mismos que los pasados por el enlace a la función de controlador de eventos de la aplicación.
Detalles | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parámetros |
|