nl:: Weave:: Bindung
#include <src/lib/core/WeaveBinding.h>
Erfassen das gewünschte Ziel einer Weave-Kommunikation und die zugehörigen Konfigurationsinformationen
Fazit
Ein Bindungsobjekt gibt das vorgesehene Ziel einer Weave-Kommunikation (auch „&Peer“ genannt) sowie eine Reihe von Konfigurationsparametern an, die die Kommunikation mit dem Peer definieren. Bindungen sind unabhängig vom Anwendungsprotokoll, das zwischen den beiden Parteien gesprochen wird. Daher erfassen sie die Eigenschaften „wer“ und „wie“ einer Kommunikation, aber nicht „wie“.
Apps müssen eine Bindung mit Parametern konfigurieren, die für den gewünschten Kommunikationskanaltyp relevant sind. Bindungen bieten Unterstützung für eine Vielzahl von Netzwerktransporten, einschließlich TCP, UDP, UDP mit Weave Zuverlässige Messaging und Weave über BLE (WoBLE). Außerdem können Anwendungen die Verwendung bestimmter Sicherheitsmechanismen erwirken, um Nachrichten zu schützen, die zwischen den Parteien gesendet werden. Dazu gehören CASE- und PASE-Sitzungen sowie Anwendungsgruppenschlüssel. Die Schnittstelle zum Konfigurieren einer Bindung verwendet ein deklaratives API-Design, mit dem Anwendungen ihre Anforderungen für die Kommunikation in einfachen Worten darstellen können.
Weitere Informationen finden Sie in der Dokumentation zu Bindung::Konfiguration.
Vorbereitung
Vor der Kommunikation muss eine Bindung vorab vorbereitet sein. Durch die Vorbereitung einer Bindung wird der erforderliche Status für die Kommunikation festgelegt. Sie können beispielsweise die Netzwerkadresse des Peers auflösen, eine Netzwerkverbindung herstellen und Sicherheitsschlüssel verhandeln. Sobald die Anwendung von der Bindung konfiguriert wurde, übernimmt sie alle Schritte, die für die Kommunikation erforderlich sind. Sie ruft die Anwendung zurück, wenn der Vorgang abgeschlossen ist. So wird die Kommunikation über Bindungen ausgeblendet, sodass sich die Apps auf die wichtigsten Interaktionen konzentrieren können.
Kommunikation
Sobald eine Bindung vorbereitet wurde, kann sie verwendet werden. In diesem Fall fordern Anwendungen (oder häufiger ein Protokollschichtcode, der im Auftrag einer Anwendung arbeitet) die Bindung an, um einen Weave-Exchange-Kontext zuzuweisen. Der resultierende Exchange-Kontext ist für die Kommunikation vorkonfiguriert, sodass die Anwendung sofort einen Weave-Exchange mit dem Peer starten kann. Die Anwendung kann weiterhin Exchange-Kontexte von der Bindung anfordern, bis die Bindung geschlossen wird oder ein Ereignis, z.B. ein Netzwerkausfall, den zugrunde liegenden Kommunikationskanal beendet.
Statusänderungen Bindung
Im Laufe der Verwendung werden durch eine Bindung API-Ereignisse an die Anwendung gesendet, um sie über Änderungen im Status Bindung zu informieren. Wenn die Vorbereitung erfolgreich ist, erhält die Anwendung ein Ereignis mit dem Hinweis, dass die Bindung einsatzbereit ist. Gleiches gilt, wenn der zugrunde liegende Kommunikationskanal fehlschlägt, ein Ereignis an die Anwendung gesendet wird, dass die Bindung nicht mehr im Status „Bereit“ ist.
API-Ereignisse werden über eine Ereignis-Callback-Funktion an die Anwendung gesendet, die bereitgestellt wird, wenn die Bindung zugewiesen ist.
Bindung wird als Referenz gezählt, um die gemeinsame Verwendung über mehrere Softwarekomponenten hinweg zu ermöglichen. Wenn eine Bindung 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 zur späteren Wiederverwendung frei ist.
Wenn eine Anwendung mit einer Bindung abgeschlossen ist, kann sie Schließen() für die Bindung aufrufen. Dadurch werden die Verweise auf die Bindung freigegeben und alle weiteren API-Ereignisse werden blockiert. Wenn die letzte Referenz auf eine Bindung veröffentlicht wird, wird sie automatisch geschlossen.
Öffentliche Typen |
|
---|---|
@23{
|
enum |
EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
|
Typdefvoid(*
|
EventType{
|
enum |
State
|
enum |
Öffentliche Attribute |
|
---|---|
AppState
|
void *
|
Öffentliche Funktionen |
|
---|---|
AddRef(void)
|
void
Verweis auf das Bindungsobjekt reservieren.
|
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()
|
wenn die Bindung konfiguriert wird.
|
CanBePrepared(void) const
|
bool
|
Close(void)
|
void
Schließen Sie das Bindungsobjekt und geben Sie eine Referenz frei.
|
GetConnection() const
|
Rufen Sie das Weave-Verbindungsobjekt ab, das mit der Bindung verknüpft ist.
|
GetDefaultResponseTimeout() const
|
uint32_t
Hiermit können Sie das Zeitlimit für die standardmäßige Anzeigenantwort aufrufen, das bei der Kommunikation mit einem Peer verwendet wird.
|
GetDefaultWRMPConfig(void) const
|
const WRMPConfig &
Rufen Sie die Standard-WRMP-Konfiguration für die Kommunikation mit dem Peer ab.
|
GetEncryptionType(void) const
|
uint8_t
Rufen Sie den Verschlüsselungstyp der Nachricht ab, der beim Verschlüsseln von Nachrichten an den Peer oder vom Peer verwendet werden soll.
|
GetEventCallback() const
|
EventCallback
Rufen Sie die Funktion ab, die aufgerufen wird, wenn ein API-Ereignis für das Bindung eintritt.
|
GetExchangeManager() const
|
|
GetKeyId(void) const
|
uint32_t
Rufen Sie die ID des Verschlüsselungsschlüssels für die Nachricht ab, der beim Verschlüsseln von Nachrichten an/von dem 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
Rufen Sie die maximale Weave-Nutzlastgröße ab, die in den gelieferten PacketBuffer passt.
|
GetPeerDescription(char *buf, uint32_t bufSize) const
|
void
Erstellt einen String, der den Peer-Knoten und die zugehörigen Adressen-/Verbindungsinformationen beschreibt.
|
GetPeerIPAddress(nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId) const
|
void
Rufen Sie die IP-Adresse des Peers 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, 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)
|
Ordnen 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 Bindungsobjekt frei.
|
RequestPrepare()
|
Beantragen Sie die Anwendung, um die Bindung 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 Standardzeitlimit für die Antwort der Anzeigenplattform fest, das bei der Kommunikation mit dem Peer verwendet werden soll.
|
SetDefaultWRMPConfig(const WRMPConfig & wrmpConfig)
|
void
Legen Sie die Standard-WRMP-Konfiguration für die Kommunikation mit dem Peer fest.
|
SetEventCallback(EventCallback aEventCallback)
|
void
Sie können festlegen, dass die app-definierte Funktion aufgerufen wird, wenn ein API-Ereignis für das Bindungsereignis auftritt.
|
SetProtocolLayerCallback(EventCallback callback, void *state)
|
void
Legen Sie eine Ereignis-Callback-Funktion für den Codeschichtcode fest. Verwenden Sie dazu die Bindung im Auftrag einer Anwendung.
|
Öffentliche statische Funktionen |
|
---|---|
DefaultEventHandler(void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam)
|
void
Standard-Handler für Bindungs-API-Ereignisse.
|
Klassen |
|
---|---|
nl:: |
Stellt eine Schnittstelle im deklarativen Stil bereit, um ein Bindungsobjekt zu konfigurieren und vorzubereiten. |
Strebenklemmen |
|
---|---|
nl:: |
Eingabeparameter in ein Bindungs-API-Ereignis eingeben. |
nl:: |
Ausgabeparameter in ein Bindungs-API-Ereignis. |
Öffentliche Typen
@23
@23
Attribute | |
---|---|
kGetPeerDescription_MaxLength
|
Maximale Länge des Strings (einschließlich NUL-Zeichen), die von GetPeerDescription() zurückgegeben wird |
Ereignis-Callback
void(* EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
EventType
EventType
Attribute | |
---|---|
kEvent_BindingFailed
|
Die Bindung ist fehlgeschlagen und kann nicht mehr zur Kommunikation mit dem Peer verwendet werden. |
kEvent_BindingReady
|
Die Vorbereitungsaktion für die Bindung wurde 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 standardmäßige Ereignisverarbeitung in der Anwendung zu prüfen. |
kEvent_PASEParametersRequested
|
Die Anwendung wird aufgefordert, Parameter anzugeben, die während der PASE-Sitzung eingerichtet werden sollen. |
kEvent_PrepareFailed
|
Die Vorbereitungsaktion für die Bindung konnte nicht ausgeführt werden. |
kEvent_PrepareRequested
|
Die Anwendung wird aufgefordert, die Bindung für die Verwendung durch den Netzwerk-Stack zu konfigurieren und vorzubereiten. |
kEvent_TAKEParametersRequested
|
Die Anwendung wird aufgefordert, Parameter anzugeben, die beim Einrichten der take-Sitzung verwendet werden sollen. |
Status
State
Öffentliche Attribute
App-Status
void * AppState
Öffentliche Funktionen
Hinzufügen Ref
void AddRef( void )
Verweis auf das Bindungsobjekt reservieren.
Zeitüberschreitung für Anpassung
WEAVE_ERROR AdjustResponseTimeout( ExchangeContext *apExchangeContext ) const
Konfigurieren Sie einen vorhandenen Exchange-Kontext neu, um das Zeitlimit für die Antwort anzupassen.
Details | |||
---|---|---|---|
Parameter |
|
Logo: AllocateRightSizedBuffer
WEAVE_ERROR AllocateRightSizedBuffer( PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize )
Anfangskonfiguration
Configuration BeginConfiguration()
wenn die Bindung konfiguriert wird.
Anwendungen müssen BeginConfiguration() aufrufen, um Bindung zu konfigurieren, bevor sie für die Kommunikation mit dem Peer vorbereitet wird.
Details | |
---|---|
Rückgabe |
Ein Bindung::Konfiguration-Objekt, das zum Konfigurieren der Bindung verwendet werden kann.
|
Kann vorbereitet werden
bool CanBePrepared( void ) const
Schließen
void Close( void )
Schließen Sie das Bindungsobjekt und geben Sie eine Referenz frei.
Beim Aufrufen dieser Methode bewirkt die Bindung den Status „Geschlossen“. Alle laufenden Vorbereitungen für die Bindung werden abgebrochen und alle externen Kommunikationsressourcen, die von der Bindung aufbewahrt werden, werden freigegeben.
Durch Aufrufen von Close() wird die mit der Bindung verbundene Referenz verringert. Das Objekt wird dann freigegeben, wenn die Referenzanzahl null wird.
GetConnection
WeaveConnection * GetConnection() const
Rufen Sie das Weave-Verbindungsobjekt ab, das mit der Bindung verknüpft ist.
Details | |
---|---|
Rückgabe |
Ein Verweis auf ein WeaveConnection-Objekt oder NULL, wenn keine Verbindung mit der Bindung verknüpft ist.
|
GetDefaultResponseTimeout
uint32_t GetDefaultResponseTimeout() const
Hiermit können Sie das Zeitlimit für die standardmäßige Anzeigenantwort aufrufen, das bei der Kommunikation mit einem Peer verwendet wird.
Details | |
---|---|
Rückgabe |
Zeitlimit für Antworten in ms.
|
StandardWRMPConfig
const WRMPConfig & GetDefaultWRMPConfig( void ) const
Rufen Sie die Standard-WRMP-Konfiguration für die Kommunikation mit dem Peer ab.
Details | |
---|---|
Rückgabe |
Ein Verweis auf eine WRMPConfig-Struktur, die die Standardkonfigurationswerte enthält.
|
Verschlüsselungstyp
uint8_t GetEncryptionType( void ) const
Rufen Sie den Verschlüsselungstyp der Nachricht ab, der beim Verschlüsseln von Nachrichten an den Peer oder vom Peer verwendet werden soll.
GetEventCallback
EventCallback GetEventCallback() const
Rufen Sie die Funktion ab, die aufgerufen wird, wenn ein API-Ereignis für das Bindung eintritt.
Details | |
---|---|
Rückgabe |
Ein Zeiger auf die Callback-Funktion.
|
Exchange-Manager abrufen
WeaveExchangeManager * GetExchangeManager() const
GetKeyId
uint32_t GetKeyId( void ) const
Rufen Sie die ID des Verschlüsselungsschlüssels für die Nachricht ab, der beim Verschlüsseln von Nachrichten an/von dem 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 )
Rufen Sie die maximale Weave-Nutzlastgröße ab, die in den gelieferten PacketBuffer passt.
Bei UDP, einschließlich UDP mit WRM, sorgt die maximale zurückgegebene Nutzlastgröße dafür, dass die resultierende Weave-Nachricht den konfigurierten UDP-MTU-Wert nicht überläuft.
Außerdem wird mit dieser Methode sichergestellt, dass die Weave-Nutzlast nicht den bereitgestellten PacketBuffer überschreitet.
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 Adressen-/Verbindungsinformationen beschreibt.
Details | |||||
---|---|---|---|---|---|
Parameter |
|
Peer-IP-Adresse abrufen
void GetPeerIPAddress( nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId ) const
Rufen Sie die IP-Adresse des Peers ab, falls verfügbar.
Die Verfügbarkeit der IP-Adressinformationen der Peers hängt vom Status und der Konfiguration der Bindung ab. IP-Adressinformationen sind nur bei Verwendung eines IP-basierten Transports verfügbar (TCP, UDP oder UDP mit WRMP). Vor Beginn der Vorbereitung sind Adressinformationen nur verfügbar, wenn sie von der Anwendung während der Konfiguration explizit festgelegt wurden. Während der Vorbereitungsphase stehen Adressinformationen zur Verfügung, wenn die Adressvorbereitung abgeschlossen ist (z.B. nach Abschluss der DNS-Auflösung). Wenn Bindungbereit ist, bleiben Adressinformationen verfügbar, bis Bindung zurückgesetzt wird.
Details | |||||||
---|---|---|---|---|---|---|---|
Parameter |
|
PeerNodeNode
uint64_t GetPeerNodeId( void ) const
Rufen Sie die Knoten-ID des Bindungs-Peers ab.
Erst gültig, nachdem das Bindungsobjekt vorbereitet wurde.
Details | |
---|---|
Rückgabe |
Knoten-ID des Peers erstellen
|
GetProtokollLayerCallback
void GetProtocolLayerCallback( EventCallback & callback, void *& state ) const
GetState
State GetState( void ) const
Rufen Sie den aktuellen Status der Bindung ab.
Details | |
---|---|
Rückgabe |
Bindungsstatus
|
IsAuthenticMessageFromPeer
bool IsAuthenticMessageFromPeer( const WeaveMessageInfo *msgInfo )
Ermitteln, ob eine bestimmte eingehende Nachricht vom konfigurierten Peer stammt und angemessen authentifiziert ist
Mit dieser Methode werden die folgenden Details zur angegebenen Nachricht bestätigt:
- Die Nachricht stammt vom Peer-Knoten der Bindung
- Die Nachricht wurde über denselben Transporttyp empfangen wie die Bindung. Wenn die Nachricht über eine Verbindung empfangen wurde, bestätigt die Methode auch, dass die Nachricht über die genaue Verbindung empfangen wurde, die mit der Bindung verknüpft ist.
- Der Verschlüsselungsschlüssel und der Typ, der für die Verschlüsselung der Nachricht verwendet wird, stimmen mit denen in der Bindung überein. Bei Bindungen, die ohne Verwendung von Sicherheit konfiguriert wurden, bestätigt die Methode, dass die eingehende Nachricht NICHT verschlüsselt ist.
Diese Methode ist zur Verwendung in Protokollen wie WDM gedacht, bei denen Peers Exchanges nach dem ersten Austausch vom Knoten zum Peer dynamisch zurück zum lokalen Knoten initiieren können. In diesen Fällen kann der lokale Knoten 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 aus Sicherheitsgründen keinen Wert. Sie bestätigt lediglich, dass die Knoten-ID des Absenders und die Transporttypen übereinstimmen.)
Wenn die Bindung nicht den Status „Bereit“ hat, gibt diese Methode immer „false“ zurück.
Details | |||
---|---|---|---|
Parameter |
|
||
Rückgabe |
„True“, wenn die Nachricht von einem Peer stammt.
|
Logo: IsConnectionTransport
bool IsConnectionTransport() const
Wird vorbereitet
bool IsPreparing( void ) const
Details | |
---|---|
Rückgabe |
„True“, wenn die Bindung derzeit vorbereitet wird.
|
Bereit
bool IsReady( void ) const
Details | |
---|---|
Rückgabe |
Dieser Wert ist „True“, wenn sich die Bindung im Status „Bereit“ befindet.
|
Logo: IsUDPTransport
bool IsUDPTransport() const
Ist nicht zuverlässigerUDPTransport
bool IsUnreliableUDPTransport() const
Logo: IsWRMTransport
bool IsWRMTransport() const
Neuer Exchange-Kontext
WEAVE_ERROR NewExchangeContext( ExchangeContext *& appExchangeContext )
Ordnen 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 Bindungsobjekt frei.
Wenn es keine weiteren Verweise auf das Bindungsobjekt gibt, wird die Bindung geschlossen und freigegeben.
Anfrage vorbereiten
WEAVE_ERROR RequestPrepare()
Beantragen Sie die Anwendung, um die Bindung zu konfigurieren und vorzubereiten.
Der Protokollschichtcode kann diese Methode für eine Bindung verwenden, die nicht konfiguriert wurde oder fehlgeschlagen ist, um ein Ereignis für die Anwendung (kEvent_PrepareRequested) auszulösen, mit der die Bindung angefordert und vorbereitet wird.
Diese Methode kann nur für Bindungen im Status „Nicht konfiguriert“ oder „Fehlgeschlagen“ 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 externen Kommunikationsressourcen, die von der Bindung enthalten sind, freigegeben. Reset() fügt die Bindung in den Status "Nicht konfiguriert" ein und kann anschließend wieder konfiguriert und vorbereitet werden.
Reset() wirkt sich nicht auf die Referenzanzahl der Bindung aus.
DefaultResponseResponseTimeout festlegen
void SetDefaultResponseTimeout( uint32_t msec )
Legen Sie das Standardzeitlimit für die Antwort der Anzeigenplattform fest, das bei der Kommunikation mit dem Peer verwendet werden soll.
Details | |||
---|---|---|---|
Parameter |
|
SetWRMPConfig
void SetDefaultWRMPConfig( const WRMPConfig & wrmpConfig )
Legen Sie die Standard-WRMP-Konfiguration für die Kommunikation mit dem Peer fest.
Details | |||
---|---|---|---|
Parameter |
|
SetEventCallback
void SetEventCallback( EventCallback aEventCallback )
Sie können festlegen, dass die app-definierte Funktion aufgerufen wird, wenn ein API-Ereignis für das Bindungsereignis auftritt.
Details | |||
---|---|---|---|
Parameter |
|
SetProtokollLayerCallback
void SetProtocolLayerCallback( EventCallback callback, void *state )
Legen Sie eine Ereignis-Callback-Funktion für den Codeschichtcode fest. Verwenden Sie dazu die Bindung im Auftrag einer Anwendung.
Diese Funktion wird zusätzlich zur anwendungsdefinierten Callback-Funktion aufgerufen, wenn API-Ereignisse für die Bindung auftreten.
Details | |||||
---|---|---|---|---|---|
Parameter |
|
Öffentliche statische Funktionen
Standard-EventHandler
void DefaultEventHandler( void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam )
Standard-Handler für Bindungs-API-Ereignisse.
Die Anwendungen müssen diese Methode für alle API-Ereignisse aufrufen, die sie nicht erkennen oder verarbeiten. Die bereitgestellten Parameter müssen mit den Parametern übereinstimmen, die von der Bindung an die Ereignis-Handler-Funktion übergeben werden.
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parameter |
|