nl:: Weave:: Binding
#include <src/lib/core/WeaveBinding.h>
捕获 Weave 通信的预期目标和关联的配置信息。
摘要
Binding 对象用于标识 Weave 通信的预期目标(也称为“对等方”),以及一组配置参数,这些参数用于描述如何与对等设备进行通信。绑定独立于双方之间读出的应用协议。因此,他们关注的是沟通的“人物”和“方式”,而非“内容”。
应用必须使用特定于所需通信渠道类型的参数配置 Binding。绑定支持一系列网络传输,包括 TCP、UDP、带有 Weave Reliable Messaging 的 UDP 和 Weave over BLE (WoBLE)。应用还可以请求使用特定的安全机制来保护双方之间发送的消息。这些键包括 CASE 和 PASE 会话,以及应用组键。用于配置 Binding 的接口使用声明式 API 样式,以便应用简单明了地阐述其通信要求。
如需了解详情,请参阅 Binding::Configuration 文档。
准备
在沟通之前,必须“准备好”绑定。准备绑定的操作涉及到建立沟通所需的必要状态。这可能包括:解析对等方的网络地址、建立网络连接和协商安全密钥。由应用配置后,绑定会负责为通信做好准备所需的所有步骤,并在流程完成时回调应用。通过这种方式,绑定隐藏了通信机制,使应用能够专注于高级交互。
通信
绑定准备就绪后,就可以使用了。在此状态下,应用(或更常见的是代表应用运行的协议层代码)请求绑定以分配 Weave 交换上下文。生成的交换上下文已预先配置为通信,允许应用立即启动与对等方的 Weave 交换。应用可以继续从绑定请求交换上下文,直到绑定关闭,或者某个事件(例如网络故障)终止底层通信通道时。
绑定状态变更
在使用过程中,Binding 会向应用传递 API 事件,以告知该应用 Binding 的状态发生了变化。例如,如果准备成功完成,应用将收到一个事件,告知它 Binding 已准备就绪,可供使用。同样,如果底层通信通道发生故障,系统会向应用传递一个事件,通知该应用 Binding 不再处于就绪状态。
API 事件通过分配 Binding 时提供的事件回调函数传递给应用。
绑定生命周期
绑定是指允许多个软件组件之间共享的引用计数。分配 Binding 时,系统会创建对该绑定的单个引用。应用负责在未来的某个时间点释放此引用,以便 Binding 可以自由用于后续再利用。
当应用使用绑定完成之后,它可以对绑定调用 Close()。这会释放应用对 Binding 的引用,并阻止以后继续传送 API 事件。当最后一个对 Binding 的引用被释放时,它会自动关闭。
公共类型 |
|
---|---|
@23{
|
枚举 |
EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
|
typedefvoid(*
|
EventType{
|
枚举 |
State
|
枚举 |
公共属性 |
|
---|---|
AppState
|
void *
|
公共函数 |
|
---|---|
AddRef(void)
|
void
预留对绑定对象的引用。
|
AdjustResponseTimeout(ExchangeContext *apExchangeContext) const
|
重新配置现有的 Exchange 上下文以调整响应超时。
|
AllocateRightSizedBuffer(PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize)
|
|
BeginConfiguration()
|
配置 Binding 的过程。
|
CanBePrepared(void) const
|
bool
|
Close(void)
|
void
关闭绑定对象并释放引用。
|
GetConnection() const
|
获取与绑定关联的 Weave 连接对象。
|
GetDefaultResponseTimeout() const
|
uint32_t
获取与对等端通信时使用的默认交换响应超时。
|
GetDefaultWRMPConfig(void) const
|
const WRMPConfig &
获取与对等端通信时使用的默认 WRMP 配置。
|
GetEncryptionType(void) const
|
uint8_t
检索对与对等方之间的消息进行加密时要使用的消息加密类型。
|
GetEventCallback() const
|
EventCallback
获取在 Binding 发生 API 事件时调用的函数。
|
GetExchangeManager() const
|
|
GetKeyId(void) const
|
uint32_t
检索在对与对等方之间的消息进行加密时要使用的消息加密密钥的 ID。
|
GetLogId(void) const
|
uint16_t
获取绑定的唯一 ID。
|
GetMaxWeavePayloadSize(const System::PacketBuffer *msgBuf)
|
uint32_t
获取可容纳在提供的 PacketBuffer 中的 Weave 载荷大小上限。
|
GetPeerDescription(char *buf, uint32_t bufSize) const
|
void
构建一个描述对等节点及其关联的地址 / 连接信息的字符串。
|
GetPeerIPAddress(nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId) const
|
void
检索对等方的 IP 地址信息(如果有)。
|
GetPeerNodeId(void) const
|
uint64_t
检索绑定对等方的节点 ID。
|
GetProtocolLayerCallback(EventCallback & callback, void *& state) const
|
void
|
GetState(void) const
|
State
检索绑定的当前状态。
|
IsAuthenticMessageFromPeer(const WeaveMessageInfo *msgInfo)
|
bool
确定特定传入消息是否来自配置的对等方且是否经过适当身份验证。
|
IsConnectionTransport() const
|
bool
|
IsPreparing(void) const
|
bool
|
IsReady(void) const
|
bool
|
IsUDPTransport() const
|
bool
|
IsUnreliableUDPTransport() const
|
bool
|
IsWRMTransport() const
|
bool
|
NewExchangeContext(ExchangeContext *& appExchangeContext)
|
分配新的 Exchange 上下文,用于与作为绑定目标的对等方进行通信。
|
Release(void)
|
void
释放对绑定对象的引用。
|
RequestPrepare()
|
请求应用配置和准备 Binding。
|
Reset(void)
|
void
将绑定重置为未配置的状态。
|
SetDefaultResponseTimeout(uint32_t msec)
|
void
设置与对等端通信时使用的默认交换响应超时。
|
SetDefaultWRMPConfig(const WRMPConfig & wrmpConfig)
|
void
设置与对等设备通信时使用的默认 WRMP 配置。
|
SetEventCallback(EventCallback aEventCallback)
|
void
设置要在 Binding 发生 API 事件时调用的应用定义的函数。
|
SetProtocolLayerCallback(EventCallback callback, void *state)
|
void
代表应用使用绑定为协议层代码设置事件回调函数。
|
公共静态函数 |
|
---|---|
DefaultEventHandler(void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam)
|
void
用于绑定 API 事件的默认处理程序。
|
类 |
|
---|---|
nl:: |
提供声明式样式的接口,用于配置和准备 Binding 对象。 |
结构体 |
|
---|---|
nl:: |
Binding API 事件的输入参数。 |
nl:: |
Binding API 事件的输出参数。 |
公共类型
EventCallback
void(* EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)
EventType
EventType
属性 | |
---|---|
kEvent_BindingFailed
|
绑定失败,无法再用于与对等方通信。 |
kEvent_BindingReady
|
对绑定的准备操作已成功执行,并且该绑定现在可以用于与对等方通信。 |
kEvent_ConnectionEstablished
|
请求的 Weave 连接已建立。 |
kEvent_DefaultCheck
|
用于验证应用中默认事件处理是否正确。 |
kEvent_PASEParametersRequested
|
请求应用提供在 PASE 会话建立期间使用的参数。 |
kEvent_PrepareFailed
|
针对绑定的准备操作失败。 |
kEvent_PrepareRequested
|
请求应用配置和准备绑定,以供网络堆栈使用。 |
kEvent_TAKEParametersRequested
|
应用需要提供将在建立 TAKE 会话期间使用的参数。 |
状态
State
公共属性
AppState
void * AppState
公共函数
AddRef
void AddRef( void )
预留对绑定对象的引用。
AdjustResponseTimeout
WEAVE_ERROR AdjustResponseTimeout( ExchangeContext *apExchangeContext ) const
重新配置现有的 Exchange 上下文以调整响应超时。
具体说明 | |||
---|---|---|---|
参数 |
|
AllocateRightSizedBuffer
WEAVE_ERROR AllocateRightSizedBuffer( PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize )
BeginConfiguration
Configuration BeginConfiguration()
配置 Binding 的过程。
应用必须先调用 BeginConfiguration() 来配置 Binding,然后再准备应用以与对等设备通信。
具体说明 | |
---|---|
返回值 |
可用于配置绑定的 Binding::Configuration 对象。
|
CanBePrepared
bool CanBePrepared( void ) const
关闭
void Close( void )
关闭绑定对象并释放引用。
调用后,此方法会使绑定进入“已关闭”状态。该绑定的所有正在进行的准备操作都会被取消,并且该绑定拥有的所有外部通信资源都会被释放。
调用 Close() 会减少与绑定关联的引用计数,在引用计数变为零时释放对象。
GetConnection
WeaveConnection * GetConnection() const
GetDefaultResponseTimeout
uint32_t GetDefaultResponseTimeout() const
获取与对等端通信时使用的默认交换响应超时。
具体说明 | |
---|---|
返回值 |
响应超时(毫秒)。
|
GetDefaultWRMPConfig
const WRMPConfig & GetDefaultWRMPConfig( void ) const
GetEncryptionType
uint8_t GetEncryptionType( void ) const
检索对与对等方之间的消息进行加密时要使用的消息加密类型。
GetEventCallback
EventCallback GetEventCallback() const
GetExchangeManager
WeaveExchangeManager * GetExchangeManager() const
GetKeyId
uint32_t GetKeyId( void ) const
检索在对与对等方之间的消息进行加密时要使用的消息加密密钥的 ID。
GetLogId
uint16_t GetLogId( void ) const
获取绑定的唯一 ID。
GetMaxWeavePayloadSize
uint32_t GetMaxWeavePayloadSize( const System::PacketBuffer *msgBuf )
获取可容纳在提供的 PacketBuffer 中的 Weave 载荷大小上限。
对于 UDP(包括支持 WRM 的 UDP),返回的最大载荷大小可确保生成的 Weave 消息不会溢出配置的 UDP MTU。
此外,此方法将确保 Weave 载荷不会溢出提供的 PacketBuffer。
具体说明 | |||
---|---|---|---|
参数 |
|
||
返回值 |
Weave 载荷大小上限。
|
GetPeerDescription
void GetPeerDescription( char *buf, uint32_t bufSize ) const
构建一个描述对等节点及其关联的地址 / 连接信息的字符串。
具体说明 | |||||
---|---|---|---|---|---|
参数 |
|
GetPeerIPAddress
void GetPeerIPAddress( nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId ) const
检索对等方的 IP 地址信息(如果有)。
对等方的 IP 地址信息的可用性取决于绑定的状态和配置。只有在使用基于 IP 的传输(TCP、UDP 或 UDP 与 WRMP)时,IP 地址信息才可用。在开始准备之前,只有应用在配置过程中明确设置了地址信息时才可用。在准备阶段,地址信息准备完成时(例如 DNS 解析完成后)可用。在 Binding 就绪后,地址信息仍然可用,直到 Binding 重置。
具体说明 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
GetPeerNodeId
uint64_t GetPeerNodeId( void ) const
检索绑定对等方的节点 ID。
仅在绑定对象准备好后有效。
具体说明 | |
---|---|
返回值 |
对等方的 Weave 节点 ID
|
GetProtocolLayerCallback
void GetProtocolLayerCallback( EventCallback & callback, void *& state ) const
GetState
State GetState( void ) const
检索绑定的当前状态。
具体说明 | |
---|---|
返回值 |
绑定状态。
|
IsAuthenticMessageFromPeer
bool IsAuthenticMessageFromPeer( const WeaveMessageInfo *msgInfo )
确定特定传入消息是否来自配置的对等方且是否经过适当身份验证。
此方法可确认有关给定消息的以下详细信息:
- 来自绑定的对等节点的消息
- 消息通过与绑定相同的传输类型接收。如果消息是通过连接接收的,该方法还会确认消息是否是通过与绑定关联的确切连接接收的。
- 用于加密消息的加密密钥和类型与绑定中配置的加密密钥和类型一致。对于在未使用安全性的情况下配置的绑定,该方法会确认传入的消息未加密。
此方法适用于 WDM 等协议。在这些协议中,对等方可以在首次交换从节点到对等方后,自发地启动回本地节点的交换。在这种情况下,此方法允许本地节点确认传入的未经请求消息是否由关联的对等方发送。(当然,对于在未使用消息加密的情况下配置的绑定,从安全角度来看,此断言没有任何价值。而只是确认发送者节点 ID 和传输类型是否匹配。)
请注意,如果绑定未处于就绪状态,此方法将始终返回 false。
具体说明 | |||
---|---|---|---|
参数 |
|
||
返回值 |
如果消息确实来自对等端,则为 true。
|
IsConnectionTransport
bool IsConnectionTransport() const
IsUDPTransport
bool IsUDPTransport() const
IsUnreliableUDPTransport
bool IsUnreliableUDPTransport() const
IsWRMTransport
bool IsWRMTransport() const
NewExchangeContext
WEAVE_ERROR NewExchangeContext( ExchangeContext *& appExchangeContext )
分配新的 Exchange 上下文,用于与作为绑定目标的对等方进行通信。
具体说明 | |||||||||
---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||
返回值 |
|
版本
void Release( void )
释放对绑定对象的引用。
如果没有对绑定对象的引用,系统会关闭并释放绑定。
RequestPrepare
WEAVE_ERROR RequestPrepare()
重置
void Reset( void )
SetDefaultResponseTimeout
void SetDefaultResponseTimeout( uint32_t msec )
设置与对等端通信时使用的默认交换响应超时。
具体说明 | |||
---|---|---|---|
参数 |
|
SetDefaultWRMPConfig
void SetDefaultWRMPConfig( const WRMPConfig & wrmpConfig )
SetEventCallback
void SetEventCallback( EventCallback aEventCallback )
SetProtocolLayerCallback
void SetProtocolLayerCallback( EventCallback callback, void *state )
公共静态函数
DefaultEventHandler
void DefaultEventHandler( void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam )
用于绑定 API 事件的默认处理程序。
应用必须针对自身无法识别或处理的任何 API 事件调用此方法。提供的参数必须与绑定传递给应用的事件处理脚本函数的参数相同。
具体说明 | |||||||||
---|---|---|---|---|---|---|---|---|---|
参数 |
|