nl::Weave::Binding

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

Menangkap target yang dimaksud dari komunikasi Weave dan informasi konfigurasi terkait.

Ringkasan

Objek Binding mengidentifikasi target yang diinginkan dari komunikasi Weave (juga dikenal sebagai "peer"), bersama dengan kumpulan parameter konfigurasi yang menjelaskan cara melakukan komunikasi dengan pembanding. Binding tidak bergantung pada protokol aplikasi yang diucapkan antara dua pihak. Dengan demikian, mereka menangkap “siapa” dan "bagaimana" dari suatu komunikasi, tetapi bukan “apa.”

Konfigurasi

Aplikasi harus mengonfigurasi Binding dengan parameter khusus untuk jenis saluran komunikasi yang diinginkan. Binding memberikan dukungan untuk berbagai transpor jaringan, termasuk TCP, UDP, UDP dengan Weave Reliable Messaging, dan Weave over BLE (WoBLE). Aplikasi juga dapat meminta penggunaan mekanisme keamanan tertentu untuk melindungi pesan yang dikirim di antara para pihak. Ini termasuk sesi CASE dan PASE, serta kunci grup aplikasi. Antarmuka untuk mengonfigurasi Binding menggunakan gaya API deklaratif yang memungkinkan aplikasi menyatakan persyaratannya untuk komunikasi dengan istilah sederhana.

Lihat dokumentasi untuk Binding::Configuration untuk detail lebih lanjut.

Persiapan

Sebelum komunikasi berlangsung, Binding harus "disiapkan". Tindakan menyiapkan Binding melibatkan penetapan status yang diperlukan agar komunikasi dapat dilakukan. Hal ini dapat mencakup hal-hal seperti: menyelesaikan alamat jaringan pembanding, membuat koneksi jaringan, dan menegosiasikan kunci keamanan. Setelah dikonfigurasi oleh aplikasi, Binding menangani semua langkah yang diperlukan untuk mempersiapkan komunikasi, sehingga melakukan callback ke aplikasi saat proses selesai. Dengan cara ini, Binding menyembunyikan mekanisme komunikasi, sehingga memungkinkan aplikasi untuk berkonsentrasi pada interaksi tingkat tinggi.

Komunikasi

Setelah disiapkan, Binding akan siap digunakan. Dalam status ini, aplikasi (atau lebih umum, kode lapisan protokol yang berfungsi atas nama aplikasi) meminta Binding untuk mengalokasikan konteks pertukaran Weave. Konteks pertukaran yang dihasilkan telah dikonfigurasi sebelumnya untuk komunikasi, sehingga aplikasi dapat segera memulai pertukaran Weave dengan peer. Aplikasi dapat terus meminta konteks pertukaran dari Binding hingga Binding ditutup, atau beberapa peristiwa, misalnya kegagalan jaringan, menghentikan saluran komunikasi yang mendasarinya.

Perubahan Status Binding

Selama penggunaannya, Binding akan mengirimkan peristiwa API ke aplikasi yang memberitahukan perubahan status Binding. Misalnya, saat persiapan berhasil, aplikasi akan menerima peristiwa yang menginformasikan bahwa Binding siap digunakan. Demikian pula, jika saluran komunikasi yang mendasarinya gagal, peristiwa akan dikirim ke aplikasi yang menginformasikan bahwa Binding tidak lagi dalam status siap.

Peristiwa API dikirim ke aplikasi melalui fungsi callback peristiwa yang disediakan saat Binding dialokasikan.

Masa Pakai Binding

Binding dihitung berdasarkan referensi untuk memungkinkan penggunaan bersama di beberapa komponen software. Saat Binding dialokasikan, satu referensi ke binding akan dibuat. Aplikasi bertanggung jawab untuk merilis referensi ini suatu saat di masa mendatang sehingga Binding bebas digunakan kembali lagi.

Jika selesai dengan Binding, aplikasi dapat memanggil Close() pada binding. Tindakan ini akan merilis referensi aplikasi ke Binding dan memblokir semua pengiriman peristiwa API lebih lanjut. Saat referensi terakhir ke Binding dilepaskan, referensi ini akan otomatis ditutup.

Jenis publik
@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

Atribut publik
AppState
void *

