En Google, luchamos por la equidad racial de la comunidad negra. Más información
Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

nl::Weave::Vinculación

#include <src/lib/core/WeaveBinding.h>

Captura el destino previsto de una comunicación de 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 conocida como "peer"); junto con un conjunto de parámetros de configuración que describen cómo se debería realizar la comunicación con el par. Las vinculaciones son independientes del protocolo de aplicaciones que se habla entre las dos partes. Como tales, capturan el "quién", el "cómo" y el "cómo" de una comunicación, pero no el "qué"

Configuration

Las aplicaciones deben configurar una Binding con parámetros específicos para el tipo de canal de comunicación deseado. Las vinculaciones proporcionan compatibilidad con un rango de transportes de red, incluidos TCP, UDP, UDP con Weave Reliable Messaging, y Weave sobre BLE (WoBLE). Las aplicaciones también pueden solicitar el uso de mecanismos de seguridad específicos para proteger los mensajes enviados entre las partes. Esto incluye las sesiones CASE y PASE, y las claves de grupo de aplicaciones. La interfaz para configurar una Binding usa un estilo de API declarativo que permite a las aplicaciones establecer sus requisitos para la comunicación en términos simples.

Consulta la documentación de Binding::Configuration para obtener más detalles.

Preparación

Antes de la comunicación, una vinculación debe estar preparada. El acto de preparar una vinculación implica establecer el estado necesario para que se realice la comunicación. Esto puede incluir lo siguiente: resolver la dirección de red del par, establecer una conexión de red y negociar las llaves de seguridad. Una vez configurada por la aplicación, la vinculación se encarga de todos los pasos necesarios para prepararse para la comunicación y vuelve a llamar a la aplicación cuando se completa el proceso. De esta manera, las vinculaciones ocultan la mecánica de la comunicación, lo que permite que las aplicaciones se concentren en las interacciones de alto nivel.

Comunicación

Una vez que se prepara una vinculación, está lista para usarse. En este estado, las aplicaciones (o, más comúnmente, el código de la capa de protocolo que funciona en nombre de una aplicación) solicitan la vinculación para asignar un contexto de intercambio de Weave. El contexto de intercambio resultante viene preconfigurado para la comunicación, lo que permite que la aplicación inicie de inmediato un intercambio de Weave con el par. La aplicación puede seguir solicitando contextos de intercambio desde la vinculación hasta que la vinculación se cierre, o bien algún evento, p.ej., un error de red, finalice el canal de comunicación subyacente.

Cambios de estado de Binding

Durante el uso, una Binding enviará eventos de API a la aplicación para informarle sobre cambios en el estado de Binding. Por ejemplo, cuando se realice correctamente la preparación, la aplicación recibirá un evento que le informará que la vinculación está lista para usarse. De manera similar, si el canal de comunicación subyacente falla, se entrega un evento a la aplicación para informarle que la vinculación ya no está en el estado listo.

Los eventos de la API se entregan a la aplicación a través de una función de devolución de llamada de eventos que se proporciona cuando se asigna la vinculación.

Duración de la vinculación

Las vinculaciones son recuentos de referencias que permiten el uso compartido en varios componentes de software. Cuando se asigna una vinculación, se crea una sola referencia a la vinculación. La aplicación es responsable de lanzar esta referencia en algún momento a fin de que la Binding sea gratuita para su reutilización posterior.

Cuando se completa una aplicación con una Binding, puede llamar a Close() en la vinculación. De esta manera, se libera la referencia de la aplicación a la Binding y se bloquea toda la entrega de eventos de la API. Cuando se libera la última referencia a una Binding, esta se cierra automáticamente.

Tipos públicos

@23{
  kGetPeerDescription_MaxLength = nl::Weave::kWeavePeerDescription_MaxLength
}
enum
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
}
enum
State enum

Atributos públicos

AppState
void *

Funciones públicas

