nl::Weave::Binding

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

Acquisisce il target previsto di una comunicazione Weave e le informazioni di configurazione associate.

Riepilogo

Un oggetto Binding identifica il target previsto di una comunicazione Weave (noto anche come "peer"), insieme a un insieme di parametri di configurazione che descrivono come dovrebbe avvenire la comunicazione con il peer. Le associazioni sono indipendenti dal protocollo dell'applicazione parlato tra le due parti. In quanto tali, catturano il "chi" e il "come" di una comunicazione, ma non il "cosa".

Configurazione

Le applicazioni devono configurare un'associazione con parametri specifici per il tipo di canale di comunicazione desiderato. Le associazioni forniscono supporto per una serie di trasporti di rete, tra cui TCP, UDP, UDP con Weave Reliable Messaging e Weave su BLE (WoBLE). Le applicazioni possono anche richiedere l'utilizzo di meccanismi di sicurezza specifici per proteggere i messaggi scambiati tra le parti. Sono incluse le sessioni CASE e PASE e le chiavi dei gruppi di applicazioni. L'interfaccia per la configurazione di un'associazione utilizza uno stile API dichiarativo che consente alle applicazioni di dichiarare in termini semplici i requisiti per la comunicazione.

Per ulteriori dettagli, consulta la documentazione relativa a Binding::Configuration.

preparazione

Prima che le comunicazioni abbiano luogo, è necessario "preparare" un'associazione. L'atto di preparare un'associazione implica lo stabilire lo stato necessario affinché la comunicazione abbia luogo. Ciò può includere, ad esempio, la risoluzione dell'indirizzo di rete del peer, la creazione di una connessione di rete e la negoziazione dei token di sicurezza. Una volta configurata dall'applicazione, l'associazione si occupa di tutti i passaggi necessari per la preparazione alla comunicazione, richiamando l'applicazione al termine della procedura. In questo modo, le associazioni nascondono i meccanismi della comunicazione, consentendo alle applicazioni di concentrarsi sulle interazioni di alto livello.

Comunicazione

