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{
  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()
配置绑定的流程。
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::Weave::Binding::配置

提供声明式界面，用于配置和准备 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

公共属性

应用状态

void * AppState

公共函数

添加引用

void AddRef(
  void
)

保留对绑定对象的引用。

AdjustResponseTimeout

WEAVE_ERROR AdjustResponseTimeout(
  ExchangeContext *apExchangeContext
) const

重新配置现有 Exchange 上下文以调整响应超时。

详细信息
参数
[in] apExchangeContext
指向要重新配置的 Exchange Context 对象的指针

分配右侧的 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

获取与绑定关联的 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

获取将在发生绑定的 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 所指向的缓冲区大小。

获取对等 IP 地址

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

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

对等 IP 地址的可用性取决于绑定的状态和配置。只有在使用基于 IP 的传输（TCP、UDP 或 UDP 和 WRMP）的情况下，才能使用 IP 地址信息。在开始准备之前，只有在应用通过配置明确设置的情况下，地址信息才可用。在准备阶段，地址信息的完成时（例如 DNS 解析完成后）可以查看地址信息。绑定准备就绪后，地址信息将一直可用，直至绑定被重置。

详细信息
参数
[out] address
对将接收对等 IP 地址的 IPAddress 对象的引用。如果对等方的 IP 地址信息不可用，其值将设为 IPAddress::Any。
[out] port
对将接收对等端口号的整数的引用。如果对等方的 IP 地址信息不可用，则未定义此值。
[out] interfaceId
对整数的引用，该整数将接收可以通过哪个对等网络到达对等设备。如果对等方的 IP 地址信息不可用，则未定义此值。

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。

详细信息
参数
[in] msgInfo
传入消息的 Weave 消息信息。
返回值
如果消息确实来自对等网络，则为 True。

IsConnectionTransport

bool IsConnectionTransport() const

正在准备

bool IsPreparing(
  void
) const

详细信息
返回值
如果 Binding 目前正在准备中，则为 true。

就绪

bool IsReady(
  void
) const

详细信息
返回值
如果 Binding 处于“Ready”状态，则为 true。

IsUDPTransport

bool IsUDPTransport() const

IsUnliliableUDPTransport

bool IsUnreliableUDPTransport() const

IsWRMTransport

bool IsWRMTransport() const

NewExchangeContext

WEAVE_ERROR NewExchangeContext(
  ExchangeContext *& appExchangeContext
)

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

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

版本

void Release(
  void
)

释放对绑定对象的引用。

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

请求准备

WEAVE_ERROR RequestPrepare()

请求应用配置和准备绑定。

协议层代码可以在尚未配置或失败的绑定上使用此方法，以触发向应用 (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
)

设置在针对绑定发生 API 事件时调用的应用定义函数。

详细信息
参数
[in] aEventCallback
指向回调函数的指针。

SetProtocolLayerCallback

void SetProtocolLayerCallback(
  EventCallback callback,
  void *state
)

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

当发生绑定的 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
事件回调传递的输出事件参数参考