AddRef(void)
void
Reserva una referencia al objeto de vinculación.
AdjustResponseTimeout(ExchangeContext *apExchangeContext) const
Vuelve 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()
Es el proceso de configuración de la vinculación.
CanBePrepared(void) const
bool
Close(void)
void
Cierra el objeto de vinculación y libera una referencia.
GetConnection() const
Obtén el objeto de conexión de Weave asociado con la vinculación.
GetDefaultResponseTimeout() const
uint32_t
Obtén el tiempo de espera predeterminado de respuesta de intercambio que se usará cuando te comuniques con el par.
GetDefaultWRMPConfig(void) const
const WRMPConfig &
Obtén la configuración predeterminada de WRMP que se usará cuando te comuniques con el par.
GetEncryptionType(void) const
uint8_t
Recupera el tipo de encriptación de mensajes que se usará cuando se encripten los mensajes hacia o desde el par.
GetEventCallback() const
EventCallback
Obtén la función que se llamará cuando se produzca un evento de API para la vinculación.
GetExchangeManager() const
GetKeyId(void) const
uint32_t
Recupera el ID de la clave de encriptación de mensajes que se usará para encriptar los mensajes hacia y desde el par.
GetLogId(void) const
uint16_t
Obtén un ID único para la vinculación.
GetMaxWeavePayloadSize(const System::PacketBuffer *msgBuf)
uint32_t
Obtén el tamaño máximo de la carga útil de Weave que puede caber dentro del PacketBuffer proporcionado.
GetPeerDescription(char *buf, uint32_t bufSize) const
void
Construye una string que describe el nodo de intercambio de tráfico y la dirección o información de conexión asociada.
GetPeerIPAddress(nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId) const
void
Recupera la información de dirección IP del par, si está disponible.
GetPeerNodeId(void) const
uint64_t
Recupera el ID del nodo del par de vinculación.
GetProtocolLayerCallback(EventCallback & callback, void *& state) const
void
GetState(void) const
State
Recupera el estado actual de la vinculación.
IsAuthenticMessageFromPeer(const WeaveMessageInfo *msgInfo)
bool
Determina si un mensaje entrante específico es del par configurado y está autenticado de forma adecuada.
IsConnectionTransport() const
bool
IsPreparing(void) const
bool
IsReady(void) const
bool
IsUDPTransport() const
bool
IsUnreliableUDPTransport() const
bool
IsWRMTransport() const
bool
NewExchangeContext(ExchangeContext *& appExchangeContext)
Asigna un nuevo contexto de intercambio para comunicarte con el par que es el destino de la vinculación.
Release(void)
void
Libera una referencia al objeto de vinculación.
RequestPrepare()
Solicite a la aplicación que configure y prepare la vinculación.
Reset(void)
void
Restablece la vinculación a un estado no configurado.
SetDefaultResponseTimeout(uint32_t msec)
void
Establece el tiempo de espera predeterminado de respuesta de intercambio que se usará cuando te comuniques con el par.
SetDefaultWRMPConfig(const WRMPConfig & wrmpConfig)
void
Establece la configuración predeterminada de WRMP que se usará cuando te comuniques con el par.
SetEventCallback(EventCallback aEventCallback)
void
Configura la función definida por la aplicación que se llamará cuando se produzca un evento de API para la vinculación.
SetProtocolLayerCallback(EventCallback callback, void *state)
void
Configure una función de devolución de llamada de eventos para el código de la capa de protocolo mediante la vinculació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::Weave::Vinculación::Configuración

Proporciona una interfaz de estilo declarativo para configurar y preparar un objeto Binding.

Structs

nl::Weave::Vinculación::InEventParam

Los parámetros de entrada para un evento de la API de Binding.

nl::Weave::Vinculación::OutEventParam

Los parámetros de salida para un evento de la API de Binding.

Tipos públicos

@23

 @23
Properties
kGetPeerDescription_MaxLength

Longitud máxima de la string (incluido el carácter NUL) que muestra GetPeerDescription().

EventCallback

void(* EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)

Tipo de evento

 EventType
Properties
kEvent_BindingFailed

La vinculación falló y ya no se puede usar para comunicarse con el par.

kEvent_BindingReady

La acción de preparación de la vinculación se realizó correctamente, y la vinculación ahora se puede usar para comunicarse con el par.

kEvent_ConnectionEstablished

Se estableció la conexión de Weave solicitada.

kEvent_DefaultCheck

Se utiliza para verificar la administración predeterminada de eventos en la aplicación.

kEvent_PASEParametersRequested

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

kEvent_PrepareFailed

No se pudo realizar la acción de preparación de la vinculación.

kEvent_PrepareRequested

