nl:: Weave:: Binding
#include <src/lib/core/WeaveBinding.h>
Przechwytuje zamierzony cel komunikacji Weave i powiązane informacje o konfiguracji.
Podsumowanie
Obiekt Binding określa zamierzony cel komunikacji Weave (nazywany też „peerem”) wraz z zestawem parametrów konfiguracji opisujących sposób komunikacji z peerem. Powiązania są niezależne od protokołu aplikacji mówionego między stronami. Dzięki temu zbierają informacje na temat relacji typu „kto” i „jak”, ale nie „co”.
Aplikacje muszą skonfigurować Wiązanie z parametrami specyficznymi dla żądanego typu kanału komunikacyjnego. Powiązania zapewniają obsługę różnych typów transportu sieciowego, w tym TCP, UDP, UDP z funkcją Weave Reliable Messaging oraz Weave over BLE (WoBLE). Aplikacje mogą także prosić o zastosowanie określonych mechanizmów zabezpieczających w celu ochrony wiadomości wysyłanych między stronami. Obejmuje to sesje CASE i PASE oraz klucze grup aplikacji. Interfejs konfiguracji Binding używa deklaratywnego stylu interfejsu API, który pozwala aplikacjom określać w prostszy sposób wymagania dotyczące komunikacji.
Więcej informacji znajdziesz w dokumentacji dotyczącej Wiązanie::Konfiguracja.
Przygotowanie
Przed rozpoczęciem komunikacji należy „przygotować” Wiązanie. Przygotowanie Wiązania obejmuje określenie stanu niezbędnego do przeprowadzenia komunikacji. Może to obejmować między innymi rozpoznawanie adresu sieciowego połączenia równorzędnego, nawiązywanie połączenia sieciowego i negocjowanie kluczy bezpieczeństwa. Po skonfigurowaniu przez aplikację funkcja Binding obejmuje wszystkie kroki niezbędne do przygotowania komunikacji. Po jego zakończeniu oddzwoni do aplikacji. W ten sposób powiązania ukrywają mechanikę komunikacji, dzięki czemu aplikacje mogą się skupić na interakcjach ogólnych.
Komunikacja
Gdy Binding będzie gotowy, staje się gotowy do użycia. W tym stanie aplikacje (lub częściej kod warstwy protokołu działający w imieniu aplikacji) żądają Wiązania, aby przydzielić kontekst wymiany Weave. Wynikowy kontekst wymiany jest wstępnie skonfigurowany pod kątem komunikacji, dzięki czemu aplikacja może natychmiast zainicjować wymianę Weave z peerem. Aplikacja może nadal prosić o konteksty wymiany z poziomu Wiązania, dopóki Wiązanie nie zostanie zamknięte lub dopóki nie nastąpi zamknięcie działającego kanału komunikacyjnego (np. awaria sieci).
Zmiany stanu Wiązania
W trakcie używania obiektu Binding będzie dostarczać do aplikacji zdarzenia interfejsu API informujące ją o zmianach stanu Binding. Jeśli się uda, aplikacja otrzyma na przykład zdarzenie informujące, że Wiązanie jest gotowe do użycia. Podobnie jeśli podstawowy kanał komunikacji zawiedzie, do aplikacji wysyłane jest zdarzenie informujące, że powiązanie nie jest już w stanie gotowości.
Zdarzenia interfejsu API są dostarczane do aplikacji przez funkcję wywołania zwrotnego zdarzenia, która jest udostępniana podczas przydzielania elementu Binding.
Czas trwania wiązania
Wiązania są liczone, by umożliwić wspólne korzystanie z nich przez wiele komponentów oprogramowania. Przydzielanie wiązania powoduje utworzenie pojedynczego odwołania do powiązania. Aplikacja jest odpowiedzialna za udostępnienie tego pliku referencyjnego w przyszłości, tak aby Wiązanie można było wykorzystać w przyszłości.
Po zakończeniu pracy z opcją Binding aplikacja może wywołać przy wiązaniu funkcję Close(). Spowoduje to udostępnienie odniesienia aplikacji do metody Binding i zablokowanie dalszego przesyłania zdarzeń interfejsu API. Gdy ostatnie odwołanie do obiektu Binding zostanie zwolnione, zostanie automatycznie zamknięte.
Typy publiczne |
|
---|---|
@23{
|
enum | typ wyliczeniowy |
EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
|
typedefvoid(*
|
EventType{
|
enum | typ wyliczeniowy |
State
|
enum | typ wyliczeniowy |
Atrybuty publiczne |
|
---|---|
AppState
|
void *
|
Funkcje publiczne |
|
---|---|
AddRef(void)
|
void
Zarezerwuj odwołanie do obiektu powiązania.
|
AdjustResponseTimeout(ExchangeContext *apExchangeContext) const
|
Ponownie skonfiguruj istniejący kontekst Exchange, aby dostosować limit czasu odpowiedzi.
|
AllocateRightSizedBuffer(PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize)
|
|
BeginConfiguration()
|
Podczas konfigurowania Wiązania.
|
CanBePrepared(void) const
|
bool
|
Close(void)
|
void
Zamknij obiekt powiązania i zwolnij odwołanie.
|
GetConnection() const
|
Pobierz obiekt połączenia Weave powiązany z powiązaniem.
|
GetDefaultResponseTimeout() const
|
uint32_t
Uzyskaj domyślny limit czasu odpowiedzi Exchange używany podczas komunikacji z peerem.
|
GetDefaultWRMPConfig(void) const
|
const WRMPConfig &
Pobierz domyślną konfigurację WRMP, która będzie używana podczas komunikacji z peerem.
|
GetEncryptionType(void) const
|
uint8_t
Pobierz typ szyfrowania wiadomości, który ma być używany podczas szyfrowania wiadomości do/z połączenia równorzędnego.
|
GetEventCallback() const
|
EventCallback
Pobierz funkcję, która zostanie wywołana po wystąpieniu zdarzenia interfejsu API dla Binding.
|
GetExchangeManager() const
|
|
GetKeyId(void) const
|
uint32_t
Pobierz identyfikator klucza szyfrowania wiadomości, który ma być używany podczas szyfrowania wiadomości do/z połączenia równorzędnego.
|
GetLogId(void) const
|
uint16_t
Uzyskaj unikalny identyfikator powiązania.
|
GetMaxWeavePayloadSize(const System::PacketBuffer *msgBuf)
|
uint32_t
Uzyskaj maksymalny rozmiar ładunku Weave, który może się zmieścić w udostępnionym buforze pakietów.
|
GetPeerDescription(char *buf, uint32_t bufSize) const
|
void
Konstruuje ciąg tekstowy opisujący węzeł równorzędny i powiązany z nim adres lub informacje o połączeniu.
|
GetPeerIPAddress(nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId) const
|
void
Pobierz informacje o adresie IP połączenia równorzędnego, jeśli są dostępne.
|
GetPeerNodeId(void) const
|
uint64_t
Pobierz identyfikator węzła peera powiązania.
|
GetProtocolLayerCallback(EventCallback & callback, void *& state) const
|
void
|
GetState(void) const
|
State
Pobierz bieżący stan powiązania.
|
IsAuthenticMessageFromPeer(const WeaveMessageInfo *msgInfo)
|
bool
Ustal, czy konkretna wiadomość przychodząca pochodzi od skonfigurowanego peera i jest odpowiednio uwierzytelniona.
|
IsConnectionTransport() const
|
bool
|
IsPreparing(void) const
|
bool
|
IsReady(void) const
|
bool
|
IsUDPTransport() const
|
bool
|
IsUnreliableUDPTransport() const
|
bool
|
IsWRMTransport() const
|
bool
|
NewExchangeContext(ExchangeContext *& appExchangeContext)
|
Przydziel nowy kontekst Exchange do komunikacji z peerem, który jest celem powiązania.
|
Release(void)
|
void
Zwolnij odwołanie do obiektu powiązania.
|
RequestPrepare()
|
Poproś aplikację o skonfigurowanie i przygotowanie Binding.
|
Reset(void)
|
void
Zresetuj powiązanie z powrotem do stanu nieskonfigurowanego.
|
SetDefaultResponseTimeout(uint32_t msec)
|
void
Ustaw domyślny czas oczekiwania na odpowiedź giełdy, który będzie używany podczas komunikacji z peerem.
|
SetDefaultWRMPConfig(const WRMPConfig & wrmpConfig)
|
void
Ustaw domyślną konfigurację WRMP, która będzie używana podczas komunikacji z peerem.
|
SetEventCallback(EventCallback aEventCallback)
|
void
Ustaw funkcję zdefiniowaną przez aplikację, która ma być wywoływana, gdy wystąpi zdarzenie interfejsu API w polu Binding.
|
SetProtocolLayerCallback(EventCallback callback, void *state)
|
void
Ustaw funkcję wywołania zwrotnego zdarzenia dla kodu warstwy protokołu, korzystając z opcji Binding (Wiązanie) w imieniu aplikacji.
|
Publiczne funkcje statyczne |
|
---|---|
DefaultEventHandler(void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam)
|
void
Domyślny moduł obsługi zdarzeń powiązanych z interfejsem API.
|
Zajęcia |
|
---|---|
nl:: |
Zapewnia interfejs w stylu deklaratywnym do konfigurowania i przygotowywania obiektu Binding. |
Konstrukcja |
|
---|---|
nl:: |
Parametry wejściowe zdarzenia w interfejsie Binding API. |
nl:: |
Parametry wyjściowe do zdarzenia w interfejsie Binding API. |
Typy publiczne
@23
@23
Właściwości | |
---|---|
kGetPeerDescription_MaxLength
|
Maksymalna długość ciągu znaków (w tym znaku NUL) zwróconego przez funkcję GetPeerDescription(). |
EventCallback
void(* EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
EventType
EventType
Właściwości | |
---|---|
kEvent_BindingFailed
|
Powiązanie nie powiodło się i nie można go już używać do komunikowania się z peerem. |
kEvent_BindingReady
|
Działanie przygotowania zostało zakończone i możesz już używać tego powiązania do komunikowania się z peerem. |
kEvent_ConnectionEstablished
|
Żądane połączenie z Weave zostało nawiązane. |
kEvent_DefaultCheck
|
Służy do weryfikowania prawidłowej domyślnej obsługi zdarzeń w aplikacji. |
kEvent_PASEParametersRequested
|
Aplikacja musi dostarczyć parametry do wykorzystania podczas nawiązywania sesji PASE. |
kEvent_PrepareFailed
|
Nie udało się wykonać działania przygotowania powiązania. |
kEvent_PrepareRequested
|
Aplikacja otrzyma prośbę o skonfigurowanie i przygotowanie powiązania do użycia przez stos sieciowy. |
kEvent_TAKEParametersRequested
|
Aplikacja musi dostarczyć parametry do wykorzystania podczas nawiązywania sesji Take. |
Stan
State
Atrybuty publiczne
AppState
void * AppState
Funkcje publiczne
AddRef
void AddRef( void )
Zarezerwuj odwołanie do obiektu powiązania.
AdjustResponseTimeout
WEAVE_ERROR AdjustResponseTimeout( ExchangeContext *apExchangeContext ) const
Ponownie skonfiguruj istniejący kontekst Exchange, aby dostosować limit czasu odpowiedzi.
Szczegóły | |||
---|---|---|---|
Parametry |
|
AllocateRightSizedBuffer
WEAVE_ERROR AllocateRightSizedBuffer( PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize )
BeginConfiguration
Configuration BeginConfiguration()
Podczas konfigurowania Wiązania.
Aplikacje muszą wywoływać metodę BeginConfiguration(), aby skonfigurować Wiązanie przed przygotowaniem do komunikacji z peerem.
Szczegóły | |
---|---|
Zwroty |
Obiekt Binding::Configuration, którego można używać do konfigurowania powiązania.
|
CanBePrepared
bool CanBePrepared( void ) const
Zamknij
void Close( void )
Zamknij obiekt powiązania i zwolnij odwołanie.
Wywołanie tej metody powoduje, że powiązanie przechodzi w stan Zamknięte. Wszystkie trwające działania przygotowujące do powiązania zostaną anulowane, a wszystkie zewnętrzne zasoby komunikacyjne przechowywane przez to powiązanie zostaną zwolnione.
Wywołanie funkcji Close() zmniejsza liczbę odwołań powiązaną z powiązaniem, zwalniając obiekt, gdy liczba odwołań spadnie do 0.
GetConnection
WeaveConnection * GetConnection() const
Pobierz obiekt połączenia Weave powiązany z powiązaniem.
Szczegóły | |
---|---|
Zwroty |
Wskaźnik do obiektu WeaveConnection lub wartość NULL, jeśli nie ma połączenia z powiązaniem.
|
GetDefaultResponseTimeout
uint32_t GetDefaultResponseTimeout() const
Uzyskaj domyślny limit czasu odpowiedzi Exchange używany podczas komunikacji z peerem.
Szczegóły | |
---|---|
Zwroty |
Limit czasu odpowiedzi w ms.
|
GetDefaultWRMPConfig
const WRMPConfig & GetDefaultWRMPConfig( void ) const
Pobierz domyślną konfigurację WRMP, która będzie używana podczas komunikacji z peerem.
Szczegóły | |
---|---|
Zwroty |
Odwołanie do struktury WRMPConfig zawierającej domyślne wartości konfiguracji.
|
GetEncryptionType
uint8_t GetEncryptionType( void ) const
Pobierz typ szyfrowania wiadomości, który ma być używany podczas szyfrowania wiadomości do/z połączenia równorzędnego.
GetEventCallback
EventCallback GetEventCallback() const
Pobierz funkcję, która zostanie wywołana po wystąpieniu zdarzenia interfejsu API dla Binding.
Szczegóły | |
---|---|
Zwroty |
Wskaźnik funkcji wywołania zwrotnego.
|
GetExchangeManager
WeaveExchangeManager * GetExchangeManager() const
GetKeyId
uint32_t GetKeyId( void ) const
Pobierz identyfikator klucza szyfrowania wiadomości, który ma być używany podczas szyfrowania wiadomości do/z połączenia równorzędnego.
GetLogId
uint16_t GetLogId( void ) const
Uzyskaj unikalny identyfikator powiązania.
GetMaxWeavePayloadSize
uint32_t GetMaxWeavePayloadSize( const System::PacketBuffer *msgBuf )
Uzyskaj maksymalny rozmiar ładunku Weave, który może się zmieścić w udostępnionym buforze pakietów.
W przypadku UDP, w tym UDP z WRM maksymalny rozmiar zwróconego ładunku zagwarantuje, że wynikowy komunikat Weave nie przekroczy skonfigurowanego protokołu UDP MTU.
Dodatkowo ta metoda zagwarantuje, że ładunek Weave nie przekroczy przesłanego pliku PacketBuffer.
Szczegóły | |||
---|---|---|---|
Parametry |
|
||
Zwroty |
Maksymalny rozmiar ładunku Weave.
|
GetPeerDescription
void GetPeerDescription( char *buf, uint32_t bufSize ) const
Konstruuje ciąg tekstowy opisujący węzeł równorzędny i powiązany z nim adres lub informacje o połączeniu.
Szczegóły | |||||
---|---|---|---|---|---|
Parametry |
|
GetPeerIPAddress
void GetPeerIPAddress( nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId ) const
Pobierz informacje o adresie IP połączenia równorzędnego, jeśli są dostępne.
Dostępność informacji o adresie IP peera zależy od stanu i konfiguracji powiązania. Informacje o adresie IP są dostępne tylko podczas korzystania z protokołu IP (TCP, UDP lub UDP z WRMP). Przed rozpoczęciem przygotowania informacje adresowe są dostępne tylko wtedy, gdy zostały wyraźnie określone przez aplikację podczas konfiguracji. W trakcie etapu przygotowania informacje adresowe są dostępne po zakończeniu przygotowywania adresu (np. po zakończeniu rozpoznawania nazw DNS). Gdy Wiązanie będzie gotowe, informacje o adresie pozostaną dostępne, dopóki Wiązanie nie zostanie zresetowane.
Szczegóły | |||||||
---|---|---|---|---|---|---|---|
Parametry |
|
GetPeerNodeId
uint64_t GetPeerNodeId( void ) const
Pobierz identyfikator węzła peera powiązania.
Ma zastosowanie tylko po przygotowaniu obiektu powiązania.
Szczegóły | |
---|---|
Zwroty |
Identyfikator węzła splotu równorzędnego
|
GetProtocolLayerCallback
void GetProtocolLayerCallback( EventCallback & callback, void *& state ) const
GetState
State GetState( void ) const
Pobierz bieżący stan powiązania.
Szczegóły | |
---|---|
Zwroty |
Stan powiązania.
|
IsAuthenticMessageFromPeer
bool IsAuthenticMessageFromPeer( const WeaveMessageInfo *msgInfo )
Ustal, czy konkretna wiadomość przychodząca pochodzi od skonfigurowanego peera i jest odpowiednio uwierzytelniona.
Ta metoda potwierdza następujące szczegóły dotyczące komunikatu:
- Komunikat pochodzi z węzła równorzędnego powiązania
- Wiadomość została odebrana za pomocą tego samego typu transportu co powiązanie. Jeśli wiadomość została odebrana przez połączenie, metoda potwierdza również, że została odebrana przez dokładne połączenie powiązane z powiązaniem.
- Klucz i typ szyfrowania użyte do zaszyfrowania wiadomości są zgodne z kluczami skonfigurowanymi w powiązaniu. W przypadku powiązań skonfigurowanych bez użycia zabezpieczeń metoda potwierdza, że wiadomość przychodząca NIE jest zaszyfrowana.
Ta metoda jest przeznaczona do stosowania w protokołach takich jak WDM, gdzie połączenia równorzędne mogą spontanicznie zainicjować wymianę wiadomości z powrotem do węzła lokalnego po początkowej wymiany między węzłem a peerem. W takich przypadkach metoda pozwala węzłowi lokalnemu sprawdzić, czy przychodząca niezamawiana wiadomość została wysłana przez powiązany peer. Oczywiście w przypadku powiązań skonfigurowanych bez szyfrowania wiadomości to potwierdzenie nie ma żadnej wartości z punktu widzenia bezpieczeństwa. Potwierdza tylko, że identyfikator węzła nadawcy i typy transportu są zgodne).
Pamiętaj, że jeśli powiązanie nie jest w stanie gotowości, ta metoda zawsze zwraca wartość false (fałsz).
Szczegóły | |||
---|---|---|---|
Parametry |
|
||
Zwroty |
Prawda, jeśli wiadomość pochodzi z grupy porównawczej.
|
IsConnectionTransport
bool IsConnectionTransport() const
IsPreparing
bool IsPreparing( void ) const
Szczegóły | |
---|---|
Zwroty |
Prawda, jeśli Wiązanie jest obecnie przygotowywane.
|
IsUDPTransport
bool IsUDPTransport() const
IsUnreliableUDPTransport
bool IsUnreliableUDPTransport() const
IsWRMTransport
bool IsWRMTransport() const
NewExchangeContext
WEAVE_ERROR NewExchangeContext( ExchangeContext *& appExchangeContext )
Przydziel nowy kontekst Exchange do komunikacji z peerem, który jest celem powiązania.
Szczegóły | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parametry |
|
||||||||
Zwracane wartości |
|
Premiera
void Release( void )
Zwolnij odwołanie do obiektu powiązania.
Jeśli nie ma więcej odwołań do obiektu powiązania, zostaje ono zamknięte i uwolnione.
RequestPrepare
WEAVE_ERROR RequestPrepare()
Poproś aplikację o skonfigurowanie i przygotowanie Binding.
Kod warstwy protokołu może używać tej metody w przypadku wiązania, które nie zostało skonfigurowane lub którego nie udało się skonfigurować, aby aktywować zdarzenie dla aplikacji (kEvent_PrepareRequested) żądające skonfigurowania i przygotowania powiązania do użycia.
Tę metodę można wywoływać tylko w przypadku powiązań w stanach Nieskonfigurowane lub Niepowodzenie.
Jeśli aplikacja nie obsługuje konfiguracji/przygotowywania powiązań na żądanie, metoda zakończy się niepowodzeniem z błędem WEAVE_ERROR_NOT_IMPLEMENTED.
Resetuj
void Reset( void )
Zresetuj powiązanie z powrotem do stanu nieskonfigurowanego.
Po wywołaniu funkcji Reset() wszystkie trwające działania przygotowujące do wiązania są anulowane, a wszystkie zewnętrzne zasoby komunikacyjne przechowywane przez powiązanie są anulowane. Funkcja Reset() ustawia powiązanie w stan Nieskonfigurowane, po czym można je skonfigurować i ponownie przygotować.
Funkcja Reset() nie zmienia liczby odwołań do powiązania.
SetDefaultResponseTimeout
void SetDefaultResponseTimeout( uint32_t msec )
Ustaw domyślny czas oczekiwania na odpowiedź giełdy, który będzie używany podczas komunikacji z peerem.
Szczegóły | |||
---|---|---|---|
Parametry |
|
SetDefaultWRMPConfig
void SetDefaultWRMPConfig( const WRMPConfig & wrmpConfig )
Ustaw domyślną konfigurację WRMP, która będzie używana podczas komunikacji z peerem.
Szczegóły | |||
---|---|---|---|
Parametry |
|
SetEventCallback
void SetEventCallback( EventCallback aEventCallback )
Ustaw funkcję zdefiniowaną przez aplikację, która ma być wywoływana, gdy wystąpi zdarzenie interfejsu API w polu Binding.
Szczegóły | |||
---|---|---|---|
Parametry |
|
SetProtocolLayerCallback
void SetProtocolLayerCallback( EventCallback callback, void *state )
Ustaw funkcję wywołania zwrotnego zdarzenia dla kodu warstwy protokołu, korzystając z opcji Binding (Wiązanie) w imieniu aplikacji.
Ta funkcja będzie wywoływana niezależnie od zdefiniowanej przez aplikację funkcji wywołania zwrotnego po wystąpieniu zdarzeń interfejsu API w polu Binding.
Szczegóły | |||||
---|---|---|---|---|---|
Parametry |
|
Publiczne funkcje statyczne
DefaultEventHandler
void DefaultEventHandler( void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam )
Domyślny moduł obsługi zdarzeń powiązanych z interfejsem API.
Aplikacje muszą wywoływać tę metodę w przypadku wszystkich zdarzeń interfejsu API, których nie rozpoznają ani nie obsługują. Podane parametry muszą być takie same jak te przekazane przez powiązanie z funkcją modułu obsługi zdarzeń aplikacji.
Szczegóły | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parametry |
|