En Google, luchamos por la equidad racial de la comunidad negra. Más información

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é".

Configuración

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 {
kGetPeerDescription_MaxLength = nl::Weave::kWeavePeerDescription_MaxLength
}
enumeración
EventCallback )(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam) typedef
void(*
EventType {
kEvent_ConnectionEstablished = 1,
kEvent_BindingReady = 2,
kEvent_PrepareFailed = 3,
kEvent_BindingFailed = 4,
kEvent_PrepareRequested = 5,
kEvent_PASEParametersRequested = 6,
kEvent_TAKEParametersRequested = 7,
kEvent_DefaultCheck = 100
}
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
Propiedades
kEvent_BindingFailed

El enlace falló y ya no se puede usar para comunicarse con el par.

kEvent_BindingReady

La acción de preparación en el enlace se realizó correctamente y el enlace ahora se puede utilizar para comunicarse con el par.

kEvent_ConnectionEstablished

Se ha establecido la conexión Weave solicitada.

kEvent_DefaultCheck

Se utiliza para verificar el correcto manejo de eventos predeterminado en la aplicación.

kEvent_PASEParametersRequested

Se solicita a la aplicación que proporcione los parámetros que se utilizarán durante el establecimiento de la sesión PASE.

kEvent_PrepareFailed

La acción de preparación en el enlace falló.

kEvent_PrepareRequested

Se solicita a la aplicación que configure y prepare el enlace para que lo utilice la pila de red.

kEvent_TAKEParametersRequested

Se solicita a la aplicación que proporcione los parámetros que se utilizarán durante el establecimiento de la sesión TAKE.

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
[in] apExchangeContext
Un puntero a un objeto de contexto de Exchange que se va a volver a configurar

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
[in] msgBuf
Un puntero al PacketBuffer en el que se escribirá la carga útil del mensaje.
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
[in] buf
Un puntero a un búfer en el que se debe escribir la cadena. El búfer proporcionado debe ser al menos tan grande como kGetPeerDescription_MaxLength. Si se proporciona un búfer más pequeño, la cadena se truncará para que quepa. La salida incluirá un carácter de terminación NUL en todos los casos.
[in] bufSize
El tamaño del búfer al que apunta buf.

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
[out] address
Una referencia a un objeto IPAddress que recibirá la dirección IP del par. Si la dirección IP del otro extremo no está disponible, este valor se establece en DirecciónIP :: Cualquier .
[out] port
Una referencia a un número entero que recibirá el número de puerto del par. Si la información de la dirección IP del par no está disponible, este valor no está definido.
[out] interfaceId
Una referencia a un número entero que recibirá la identificación de la interfaz de red a través de la cual se puede llegar al par. Si la información de la dirección IP del par no está disponible, este valor no está definido.

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
[in] msgInfo
La información del mensaje de tejido para el mensaje entrante.
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
[out] appExchangeContext
Una referencia a un puntero que recibirá el objeto Contexto de Exchange recién asignado. El puntero se establecerá en NULL en caso de que el método falle.
Valores devueltos
WEAVE_NO_ERROR
Si el contexto de intercambio se asignó correctamente.
WEAVE_ERROR_NO_MEMORY
Si no hay memoria disponible para asignar el contexto de intercambio.
WEAVE_ERROR_INCORRECT_STATE
Si el enlace no está en estado Listo.
other
Otros errores relacionados con la configuración del contexto de intercambio en función de la configuración del enlace.

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
[in] timeout
El nuevo tiempo de espera de respuesta en ms.

SetDefaultWRMPConfig

void SetDefaultWRMPConfig(
  const WRMPConfig & wrmpConfig
)

Establezca la configuración WRMP predeterminada que se utilizará al comunicarse con el par.

Detalles
Parámetros
[in] aWRMPConfig
Una referencia a un WRMPConfig estructura que contiene la nueva configuración predeterminada.

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
[in] aEventCallback
Un puntero a la función de devolución de llamada.

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
[in] callback
Un puntero a la función de devolución de llamada.
[in] state
Un puntero a un objeto de estado que se suministrará al código de la capa de protocolo cuando se produzca una devolución de llamada de la capa de protocolo.

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
[in] apAppState
Un puntero a la información de estado definida por la aplicación asociada con el enlace.
[in] aEvent
ID de evento transmitido por la devolución de llamada
[in] aInParam
Referencia de los parámetros del evento de entrada pasados ​​por la devolución de llamada del evento
[in] aOutParam
Referencia de los parámetros del evento de salida pasados ​​por la devolución de llamada del evento