Se solicita a la aplicación que configure y prepare la vinculación para que la use la pila de red.

kEvent_TAKEParametersRequested

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

Estado

 State

Atributos públicos

Estado de la aplicación

void * AppState

Funciones públicas

Agregar referencia

void AddRef(
  void
)

Reserva una referencia al objeto de vinculación.

Ajuste de respuesta

WEAVE_ERROR AdjustResponseTimeout(
  ExchangeContext *apExchangeContext
) const 

Vuelve a configurar un contexto de Exchange existente para ajustar el tiempo de espera de respuesta.

Detalles
Parámetros
[in] apExchangeContext
Un puntero para un objeto de contexto de intercambio que se reconfigurará

Asignar a la derecha

WEAVE_ERROR AllocateRightSizedBuffer(
  PacketBuffer *& buf,
  const uint32_t desiredSize,
  const uint32_t minSize,
  uint32_t & outMaxPayloadSize
)

ComenzarConfiguración

Configuration BeginConfiguration()

Es el proceso de configuración de la vinculación.

Las aplicaciones deben llamar a beginConfiguration() para configurar la Binding antes de prepararla para comunicarse con el par.

Detalles
Qué muestra
Un objeto Binding::Configuration que se puede usar para configurar la vinculación

Preparación

bool CanBePrepared(
  void
) const 

Cerrar

void Close(
  void
)

Cierra el objeto de vinculación y libera una referencia.

Cuando se lo llama, este método hace que la vinculación entre en el estado Closed. Se cancelan todas las acciones de preparación en curso para la vinculación y se liberan todos los recursos de comunicaciones externos que esta contenga.

Llamar a Close() disminuye el recuento de referencia asociado a la vinculación, lo cual libera el objeto si el recuento de referencia se vuelve cero.

GetConnection

WeaveConnection * GetConnection() const 

Obtén el objeto de conexión de Weave asociado con la vinculación.

Detalles
Qué muestra
Un puntero para un objeto WeaveConnection, o NULL si no hay una conexión asociada con la vinculación.

GetDefaultResponseTimeout

uint32_t GetDefaultResponseTimeout() const 

Obtén el tiempo de espera predeterminado de respuesta de intercambio que se usará cuando te comuniques con el par.

Detalles
Qué muestra
Tiempo de espera de respuesta en ms.

GetDefaultWRMPConfig.

const WRMPConfig & GetDefaultWRMPConfig(
  void
) const 

Obtén la configuración predeterminada de WRMP que se usará cuando te comuniques con el par.

Detalles
Qué muestra
Una referencia a una estructura WRMPConfig que contiene los valores de configuración predeterminados.

Tipo de encriptación

uint8_t GetEncryptionType(
  void
) const 

Recupera el tipo de encriptación de mensajes que se usará cuando se encripten los mensajes hacia o desde el par.

GetEventCallback

EventCallback GetEventCallback() const 

Obtén la función que se llamará cuando se produzca un evento de API para la vinculación.

Detalles
Qué muestra
Un puntero para la función de devolución de llamada.

GetExchangeManager.

WeaveExchangeManager * GetExchangeManager() const 

ID de getKey

uint32_t GetKeyId(
  void
) const 

Recupera el ID de la clave de encriptación de mensajes que se usará para encriptar los mensajes hacia y desde el par.

GetLogId

uint16_t GetLogId(
  void
) const 

Obtén un ID único para la vinculación.

GetMaxWeavePayloadSize

uint32_t GetMaxWeavePayloadSize(
  const System::PacketBuffer *msgBuf
)

Obtén el tamaño máximo de la carga útil de Weave que puede caber dentro del PacketBuffer proporcionado.

Para UDP, incluido UDP con WRM, el tamaño máximo de la carga útil que se muestra garantizará que el mensaje de Weave resultante no supere la MTU de UDP configurada.

Además, este método garantizará que la carga útil de Weave no sobrepase el PacketBuffer proporcionado.

Detalles
Parámetros
[in] msgBuf
Un puntero para el PacketBuffer a la que se escribirá la carga útil del mensaje.
Qué muestra
Tamaño máximo de la carga útil de Weave.

GetPeerDescription

void GetPeerDescription(
  char *buf,
  uint32_t bufSize
) const 