Fungsi publik
AddRef(void)
void
Mencadangkan referensi ke objek binding.
AdjustResponseTimeout(ExchangeContext *apExchangeContext) const
Konfigurasi ulang Konteks Exchange yang ada untuk menyesuaikan waktu tunggu respons.
AllocateRightSizedBuffer(PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize)
BeginConfiguration()
Sedangkan proses mengonfigurasi Binding.
CanBePrepared(void) const
bool
Close(void)
void
Tutup objek binding dan lepaskan referensi.
GetConnection() const
Dapatkan objek koneksi Weave yang terkait dengan binding.
GetDefaultResponseTimeout() const
uint32_t
Dapatkan waktu tunggu respons pertukaran default untuk digunakan saat berkomunikasi dengan rekan.
GetDefaultWRMPConfig(void) const
const WRMPConfig &
Dapatkan konfigurasi WRMP default yang akan digunakan saat berkomunikasi dengan peer.
GetEncryptionType(void) const
uint8_t
Ambil jenis enkripsi pesan yang akan digunakan saat mengenkripsi pesan ke/dari peer.
GetEventCallback() const
EventCallback
Mendapatkan fungsi yang akan dipanggil saat peristiwa API terjadi untuk Binding.
GetExchangeManager() const
GetKeyId(void) const
uint32_t
Ambil ID kunci enkripsi pesan yang akan digunakan saat mengenkripsi pesan ke/dari ke peer.
GetLogId(void) const
uint16_t
Dapatkan ID unik untuk binding.
GetMaxWeavePayloadSize(const System::PacketBuffer *msgBuf)
uint32_t
Dapatkan ukuran payload Weave maksimal yang dapat ditampung di dalam PacketBuffer yang disediakan.
GetPeerDescription(char *buf, uint32_t bufSize) const
void
Membuat string yang mendeskripsikan node peer dan informasi alamat / koneksi terkait.
GetPeerIPAddress(nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId) const
void
Ambil informasi alamat IP untuk pembanding, jika tersedia.
GetPeerNodeId(void) const
uint64_t
Ambil ID node dari peer binding.
GetProtocolLayerCallback(EventCallback & callback, void *& state) const
void
GetState(void) const
State
Ambil status binding saat ini.
IsAuthenticMessageFromPeer(const WeaveMessageInfo *msgInfo)
bool
Menentukan apakah pesan masuk tertentu berasal dari peer yang dikonfigurasi dan diautentikasi.
IsConnectionTransport() const
bool
IsPreparing(void) const
bool
IsReady(void) const
bool
IsUDPTransport() const
bool
IsUnreliableUDPTransport() const
bool
IsWRMTransport() const
bool
NewExchangeContext(ExchangeContext *& appExchangeContext)
Alokasikan Konteks Exchange baru untuk berkomunikasi dengan peer yang merupakan target binding.
Release(void)
void
Merilis referensi ke objek binding.
RequestPrepare()
Minta aplikasi untuk mengonfigurasi dan menyiapkan Binding.
Reset(void)
void
Reset binding kembali ke status yang tidak dikonfigurasi.
SetDefaultResponseTimeout(uint32_t msec)
void
Tetapkan waktu tunggu respons pertukaran default yang akan digunakan saat berkomunikasi dengan rekan.
SetDefaultWRMPConfig(const WRMPConfig & wrmpConfig)
void
Tetapkan konfigurasi WRMP default yang akan digunakan saat berkomunikasi dengan peer.
SetEventCallback(EventCallback aEventCallback)
void
Menetapkan fungsi yang ditentukan aplikasi agar dipanggil saat peristiwa API terjadi untuk Binding.
SetProtocolLayerCallback(EventCallback callback, void *state)
void
Tetapkan fungsi callback peristiwa untuk kode lapisan protokol menggunakan Binding atas nama aplikasi.

Fungsi statis publik
DefaultEventHandler(void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam)
void
Pengendali default untuk peristiwa API binding.

Class
nl::Weave::Binding::Configuration

Menyediakan antarmuka bergaya deklaratif untuk mengonfigurasi dan menyiapkan objek Binding.

Struct
nl::Weave::Binding::InEventParam

Parameter input ke peristiwa Binding API.

nl::Weave::Binding::OutEventParam

Parameter output ke peristiwa Binding API.

Jenis publik

@23

 @23
Properti
kGetPeerDescription_MaxLength

Panjang string maksimum (termasuk karakter NUL) yang ditampilkan oleh GetPeerDescription().

EventCallback

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

EventType

 EventType
Properti
kEvent_BindingFailed

Binding gagal dan tidak dapat digunakan lagi untuk berkomunikasi dengan peer.

kEvent_BindingReady

Tindakan persiapan pada binding berhasil, dan binding sekarang dapat digunakan untuk berkomunikasi dengan peer.

kEvent_ConnectionEstablished

Koneksi Weave yang diminta telah dibuat.

kEvent_DefaultCheck

