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{
  kGetPeerDescription_MaxLength = nl::Weave::kWeavePeerDescription_MaxLength
} 		枚举
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
} 		枚举
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::Weave::Binding::Configuration

提供声明式样式的接口，用于配置和准备 Binding 对象。

结构体
nl::Weave::Binding::InEventParam

Binding API 事件的输入参数。
nl::Weave::Binding::OutEventParam

Binding API 事件的输出参数。

公共类型

@23

 @23
属性
kGetPeerDescription_MaxLength

GetPeerDescription() 返回的字符串最大长度（包括 NUL 字符）。

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 上下文以调整响应超时。

具体说明
参数
[in] apExchangeContext
指向要重新配置的 Exchange Context 对象的指针

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

获取与绑定关联的 Weave 连接对象。

具体说明
返回值
指向 WeaveConnection 对象的指针；如果没有与该绑定相关联的连接，则为 NULL。

GetDefaultResponseTimeout

uint32_t GetDefaultResponseTimeout() const

获取与对等端通信时使用的默认交换响应超时。

具体说明
返回值
响应超时（毫秒）。

GetDefaultWRMPConfig

const WRMPConfig & GetDefaultWRMPConfig(
  void
) const

获取与对等端通信时使用的默认 WRMP 配置。

具体说明
返回值
对包含默认配置值的 WRMPConfig 结构的引用。

GetEncryptionType

uint8_t GetEncryptionType(
  void
) const

检索对与对等方之间的消息进行加密时要使用的消息加密类型。

GetEventCallback

EventCallback GetEventCallback() const

获取在 Binding 发生 API 事件时调用的函数。

具体说明
返回值
指向回调函数的指针。

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。

具体说明
参数
[in] msgBuf
指向消息载荷将写入到的 PacketBuffer 的指针。
返回值
Weave 载荷大小上限。

GetPeerDescription

void GetPeerDescription(
  char *buf,
  uint32_t bufSize
) const

构建一个描述对等节点及其关联的地址 / 连接信息的字符串。

具体说明
参数
[in] buf
指向应将字符串写入到的缓冲区的指针。提供的缓冲区至少应与 kGetPeerDescription_MaxLength 一样大。如果提供的是较小的缓冲区，字符串将被截断以适应。在所有情况下，输出都将包含 NUL 终止字符。
[in] bufSize
buf 所指向的缓冲区的大小。

GetPeerIPAddress

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

检索对等方的 IP 地址信息（如果有）。

对等方的 IP 地址信息的可用性取决于绑定的状态和配置。只有在使用基于 IP 的传输（TCP、UDP 或 UDP 与 WRMP）时，IP 地址信息才可用。在开始准备之前，只有应用在配置过程中明确设置了地址信息时才可用。在准备阶段，地址信息准备完成时（例如 DNS 解析完成后）可用。在 Binding 就绪后，地址信息仍然可用，直到 Binding 重置。

具体说明
参数
[out] address
对将接收对等方 IP 地址的 IPAddress 对象的引用。如果对等方的 IP 地址信息不可用，此值将设置为 IPAddress::Any。
[out] port
对将接收对等方端口号的整数的引用。如果对等方的 IP 地址信息不可用，则此值未定义。
[out] interfaceId
对整数的引用，系统将接收相应接口（通过该接口可以访问对等设备）的 ID。如果对等方的 IP 地址信息不可用，则此值未定义。

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。

具体说明
参数
[in] msgInfo
传入消息的 Weave 消息信息。
返回值
如果消息确实来自对等端，则为 true。

IsConnectionTransport

bool IsConnectionTransport() const

IsPreparing

bool IsPreparing(
  void
) const

具体说明
返回值
如果 Binding 目前正在准备中，则为 true。

IsReady

bool IsReady(
  void
) const

具体说明
返回值
如果 Binding 处于就绪状态，则为 true。

IsUDPTransport

bool IsUDPTransport() const

IsUnreliableUDPTransport

bool IsUnreliableUDPTransport() const

IsWRMTransport

bool IsWRMTransport() const

NewExchangeContext

WEAVE_ERROR NewExchangeContext(
  ExchangeContext *& appExchangeContext
)

分配新的 Exchange 上下文，用于与作为绑定目标的对等方进行通信。

具体说明
参数
[out] appExchangeContext
对将接收新分配的 Exchange Context 对象的指针的引用。如果方法失败，指针将设置为 NULL。
返回值
WEAVE_NO_ERROR
是否已成功分配交换上下文。
WEAVE_ERROR_NO_MEMORY
如果没有可用于分配交换上下文的内存。
WEAVE_ERROR_INCORRECT_STATE
如果绑定未处于就绪状态。
other
与根据绑定配置配置 Exchange 上下文相关的其他错误。

版本

void Release(
  void
)

释放对绑定对象的引用。

如果没有对绑定对象的引用，系统会关闭并释放绑定。

RequestPrepare

WEAVE_ERROR RequestPrepare()

请求应用配置和准备 Binding。

协议层代码可以在尚未配置或失败的 Binding 上使用此方法，触发向应用的事件 (kEvent_PrepareRequested) 请求配置和准备绑定以供使用。

只能对处于“NotConfigured”或“Failed”状态的绑定调用此方法。

如果应用不支持按需配置/准备绑定，则该方法将失败并显示 WEAVE_ERROR_NOT_IMPLEMENTED。

重置

void Reset(
  void
)

将绑定重置为未配置的状态。

调用 Reset() 后，系统会取消该绑定的所有正在进行的准备操作，并释放该绑定保留的所有外部通信资源。Reset() 会将绑定置于“未配置”状态，之后便可再次对其进行配置和准备。

Reset() 不会更改绑定的引用计数。

SetDefaultResponseTimeout

void SetDefaultResponseTimeout(
  uint32_t msec
)

设置与对等端通信时使用的默认交换响应超时。

具体说明
参数
[in] timeout
新的响应超时（以毫秒为单位）。

SetDefaultWRMPConfig

void SetDefaultWRMPConfig(
  const WRMPConfig & wrmpConfig
)

设置与对等设备通信时使用的默认 WRMP 配置。

具体说明
参数
[in] aWRMPConfig
对包含新默认配置的 WRMPConfig 结构的引用。

SetEventCallback

void SetEventCallback(
  EventCallback aEventCallback
)

设置要在 Binding 发生 API 事件时调用的应用定义的函数。

具体说明
参数
[in] aEventCallback
指向回调函数的指针。

SetProtocolLayerCallback

void SetProtocolLayerCallback(
  EventCallback callback,
  void *state
)

代表应用使用绑定为协议层代码设置事件回调函数。

当 Binding 发生 API 事件时，除了应用定义的回调函数之外，系统还会调用此函数。

具体说明
参数
[in] callback
指向回调函数的指针。
[in] state
指向将在发生协议层回调时提供给协议层代码的状态对象的指针。

公共静态函数

DefaultEventHandler

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

用于绑定 API 事件的默认处理程序。

应用必须针对自身无法识别或处理的任何 API 事件调用此方法。提供的参数必须与绑定传递给应用的事件处理脚本函数的参数相同。

具体说明
参数
[in] apAppState
指向与绑定关联的应用定义状态信息的指针。
[in] aEvent
事件回调函数传递的事件 ID
[in] aInParam
对事件回调函数传递的输入事件参数的引用
[in] aOutParam
对事件回调函数传递的输出事件参数的引用