Construye una string que describe el nodo de intercambio de tráfico y la dirección o información de conexión asociada.

Detalles
Parámetros
[in] buf
Un puntero para un búfer en el que se debe escribir la string. El búfer suministrado debe ser al menos tan grande como kGetPeerDescription_MaxLength. Si se proporciona un búfer más pequeño, la string se truncará para que quepa. El resultado incluirá un carácter de terminación NUL en todos los casos.
[in] bufSize
Tamaño del búfer al que apunta un búfer.

ObtenerDirección IP

void GetPeerIPAddress(
  nl::Inet::IPAddress & address,
  uint16_t & port,
  InterfaceId & interfaceId
) const 

Recupera la información de dirección IP del par, si está disponible.

La disponibilidad de la información de dirección IP de par depende del estado y la configuración de la vinculación. La información de dirección IP solo está disponible cuando se usa un transporte basado en IP (TCP, UDP o UDP con WRMP). Antes de comenzar la preparación, la información de dirección solo está disponible si la aplicación la estableció explícitamente durante la configuración. Durante la fase de preparación, la información de dirección está disponible cuando se completa la dirección (p.ej., después de que se completa la resolución de DNS). Una vez que la vinculación esté lista, la información de la dirección permanecerá disponible hasta que se restablezca la vinculación.

Detalles
Parámetros
[out] address
Una referencia a un objeto de IPAddress que recibirá la dirección IP de par. Si la información de la dirección IP de par no está disponible, el valor se establecerá como IPAddress::Any.
[out] port
Una referencia a un número entero que recibirá el número de puerto de par. Si la información de la dirección IP de par no está disponible, este valor no está definido.
[out] interfaceId
Una referencia a un número entero que recibirá el ID de la interfaz de red a través del cual se puede alcanzar el par. Si la información de la dirección IP de par no está disponible, este valor no está definido.

ID de GetPeerNode

uint64_t GetPeerNodeId(
  void
) const 

Recupera el ID del nodo del par de vinculación.

Solo es válido una vez que se prepara el objeto de vinculación.

Detalles
Qué muestra
ID del nodo de Weave

GetProtocolLayerCallback

void GetProtocolLayerCallback(
  EventCallback & callback,
  void *& state
) const 

Obtener estado

State GetState(
  void
) const 

Recupera el estado actual de la vinculación.

Detalles
Qué muestra
El estado de vinculación.

IsAuthenticMessageFromPeer

bool IsAuthenticMessageFromPeer(
  const WeaveMessageInfo *msgInfo
)

Determina si un mensaje entrante específico es del par configurado y está autenticado de forma adecuada.

Este método confirma los siguientes detalles sobre el mensaje dado:

  • El mensaje se originó del nodo de par de la vinculación.
  • El mensaje se recibió en el mismo tipo de transporte que la vinculación. Si el mensaje se recibió a través de una conexión, el método también confirma que se recibió a través de la conexión exacta asociada con la vinculación.
  • La clave y el tipo de encriptación que se usan para encriptar el mensaje coinciden con los que se configuraron en la vinculación. En el caso de las vinculaciones configuradas sin usar la seguridad, el método confirma que el mensaje entrante NO está encriptado.

Este método está diseñado para usarse en protocolos como WDM, en donde los pares pueden iniciar espontáneamente intercambios con el nodo local después de un intercambio inicial entre nodos. En estos casos, el método permite que el nodo local confirme que el par asociado envió el mensaje no solicitado entrante. (Por supuesto, para Bindings configurada sin el uso de encriptación de mensaje, esta aserción no proporciona valor desde la perspectiva de seguridad. Solo confirma que el ID del nodo remitente y los tipos de transporte coinciden).

Ten en cuenta que, si la vinculación no tiene el estado Ready, este método siempre mostrará el valor "false".

Detalles
Parámetros
[in] msgInfo
Información de mensaje de Weave para el mensaje entrante.
Qué muestra
Verdadero si el mensaje es auténtico del par.

IsConnectionTransport

bool IsConnectionTransport() const 

En preparación

bool IsPreparing(
  void
) const 

Detalles
Qué muestra
Verdadero si actualmente se está preparando el Binding.

Está listo

bool IsReady(
  void
) const 

Detalles
Qué muestra
Se asigna el valor true si la Binding tiene el estado Listo.