Digunakan untuk memverifikasi penanganan peristiwa default yang benar dalam aplikasi.

kEvent_PASEParametersRequested

Aplikasi diminta untuk menyediakan parameter yang akan digunakan selama penetapan sesi PASE.

kEvent_PrepareFailed

Tindakan persiapan pada binding gagal.

kEvent_PrepareRequested

Aplikasi diminta untuk mengonfigurasi dan menyiapkan binding untuk digunakan oleh stack jaringan.

kEvent_TAKEParametersRequested

Aplikasi diminta untuk menyediakan parameter yang akan digunakan selama pembentukan sesi TAKE.

Negara Bagian

 State

Atribut publik

AppState

void * AppState

Fungsi publik

AddRef

void AddRef(
  void
)

Mencadangkan referensi ke objek binding.

AdjustResponseTimeout

WEAVE_ERROR AdjustResponseTimeout(
  ExchangeContext *apExchangeContext
) const

Konfigurasi ulang Konteks Exchange yang ada untuk menyesuaikan waktu tunggu respons.

Detail
Parameter
[in] apExchangeContext
Pointer ke objek Konteks Exchange yang akan dikonfigurasi ulang

AllocateRightSizedBuffer

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

BeginConfiguration

Configuration BeginConfiguration()

Sedangkan proses mengonfigurasi Binding.

Aplikasi harus memanggil BeginConfiguration() guna mengonfigurasi Binding sebelum menyiapkannya untuk berkomunikasi dengan peer.

Detail
Hasil
Objek Binding::Configuration yang dapat digunakan untuk mengonfigurasi binding.

CanBePrepared

bool CanBePrepared(
  void
) const

Tutup

void Close(
  void
)

Tutup objek binding dan lepaskan referensi.

Jika dipanggil, metode ini akan menyebabkan binding memasuki status Tertutup. Setiap tindakan persiapan yang sedang berlangsung untuk binding akan dibatalkan dan semua resource komunikasi eksternal yang disimpan oleh binding akan dilepaskan.

Memanggil Close() akan mengurangi jumlah referensi yang terkait dengan binding, yang membebaskan objek jika jumlah referensi menjadi nol.

GetConnection

WeaveConnection * GetConnection() const

Dapatkan objek koneksi Weave yang terkait dengan binding.

Detail
Hasil
Pointer ke objek WeaveConnection, atau NULL jika tidak ada koneksi yang terkait dengan binding.

GetDefaultResponseTimeout

uint32_t GetDefaultResponseTimeout() const

Dapatkan waktu tunggu respons pertukaran default untuk digunakan saat berkomunikasi dengan rekan.

Detail
Hasil
Waktu tunggu respons dalam milidetik.

GetDefaultWRMPConfig

const WRMPConfig & GetDefaultWRMPConfig(
  void
) const

Dapatkan konfigurasi WRMP default yang akan digunakan saat berkomunikasi dengan peer.

Detail
Hasil
Referensi ke struktur WRMPConfig yang berisi nilai konfigurasi default.

GetEncryptionType

uint8_t GetEncryptionType(
  void
) const

Ambil jenis enkripsi pesan yang akan digunakan saat mengenkripsi pesan ke/dari peer.

GetEventCallback

EventCallback GetEventCallback() const

Mendapatkan fungsi yang akan dipanggil saat peristiwa API terjadi untuk Binding.

Detail
Hasil
Pointer ke fungsi callback.

GetExchangeManager

WeaveExchangeManager * GetExchangeManager() const

GetKeyId

uint32_t GetKeyId(
  void
) const

Ambil ID kunci enkripsi pesan yang akan digunakan saat mengenkripsi pesan ke/dari ke peer.

GetLogId

uint16_t GetLogId(
  void
) const

Dapatkan ID unik untuk binding.

GetMaxWeavePayloadSize

uint32_t GetMaxWeavePayloadSize(
  const System::PacketBuffer *msgBuf
)

Dapatkan ukuran payload Weave maksimal yang dapat ditampung di dalam PacketBuffer yang disediakan.

Untuk UDP, termasuk UDP dengan WRM, ukuran payload maksimum yang ditampilkan akan memastikan pesan Weave yang dihasilkan tidak melebihi MTU UDP yang dikonfigurasi.

Selain itu, metode ini akan memastikan payload Weave tidak akan melebihi PacketBuffer yang disediakan.

Detail
Parameter
[in] msgBuf
Pointer ke PacketBuffer yang menjadi tempat penulisan payload pesan.
Hasil
Ukuran payload Weave maksimum.

GetPeerDescription

