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
Un objeto Binding identifica el objetivo previsto de una comunicación de Weave (también conocido como "par"), junto con un conjunto de parámetros de configuración que describen cómo debe tener lugar la comunicación con el par. 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 aplicaciones deben configurar un Binding con parámetros específicos al tipo de canal de comunicación deseado. 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 grupos de aplicaciones. La interfaz para configurar un enlace utiliza un estilo API declarativo que permite que las aplicaciones establezcan sus requisitos para la comunicación en términos simples.
Consulte la documentación de Binding :: Configuration para obtener más detalles.
Preparación
Antes de que tenga lugar la comunicación, se debe "preparar" un enlace . El acto de preparar un Enlace implica establecer el estado necesario para que se produzca la comunicación. 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 configurado por la aplicación, el enlace se encarga de todos los pasos necesarios para prepararse para la comunicación, volviendo a llamar a la aplicación cuando se completa el proceso. 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 se ha preparado una encuadernación , está lista para su uso. En este estado, las aplicaciones (o más comúnmente, el código de la capa de protocolo que trabaja en nombre de una aplicación) solicitan al enlace que asigne un contexto de intercambio de tejido. 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 solicitando contextos de intercambio de la vinculación hasta que se cierre la vinculación , o algún evento, por ejemplo, un fallo de red, finalice el canal de comunicación subyacente.
Cambios de estado vinculantes
Durante el transcurso de su uso, un enlace entregará eventos de API a la aplicación informándole de los cambios en el estado del enlace . Por ejemplo, cuando la preparación tiene éxito, la aplicación recibirá un evento informándole que el enlace está listo para su uso. De manera similar, si falla el canal de comunicación subyacente, se envía un evento a la aplicación informándole que el enlace ya no está en el estado listo.
Los eventos de la API se envían a la aplicación a través de una función de devolución de llamada de eventos proporcionada cuando se asigna el enlace .
Enlace de por vida
Los enlaces se cuentan por referencias para permitir el uso compartido entre varios componentes de software. Cuando una unión se asigna, se crea una sola referencia a la unión. La aplicación es responsable de publicar esta referencia en algún momento en el futuro, de modo que el enlace sea gratuito para su posterior reutilización.
Cuando una aplicación termina con un enlace , puede llamar a Close () en el enlace. Esto libera la referencia de la aplicación al enlace y bloquea toda entrega adicional de eventos de API. Cuando se libera la última referencia a un enlace , 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 del Binding . |
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 Obtenga la función que se llamará cuando se produzca un evento de API para el enlace . |
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 () | Solicite la aplicación para configurar y preparar el enlace . |
Reset (void) | void Restablezca la vinculación 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 Establezca la función definida por la aplicación que se llamará cuando se produzca un evento de API para el enlace . |
SetProtocolLayerCallback (EventCallback callback, void *state) | void Establezca una función de devolución de llamada de evento para el código de la capa de protocolo utilizando el enlace 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 :: Weave :: Binding :: Configuration | Proporciona una interfaz de estilo declarativo para configurar y preparar un objeto Binding . |
Estructuras | |
---|---|
nl :: Weave :: Binding :: InEventParam | Ingrese parámetros a un evento de API de vinculación . |
nl :: Weave :: Binding :: OutEventParam | Salida de parámetros a un evento Binding API. |
Tipos públicos
@ 23
@23
Propiedades | |
---|---|
kGetPeerDescription_MaxLength | Longitud máxima de la cadena (incluido el carácter NUL) devuelta 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
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 del Binding .
Las aplicaciones deben llamar a BeginConfiguration () para configurar el enlace antes de prepararlo para comunicarse con el par.
Detalles | |
---|---|
Devoluciones | Un objeto Binding :: Configuration que se puede utilizar para configurar el enlace. |
CanBePrepared
bool CanBePrepared( void ) const
Cerrar
void Close( void )
Cierre el objeto de enlace y libere una referencia.
Cuando se llama, este método hace que el enlace entre en 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 () disminuye el recuento de referencias asociado con el enlace, liberando el objeto si el recuento de referencias se vuelve cero.
GetConnection
WeaveConnection * GetConnection() const
Obtenga el objeto de conexión Weave asociado con el enlace.
Detalles | |
---|---|
Devoluciones | Un puntero a un objeto WeaveConnection , o NULL si no hay ninguna conexión asociada con el enlace. |
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 una estructura WRMPConfig que contiene los valores de configuración predeterminados. |
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
Obtenga la función que se llamará cuando se produzca un evento de API para el enlace .
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 el UDP MTU configurado.
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 establecido 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 completa la resolución de DNS). Una vez que el enlace está listo, la información de la dirección permanece disponible hasta que se restablece el enlace .
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 espontáneamente intercambios de regreso al nodo local después de un intercambio inicial del nodo al par. En tales casos, el método permite al nodo local confirmar que el par asociado envió el mensaje no solicitado entrante. (Por supuesto, para los enlaces configurados sin el uso del 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 | Verdadero si el enlace se está preparando actualmente. |
Está listo
bool IsReady( void ) const
Detalles | |
---|---|
Devoluciones | Verdadero si el enlace está en estado Listo. |
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 objetivo 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()
Solicite la aplicación para configurar y preparar el enlace .
El código de la capa de protocolo puede utilizar este método en un enlace que no se ha configurado o que ha fallado para activar un evento en la aplicación (kEvent_PrepareRequested) solicitando que configure y prepare el enlace para su uso.
Este método solo se puede llamar en enlaces 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 la vinculación a un estado no configurado.
Cuando se llama a Reset () , se cancelan todas las acciones de preparación en curso para el enlace y se liberan todos los recursos de comunicaciones externas retenidos por el enlace. Reset () coloca el enlace en el estado No configurado, después de lo cual puede configurarse y prepararse nuevamente.
Reset () no altera el recuento de referencias del enlace.
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 )
Establezca la función definida por la aplicación que se llamará cuando se produzca un evento de API para el enlace .
Detalles | |||
---|---|---|---|
Parámetros |
|
SetProtocolLayerCallback
void SetProtocolLayerCallback( EventCallback callback, void *state )
Establezca una función de devolución de llamada de evento para el código de capa de protocolo utilizando el enlace en nombre de una aplicación.
Esta función se llamará además de la función de devolución de llamada definida por la aplicación cuando se produzcan eventos de API para el enlace .
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 |
|