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".
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{
|
enum |
EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
|
typedefvoid(*
|
EventType{
|
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:: |
Fornisce un'interfaccia di stile dichiarativo per la configurazione e la preparazione di un oggetto Binding. |
Strutture |
|
---|---|
nl:: |
Parametri di input a un evento dell'API Binding. |
nl:: |
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 |
|
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 |
|
||
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 |
|
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 |
|
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 |
|
||
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 |
|
||||||||
Valori restituiti |
|
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 |
|
SetDefaultWRMPConfig
void SetDefaultWRMPConfig( const WRMPConfig & wrmpConfig )
Imposta la configurazione WRMP predefinita da utilizzare per la comunicazione con il peer.
Dettagli | |||
---|---|---|---|
Parametri |
|
SetEventCallback
void SetEventCallback( EventCallback aEventCallback )
Imposta la funzione definita dall'applicazione da chiamare quando si verifica un evento API per l'associazione.
Dettagli | |||
---|---|---|---|
Parametri |
|
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 |
|
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 |
|