nl:: Weave:: Binding
#include <src/lib/core/WeaveBinding.h>
Chụp mục tiêu dự định của giao tiếp Weave và thông tin cấu hình liên quan.
Tóm tắt
Đối tượng Binding xác định mục tiêu dự kiến của giao tiếp Weave (còn gọi là "ngang hàng"), cùng với một tập hợp các tham số cấu hình mô tả cách giao tiếp với ứng dụng ngang hàng. Các liên kết độc lập với giao thức ứng dụng được nói giữa hai bên. Như vậy, chúng nắm bắt "ai" và "cách thức" giao tiếp, chứ không ghi "cái gì".
Các ứng dụng phải định cấu hình Binding với các tham số dành riêng cho loại kênh liên lạc mong muốn. Các liên kết hỗ trợ nhiều phương thức truyền tải mạng, bao gồm cả TCP, UDP, UDP với tính năng Weave trust Messaging và Weave over BLE (WoBLE). Ứng dụng cũng có thể yêu cầu sử dụng các cơ chế bảo mật cụ thể để bảo vệ thư được gửi giữa các bên. Các khoá này bao gồm các phiên CASE và PASE cũng như các khoá nhóm ứng dụng. Giao diện để định cấu hình Liên kết sử dụng kiểu API khai báo cho phép các ứng dụng đưa ra yêu cầu giao tiếp bằng các điều khoản đơn giản.
Xem tài liệu về Binding::Configuration để biết thêm thông tin chi tiết.
Chuẩn bị
Trước khi giao tiếp diễn ra, Binding phải được "chuẩn bị". Hành động chuẩn bị Ràng buộc liên quan đến việc thiết lập trạng thái cần thiết để hoạt động giao tiếp diễn ra. Việc này có thể bao gồm những việc như: phân giải địa chỉ mạng của ứng dụng ngang hàng, thiết lập kết nối mạng và thương lượng khoá bảo mật. Sau khi được ứng dụng định cấu hình, Binding sẽ thực hiện tất cả các bước cần thiết để chuẩn bị giao tiếp, gọi lại ứng dụng khi quá trình hoàn tất. Bằng cách này, Liên kết ẩn cơ chế giao tiếp, cho phép các ứng dụng tập trung vào các hoạt động tương tác cấp cao.
Liên lạc
Sau khi chuẩn bị Liên kết, bạn sẽ có thể sử dụng nó. Ở trạng thái này, các ứng dụng (hoặc phổ biến hơn là mã lớp giao thức hoạt động thay cho một ứng dụng) yêu cầu Binding (Liên kết) để phân bổ ngữ cảnh Weave Exchange. Ngữ cảnh trao đổi kết quả được định cấu hình sẵn cho hoạt động giao tiếp, cho phép ứng dụng ngay lập tức bắt đầu trao đổi Weave với ứng dụng ngang hàng. Ứng dụng có thể tiếp tục yêu cầu ngữ cảnh trao đổi từ Liên kết cho đến khi Liên kết được đóng hoặc một số sự kiện như lỗi mạng sẽ chấm dứt kênh liên lạc cơ bản.
Các thay đổi về trạng thái liên kết
Trong quá trình sử dụng, Binding sẽ gửi các sự kiện API đến ứng dụng để thông báo cho ứng dụng về những thay đổi trong trạng thái của Binding. Ví dụ: khi chuẩn bị thành công, ứng dụng sẽ nhận được một sự kiện thông báo rằng Binding đã sẵn sàng để sử dụng. Tương tự, nếu kênh liên lạc cơ bản không thành công, thì một sự kiện sẽ được gửi đến ứng dụng thông báo cho ứng dụng rằng Binding không còn ở trạng thái sẵn sàng.
Các sự kiện API được phân phối đến ứng dụng thông qua hàm callback sự kiện được cung cấp khi Binding được phân bổ.
Thời gian tồn tại liên kết
Liên kết là các tệp đối chiếu được tính để cho phép sử dụng chung giữa nhiều thành phần phần mềm. Khi một Liên kết được phân bổ, một tham chiếu đến liên kết đó sẽ được tạo. Ứng dụng chịu trách nhiệm phát hành tệp đối chiếu này tại một thời điểm nào đó trong tương lai để Liên kết được tự do sử dụng lại sau này.
Khi một ứng dụng hoàn tất với một Binding, ứng dụng có thể gọi Close() trên liên kết. Thao tác này sẽ giải phóng tệp tham chiếu của ứng dụng đến Liên kết và chặn tất cả các sự kiện API được phân phối thêm. Khi tham chiếu cuối cùng đến một Liên kết được giải phóng, tệp này sẽ tự động bị đóng.
Loại công khai |
|
---|---|
@23{
|
enum |
EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
|
typedefvoid(*
|
EventType{
|
enum |
State
|
enum |
Thuộc tính công khai |
|
---|---|
AppState
|
void *
|
Hàm công khai |
|
---|---|
AddRef(void)
|
void
Đặt trước một tham chiếu đến đối tượng liên kết.
|
AdjustResponseTimeout(ExchangeContext *apExchangeContext) const
|
Định cấu hình lại Ngữ cảnh Exchange hiện có để điều chỉnh thời gian chờ phản hồi.
|
AllocateRightSizedBuffer(PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize)
|
|
BeginConfiguration()
|
Là quy trình định cấu hình Liên kết.
|
CanBePrepared(void) const
|
bool
|
Close(void)
|
void
Đóng đối tượng liên kết và giải phóng tệp tham chiếu.
|
GetConnection() const
|
Lấy đối tượng kết nối Weave liên kết với liên kết.
|
GetDefaultResponseTimeout() const
|
uint32_t
Sử dụng thời gian chờ phản hồi trao đổi mặc định khi giao tiếp với ứng dụng ngang hàng.
|
GetDefaultWRMPConfig(void) const
|
const WRMPConfig &
Cài đặt cấu hình WRMP mặc định để sử dụng khi giao tiếp với ứng dụng ngang hàng.
|
GetEncryptionType(void) const
|
uint8_t
Truy xuất loại mã hoá thư sẽ dùng khi mã hoá thư đến/từ ứng dụng ngang hàng.
|
GetEventCallback() const
|
EventCallback
Lấy hàm sẽ được gọi khi sự kiện API xảy ra cho Binding.
|
GetExchangeManager() const
|
|
GetKeyId(void) const
|
uint32_t
Truy xuất mã của khoá mã hoá thư sẽ được dùng khi mã hoá thư đến/gửi đến ứng dụng ngang hàng.
|
GetLogId(void) const
|
uint16_t
Tạo mã nhận dạng duy nhất cho liên kết.
|
GetMaxWeavePayloadSize(const System::PacketBuffer *msgBuf)
|
uint32_t
Lấy kích thước tải trọng tối đa của Weave có thể nằm vừa bên trong PacketBuffer được cung cấp.
|
GetPeerDescription(char *buf, uint32_t bufSize) const
|
void
Tạo một chuỗi mô tả nút ngang hàng và thông tin địa chỉ / kết nối liên kết của nút đó.
|
GetPeerIPAddress(nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId) const
|
void
Truy xuất thông tin địa chỉ IP của ứng dụng ngang hàng, nếu có.
|
GetPeerNodeId(void) const
|
uint64_t
Truy xuất mã nhận dạng nút của mạng ngang hàng liên kết.
|
GetProtocolLayerCallback(EventCallback & callback, void *& state) const
|
void
|
GetState(void) const
|
State
Truy xuất trạng thái hiện tại của liên kết.
|
IsAuthenticMessageFromPeer(const WeaveMessageInfo *msgInfo)
|
bool
Xác định xem một thư đến cụ thể có phải từ ứng dụng ngang hàng đã định cấu hình và có được xác thực phù hợp hay không.
|
IsConnectionTransport() const
|
bool
|
IsPreparing(void) const
|
bool
|
IsReady(void) const
|
bool
|
IsUDPTransport() const
|
bool
|
IsUnreliableUDPTransport() const
|
bool
|
IsWRMTransport() const
|
bool
|
NewExchangeContext(ExchangeContext *& appExchangeContext)
|
Phân bổ Ngữ cảnh trao đổi mới để giao tiếp với ứng dụng ngang hàng là mục tiêu của mối liên kết.
|
Release(void)
|
void
Giải phóng tham chiếu đến đối tượng liên kết.
|
RequestPrepare()
|
Yêu cầu ứng dụng định cấu hình và chuẩn bị Liên kết.
|
Reset(void)
|
void
Đặt lại liên kết trở lại trạng thái chưa định cấu hình.
|
SetDefaultResponseTimeout(uint32_t msec)
|
void
Đặt thời gian chờ phản hồi trao đổi mặc định sẽ được sử dụng khi giao tiếp với ứng dụng ngang hàng.
|
SetDefaultWRMPConfig(const WRMPConfig & wrmpConfig)
|
void
Thiết lập cấu hình WRMP mặc định sẽ sử dụng khi giao tiếp với ứng dụng ngang hàng.
|
SetEventCallback(EventCallback aEventCallback)
|
void
Đặt hàm do ứng dụng xác định được gọi khi sự kiện API xảy ra cho Binding.
|
SetProtocolLayerCallback(EventCallback callback, void *state)
|
void
Đặt hàm callback sự kiện cho mã lớp giao thức bằng cách sử dụng Binding thay mặt cho ứng dụng.
|
Hàm tĩnh công khai |
|
---|---|
DefaultEventHandler(void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam)
|
void
Trình xử lý mặc định cho các sự kiện API liên kết.
|
Lớp |
|
---|---|
nl:: |
Cung cấp giao diện kiểu khai báo để định cấu hình và chuẩn bị đối tượng Binding. |
Cấu trúc |
|
---|---|
nl:: |
Nhập tham số vào sự kiện Binding API. |
nl:: |
Xuất tham số đến một sự kiện Binding API. |
Loại công khai
@23
@23
Thuộc tính | |
---|---|
kGetPeerDescription_MaxLength
|
Độ dài tối đa của chuỗi (bao gồm cả ký tự NUL) do hàm GetPeerDescription() trả về. |
EventCallback
void(* EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
EventType
EventType
Thuộc tính | |
---|---|
kEvent_BindingFailed
|
Liên kết không thành công và không thể dùng để giao tiếp với ứng dụng ngang hàng nữa. |
kEvent_BindingReady
|
Đã thực hiện thành công hành động chuẩn bị trên liên kết và liên kết giờ đây có thể được dùng để giao tiếp với ứng dụng ngang hàng. |
kEvent_ConnectionEstablished
|
Kết nối Weave yêu cầu đã được thiết lập. |
kEvent_DefaultCheck
|
Dùng để xác minh cách xử lý sự kiện mặc định chính xác trong ứng dụng. |
kEvent_PASEParametersRequested
|
Ứng dụng được yêu cầu cung cấp các thông số sẽ được sử dụng trong quá trình thiết lập phiên PASE. |
kEvent_PrepareFailed
|
Không thực hiện được thao tác chuẩn bị trên mối liên kết này. |
kEvent_PrepareRequested
|
Ứng dụng được yêu cầu định cấu hình và chuẩn bị liên kết để ngăn xếp mạng sử dụng. |
kEvent_TAKEParametersRequested
|
Ứng dụng được yêu cầu cung cấp các tham số để dùng trong quá trình thiết lập phiên Take. |
Tiểu bang
State
Thuộc tính công khai
AppState
void * AppState
Hàm công khai
AddRef
void AddRef( void )
Đặt trước một tham chiếu đến đối tượng liên kết.
AdjustResponseTimeout
WEAVE_ERROR AdjustResponseTimeout( ExchangeContext *apExchangeContext ) const
Định cấu hình lại Ngữ cảnh Exchange hiện có để điều chỉnh thời gian chờ phản hồi.
Thông tin chi tiết | |||
---|---|---|---|
Các tham số |
|
AllocateRightSizedBuffer
WEAVE_ERROR AllocateRightSizedBuffer( PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize )
BeginConfiguration
Configuration BeginConfiguration()
Là quy trình định cấu hình Liên kết.
Các ứng dụng phải gọi BeginConfiguration() để định cấu hình Binding trước khi chuẩn bị giao tiếp với ứng dụng ngang hàng.
Thông tin chi tiết | |
---|---|
Trả về |
Bạn có thể dùng đối tượng Binding::Configuration để định cấu hình liên kết.
|
CanBePrepared
bool CanBePrepared( void ) const
Đóng
void Close( void )
Đóng đối tượng liên kết và giải phóng tệp tham chiếu.
Khi được gọi, phương thức này sẽ khiến liên kết chuyển sang trạng thái Đã đóng. Mọi hành động đang chuẩn bị cho mối liên kết này đều bị huỷ và mọi tài nguyên giao tiếp bên ngoài mà liên kết này giữ lại sẽ được giải phóng.
Lệnh gọi Close() sẽ giảm số lượng tham chiếu được liên kết với liên kết, giải phóng đối tượng nếu số lượng tham chiếu trở thành 0.
GetConnection
WeaveConnection * GetConnection() const
Lấy đối tượng kết nối Weave liên kết với liên kết.
Thông tin chi tiết | |
---|---|
Trả về |
Con trỏ đến đối tượng WeaveConnection hoặc NULL nếu không có kết nối nào được liên kết với liên kết.
|
GetDefaultResponseTimeout
uint32_t GetDefaultResponseTimeout() const
Sử dụng thời gian chờ phản hồi trao đổi mặc định khi giao tiếp với ứng dụng ngang hàng.
Thông tin chi tiết | |
---|---|
Trả về |
Thời gian chờ phản hồi tính bằng mili giây.
|
GetDefaultWRMPConfig
const WRMPConfig & GetDefaultWRMPConfig( void ) const
Cài đặt cấu hình WRMP mặc định để sử dụng khi giao tiếp với ứng dụng ngang hàng.
Thông tin chi tiết | |
---|---|
Trả về |
Tham chiếu đến cấu trúc WRMPConfig có chứa các giá trị cấu hình mặc định.
|
GetEncryptionType
uint8_t GetEncryptionType( void ) const
Truy xuất loại mã hoá thư sẽ dùng khi mã hoá thư đến/từ ứng dụng ngang hàng.
GetEventCallback
EventCallback GetEventCallback() const
Lấy hàm sẽ được gọi khi sự kiện API xảy ra cho Binding.
Thông tin chi tiết | |
---|---|
Trả về |
Con trỏ đến hàm callback.
|
GetExchangeManager
WeaveExchangeManager * GetExchangeManager() const
GetKeyId
uint32_t GetKeyId( void ) const
Truy xuất mã của khoá mã hoá thư sẽ được dùng khi mã hoá thư đến/gửi đến ứng dụng ngang hàng.
GetLogId
uint16_t GetLogId( void ) const
Tạo mã nhận dạng duy nhất cho liên kết.
GetMaxWeavePayloadSize
uint32_t GetMaxWeavePayloadSize( const System::PacketBuffer *msgBuf )
Lấy kích thước tải trọng tối đa của Weave có thể nằm vừa bên trong PacketBuffer được cung cấp.
Đối với UDP, bao gồm cả UDP có WRM, kích thước tải trọng tối đa được trả về sẽ đảm bảo thông báo Weave thu được sẽ không tràn MTU UDP đã định cấu hình.
Ngoài ra, phương pháp này đảm bảo tải trọng Weave sẽ không tràn gói (packetBuffer) được cung cấp.
Thông tin chi tiết | |||
---|---|---|---|
Các tham số |
|
||
Trả về |
Kích thước tải trọng tối đa của Weave.
|
GetPeerDescription
void GetPeerDescription( char *buf, uint32_t bufSize ) const
Tạo một chuỗi mô tả nút ngang hàng và thông tin địa chỉ / kết nối liên kết của nút đó.
Thông tin chi tiết | |||||
---|---|---|---|---|---|
Các tham số |
|
GetPeerIPAddress
void GetPeerIPAddress( nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId ) const
Truy xuất thông tin địa chỉ IP của ứng dụng ngang hàng, nếu có.
Thông tin địa chỉ IP có sẵn của ứng dụng ngang hàng hay không phụ thuộc vào trạng thái và cấu hình của mối liên kết. Thông tin về địa chỉ IP chỉ có sẵn khi sử dụng phương thức truyền tải dựa trên IP (TCP, UDP hoặc UDP với WRMP). Trước khi bắt đầu chuẩn bị, thông tin địa chỉ chỉ có sẵn nếu ứng dụng đã đặt rõ ràng thông tin đó trong quá trình định cấu hình. Trong giai đoạn chuẩn bị, thông tin về địa chỉ sẽ được cung cấp khi hoàn tất quá trình chuẩn bị địa chỉ (ví dụ: sau khi quá trình phân giải DNS đã hoàn tất). Sau khi Liên kết đã sẵn sàng, thông tin địa chỉ vẫn còn cho đến khi Liên kết được đặt lại.
Thông tin chi tiết | |||||||
---|---|---|---|---|---|---|---|
Các tham số |
|
GetPeerNodeId
uint64_t GetPeerNodeId( void ) const
Truy xuất mã nhận dạng nút của mạng ngang hàng liên kết.
Chỉ hợp lệ sau khi đối tượng liên kết đã được chuẩn bị.
Thông tin chi tiết | |
---|---|
Trả về |
Mã nút dệt của ứng dụng ngang hàng
|
GetProtocolLayerCallback
void GetProtocolLayerCallback( EventCallback & callback, void *& state ) const
GetState
State GetState( void ) const
Truy xuất trạng thái hiện tại của liên kết.
Thông tin chi tiết | |
---|---|
Trả về |
Trạng thái liên kết.
|
IsAuthenticMessageFromPeer
bool IsAuthenticMessageFromPeer( const WeaveMessageInfo *msgInfo )
Xác định xem một thư đến cụ thể có phải từ ứng dụng ngang hàng đã định cấu hình và có được xác thực phù hợp hay không.
Phương thức này xác nhận các thông tin chi tiết sau đây về thông báo đã cho:
- Thông báo bắt nguồn từ nút ngang hàng của liên kết
- Thông báo đã được nhận qua cùng một loại hình truyền tải với liên kết. Nếu thông báo được nhận qua một kết nối, phương thức này cũng xác nhận rằng thông báo đã được nhận qua kết nối chính xác được liên kết với liên kết.
- Khoá và loại khoá mã hoá dùng để mã hoá thư sẽ khớp với khoá và loại được định cấu hình trong liên kết. Đối với các liên kết được định cấu hình mà không sử dụng bảo mật, phương thức này sẽ xác nhận rằng thư đến KHÔNG được mã hoá.
Phương thức này được dự định sẽ được dùng trong các giao thức như WDM, trong đó các ứng dụng ngang hàng có thể tự động bắt đầu trao đổi trở lại nút cục bộ sau quá trình trao đổi ban đầu từ nút này sang nút ngang hàng. Trong những trường hợp như vậy, phương thức này cho phép nút cục bộ xác nhận rằng thông báo không mong muốn đến do ứng dụng ngang hàng được liên kết gửi. (Tất nhiên, đối với các Liên kết được định cấu hình mà không sử dụng mã hoá thư, câu nhận định này sẽ không có giá trị nào từ góc độ bảo mật. Thông báo này chỉ xác nhận rằng mã nhận dạng nút người gửi và loại truyền tải khớp với nhau.)
Lưu ý rằng nếu liên kết không ở trạng thái Sẵn sàng, phương thức này sẽ luôn trả về giá trị false.
Thông tin chi tiết | |||
---|---|---|---|
Các tham số |
|
||
Trả về |
Đúng nếu tin nhắn đó đúng là của một người ngang hàng.
|
IsConnectionTransport
bool IsConnectionTransport() const
IsPreparing
bool IsPreparing( void ) const
Thông tin chi tiết | |
---|---|
Trả về |
Đúng nếu Liên kết hiện đang được chuẩn bị.
|
IsReady
bool IsReady( void ) const
Thông tin chi tiết | |
---|---|
Trả về |
Đúng nếu Liên kết ở trạng thái Sẵn sàng.
|
IsUDPTransport
bool IsUDPTransport() const
IsUnreliableUDPTransport
bool IsUnreliableUDPTransport() const
IsWRMTransport
bool IsWRMTransport() const
NewExchangeContext
WEAVE_ERROR NewExchangeContext( ExchangeContext *& appExchangeContext )
Phân bổ Ngữ cảnh trao đổi mới để giao tiếp với ứng dụng ngang hàng là mục tiêu của mối liên kết.
Thông tin chi tiết | |||||||||
---|---|---|---|---|---|---|---|---|---|
Các tham số |
|
||||||||
Giá trị trả về |
|
Bản phát hành
void Release( void )
Giải phóng tham chiếu đến đối tượng liên kết.
Nếu không có tham chiếu nào nữa đến đối tượng liên kết, liên kết sẽ được đóng và giải phóng.
RequestPrepare
WEAVE_ERROR RequestPrepare()
Yêu cầu ứng dụng định cấu hình và chuẩn bị Liên kết.
Mã lớp giao thức có thể sử dụng phương thức này trên một Binding chưa được định cấu hình, hoặc đã không thành công, để kích hoạt sự kiện cho ứng dụng (kEvent_Available) yêu cầu nó định cấu hình và chuẩn bị liên kết để sử dụng.
Phương thức này chỉ có thể được gọi trên các Liên kết ở trạng thái Chưa được định cấu hình hoặc Không thành công.
Nếu ứng dụng không hỗ trợ cấu hình/chuẩn bị các Liên kết theo yêu cầu, thì phương thức này sẽ không thành công với WEAVE_ERROR_NOT_IMPLEMENTED.
Đặt lại
void Reset( void )
Đặt lại liên kết trở lại trạng thái chưa định cấu hình.
Khi lệnh Reset() được gọi, mọi hành động đang chuẩn bị cho liên kết này sẽ bị huỷ và mọi tài nguyên giao tiếp bên ngoài do liên kết này giữ lại sẽ được giải phóng. Reset() đặt liên kết ở trạng thái Chưa được định cấu hình, sau đó nó có thể được định cấu hình và chuẩn bị lại.
Reset() không làm thay đổi số lượng tham chiếu của liên kết.
SetDefaultResponseTimeout
void SetDefaultResponseTimeout( uint32_t msec )
Đặt thời gian chờ phản hồi trao đổi mặc định sẽ được sử dụng khi giao tiếp với ứng dụng ngang hàng.
Thông tin chi tiết | |||
---|---|---|---|
Các tham số |
|
SetDefaultWRMPConfig
void SetDefaultWRMPConfig( const WRMPConfig & wrmpConfig )
Thiết lập cấu hình WRMP mặc định sẽ sử dụng khi giao tiếp với ứng dụng ngang hàng.
Thông tin chi tiết | |||
---|---|---|---|
Các tham số |
|
SetEventCallback
void SetEventCallback( EventCallback aEventCallback )
Đặt hàm do ứng dụng xác định được gọi khi sự kiện API xảy ra cho Binding.
Thông tin chi tiết | |||
---|---|---|---|
Các tham số |
|
SetProtocolLayerCallback
void SetProtocolLayerCallback( EventCallback callback, void *state )
Đặt hàm callback sự kiện cho mã lớp giao thức bằng cách sử dụng Binding thay mặt cho ứng dụng.
Hàm này sẽ được gọi cùng với hàm callback do ứng dụng xác định khi sự kiện API xảy ra cho Binding.
Thông tin chi tiết | |||||
---|---|---|---|---|---|
Các tham số |
|
Hàm tĩnh công khai
DefaultEventHandler
void DefaultEventHandler( void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam )
Trình xử lý mặc định cho các sự kiện API liên kết.
Ứng dụng bắt buộc phải gọi phương thức này cho mọi sự kiện API mà ứng dụng không nhận dạng hoặc xử lý. Các tham số được cung cấp phải giống với tham số được chuyển bằng liên kết đến hàm trình xử lý sự kiện của ứng dụng.
Thông tin chi tiết | |||||||||
---|---|---|---|---|---|---|---|---|---|
Các tham số |
|