Transporte_UDP

bool IsUDPTransport() const 

IsUnreliableUDPTransport (en inglés)

bool IsUnreliableUDPTransport() const 

IsWRMTransport

bool IsWRMTransport() const 

Contexto nuevo de intercambio

WEAVE_ERROR NewExchangeContext(
  ExchangeContext *& appExchangeContext
)

Asigna un nuevo contexto de intercambio para comunicarte con el par que es el destino de la vinculación.

Detalles
Parámetros
[out] appExchangeContext
Una referencia a un puntero que recibirá el objeto de Contexto de Exchange asignado recientemente. El puntero se establecerá en NULL en el caso de que falle el método.
Valores que se muestran
WEAVE_NO_ERROR
Si el contexto de intercambio se asignó de forma correcta.
WEAVE_ERROR_NO_MEMORY
Si no había memoria disponible para asignar el contexto de intercambio.
WEAVE_ERROR_INCORRECT_STATE
Si la vinculación no está en el estado Listo.
other
Otros errores relacionados con la configuración del contexto de intercambio basados en la configuración de la vinculación.

Lanzar

void Release(
  void
)

Libera una referencia al objeto de vinculación.

Si no hay más referencias al objeto de vinculación, la vinculación se cierra y se libera.

Solicitar preparación

WEAVE_ERROR RequestPrepare()

Solicite a la aplicación que configure y prepare la vinculación.

El código de la capa de protocolo puede usar este método en una Binding que no se configuró o que falló a fin de activar un evento para la aplicación (kEvent_PrepareRequested) a fin de solicitarle que configure y prepare la vinculación para usarla.

Solo se puede llamar a este método en vinculaciones en los estados NotConfigured o Fallido.

Si la aplicación no admite la configuración o preparación a pedido de las vinculaciones, el método fallará con WEAVE_ERROR_NOT_IMPLEMENTED.

Restablecer

void Reset(
  void
)

Restablece la vinculación a un estado no configurado.

Cuando se llama a Reset(), se cancelan todas las acciones de preparación en curso para la vinculación y se liberan todos los recursos de comunicaciones externos que esta contenga. Reset() establece la vinculación en el estado UnUnized, después de lo cual puede volver a configurarse y prepararse.

Reset() no modifica el recuento de referencias de la vinculación.

SetDefaultResponseTimeout

void SetDefaultResponseTimeout(
  uint32_t msec
)

Establece el tiempo de espera predeterminado de respuesta de intercambio que se usará cuando te comuniques con el par.

Detalles
Parámetros
[in] timeout
El nuevo tiempo de espera de respuesta en ms.

SetDefaultWRMPConfig.

void SetDefaultWRMPConfig(
  const WRMPConfig & wrmpConfig
)

Establece la configuración predeterminada de WRMP que se usará cuando te comuniques con el par.

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

SetEventCallback

void SetEventCallback(
  EventCallback aEventCallback
)

Configura la función definida por la aplicación que se llamará cuando se produzca un evento de API para la vinculación.

Detalles
Parámetros
[in] aEventCallback
Un puntero para la función de devolución de llamada.

SetProtocolLayerCallback

void SetProtocolLayerCallback(
  EventCallback callback,
  void *state
)

Configure una función de devolución de llamada de eventos para el código de la capa de protocolo mediante la vinculación en nombre de una aplicación.

Se llamará a esta función además de la función de devolución de llamada definida por la aplicación cuando se produzcan eventos de API para la vinculación.

Detalles
Parámetros
[in] callback
Un puntero para la función de devolución de llamada.
[in] state
Un puntero para un objeto de estado que se brindará al código de la capa de protocolo cuando se realice 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 la API que no reconozcan ni manejen. Los parámetros proporcionados deben ser los mismos que los que se pasan por la vinculación con la función del controlador de eventos de la aplicación.

Detalles
Parámetros
[in] apAppState
Un puntero para la información de estado definida por la aplicación asociada con la vinculación.
[in] aEvent
ID de evento pasado por la devolución de llamada de evento
[in] aInParam
Referencia de los parámetros de eventos de entrada que pasa la devolución de llamada de eventos.
[in] aOutParam
Referencia de los parámetros de eventos de salida que pasa la devolución de llamada de eventos.