nl:: Dệt:: Liên kết
#include <src/lib/core/WeaveBinding.h>
Chụp mục tiêu dự kiến của thông tin Weave và thông tin cấu hình được liên kết.
Tóm tắt
Đối tượng Liên kết xác định mục tiêu dự kiến của giao tiếp Weave (còn gọi là "Peer"), cùng với một tập hợp tham số cấu hình mô tả quá trình giao tiếp với ứng dụng ngang hàng sẽ diễn ra như thế nào. 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. Do đó, họ có thể theo dõi "ai" và "how" của thông tin liên lạc, nhưng không phải &"what."
Ứng dụng phải định cấu hình Liên kết với các thông số dành riêng cho loại kênh liên lạc mong muốn. Liên kết hỗ trợ một loạt phương thức truyền mạng, bao gồm TCP, UDP, UDP với Weave Messaging Messaging và Weave qua BLE (WoBLE). Các ứ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 phiên này bao gồm phiên CASE và PASE và khóa 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 nêu rõ yêu cầu đối với giao tiếp theo cách ngắn gọn.
Hãy xem tài liệu về Binding::Configuration để biết thêm chi tiết.
Chuẩn bị
Trước khi thông báo diễn ra, Liên kết phải là "chuẩn bị." Hành động chuẩn bị Thỏa thuận bao gồm việc thiết lập trạng thái cần thiết cho hoạt động giao tiếp. Quá trình này có thể bao gồm những việc như: giải quyết địa chỉ mạng của đồng nghiệp, thiết lập kết nối mạng và thương lượng các khóa bảo mật. Sau khi ứng dụng định cấu hình, Liên kết sẽ thực hiện mọi bước cần thiết để chuẩn bị liên lạc, gọi lại cho ứng dụng khi quy trình hoàn tất. Bằng cách này, Binding ẩn cơ chế giao tiếp, cho phép ứng dụng tập trung vào các tương tác cấp cao.
Truyền thông
Sau khi chuẩn bị một Binding, liên kết sẽ sẵn sàng để sử dụng. Ở 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 mặt cho một ứng dụng) yêu cầu địa chỉ liên kết phân bổ ngữ cảnh trao đổi Weave. Ngữ cảnh trao đổi kết quả được định cấu hình sẵn để giao tiếp, cho phép ứng dụng bắt đầu ngay một cuộc 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ừ Binding cho đến khi đóng Binding hoặc một số sự kiện, chẳng hạn như lỗi mạng, chấm dứt kênh liên lạc cơ bản.
Thay đổi trạng thái liên kết
Trong quá trình sử dụng, Binding sẽ phân phối các sự kiện API tới ứng dụng để thông báo về các thay đổi trong trạng thái Binding\39; Ví dụ: khi quá trình chuẩn bị thành công, ứng dụng sẽ nhận được 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 hoạt động, thì sự kiện được gửi tới ứng dụng để thông báo rằng Binding không còn ở trạng thái sẵn sàng.
Các sự kiện API được gửi đến ứng dụng thông qua hàm gọi lại sự kiện được cung cấp khi Liên kết được phân bổ.
Giá trị lâu dài của Binding
Liên kết được tham chiếu để tính cho phép sử dụng chung trên nhiều thành phần phần mềm. Khi một Liên kết được phân bổ, một tệp tham chiếu duy nhất đế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 vào một thời điểm nào đó trong tương lai để Binding miễn phí cho lần 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ẽ hủy bỏ tệp tham chiếu đến ứng dụng đối với Binding và chặn tất cả các sự kiện phân phối tiếp theo của API. Khi tệp đối chiếu cuối cùng liên kết với Binding được phát hành, tệp đối chiếu đó sẽ tự động đó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 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()
|
Đang trong quá trình định cấu hình Binding.
|
CanBePrepared(void) const
|
bool
|
Close(void)
|
void
Đóng đối tượng liên kết và thả tệp đối chiếu.
|
GetConnection() const
|
Lấy đối tượng Kết nối Weave liên kết với liên kết này.
|
GetDefaultResponseTimeout() const
|
uint32_t
Lấy thời gian chờ phản hồi trao đổi mặc định được sử dụng khi giao tiếp với đồng nghiệp.
|
GetDefaultWRMPConfig(void) const
|
const WRMPConfig &
Lấy cấu hình WRMP mặc định dùng khi giao tiếp với đồng nghiệp.
|
GetEncryptionType(void) const
|
uint8_t
Truy xuất loại mã hóa thư dùng để mã hóa thư tới/từ đồng nghiệp.
|
GetEventCallback() const
|
EventCallback
Nhận hàm sẽ được gọi khi một sự kiện API xảy ra cho Binding.
|
GetExchangeManager() const
|
|
GetKeyId(void) const
|
uint32_t
Truy xuất mã nhận dạng của khóa mã hóa thư sẽ sử dụng khi mã hóa thư đến/từ máy tính ngang hàng.
|
GetLogId(void) const
|
uint16_t
Nhận một mã nhận dạng duy nhất cho liên kết.
|
GetMaxWeavePayloadSize(const System::PacketBuffer *msgBuf)
|
uint32_t
Nhận kích thước tải trọng Weave tối đa có thể vừa với gói PacketBuffer đã 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 kết nối / địa chỉ 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 cho ứng dụng ngang hàng, nếu có.
|
GetPeerNodeId(void) const
|
uint64_t
Truy xuất mã nút của ứng dụ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 thư đến cụ thể có đến từ ứng dụng ngang hàng đã được định cấu hình và 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 Exchange mới để giao tiếp với đồng nghiệp là mục tiêu của liên kết.
|
Release(void)
|
void
Hủy bỏ tệp 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 về trạng thái chưa được định cấu hình.
|
SetDefaultResponseTimeout(uint32_t msec)
|
void
Đặt thời gian chờ phản hồi trao đổi mặc định được sử dụng khi giao tiếp với đồng nghiệp.
|
SetDefaultWRMPConfig(const WRMPConfig & wrmpConfig)
|
void
Đặt cấu hình WRMP mặc định mà bạn muốn sử dụng khi giao tiếp với đồng nghiệp.
|
SetEventCallback(EventCallback aEventCallback)
|
void
Đặt hàm xác định ứng dụng được gọi khi một sự kiện API xảy ra cho Binding.
|
SetProtocolLayerCallback(EventCallback callback, void *state)
|
void
Đặt một hàm gọi lại sự kiện cho mã lớp giao thức bằng cách dùng Binding thay 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 Liên kết. |
Cấu trúc |
|
---|---|
nl:: |
Nhập các thông số vào một sự kiện API Binding. |
nl:: |
Thông số đầu ra cho sự kiện API Binding. |
Loại công khai
@33
@23
Thuộc tính | |
---|---|
kGetPeerDescription_MaxLength
|
Độ dài tối đa của chuỗi (bao gồm ký tự NUL) do GetPeerDescription() trả về. |
Lệnh gọi lại sự kiện
void(* EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
Loại sự kiện
EventType
Thuộc tính | |
---|---|
kEvent_BindingFailed
|
Không liên kết được và không còn dùng để giao tiếp với đồng nghiệp. |
kEvent_BindingReady
|
Bạn đã có thể thực hiện hành động liên kết với liên kết này và giờ đây, bạn có thể dùng liên kết này để giao tiếp với ứng dụng ngang hàng. |
kEvent_ConnectionEstablished
|
Đã thiết lập kết nối Weave được yêu cầu. |
kEvent_DefaultCheck
|
Dùng để xác minh rằng hoạt động 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ử 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ị đối với liên kết. |
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 thông số để 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
Thêm tham chiếu
void AddRef( void )
Đặt tham chiếu đến đối tượng liên kết.
Thời gian chờ điều chỉnh
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 thông số |
|
Phân cấp quyền
WEAVE_ERROR AllocateRightSizedBuffer( PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize )
Cấu hình bắt đầu
Configuration BeginConfiguration()
Đang trong quá trình định cấu hình Binding.
Các ứng dụng phải gọi StartConfiguration() để định cấu hình Binding trước khi chuẩn bị giao tiếp với đồng nghiệp.
Thông tin chi tiết | |
---|---|
Trả về |
Đối tượng Binding::Configuration có thể dùng để định cấu hình liên kết.
|
Có thể chuẩn bị
bool CanBePrepared( void ) const
Đóng
void Close( void )
Đóng đối tượng liên kết và thả tệp đối chiếu.
Khi được gọi, phương thức này khiến liên kết chuyển sang trạng thái Đã đóng. Mọi thao tác chuẩn bị đang tiến hành cho liên kết đó sẽ bị hủy và tất cả tài nguyên liên lạc bên ngoài do liên kết này sẽ giữ lại sẽ được hủy bỏ.
Việc gọi Close() giảm số lượng tham chiếu liên kết với liên kết, giải phóng đối tượng nếu số tham chiếu trở thành 0.
Lấy kết nối
WeaveConnection * GetConnection() const
Lấy đối tượng Kết nối Weave liên kết với liên kết này.
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 liên kết với liên kết.
|
GetDefaultResponseResponse
uint32_t GetDefaultResponseTimeout() const
Lấy thời gian chờ phản hồi trao đổi mặc định được sử dụng khi giao tiếp với đồng nghiệp.
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
Lấy cấu hình WRMP mặc định dùng khi giao tiếp với đồng nghiệp.
Thông tin chi tiết | |
---|---|
Trả về |
Tham chiếu đến cấu trúc WRMPConfig chứa các giá trị cấu hình mặc định.
|
Loại mã hóa
uint8_t GetEncryptionType( void ) const
Truy xuất loại mã hóa thư dùng để mã hóa thư tới/từ đồng nghiệp.
GetEventCallback
EventCallback GetEventCallback() const
Nhận hàm sẽ được gọi khi một 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ã nhận dạng của khóa mã hóa thư sẽ sử dụng khi mã hóa thư đến/từ máy tính ngang hàng.
GetLogId
uint16_t GetLogId( void ) const
Nhận một mã nhận dạng duy nhất cho liên kết.
GetMaxWeavePayloadSize
uint32_t GetMaxWeavePayloadSize( const System::PacketBuffer *msgBuf )
Nhận kích thước tải trọng Weave tối đa có thể vừa với gói PacketBuffer đã cung cấp.
Đối với UDP, bao gồm cả UDP với WRM, kích thước tải trọng tối đa trả về sẽ đảm bảo thông báo Weave thu được sẽ không tràn mục hàng UDP MTU đã định cấu hình.
Ngoài ra, phương thức này sẽ đảm bảo phần tải dữ liệu Weave sẽ không làm tràn gói PacketBuffer đã cung cấp.
Thông tin chi tiết | |||
---|---|---|---|
Các thông số |
|
||
Trả về |
Kích thước nội dung Weave tối đa.
|
GetMô tả
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 kết nối / địa chỉ liên kết của nút đó.
Thông tin chi tiết | |||||
---|---|---|---|---|---|
Các thông số |
|
GetPeerIPĐịa chỉ
void GetPeerIPAddress( nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId ) const
Truy xuất thông tin địa chỉ IP cho ứng dụng ngang hàng, nếu có.
Khả năng cung cấp thông tin địa chỉ IP của ứng dụng ngang hàng tùy thuộc vào trạng thái và cấu hình của liên kết. Thông tin địa chỉ IP chỉ có sẵn khi sử dụng 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 được ứng dụng đặt rõ ràng trong quá trình định cấu hình. Trong giai đoạn chuẩn bị, thông tin địa chỉ sẽ có sẵn khi quá trình chuẩn bị địa chỉ hoàn tất (ví dụ: sau khi DNS phân giải xong). Sau khi Liên kết sẵn sàng, thông tin địa chỉ sẽ vẫn hiển thị cho đến khi bạn đặt lại Liên kết.
Thông tin chi tiết | |||||||
---|---|---|---|---|---|---|---|
Các thông số |
|
GetPeerNodeId
uint64_t GetPeerNodeId( void ) const
Truy xuất mã nút của ứng dụng ngang hàng liên kết.
Chỉ hợp lệ khi đối tượng liên kết đã được chuẩn bị.
Thông tin chi tiết | |
---|---|
Trả về |
ID nút dệt của ứng dụng ngang hàng
|
Nhận giao thức lớp giao thức
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 thư đến cụ thể có đến từ ứng dụng ngang hàng đã được định cấu hình và có xác thực phù hợp hay không.
Phương thức này xác nhận những 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ư đã được nhận qua cùng một loại phương thức truyền tải như là liên kết. Nếu thư đượ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ư đã được nhận qua kết nối chính xác liên kết với liên kết này.
- Khóa và loại mã hóa dùng để mã hóa thông báo khớp với khóa và tùy chọn đượ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 tính năng bảo mật, phương thức này sẽ xác nhận rằng thư đến KHÔNG được mã hóa.
Phương pháp này dành cho các giao thức như WDM, trong đó các ứng dụng ngang hàng có thể tự khởi tạo giao dịch trở lại nút cục bộ sau khi trao đổi ban đầu từ nút này sang ứng dụng ngang hàng. Trong những trường hợp như vậy, phương thức sẽ cho phép nút cục bộ xác nhận rằng tin nhắn không mong muốn đến đã được đồng nghiệp 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 tính năng mã hóa thư, lời khẳng định này không cung cấp giá trị từ góc độ bảo mật. Tệp này chỉ xác nhận rằng mã nút của người gửi và các loại phương thức truyền tải khớp với nhau.)
Xin 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ề false.
Thông tin chi tiết | |||
---|---|---|---|
Các thông số |
|
||
Trả về |
Đúng nếu thông điệp chân thực từ đồng nghiệp.
|
IsConnectionTransport
bool IsConnectionTransport() const
Đang chuẩn bị
bool IsPreparing( void ) const
Thông tin chi tiết | |
---|---|
Trả về |
True nếu Liên kết hiện đang được chuẩn bị.
|
IsUDPTransport (IsUDPTransport)
bool IsUDPTransport() const
ISUnliableUDPTransport
bool IsUnreliableUDPTransport() const
IsWRMTransport
bool IsWRMTransport() const
Ngữ cảnh Exchange
WEAVE_ERROR NewExchangeContext( ExchangeContext *& appExchangeContext )
Phân bổ ngữ cảnh Exchange mới để giao tiếp với đồng nghiệp là mục tiêu của liên kết.
Thông tin chi tiết | |||||||||
---|---|---|---|---|---|---|---|---|---|
Các thông số |
|
||||||||
Giá trị trả về |
|
Phát hành
void Release( void )
Hủy bỏ tệp tham chiếu đến đối tượng liên kết.
Nếu không có thêm tham chiếu nào đến đối tượng liên kết thì liên kết đó sẽ bị đóng và được giải phóng.
Đã chuẩn bị yêu cầu
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_ChuẩnBị yêu cầu) yêu cầu cấu hình và chuẩn bị liên kết để sử dụng.
Chỉ có thể gọi phương thức này trên các Liên kết ở trạng thái Chưa đị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 theo yêu cầu/chuẩn bị liên kết, 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 về trạng thái chưa được định cấu hình.
Khi lệnh Đặt lại() được gọi, mọi thao tác chuẩn bị đang tiến hành cho liên kết sẽ bị hủy và tất cả tài nguyên giao tiếp bên ngoài do liên kết đã giữ sẽ bị hủy bỏ. Đặt lại() đặt liên kết ở trạng thái Chưa định cấu hình, sau đó liên kết này có thể được định cấu hình và chuẩn bị lại.
Đặt lại() không thay đổi số lượng tham chiếu của liên kết.
Đặt mặc định thời gian chờ
void SetDefaultResponseTimeout( uint32_t msec )
Đặt thời gian chờ phản hồi trao đổi mặc định được sử dụng khi giao tiếp với đồng nghiệp.
Thông tin chi tiết | |||
---|---|---|---|
Các thông số |
|
SetDefaultWRMPConfig
void SetDefaultWRMPConfig( const WRMPConfig & wrmpConfig )
Đặt cấu hình WRMP mặc định mà bạn muốn sử dụng khi giao tiếp với đồng nghiệp.
Thông tin chi tiết | |||
---|---|---|---|
Các thông số |
|
Đặt lại sự kiện
void SetEventCallback( EventCallback aEventCallback )
Đặt hàm xác định ứng dụng được gọi khi một sự kiện API xảy ra cho Binding.
Thông tin chi tiết | |||
---|---|---|---|
Các thông số |
|
Đặt lại lớp giao thức
void SetProtocolLayerCallback( EventCallback callback, void *state )
Đặt một hàm gọi lại sự kiện cho mã lớp giao thức bằng cách dùng Binding thay cho ứng dụng.
Hàm này sẽ được gọi ngoài hàm callback được xác định của ứng dụng khi sự kiện API xảy ra cho Binding.
Thông tin chi tiết | |||||
---|---|---|---|---|---|
Các thông số |
|
Hàm tĩnh công khai
Trình xử lý sự kiện mặc định
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.
Các ứng dụng bắt buộc phải gọi phương thức này cho bất kỳ sự kiện API nào mà chúng không nhận ra hoặc xử lý. Các thông số đã cung cấp phải giống với các thông số được chuyển bởi hàm liên kết với hàm trình xử lý sự kiện của ứng dụng.
Thông tin chi tiết | |||||||||
---|---|---|---|---|---|---|---|---|---|
Các thông số |
|