void GetPeerDescription(
  char *buf,
  uint32_t bufSize
) const

Membuat string yang mendeskripsikan node peer dan informasi alamat / koneksi terkait.

Detail
Parameter
[in] buf
Pointer ke buffer tempat string harus ditulis. Buffer yang disediakan harus berukuran minimal sebesar kGetPeerDescription_MaxLength. Jika buffer yang lebih kecil diberikan, string akan dipotong agar pas. Output-nya akan mencakup karakter penghentian NUL dalam semua kasus.
[in] bufSize
Ukuran buffer yang ditunjuk oleh buf.

GetPeerIPAddress

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

Ambil informasi alamat IP untuk pembanding, jika tersedia.

Ketersediaan informasi alamat IP peer bergantung pada status dan konfigurasi binding. Informasi alamat IP hanya tersedia saat menggunakan transportasi berbasis IP (TCP, UDP, atau UDP dengan WRMP). Sebelum memulai persiapan, informasi alamat hanya tersedia jika telah ditetapkan secara jelas oleh aplikasi selama konfigurasi. Selama fase persiapan, informasi alamat tersedia saat persiapan alamat selesai (mis. setelah resolusi DNS selesai). Setelah Binding siap, informasi alamat akan tetap tersedia hingga Binding direset.

Detail
Parameter
[out] address
Referensi ke objek IPAddress yang akan menerima alamat IP peer. Jika informasi alamat IP peer tidak tersedia, nilai ini akan ditetapkan ke IPAddress::Any.
[out] port
Referensi ke bilangan bulat yang akan menerima nomor port peer. Jika informasi alamat IP pembanding tidak tersedia, nilai ini tidak ditentukan.
[out] interfaceId
Referensi ke integer yang akan menerima ID antarmuka jaringan yang dapat dijangkau peer. Jika informasi alamat IP pembanding tidak tersedia, nilai ini tidak ditentukan.

GetPeerNodeId

uint64_t GetPeerNodeId(
  void
) const

Ambil ID node dari peer binding.

Hanya berlaku setelah objek binding disiapkan.

Detail
Hasil
ID node Weave pembanding

GetProtocolLayerCallback

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

GetState

State GetState(
  void
) const

Ambil status binding saat ini.

Detail
Hasil
Status binding.

IsAuthenticMessageFromPeer

bool IsAuthenticMessageFromPeer(
  const WeaveMessageInfo *msgInfo
)

Menentukan apakah pesan masuk tertentu berasal dari peer yang dikonfigurasi dan diautentikasi.

Metode ini akan mengonfirmasi detail berikut tentang pesan yang diberikan:

  • Pesan berasal dari node peer dari binding
  • Pesan diterima melalui jenis transport yang sama dengan binding. Jika pesan diterima melalui koneksi, metode juga mengonfirmasi bahwa pesan telah diterima melalui koneksi yang tepat yang terkait dengan binding.
  • Kunci dan jenis enkripsi yang digunakan untuk mengenkripsi pesan cocok dengan yang dikonfigurasi dalam binding. Untuk binding yang dikonfigurasi tanpa penggunaan keamanan, metode ini mengonfirmasi bahwa pesan masuk TIDAK dienkripsi.

Metode ini dimaksudkan untuk digunakan dalam protokol seperti WDM di mana rekan dapat secara spontan memulai pertukaran kembali ke node lokal setelah pertukaran awal dari node ke peer. Dalam kasus seperti itu, metode ini memungkinkan node lokal untuk mengonfirmasi bahwa pesan masuk yang tidak diminta dikirim oleh peer terkait. (Tentu saja, untuk Binding yang dikonfigurasi tanpa penggunaan enkripsi pesan, pernyataan ini tidak memberikan nilai dari perspektif keamanan. Metode ini hanya mengonfirmasi bahwa ID node pengirim dan jenis transpor cocok.)

Perhatikan bahwa jika binding tidak dalam status Siap, metode ini akan selalu menampilkan false.

Detail
Parameter
[in] msgInfo
Informasi pesan Weave untuk pesan masuk.
Hasil
True jika pesan tersebut asli dari rekan.

IsConnectionTransport

bool IsConnectionTransport() const

IsPreparing

bool IsPreparing(
  void
) const

Detail
Hasil
True jika Binding sedang disiapkan.

IsReady

bool IsReady(
  void
) const

Detail
Hasil
True jika Binding dalam status Siap.

IsUDPTransport

bool IsUDPTransport() const

IsUnreliableUDPTransport

bool IsUnreliableUDPTransport() const

IsWRMTransport

bool IsWRMTransport() const

NewExchangeContext

