nl:: Weave:: Binding
#include <src/lib/core/WeaveBinding.h>
Erfasst das beabsichtigte Ziel einer Weave-Kommunikation und die zugehörigen Konfigurationsinformationen.
Zusammenfassung
Ein Binding-Objekt identifiziert das beabsichtigte Ziel einer Weave-Kommunikation (auch als "Peer" bezeichnet) zusammen mit einer Reihe von Konfigurationsparametern, die beschreiben, wie die Kommunikation mit dem Peer stattfinden soll. Bindungen sind unabhängig vom Anwendungsprotokoll, das zwischen den beiden Parteien gesprochen wird. Daher erfassen sie das „Wer“ und „Wie“ einer Kommunikation, aber nicht das „Was“.
Anwendungen müssen eine Binding mit Parametern konfigurieren, die für den gewünschten Kommunikationskanal spezifisch sind. Bindungen bieten Unterstützung für eine Reihe von Netzwerktransporten, einschließlich TCP, UDP, UDP mit Weave Zuverlässiges Messaging und Weave over BLE (WoBLE). Anwendungen können auch die Verwendung bestimmter Sicherheitsmechanismen zum Schutz von Nachrichten anfordern, die zwischen den Parteien gesendet werden. Dazu gehören CASE- und PASE-Sitzungen sowie Anwendungsgruppenschlüssel. Die Schnittstelle zum Konfigurieren einer Binding verwendet einen deklarativen API-Stil, mit dem Anwendungen ihre Anforderungen an die Kommunikation in einfachen Worten angeben können.
Weitere Informationen finden Sie in der Dokumentation zu Binding::Configuration (Binding::Configuration).
Vorbereitung
Vor der Kommunikation muss eine Bindung vorbereitet werden. Bei der Vorbereitung einer Verbindlichkeit wird der erforderliche Zustand für die Kommunikation festgelegt. Dies kann Dinge wie das Auflösen der Netzwerkadresse des Peers, das Herstellen einer Netzwerkverbindung und das Aushandeln von Sicherheitsschlüsseln umfassen. Nach der Konfiguration durch die Anwendung übernimmt das Binding alle Schritte, die zur Vorbereitung der Kommunikation erforderlich sind, und ruft die Anwendung nach Abschluss des Vorgangs zurück. Auf diese Weise verbergen Bindings die Mechanismen der Kommunikation, sodass sich Anwendungen auf die allgemeinen Interaktionen konzentrieren können.
Kommunikation
Sobald eine Binding vorbereitet wurde, ist sie einsatzbereit. In diesem Status fordern Anwendungen (oder häufiger Protokollschichtcode, der im Auftrag einer Anwendung arbeitet) das Binding an, um einen Weave-Austauschkontext zuzuweisen. Der resultierende Austauschkontext ist für die Kommunikation vorkonfiguriert, sodass die Anwendung sofort einen Weave-Austausch mit dem Peer initiieren kann. Die Anwendung kann weiterhin Austauschkontexte aus der Bindung anfordern, bis die Bindung geschlossen oder ein Ereignis (z.B. ein Netzwerkfehler) den zugrunde liegenden Kommunikationskanal beendet.
Änderungen des Bindungsstatus
Bei einer Bindung werden API-Ereignisse an die Anwendung gesendet, um sie über Änderungen am Status der Bindung zu informieren. Wenn die Vorbereitung beispielsweise erfolgreich war, empfängt die Anwendung ein Ereignis, das sie darüber informiert, dass die Binding verwendet werden kann. Wenn der zugrunde liegende Kommunikationskanal fehlschlägt, wird ein Ereignis an die Anwendung gesendet, in dem sie darüber informiert wird, dass das Binding-Objekt nicht mehr im Status „Bereit“ ist.
API-Ereignisse werden über eine Ereignis-Callback-Funktion an die Anwendung gesendet, wenn das Binding zugewiesen wird.
Lebensdauer der Bindung
Bindungen werden als Referenz gezählt, um eine gemeinsame Verwendung durch mehrere Softwarekomponenten zu ermöglichen. Wenn eine Binding zugewiesen wird, wird ein einzelner Verweis auf die Bindung erstellt. Die Anwendung ist dafür verantwortlich, diese Referenz zu einem späteren Zeitpunkt freizugeben, sodass die Bindung für eine spätere Wiederverwendung kostenlos ist.
Wenn eine Anwendung mit einem Binding fertig ist, kann sie Close() für die Bindung aufrufen. Dadurch wird der Verweis der Anwendung auf die Bindung freigegeben und die weitere Übermittlung von API-Ereignissen blockiert. Wenn der letzte Verweis auf eine Binding aufgehoben wird, wird er automatisch geschlossen.
Öffentliche Typen |
|
---|---|
@23{
|
enum |
EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
|
typedefvoid(*
|
EventType{
|
enum |
State
|
enum |
Öffentliche Attribute |
|
---|---|
AppState
|
void *
|
Öffentliche Funktionen |
|
---|---|
AddRef(void)
|
void
Reservieren Sie einen Verweis auf das Bindungsobjekt.
|
AdjustResponseTimeout(ExchangeContext *apExchangeContext) const
|
Konfigurieren Sie einen vorhandenen Exchange-Kontext neu, um das Zeitlimit für die Antwort anzupassen.
|
AllocateRightSizedBuffer(PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize)
|
|
BeginConfiguration()
|
Die Konfiguration der Bindung.
|
CanBePrepared(void) const
|
bool
|
Close(void)
|
void
Schließen Sie das Bindungsobjekt und geben Sie eine Referenz frei.
|
GetConnection() const
|
Ruft das Weave-Verbindungsobjekt ab, das der Bindung zugeordnet ist.
|
GetDefaultResponseTimeout() const
|
uint32_t
Hiermit wird das Standardzeitlimit für Austauschantworten abgerufen, das bei der Kommunikation mit dem Peer verwendet werden soll.
|
GetDefaultWRMPConfig(void) const
|
const WRMPConfig &
Rufen Sie die WRMP-Standardkonfiguration ab, die bei der Kommunikation mit dem Peer verwendet werden soll.
|
GetEncryptionType(void) const
|
uint8_t
Rufen Sie den Nachrichtenverschlüsselungstyp ab, der beim Verschlüsseln von Nachrichten zum/vom Peer verwendet werden soll.
|
GetEventCallback() const
|
EventCallback
Ruft die Funktion ab, die aufgerufen wird, wenn ein API-Ereignis für das Binding eintritt.
|
GetExchangeManager() const
|
|
GetKeyId(void) const
|
uint32_t
Rufen Sie die ID des Nachrichtenverschlüsselungsschlüssels ab, der beim Verschlüsseln von Nachrichten zum/vom Peer verwendet werden soll.
|
GetLogId(void) const
|
uint16_t
Rufen Sie eine eindeutige ID für die Bindung ab.
|
GetMaxWeavePayloadSize(const System::PacketBuffer *msgBuf)
|
uint32_t
Ruft die maximale Weave-Nutzlastgröße ab, die in den bereitgestellten PacketBuffer passt.
|
GetPeerDescription(char *buf, uint32_t bufSize) const
|
void
Erstellt einen String, der den Peer-Knoten und die zugehörigen Adress-/Verbindungsinformationen beschreibt.
|
GetPeerIPAddress(nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId) const
|
void
Rufen Sie die IP-Adressinformationen für den Peer ab, falls verfügbar.
|
GetPeerNodeId(void) const
|
uint64_t
Rufen Sie die Knoten-ID des Bindungs-Peers ab.
|
GetProtocolLayerCallback(EventCallback & callback, void *& state) const
|
void
|
GetState(void) const
|
State
Rufen Sie den aktuellen Status der Bindung ab.
|
IsAuthenticMessageFromPeer(const WeaveMessageInfo *msgInfo)
|
bool
Ermitteln Sie, ob eine bestimmte eingehende Nachricht vom konfigurierten Peer stammt und angemessen authentifiziert ist.
|
IsConnectionTransport() const
|
bool
|
IsPreparing(void) const
|
bool
|
IsReady(void) const
|
bool
|
IsUDPTransport() const
|
bool
|
IsUnreliableUDPTransport() const
|
bool
|
IsWRMTransport() const
|
bool
|
NewExchangeContext(ExchangeContext *& appExchangeContext)
|
Weisen Sie einen neuen Exchange-Kontext für die Kommunikation mit dem Peer zu, der das Ziel der Bindung ist.
|
Release(void)
|
void
Geben Sie einen Verweis auf das Binding-Objekt frei.
|
RequestPrepare()
|
Fordern Sie die Anwendung an, die Binding zu konfigurieren und vorzubereiten.
|
Reset(void)
|
void
Setzen Sie die Bindung auf einen nicht konfigurierten Status zurück.
|
SetDefaultResponseTimeout(uint32_t msec)
|
void
Legen Sie das standardmäßige Zeitlimit für Austauschantworten fest, das bei der Kommunikation mit dem Peer verwendet werden soll.
|
SetDefaultWRMPConfig(const WRMPConfig & wrmpConfig)
|
void
Legen Sie die WRMP-Standardkonfiguration fest, die bei der Kommunikation mit dem Peer verwendet werden soll.
|
SetEventCallback(EventCallback aEventCallback)
|
void
Legen Sie fest, dass die anwendungsdefinierte Funktion aufgerufen wird, wenn ein API-Ereignis für das Binding eintritt.
|
SetProtocolLayerCallback(EventCallback callback, void *state)
|
void
Mithilfe der Binding-Funktion im Namen einer Anwendung können Sie eine Ereignisrückruffunktion für den Code der Protokollebene festlegen.
|
Öffentliche statische Funktionen |
|
---|---|
DefaultEventHandler(void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam)
|
void
Standard-Handler zum Binden von API-Ereignissen.
|
Kurse |
|
---|---|
nl:: |
Bietet eine deklarative Schnittstelle zum Konfigurieren und Vorbereiten eines Binding-Objekts. |
Strukturen |
|
---|---|
nl:: |
Eingabeparameter in ein Binding-API-Ereignis. |
nl:: |
Ausgabeparameter an ein Binding API-Ereignis. |
Öffentliche Typen
@23
@23
Attribute | |
---|---|
kGetPeerDescription_MaxLength
|
Maximale Länge des Strings, einschließlich NUL-Zeichen, der von GetPeerDescription() zurückgegeben wird. |
EventCallback
void(* EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
EventType
EventType
Attribute | |
---|---|
kEvent_BindingFailed
|
Die Bindung ist fehlgeschlagen und kann nicht mehr für die Kommunikation mit dem Peer verwendet werden. |
kEvent_BindingReady
|
Die Vorbereitungsaktion für die Bindung war erfolgreich und die Bindung kann jetzt für die Kommunikation mit dem Peer verwendet werden. |
kEvent_ConnectionEstablished
|
Die angeforderte Weave-Verbindung wurde hergestellt. |
kEvent_DefaultCheck
|
Wird verwendet, um die korrekte Verarbeitung von Standardereignissen in der Anwendung zu überprüfen. |
kEvent_PASEParametersRequested
|
Die Anwendung muss Parameter bereitstellen, die während der Einrichtung einer PASE-Sitzung verwendet werden sollen. |
kEvent_PrepareFailed
|
Die Vorbereitungsaktion für die Bindung ist fehlgeschlagen. |
kEvent_PrepareRequested
|
Die Anwendung wird aufgefordert, die Bindung für die Verwendung durch den Netzwerkstack zu konfigurieren und vorzubereiten. |
kEvent_TAKEParametersRequested
|
Die Anwendung muss Parameter bereitstellen, die bei der Einrichtung einer TAKE-Sitzung verwendet werden. |
Status
State
Öffentliche Attribute
AppState
void * AppState
Öffentliche Funktionen
AddRef
void AddRef( void )
Reservieren Sie einen Verweis auf das Bindungsobjekt.
AdjustResponseTimeout
WEAVE_ERROR AdjustResponseTimeout( ExchangeContext *apExchangeContext ) const
Konfigurieren Sie einen vorhandenen Exchange-Kontext neu, um das Zeitlimit für die Antwort anzupassen.
Details | |||
---|---|---|---|
Parameter |
|
AllocateRightSizedBuffer
WEAVE_ERROR AllocateRightSizedBuffer( PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize )
BeginConfiguration
Configuration BeginConfiguration()
Die Konfiguration der Bindung.
Anwendungen müssen BeginConfiguration() aufrufen, um die Binding zu konfigurieren, bevor sie für die Kommunikation mit dem Peer vorbereitet wird.
Details | |
---|---|
Rückgabe |
Ein Binding::Configuration-Objekt, mit dem die Bindung konfiguriert werden kann.
|
CanBePrepared
bool CanBePrepared( void ) const
Schließen
void Close( void )
Schließen Sie das Bindungsobjekt und geben Sie eine Referenz frei.
Wenn diese Methode aufgerufen wird, bewirkt sie, dass die Bindung in den Status Closed (Geschlossen) wechselt. Alle laufenden Vorbereitungsaktionen für die Bindung werden abgebrochen und alle externen Kommunikationsressourcen der Bindung werden freigegeben.
Durch das Aufrufen von Close() wird die mit der Bindung verknüpfte Referenzanzahl verringert. Das Objekt wird freigegeben, wenn die Referenzanzahl null wird.
GetConnection
WeaveConnection * GetConnection() const
Ruft das Weave-Verbindungsobjekt ab, das der Bindung zugeordnet ist.
Details | |
---|---|
Rückgabe |
Ein Zeiger auf ein WeaveConnection-Objekt oder NULL, wenn der Bindung keine Verbindung zugeordnet ist.
|
GetDefaultResponseTimeout
uint32_t GetDefaultResponseTimeout() const
Hiermit wird das Standardzeitlimit für Austauschantworten abgerufen, das bei der Kommunikation mit dem Peer verwendet werden soll.
Details | |
---|---|
Rückgabe |
Antwortzeitlimit in ms.
|
GetDefaultWRMPConfig
const WRMPConfig & GetDefaultWRMPConfig( void ) const
Rufen Sie die WRMP-Standardkonfiguration ab, die bei der Kommunikation mit dem Peer verwendet werden soll.
Details | |
---|---|
Rückgabe |
Ein Verweis auf eine WRMPConfig-Struktur, die die Standardkonfigurationswerte enthält.
|
GetEncryptionType
uint8_t GetEncryptionType( void ) const
Rufen Sie den Nachrichtenverschlüsselungstyp ab, der beim Verschlüsseln von Nachrichten zum/vom Peer verwendet werden soll.
GetEventCallback
EventCallback GetEventCallback() const
Ruft die Funktion ab, die aufgerufen wird, wenn ein API-Ereignis für das Binding eintritt.
Details | |
---|---|
Rückgabe |
Ein Zeiger auf die Callback-Funktion.
|
GetExchangeManager
WeaveExchangeManager * GetExchangeManager() const
GetKeyId
uint32_t GetKeyId( void ) const
Rufen Sie die ID des Nachrichtenverschlüsselungsschlüssels ab, der beim Verschlüsseln von Nachrichten zum/vom Peer verwendet werden soll.
GetLogId
uint16_t GetLogId( void ) const
Rufen Sie eine eindeutige ID für die Bindung ab.
GetMaxWeavePayloadSize
uint32_t GetMaxWeavePayloadSize( const System::PacketBuffer *msgBuf )
Ruft die maximale Weave-Nutzlastgröße ab, die in den bereitgestellten PacketBuffer passt.
Bei UDP, einschließlich UDP mit WRM, wird durch die zurückgegebene maximale Nutzlastgröße sichergestellt, dass die resultierende Weave-Nachricht die konfigurierte UDP-MTU nicht überläuft.
Außerdem sorgt diese Methode dafür, dass die Weave-Nutzlast den bereitgestellten PacketBuffer nicht überläuft.
Details | |||
---|---|---|---|
Parameter |
|
||
Rückgabe |
Die maximale Weave-Nutzlastgröße.
|
GetPeerDescription
void GetPeerDescription( char *buf, uint32_t bufSize ) const
Erstellt einen String, der den Peer-Knoten und die zugehörigen Adress-/Verbindungsinformationen beschreibt.
Details | |||||
---|---|---|---|---|---|
Parameter |
|
GetPeerIPAddress
void GetPeerIPAddress( nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId ) const
Rufen Sie die IP-Adressinformationen für den Peer ab, falls verfügbar.
Die Verfügbarkeit der IP-Adressinformationen des Peers hängt vom Status und der Konfiguration der Bindung ab. IP-Adressinformationen sind nur verfügbar, wenn eine IP-basierte Übertragung (TCP, UDP oder UDP mit WRMP) verwendet wird. Vor Beginn der Vorbereitung sind Adressinformationen nur verfügbar, wenn sie bei der Konfiguration ausdrücklich von der Anwendung festgelegt wurden. In der Vorbereitungsphase sind die Adressinformationen verfügbar, wenn die Adressvorbereitung abgeschlossen ist (z.B. nach Abschluss der DNS-Auflösung). Wenn die Bindung bereit ist, bleiben die Adressinformationen verfügbar, bis die Bindung zurückgesetzt wird.
Details | |||||||
---|---|---|---|---|---|---|---|
Parameter |
|
GetPeerNodeId
uint64_t GetPeerNodeId( void ) const
Rufen Sie die Knoten-ID des Bindungs-Peers ab.
Nur gültig, wenn das Bindungsobjekt vorbereitet wurde.
Details | |
---|---|
Rückgabe |
Weave-Knoten-ID des Peers
|
GetProtocolLayerCallback
void GetProtocolLayerCallback( EventCallback & callback, void *& state ) const
GetState
State GetState( void ) const
Rufen Sie den aktuellen Status der Bindung ab.
Details | |
---|---|
Rückgabe |
Der Bindungsstatus.
|
IsAuthenticMessageFromPeer
bool IsAuthenticMessageFromPeer( const WeaveMessageInfo *msgInfo )
Ermitteln Sie, ob eine bestimmte eingehende Nachricht vom konfigurierten Peer stammt und angemessen authentifiziert ist.
Mit dieser Methode werden die folgenden Details zur jeweiligen Nachricht bestätigt:
- Die Nachricht stammt vom Peer-Knoten der Bindung
- Die Nachricht wurde über denselben Transporttyp wie die Bindung empfangen. Wenn die Nachricht über eine Verbindung empfangen wurde, bestätigt die Methode außerdem, dass die Nachricht über die genaue Verbindung empfangen wurde, die der Bindung zugeordnet ist.
- Der Verschlüsselungsschlüssel und der Typ, die zum Verschlüsseln der Nachricht verwendet werden, stimmen mit denen in der Bindung überein. Bei Bindungen, die ohne Verwendung von Sicherheitsmaßnahmen konfiguriert wurden, bestätigt die Methode, dass die eingehende Nachricht NICHT verschlüsselt ist.
Diese Methode ist für den Einsatz in Protokollen wie WDM gedacht, bei denen Peers nach einem ersten Austausch vom Knoten zum Peer spontan den Austausch zum lokalen Knoten initiieren können. In solchen Fällen ermöglicht die Methode dem lokalen Knoten, zu bestätigen, dass die eingehende unerwünschte Nachricht vom zugehörigen Peer gesendet wurde. Bei Bindungen, die ohne Nachrichtenverschlüsselung konfiguriert wurden, bietet diese Assertion natürlich aus Sicherheitsgründen keinen Mehrwert. Es wird lediglich bestätigt, dass die Senderknoten-ID und die Transporttypen übereinstimmen.)
Wenn die Bindung nicht im Status „Ready“ ist, gibt diese Methode immer „false“ zurück.
Details | |||
---|---|---|---|
Parameter |
|
||
Rückgabe |
„True“, wenn die Nachricht authentisch vom Peer stammt.
|
IsConnectionTransport
bool IsConnectionTransport() const
IsPreparing
bool IsPreparing( void ) const
Details | |
---|---|
Rückgabe |
True, wenn Binding gerade vorbereitet wird.
|
IsReady
bool IsReady( void ) const
Details | |
---|---|
Rückgabe |
True, wenn Binding den Status „Ready“ (Bereit) hat.
|
IsUDPTransport
bool IsUDPTransport() const
IsUnreliableUDPTransport
bool IsUnreliableUDPTransport() const
IsWRMTransport
bool IsWRMTransport() const
NewExchangeContext
WEAVE_ERROR NewExchangeContext( ExchangeContext *& appExchangeContext )
Weisen Sie einen neuen Exchange-Kontext für die Kommunikation mit dem Peer zu, der das Ziel der Bindung ist.
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parameter |
|
||||||||
Rückgabewerte |
|
Release
void Release( void )
Geben Sie einen Verweis auf das Binding-Objekt frei.
Wenn es keine Verweise mehr auf das Bindungsobjekt gibt, wird die Bindung geschlossen und freigegeben.
RequestPrepare
WEAVE_ERROR RequestPrepare()
Fordern Sie die Anwendung an, die Binding zu konfigurieren und vorzubereiten.
Mit dem Code auf Protokollebene kann diese Methode für eine Binding verwendet werden, die nicht konfiguriert wurde oder fehlgeschlagen ist, um ein Ereignis an die Anwendung (kEvent_Prepareinquiry) auszulösen, in der sie aufgefordert wird, die Bindung zu konfigurieren und für die Verwendung vorzubereiten.
Diese Methode kann nur für Bindungen im Status „NotConfigured“ oder „Failed“ aufgerufen werden.
Wenn die Anwendung die On-Demand-Konfiguration/-Vorbereitung von Bindungen nicht unterstützt, schlägt die Methode mit WEAVE_ERROR_NOT_IMPLEMENTED fehl.
Zurücksetzen
void Reset( void )
Setzen Sie die Bindung auf einen nicht konfigurierten Status zurück.
Wenn Reset() aufgerufen wird, werden alle laufenden Vorbereitungsaktionen für die Bindung abgebrochen und alle von der Bindung betroffenen externen Kommunikationsressourcen werden freigegeben. Reset() versetzt die Bindung in den Status Nicht konfiguriert. Danach kann sie wieder konfiguriert und vorbereitet werden.
Reset() ändert nicht die Referenzanzahl der Bindung.
SetDefaultResponseTimeout
void SetDefaultResponseTimeout( uint32_t msec )
Legen Sie das standardmäßige Zeitlimit für Austauschantworten fest, das bei der Kommunikation mit dem Peer verwendet werden soll.
Details | |||
---|---|---|---|
Parameter |
|
SetDefaultWRMPConfig
void SetDefaultWRMPConfig( const WRMPConfig & wrmpConfig )
Legen Sie die WRMP-Standardkonfiguration fest, die bei der Kommunikation mit dem Peer verwendet werden soll.
Details | |||
---|---|---|---|
Parameter |
|
SetEventCallback
void SetEventCallback( EventCallback aEventCallback )
Legen Sie fest, dass die anwendungsdefinierte Funktion aufgerufen wird, wenn ein API-Ereignis für das Binding eintritt.
Details | |||
---|---|---|---|
Parameter |
|
SetProtocolLayerCallback
void SetProtocolLayerCallback( EventCallback callback, void *state )
Mithilfe der Binding-Funktion im Namen einer Anwendung können Sie eine Ereignisrückruffunktion für den Code der Protokollebene festlegen.
Diese Funktion wird zusätzlich zur anwendungsdefinierten Callback-Funktion aufgerufen, wenn API-Ereignisse für das Binding auftreten.
Details | |||||
---|---|---|---|---|---|
Parameter |
|
Öffentliche statische Funktionen
DefaultEventHandler
void DefaultEventHandler( void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam )
Standard-Handler zum Binden von API-Ereignissen.
Anwendungen müssen diese Methode für alle API-Ereignisse aufrufen, die sie nicht erkennen oder verarbeiten. Die bereitgestellten Parameter müssen mit denen übereinstimmen, die von der Bindung an die Event-Handler-Funktion der Anwendung übergeben werden.
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parameter |
|