Una volta preparata, l'associazione è pronta per l'uso. In questo stato, le applicazioni (o più comunemente, il codice del livello di protocollo che funziona per conto di un'applicazione) richiedono all'Binding di allocare un contesto di scambio Weave. Il contesto di scambio risultante viene preconfigurato per la comunicazione, consentendo all'applicazione di avviare immediatamente uno scambio Weave con il peer. L'applicazione può continuare a richiedere contesti di scambio dall'associazione fino alla chiusura dell'associazione o fino a quando un evento, ad esempio un errore di rete, termina il canale di comunicazione sottostante.

Modifiche dello stato dell'associazione

Nel corso del suo utilizzo, un'associazione invierà eventi API all'applicazione che la informano delle modifiche allo stato dell'associazione. Ad esempio, al termine della preparazione, l'applicazione riceverà un evento che la informa che l'associazione è pronta per l'uso. Analogamente, se si verifica un errore nel canale di comunicazione sottostante, viene inviato un evento all'applicazione che comunica che l'associazione non è più nello stato pronto.

Gli eventi API vengono inviati all'applicazione tramite una funzione di callback dell'evento fornita al momento dell'allocazione dell'Binding.

Durata associazione

Le associazioni vengono conteggiate per consentire l'uso condiviso tra più componenti software. Quando viene allocata un'associazione, viene creato un singolo riferimento all'associazione. L'applicazione è responsabile del rilascio di questo riferimento in futuro, in modo che l'associazione sia senza costi e possa essere riutilizzata in un secondo momento.

Quando un'applicazione viene eseguita con un'Binding, può chiamare Close() nell'associazione. In questo modo viene rilasciato il riferimento dell'applicazione all'associazione e viene bloccata ogni ulteriore distribuzione degli eventi API. Quando viene rilasciato l'ultimo riferimento a un'associazione, questa viene chiusa automaticamente.

Tipi pubblici

@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

Attributi pubblici

AppState
void *

Funzioni pubbliche

AddRef(void)
void
Prenota un riferimento all'oggetto di associazione.
AdjustResponseTimeout(ExchangeContext *apExchangeContext) const
Riconfigura un contesto di Exchange esistente per modificare il timeout della risposta.
AllocateRightSizedBuffer(PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize)
BeginConfiguration()
Essere il processo di configurazione dell'associazione.
CanBePrepared(void) const
bool
Close(void)
void
Chiudi l'oggetto di associazione e rilascia un riferimento.
GetConnection() const
Recupera l'oggetto di connessione Weave associato all'associazione.
GetDefaultResponseTimeout() const
uint32_t
Ottieni il timeout predefinito della risposta della piattaforma di scambio da utilizzare per la comunicazione con il peer.
GetDefaultWRMPConfig(void) const
const WRMPConfig &
Ottieni la configurazione WRMP predefinita da utilizzare per la comunicazione con il peer.
GetEncryptionType(void) const
uint8_t
Recupera il tipo di crittografia dei messaggi da utilizzare per la crittografia dei messaggi da e verso il peer.
GetEventCallback() const
EventCallback
Ottieni la funzione che verrà chiamata quando si verifica un evento API per l'associazione.
GetExchangeManager() const
GetKeyId(void) const
uint32_t
Recupera l'ID della chiave di crittografia dei messaggi da utilizzare per la crittografia dei messaggi da e verso il peer.
GetLogId(void) const
uint16_t
Ottieni un ID univoco per l'associazione.
GetMaxWeavePayloadSize(const System::PacketBuffer *msgBuf)
uint32_t
Ottieni la dimensione massima del payload Weave che può rientrare nel PacketBuffer fornito.
GetPeerDescription(char *buf, uint32_t bufSize) const
void
Crea una stringa che descrive il nodo peer e l'indirizzo / le informazioni di connessione associati.
GetPeerIPAddress(nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId) const
void
Recupera le informazioni sull'indirizzo IP del peer, se disponibili.
GetPeerNodeId(void) const
uint64_t
Recupera l'ID nodo del peer di associazione.
GetProtocolLayerCallback(EventCallback & callback, void *& state) const
void
GetState(void) const
State
Recupera lo stato attuale dell'associazione.
IsAuthenticMessageFromPeer(const WeaveMessageInfo *msgInfo)
bool
Determina se un determinato messaggio in arrivo proviene dal peer configurato ed è correttamente autenticato.
IsConnectionTransport() const
bool
IsPreparing(void) const
bool
IsReady(void) const
bool
IsUDPTransport() const
bool
IsUnreliableUDPTransport() const
bool
IsWRMTransport() const
bool
NewExchangeContext(ExchangeContext *& appExchangeContext)
Alloca un nuovo contesto di Exchange per comunicare con il peer che è l'obiettivo dell'associazione.
Release(void)
void
Rilascia un riferimento all'oggetto di associazione.
RequestPrepare()
Richiedi all'applicazione di configurare e preparare l'associazione.
Reset(void)
void
Ripristina lo stato non configurato dell'associazione.
SetDefaultResponseTimeout(uint32_t msec)
void
Imposta il timeout predefinito della risposta della piattaforma di scambio da utilizzare per la comunicazione con il peer.
SetDefaultWRMPConfig(const WRMPConfig & wrmpConfig)
void
Imposta la configurazione WRMP predefinita da utilizzare per la comunicazione con il peer.
SetEventCallback(EventCallback aEventCallback)
void
Imposta la funzione definita dall'applicazione da chiamare quando si verifica un evento API per l'associazione.
SetProtocolLayerCallback(EventCallback callback, void *state)
void
Imposta una funzione di callback dell'evento per il codice del livello di protocollo utilizzando l'associazione per conto di un'applicazione.

Funzioni statiche pubbliche

DefaultEventHandler(void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam)
void
Gestore predefinito per l'associazione di eventi API.

Corsi

nl::Weave::Binding::Configuration

Fornisce un'interfaccia di stile dichiarativo per la configurazione e la preparazione di un oggetto Binding.

Strutture

nl::Weave::Binding::InEventParam

Parametri di input a un evento dell'API Binding.

nl::Weave::Binding::OutEventParam

Parametri di output in un evento API Binding.

Tipi pubblici

@23

 @23
Proprietà
kGetPeerDescription_MaxLength

Lunghezza massima della stringa (incluso il carattere NUL) restituita da GetPeerDescription().

EventCallback

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

EventType

 EventType
Proprietà
kEvent_BindingFailed

L'associazione non è riuscita e non può più essere utilizzata per comunicare con il peer.

kEvent_BindingReady

L'azione di preparazione sull'associazione è riuscita e ora l'associazione può essere utilizzata per comunicare con il peer.

kEvent_ConnectionEstablished

La connessione Weave richiesta è stata stabilita.

kEvent_DefaultCheck

Utilizzato per verificare la corretta gestione predefinita degli eventi nell'applicazione.

kEvent_PASEParametersRequested

L'applicazione deve fornire i parametri da utilizzare durante la creazione della sessione PASE.

kEvent_PrepareFailed

L'azione di preparazione nell'associazione non è riuscita.

kEvent_PrepareRequested

L'applicazione deve configurare e preparare l'associazione per l'utilizzo da parte dello stack di rete.

kEvent_TAKEParametersRequested

L'applicazione deve fornire parametri da utilizzare durante la creazione della sessione take.

Stato

 State

Attributi pubblici

AppState

void * AppState

Funzioni pubbliche

AddRef

void AddRef(
  void
)

Prenota un riferimento all'oggetto di associazione.

AdjustResponseTimeout

WEAVE_ERROR AdjustResponseTimeout(
  ExchangeContext *apExchangeContext
) const 

Riconfigura un contesto di Exchange esistente per modificare il timeout della risposta.

Dettagli
Parametri
[in] apExchangeContext
Un puntatore a un oggetto Contesto di Exchange da riconfigurare

AllocateRightSizedBuffer

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

BeginConfiguration

Configuration BeginConfiguration()

Essere il processo di configurazione dell'associazione.

Le applicazioni devono chiamare BeginConfiguration() per configurare l'Binding prima di prepararla per la comunicazione con il peer.

Dettagli
Restituisce
Un oggetto Binding::Configuration che può essere utilizzato per configurare l'associazione.

CanBePrepared

bool CanBePrepared(
  void
) const 

Chiudi

void Close(
  void
)

Chiudi l'oggetto di associazione e rilascia un riferimento.

Quando viene chiamato, questo metodo fa sì che l'associazione entri nello stato Chiuso. Tutte le azioni di preparazione per l'associazione in corso vengono annullate e tutte le risorse di comunicazione esterne utilizzate dall'associazione vengono svincolate.

La chiamata a Close() diminuisce il conteggio dei riferimenti associato all'associazione, liberando l'oggetto se il conteggio dei riferimenti diventa zero.

GetConnection

WeaveConnection * GetConnection() const 

Recupera l'oggetto di connessione Weave associato all'associazione.

Dettagli
Restituisce
Un puntatore a un oggetto WeaveConnection o NULL se non esiste alcuna connessione associata all'associazione.

GetDefaultResponseTimeout

uint32_t GetDefaultResponseTimeout() const 

Ottieni il timeout predefinito della risposta della piattaforma di scambio da utilizzare per la comunicazione con il peer.

Dettagli
Restituisce
Timeout risposta in ms.

GetDefaultWRMPConfig

const WRMPConfig & GetDefaultWRMPConfig(
  void
) const 

Ottieni la configurazione WRMP predefinita da utilizzare per la comunicazione con il peer.

Dettagli
Restituisce
Un riferimento a una struttura WRMPConfig contenente i valori di configurazione predefiniti.

GetEncryptionType

uint8_t GetEncryptionType(
  void
) const 

Recupera il tipo di crittografia dei messaggi da utilizzare per la crittografia dei messaggi da e verso il peer.

GetEventCallback

EventCallback GetEventCallback() const 

Ottieni la funzione che verrà chiamata quando si verifica un evento API per l'associazione.

Dettagli
Restituisce
Un puntatore alla funzione di callback.

GetExchangeManager

WeaveExchangeManager * GetExchangeManager() const 

GetKeyId

uint32_t GetKeyId(
  void
) const 

Recupera l'ID della chiave di crittografia dei messaggi da utilizzare per la crittografia dei messaggi da e verso il peer.

GetLogId

uint16_t GetLogId(
  void
) const 

Ottieni un ID univoco per l'associazione.

GetMaxWeavePayloadSize

uint32_t GetMaxWeavePayloadSize(
  const System::PacketBuffer *msgBuf
)

Ottieni la dimensione massima del payload Weave che può rientrare nel PacketBuffer fornito.

Per UDP, incluso UDP con WRM, la dimensione massima del payload restituita garantirà che il messaggio Weave risultante non superi la MTU UDP configurata.

Inoltre, questo metodo garantisce che il payload Weave non superi il PacketBuffer specificato.

Dettagli
Parametri
[in] msgBuf
Un puntatore al PacketBuffer in cui verrà scritto il payload del messaggio.
Restituisce
La dimensione massima del payload Weave.

GetPeerDescription

void GetPeerDescription(
  char *buf,
  uint32_t bufSize
) const 

Crea una stringa che descrive il nodo peer e l'indirizzo / le informazioni di connessione associati.

Dettagli
Parametri
[in] buf
Un puntatore a un buffer in cui deve essere scritta la stringa. Il buffer fornito deve avere dimensioni minime pari a kGetPeerDescription_MaxLength. Se viene fornito un buffer più piccolo, la stringa verrà troncata per adattarla. L'output includerà un carattere di terminazione NUL in tutti i casi.
[in] bufSize
La dimensione del buffer a cui punta il buf.

GetPeerIPAddress

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

Recupera le informazioni sull'indirizzo IP del peer, se disponibili.

La disponibilità delle informazioni sull'indirizzo IP del peer dipende dallo stato e dalla configurazione dell'associazione. Le informazioni sull'indirizzo IP sono disponibili solo quando si utilizza un trasporto basato su IP (TCP, UDP o UDP con WRMP). Prima dell'inizio della preparazione, le informazioni sull'indirizzo sono disponibili solo se sono state impostate espressamente dall'applicazione durante la configurazione. Durante la fase di preparazione, le informazioni sull'indirizzo sono disponibili al termine della preparazione dell'indirizzo (ad es. al termine della risoluzione DNS). Quando l'associazione è pronta, le informazioni sull'indirizzo rimangono disponibili fino alla reimpostazione dell'associazione.

Dettagli
Parametri
[out] address
Un riferimento a un oggetto IPAddress che riceverà l'indirizzo IP del peer. Se le informazioni sull'indirizzo IP del peer non sono disponibili, questo valore verrà impostato su IPAddress::Any.
[out] port
Un riferimento a un numero intero che riceverà il numero di porta del peer. Se le informazioni sull'indirizzo IP del peer non sono disponibili, questo valore non è definito.
[out] interfaceId
Un riferimento a un numero intero che riceverà l'ID dell'interfaccia di rete tramite la quale è possibile raggiungere il peer. Se le informazioni sull'indirizzo IP del peer non sono disponibili, questo valore non è definito.

GetPeerNodeId

uint64_t GetPeerNodeId(
  void
) const 

Recupera l'ID nodo del peer di associazione.

Valido solo dopo la preparazione dell'oggetto di associazione.

Dettagli
Restituisce
ID nodo Weave del peer

GetProtocolLayerCallback

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

GetState

State GetState(
  void
) const 

Recupera lo stato attuale dell'associazione.

Dettagli
Restituisce
Lo stato di associazione.

IsAuthenticMessageFromPeer

bool IsAuthenticMessageFromPeer(
  const WeaveMessageInfo *msgInfo
)

Determina se un determinato messaggio in arrivo proviene dal peer configurato ed è correttamente autenticato.

Questo metodo conferma i seguenti dettagli relativi al messaggio specificato:

  • Il messaggio ha avuto origine dal nodo peer dell'associazione
  • Il messaggio è stato ricevuto con lo stesso tipo di trasporto dell'associazione. Se il messaggio è stato ricevuto tramite una connessione, il metodo conferma anche che il messaggio sia stato ricevuto tramite la connessione esatta associata all'associazione.
  • La chiave e il tipo di crittografia utilizzati per criptare il messaggio corrispondono a quelli configurati nell'associazione. Per le associazioni configurate senza l'utilizzo della sicurezza, il metodo conferma che il messaggio in arrivo NON è criptato.

Questo metodo è pensato per essere utilizzato in protocolli come WDM, in cui i peer possono avviare spontaneamente scambi di ritorno al nodo locale dopo uno scambio iniziale dal nodo al peer. In questi casi, il metodo consente al nodo locale di confermare che il messaggio non richiesto in arrivo è stato inviato dal peer associato. (Ovviamente, per le associazioni configurate senza l'utilizzo della crittografia dei messaggi, questa asserzione non fornisce alcun valore dal punto di vista della sicurezza. Conferma semplicemente che l'ID nodo del mittente e i tipi di trasporto corrispondono.

Tieni presente che se l'associazione non è in stato Pronto, questo metodo restituirà sempre false.

Dettagli
Parametri
[in] msgInfo
Le informazioni del messaggio Weave per il messaggio in arrivo.
Restituisce
True se il messaggio proviene in modo autentico dal peer.

IsConnectionTransport

bool IsConnectionTransport() const 

IsPreparing

bool IsPreparing(
  void
) const 

Dettagli
Restituisce
True se l'Associazione è attualmente in fase di preparazione.

IsReady

bool IsReady(
  void
) const 

Dettagli
Restituisce
True se l'Associazione è nello stato Pronto.

IsUDPTransport

bool IsUDPTransport() const 

IsUnreliableUDPTransport

bool IsUnreliableUDPTransport() const 

IsWRMTransport

bool IsWRMTransport() const 

NewExchangeContext

WEAVE_ERROR NewExchangeContext(
  ExchangeContext *& appExchangeContext
)

Alloca un nuovo contesto di Exchange per comunicare con il peer che è l'obiettivo dell'associazione.

Dettagli
Parametri
[out] appExchangeContext
Un riferimento a un puntatore che riceverà l'oggetto Contesto di Exchange appena allocato. Il puntatore verrà impostato su NULL nel caso in cui il metodo non funzioni.
Valori restituiti
WEAVE_NO_ERROR
Se il contesto della piattaforma di scambio è stato allocato correttamente.
WEAVE_ERROR_NO_MEMORY
Se non era disponibile alcuna memoria per allocare il contesto di Exchange.
WEAVE_ERROR_INCORRECT_STATE
Se l'associazione non è in stato Pronto.
other
Altri errori relativi alla configurazione del contesto di Exchange in base alla configurazione dell'associazione.

Release

void Release(
  void
)

Rilascia un riferimento all'oggetto di associazione.

Se non esistono altri riferimenti all'oggetto di associazione, l'associazione viene chiusa e liberata.

RequestPrepare

WEAVE_ERROR RequestPrepare()

Richiedi all'applicazione di configurare e preparare l'associazione.

Il codice del livello di protocollo può utilizzare questo metodo su un'associazione che non è stata configurata o che non è riuscita ad attivare un evento per l'applicazione (kEvent_PrepareRequested) per richiedere la configurazione e la preparazione dell'associazione per l'utilizzo.

Questo metodo può essere chiamato solo sulle associazioni in stato NotConfigurato o Non riuscito.

Se l'applicazione non supporta la configurazione/preparazione on demand delle associazioni, il metodo non riuscirà con WEAVE_ERROR_NOT_IMPLEMENTED.

Reimposta

void Reset(
  void
)

Ripristina lo stato non configurato dell'associazione.

Quando viene richiamata la funzione Reset(), tutte le azioni di preparazione per l'associazione in corso vengono annullate e tutte le risorse di comunicazione esterne conservate dall'associazione vengono rilasciate. Reset() imposta l'associazione nello stato Non configurato, dopodiché può essere configurata e preparata di nuovo.

Reset() non modifica il conteggio dei riferimenti dell'associazione.

SetDefaultResponseTimeout

void SetDefaultResponseTimeout(
  uint32_t msec
)

Imposta il timeout predefinito della risposta della piattaforma di scambio da utilizzare per la comunicazione con il peer.

Dettagli
Parametri
[in] timeout
Il nuovo timeout della risposta in ms.

SetDefaultWRMPConfig

void SetDefaultWRMPConfig(
  const WRMPConfig & wrmpConfig
)

Imposta la configurazione WRMP predefinita da utilizzare per la comunicazione con il peer.

Dettagli
Parametri
[in] aWRMPConfig
Un riferimento a una struttura WRMPConfig contenente la nuova configurazione predefinita.

SetEventCallback

void SetEventCallback(
  EventCallback aEventCallback
)

Imposta la funzione definita dall'applicazione da chiamare quando si verifica un evento API per l'associazione.

Dettagli
Parametri
[in] aEventCallback
Un puntatore alla funzione di callback.

SetProtocolLayerCallback

void SetProtocolLayerCallback(
  EventCallback callback,
  void *state
)

Imposta una funzione di callback dell'evento per il codice del livello di protocollo utilizzando l'associazione per conto di un'applicazione.

Questa funzione verrà chiamata in aggiunta alla funzione di callback definita dall'applicazione quando si verificano eventi API per l'associazione.

Dettagli
Parametri
[in] callback
Un puntatore alla funzione di callback.
[in] state
Un puntatore a un oggetto di stato che verrà fornito al codice del livello di protocollo quando si verifica un callback di livello di protocollo.

Funzioni statiche pubbliche

DefaultEventHandler

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

Gestore predefinito per l'associazione di eventi API.

Le applicazioni devono chiamare questo metodo per tutti gli eventi API che non riconoscono o non gestiscono. I parametri forniti devono essere gli stessi passati dall'associazione alla funzione gestore di eventi dell'applicazione.

Dettagli
Parametri
[in] apAppState
Un puntatore alle informazioni sullo stato definite dall'applicazione associate all'associazione.
[in] aEvent
ID evento trasmesso dal callback dell'evento
[in] aInParam
Riferimento dei parametri evento di input passati dal callback dell'evento
[in] aOutParam
Riferimento dei parametri evento di output passati dal callback dell'evento