nl::Weave::Binding

#include <src/lib/core/WeaveBinding.h>

捕获 Weave 通信的预期目标和关联的配置信息。

摘要

Binding 对象可标识 Weave 通信的预期目标（也称为“对等设备”），以及一组用于说明应如何与对等设备进行通信的配置参数。绑定独立于双方之间讲述的应用协议。因此，它们会找出以及“如何”而不是“内容”是什么

配置

应用必须使用特定于所需通信通道类型的参数来配置 Binding。绑定支持一系列网络传输，包括 TCP、UDP、UDP（具有 Weave Reliable Messaging）的 UDP 和 Weave over BLE (WoBLE)。应用也可以请求使用特定的安全机制来保护双方之间发送的消息。包括 CASE 和 PASE 会话以及应用组密钥。用于配置 Binding 的接口使用声明式 API 样式，允许应用用简单的语言声明其通信要求。

如需了解详情，请参阅 Binding::Configuration 的文档。

准备工作

在通信之前，必须“准备好”Binding。准备 Binding 涉及到建立通信的必要状态。这可能包括解析对等设备的网络地址、建立网络连接和协商安全密钥等操作。由应用配置后，Binding 会负责准备通信所需的所有步骤，并在进程完成后回调应用。这样，绑定隐藏了通信机制，使应用能够专注于高级交互。

通信

Binding 就绪后，即可供使用。在此状态下，应用（或更常见的是代表应用运行的协议层代码）请求 Binding 以分配 Weave 交换上下文。生成的交换上下文针对通信进行了预先配置，允许应用立即启动与对端的 Weave 交换。应用可以继续从 Binding 请求交换上下文，直到 Binding 关闭或某个事件（例如网络故障）终止底层通信通道。

绑定状态更改

在使用过程中，Binding 会将 API 事件传递给应用，告知应用 Binding 状态发生的变化。例如，如果准备成功，应用将收到一个事件，告知其 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
使用 Binding 代表应用为协议层代码设置事件回调函数。

公共静态函数
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 上下文对象的指针

AllocateRightSizedBuffer

WEAVE_ERROR AllocateRightSizedBuffer(
  PacketBuffer *& buf,
  const uint32_t desiredSize,
  const uint32_t minSize,
  uint32_t & outMaxPayloadSize
)

BeginConfiguration

Configuration BeginConfiguration()

这是配置 Binding 的过程。

在准备 Binding 与对等设备通信之前，应用必须调用 BeginConfiguration() 以配置绑定。

详细信息
返回值
可用于配置绑定的 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 解析完成后）可用。绑定就绪后，地址信息在绑定重置之前仍然可用。

详细信息
参数
[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
与根据绑定配置来配置广告交易平台上下文相关的其他错误。

版本

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 代表应用为协议层代码设置事件回调函数。

当 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
对由事件回调函数传递的输出事件参数的引用