WEAVE_ERROR NewExchangeContext(
  ExchangeContext *& appExchangeContext
)

Alokasikan Konteks Exchange baru untuk berkomunikasi dengan peer yang merupakan target binding.

Detail
Parameter
[out] appExchangeContext
Referensi ke pointer yang akan menerima objek Konteks Exchange yang baru dialokasikan. Pointer akan diatur ke NULL jika metode tersebut gagal.
Nilai yang Ditampilkan
WEAVE_NO_ERROR
Jika konteks pertukaran berhasil dialokasikan.
WEAVE_ERROR_NO_MEMORY
Jika tidak ada memori yang tersedia untuk mengalokasikan konteks pertukaran.
WEAVE_ERROR_INCORRECT_STATE
Jika binding tidak dalam status Siap.
other
Error lain terkait konfigurasi konteks pertukaran berdasarkan konfigurasi binding.

Rilis

void Release(
  void
)

Merilis referensi ke objek binding.

Jika tidak ada lagi referensi ke objek binding, binding akan ditutup dan dibebaskan.

RequestPrepare

WEAVE_ERROR RequestPrepare()

Minta aplikasi untuk mengonfigurasi dan menyiapkan Binding.

Kode lapisan protokol dapat menggunakan metode ini pada Binding yang belum dikonfigurasi, atau gagal, untuk memicu peristiwa ke aplikasi (kEvent_PrepareRequest) yang memintanya mengonfigurasi dan menyiapkan binding untuk digunakan.

Metode ini hanya dapat dipanggil pada Binding dalam status NotConfigured atau Failed.

Jika aplikasi tidak mendukung konfigurasi/persiapan Binding sesuai permintaan, metode ini akan gagal dengan WEAVE_ERROR_NOT_IMPLEMENTED.

Reset

void Reset(
  void
)

Reset binding kembali ke status yang tidak dikonfigurasi.

Saat Reset() dipanggil, semua tindakan persiapan yang sedang berlangsung untuk binding akan dibatalkan dan semua resource komunikasi eksternal yang disimpan oleh binding akan dilepaskan. Reset() menempatkan binding dalam status Belum dikonfigurasi, setelah itu dapat dikonfigurasi dan disiapkan lagi.

Reset() tidak mengubah jumlah referensi binding.

SetDefaultResponseTimeout

void SetDefaultResponseTimeout(
  uint32_t msec
)

Tetapkan waktu tunggu respons pertukaran default yang akan digunakan saat berkomunikasi dengan rekan.

Detail
Parameter
[in] timeout
Waktu tunggu respons baru dalam milidetik.

SetDefaultWRMPConfig

void SetDefaultWRMPConfig(
  const WRMPConfig & wrmpConfig
)

Tetapkan konfigurasi WRMP default yang akan digunakan saat berkomunikasi dengan peer.

Detail
Parameter
[in] aWRMPConfig
Referensi ke struktur WRMPConfig yang berisi konfigurasi default baru.

SetEventCallback

void SetEventCallback(
  EventCallback aEventCallback
)

Menetapkan fungsi yang ditentukan aplikasi agar dipanggil saat peristiwa API terjadi untuk Binding.

Detail
Parameter
[in] aEventCallback
Pointer ke fungsi callback.

SetProtocolLayerCallback

void SetProtocolLayerCallback(
  EventCallback callback,
  void *state
)

Tetapkan fungsi callback peristiwa untuk kode lapisan protokol menggunakan Binding atas nama aplikasi.

Fungsi ini akan dipanggil selain fungsi callback yang ditentukan aplikasi saat peristiwa API terjadi untuk Binding.

Detail
Parameter
[in] callback
Pointer ke fungsi callback.
[in] state
Pointer ke objek status yang akan diberikan ke kode lapisan protokol saat callback lapisan protokol terjadi.

Fungsi statis publik

DefaultEventHandler

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

Pengendali default untuk peristiwa API binding.

Aplikasi diperlukan untuk memanggil metode ini untuk setiap peristiwa API yang tidak dikenali atau ditangani. Parameter yang diberikan harus sama dengan parameter yang diteruskan oleh binding ke fungsi pengendali peristiwa aplikasi.

Detail
Parameter
[in] apAppState
Pointer ke informasi status yang ditetapkan aplikasi yang terkait dengan binding.
[in] aEvent
ID peristiwa yang diteruskan oleh callback peristiwa
[in] aInParam
Referensi parameter peristiwa input yang diteruskan oleh callback peristiwa
[in] aOutParam
Referensi parameter peristiwa output yang diteruskan oleh callback peristiwa