nl:: Weave:: 装订
#include <src/lib/core/WeaveBinding.h>
捕获 Weave 通信和关联配置信息的预期目标。
摘要
Binding 对象用于标识 Weave 通信的预期目标(也称为“对等”)以及一组配置参数,描述应如何进行与对等通信。绑定与双方使用的应用协议无关。因此,他们捕获的是交流的“谁”和“方式”,但不是“什么”。
应用必须使用特定于所需通信信道类型的参数配置绑定。绑定支持一系列网络传输,包括使用 Weave Reliable Messaging 的 TCP、UDP、UDP 和 Weave over BLE (WoBLE)。应用还可以请求使用特定的安全机制来保护双方之间发送的邮件。其中包括 CASE 和 PASE 会话以及应用组密钥。用于配置 Binding 的接口使用的是声明式 API 样式,允许应用用简单词语声明自己对通信的要求。
如需了解详情,请参阅 Binding::Configuration 的文档。
准备工作
在进行沟通之前,必须准备绑定。准备绑定的行为涉及建立通信所需的必要状态。其中可能包括:解析对等设备的网络地址、建立网络连接、协商安全密钥等。应用配置后,Binding 将负责准备通信所需的所有步骤,并在进程完成时回调应用。采用这种方式时,绑定会隐藏通信机制,让应用能够专注于高级交互。
通信
Binding 准备就绪后,即可供使用。在这种状态下,应用(或者代表应用工作的协议层代码)请求绑定以分配 Weave 交换上下文。生成的交换上下文已针对通信预先配置,使应用能够立即启动与对等设备的 Weave 交换。应用可以继续从 Binding 请求交换上下文,直到 Binding 被关闭或某个事件(例如网络故障)终止底层通信通道为止。
绑定 状态变更
在使用过程中,绑定将向应用传递 API 事件,以告知其绑定状态的变化。例如,准备成功时,应用将收到一个事件,告知其 Binding 已可供使用。同样,如果底层通信信道失败,则系统将向应用传递事件,告知其绑定不再处于就绪状态。
API 事件通过分配 Binding 时提供的事件回调函数传送到应用。
生命周期绑定
绑定是指允许在多个软件组件之间共享使用情况的引用。分配 Binding 时,系统会创建对绑定的单个引用。应用负责在未来的某个时间发布此引用,以便绑定可以免费重复使用。
当应用完成 Binding 后,它可以针对绑定调用 Close()。这将释放应用对绑定的引用,并阻止 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()
|
配置绑定的流程。
|
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
获取将在发生绑定的 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
检索绑定对等节点。
|
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()
|
请求应用配置和准备绑定。
|
Reset(void)
|
void
将绑定重置为未配置状态。
|
SetDefaultResponseTimeout(uint32_t msec)
|
void
设置与对等设备通信时要使用的默认交换响应超时。
|
SetDefaultWRMPConfig(const WRMPConfig & wrmpConfig)
|
void
设置与对等设备通信时要使用的默认 WRMP 配置。
|
SetEventCallback(EventCallback aEventCallback)
|
void
设置在针对绑定发生 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
公共属性
应用状态
void * AppState
公共函数
添加引用
void AddRef( void )
保留对绑定对象的引用。
AdjustResponseTimeout
WEAVE_ERROR AdjustResponseTimeout( ExchangeContext *apExchangeContext ) const
重新配置现有 Exchange 上下文以调整响应超时。
详细信息 | |||
---|---|---|---|
参数 |
|
分配右侧的 SizedBuffer
WEAVE_ERROR AllocateRightSizedBuffer( PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize )
开始配置
Configuration BeginConfiguration()
配置绑定的流程。
应用必须先调用 BeginConfiguration() 来配置 Binding,然后才能准备它与对等设备进行通信。
详细信息 | |
---|---|
返回值 |
一个 Binding::Configuration 对象,可用于配置绑定。
|
可以做准备
bool CanBePrepared( void ) const
关闭
void Close( void )
关闭绑定对象并释放引用。
调用此方法时,此方法会使绑定进入“封闭”状态。系统将取消绑定中正在进行的所有准备操作,并释放绑定拥有的所有外部通信资源。
调用 Close() 可减少与绑定关联的引用计数,如果引用计数变为 0,则会释放对象。
GetConnection
WeaveConnection * GetConnection() const
GetDefaultResponseTimeout
uint32_t GetDefaultResponseTimeout() const
获取与对等设备通信时使用的默认交换响应超时。
详细信息 | |
---|---|
返回值 |
响应超时(以毫秒为单位)。
|
GetDefaultWRMPConfig
const WRMPConfig & GetDefaultWRMPConfig( void ) const
GetEncryptionType
uint8_t GetEncryptionType( void ) 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
构造一个字符串,描述对等节点及其关联的地址 / 连接信息。
详细信息 | |||||
---|---|---|---|---|---|
参数 |
|
获取对等 IP 地址
void GetPeerIPAddress( nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId ) const
检索对等体的 IP 地址信息(如果有)。
对等 IP 地址的可用性取决于绑定的状态和配置。只有在使用基于 IP 的传输(TCP、UDP 或 UDP 和 WRMP)的情况下,才能使用 IP 地址信息。在开始准备之前,只有在应用通过配置明确设置的情况下,地址信息才可用。在准备阶段,地址信息的完成时(例如 DNS 解析完成后)可以查看地址信息。绑定准备就绪后,地址信息将一直可用,直至绑定被重置。
详细信息 | |||||||
---|---|---|---|---|---|---|---|
参数 |
|
GetPeerNodeId
uint64_t GetPeerNodeId( void ) const
检索绑定对等节点。
仅在绑定对象准备就绪后。
详细信息 | |
---|---|
返回值 |
对等设备的编织节点 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
IsUnliliableUDPTransport
bool IsUnreliableUDPTransport() const
IsWRMTransport
bool IsWRMTransport() const
NewExchangeContext
WEAVE_ERROR NewExchangeContext( ExchangeContext *& appExchangeContext )
分配新的 Exchange 上下文,以与作为绑定目标的对等方进行通信。
详细信息 | |||||||||
---|---|---|---|---|---|---|---|---|---|
参数 |
|
||||||||
返回值 |
|
版本
void Release( void )
释放对绑定对象的引用。
如果没有对绑定对象的更多引用,系统将关闭并释放绑定。
请求准备
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 事件调用此方法。提供的参数必须与通过绑定传递给应用的事件处理脚本函数传递的参数相同。
详细信息 | |||||||||
---|---|---|---|---|---|---|---|---|---|
参数 |
|