nl::Weave::Profiles::DataManagement_Legacy::Binding

#include <src/lib/profiles/data-management/Legacy/Binding.h>

Binding 类使用 Weave 代表应用实体管理通信状态。

摘要

当应用想要使用 Weave 与远程实体通信时，可以使用多种选项。Binding 类将这些选项捆绑在一起，并按以下方式排列它们：简单内容很简单，而较难的部分至少易于处理。涵盖的选项包括：

  • 与已知对等节点进行单播 UDP 通信。
  • 具有“任意”节点的 UDP 广播。
  • 与已知对等节点进行单播 WRMP 通信。
  • 与已知对等节点进行 TCP 通信。
  • 使用服务管理器实例与已知服务端点之间的 TCP 通信进行设置。
  • 基于预先建立的连接的 TCP 通信。

构造函数和析构函数
Binding(void)
Binding 对象的默认构造函数。
~Binding(void)
Binding 对象的析构函数。

公共类型
@165{
  kState_Incomplete = 0,
  kState_Completing = 1,
  kState_Complete = 2
} 		枚举
一组 Binding 对象状态。

公共属性
mAuthMode
WeaveAuthMode
要使用的 Weave 身份验证模式。
mConnection
指向此绑定中当前使用的 Weave 连接的指针。
mEngine
指向与此 Binding 相关的 ProtocolEngine 对象的指针。
mPeerNodeId
uint64_t
绑定目标的 64 位节点 ID。
mServiceMgr
指向（可选）ServiceManager 对象的指针，用于完成此绑定。
mState
uint8_t
当前的 Binding 对象状态。
mTransport
uint8_t
完成此 Binding 时使用的传输。

公共函数
CompleteConfirm(WeaveConnection *aConnection)
void
处理绑定请求的确认。
CompleteConfirm(StatusReport & aReport)
void
处理绑定请求失败的情况。
CompleteConfirm(void)
void
处理绑定请求的确认。
CompleteRequest(ProtocolEngine *aEngine)
请求完成绑定。
Connect(WeaveConnection *aConnection)
提供已完成的连接以完成 TCP 绑定。
Finalize(void)
void
“未完成”绑定并将其释放。
Finalize(WEAVE_ERROR aErr)
void
“未完成”绑定并将其释放。
Free(void)
void
清除绑定状态。
GetExchangeCtx(WeaveExchangeManager *aExchangeMgr, void *aAppState)
通过 Binding 生成 ExchangeContext 对象。
IncompleteIndication(StatusReport & aReport)
void
处理绑定失败。
Init(const uint64_t & aPeerNodeId)
仅使用节点 ID 初始化 Binding。
Init(const uint64_t & aPeerNodeId, uint8_t aTransport)
根据对等 ID 和传输初始化 Binding 对象。
Init(const uint64_t & aServiceEpt, WeaveServiceManager *aServiceMgr, WeaveAuthMode aAuthMode)
初始化到服务端点的 Binding 对象。
Init(WeaveConnection *aConnection)
使用 WeaveConnection 初始化 Binding 对象。
IsComplete(void)
bool
检查绑定是否已完成。
IsFree(void)
bool
检查绑定是否免费。
UncompleteRequest(void)
void
导致绑定不完整。
UncompleteRequest(WEAVE_ERROR aErr)
void
导致绑定不完整。

公共类型

@165

 @165

一组 Binding 对象状态。

属性
kState_Complete

已完成且可供使用的 Binding 的状态。
kState_Completing

正处于完成过程中的 Binding 状态。
kState_Incomplete

Binding 的初始（和最终）状态。

公共属性

mAuthMode

WeaveAuthMode mAuthMode

要使用的 Weave 身份验证模式。

（只读）

这是在受此绑定约束的所有通信中使用的身份验证模式。

mConnection

WeaveConnection * mConnection

指向此绑定中当前使用的 Weave 连接的指针。

（只读）

TCP 绑定可以立即使用连接进行初始化，也可以在完成时分配一个。

mEngine

ProtocolEngine * mEngine

指向与此 Binding 相关的 ProtocolEngine 对象的指针。

绑定通常与特定协议引擎完成，主要用作访问 MessageLayer 的方式。我们会在这里跟踪它。

mPeerNodeId

uint64_t mPeerNodeId

绑定目标的 64 位节点 ID。

（只读）

每个 Binding 都有一个目标实体，该实体在此处命名。除了 Weave 节点 ID 之外，还可以为服务端点命名。

mServiceMgr

nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager * mServiceMgr

指向（可选）ServiceManager 对象的指针，用于完成此绑定。

（只读）

绑定到 Weave 服务时，可以在初始化时提供 64 位服务端点 ID 来代替 Weave 节点 ID。在这种情况下，还需要一个 ServiceManager 对象来完成绑定。普通的 TCP 或 WRMP 绑定不需要 ServiceManager 对象。

mState

uint8_t mState

当前的 Binding 对象状态。

一次只能运行一个“完成”操作，而且在任何情况下，如果您要求完成已完成的绑定，它都会立即调用确认函数。下面的状态变量会跟踪当前状态，并起到锁定功能的作用。

mTransport

uint8_t mTransport

完成此 Binding 时使用的传输。

（只读）

mTransport 的可能值在 DMConstants.h 中定义。

公共函数

绑定

 Binding(
  void
)

Binding 对象的默认构造函数。

清除所有内部状态。

CompleteConfirm

void CompleteConfirm(
  WeaveConnection *aConnection
)

处理绑定请求的确认。

具体说明
参数
[in] aConnection
指向绑定目标的有效 WeaveConnection 的指针。

CompleteConfirm

void CompleteConfirm(
  StatusReport & aReport
)

处理绑定请求失败的情况。

具体说明
参数
[in] aReport
对 StatusReport 对象的引用，用于描述失败情况。

CompleteConfirm

void CompleteConfirm(
  void
)

处理绑定请求的确认。

CompleteRequest

WEAVE_ERROR CompleteRequest(
  ProtocolEngine *aEngine
)

请求完成绑定。

至少对于需要 TCP 的绑定，绑定的完成是相对于特定的 ProtocolEngine 对象执行，该对象可提供对 ExchangeManager 实例的访问。

具体说明
参数
[in] aEngine
指向代表其执行完成的 ProtocolEngine 对象的指针。
返回值
WEAVE_NO_ERROR
成功时。
WEAVE_ERROR_INCORRECT_STATE
如果绑定已完成，则会发生该错误。
WEAVE_ERROR_NO_MEMORY
如果需要连接，但没有可用的服务
返回值
否则，系统会在尝试连接时返回任何 WEAVE_ERROR。

连接

WEAVE_ERROR Connect(
  WeaveConnection *aConnection
)

提供已完成的连接以完成 TCP 绑定。

新初始化的 TCP 绑定在完成之前无法使用。通常，系统会在应用尝试使用绑定发送消息时按需完成此过程，但也可以通过提供 Weave 连接来显式完成此过程。

具体说明
参数
[in] aConnection
指向用于完成绑定的 WeaveConnection 的指针。
返回值
WEAVE_NO_ERROR
成功时。
WEAVE_ERROR_INCORRECT_STATE
该绑定是否已建立连接。
WEAVE_ERROR_INVALID_ARGUMENT
如果连接为 NULL。

完成

void Finalize(
  void
)

“未完成”绑定并将其释放。

绑定可能具有需要清理的状态，例如连接闭包，除了通过 Free() 方法简单清除为其初始状态的状态之外，还由 Uncomplete() 方法处理。该方法会调用这两种方法，主要是为了方便起见。

另请参阅：
Finalize(WEAVE_ERROR)

完成

void Finalize(
  WEAVE_ERROR aErr
)

“未完成”绑定并将其释放。

绑定可能具有需要清理的状态，例如连接闭包，除了通过 Free() 方法简单清除为其初始状态的状态之外，还由 Uncomplete() 方法处理。该方法会调用这两种方法，主要是为了方便起见。

具体说明
参数
[in] aErr
此错误代码说明了此请求的原因。如果不是 WEAVE_NO_ERROR，则 TCP 连接可能会取消。
另请参阅：
Finalize(void)

免费

void Free(
  void
)

清除绑定状态。

无条件将所有绑定状态恢复为其原始状态。

GetExchangeCtx

ExchangeContext * GetExchangeCtx(
  WeaveExchangeManager *aExchangeMgr,
  void *aAppState
)

通过 Binding 生成 ExchangeContext 对象。

具体说明
参数
[in] aExchangeMgr
指向交换管理器的指针，可从中请求上下文。
[in] aAppState
指向要存储在交换上下文中供日后使用的应用状态对象的空指针。
返回值
指向 ExchangeContext 对象的指针或者在失败时为 NULL。

IncompleteIndication

void IncompleteIndication(
  StatusReport & aReport
)

处理绑定失败。

系统调用了此方法，然后当绑定完成后（即在调用 CompleteConfirm() 且状态指示成功时）时调用更高级的处理程序。

具体说明
参数
[in] aReport
对 StatusReport 的引用，用于描述哪里出了问题。
另请参阅：
CompleteConfirm(StatusReport &aReport)。

Init

WEAVE_ERROR Init(
  const uint64_t & aPeerNodeId
)

仅使用节点 ID 初始化 Binding。

这会导致与配置的默认传输进行绑定。

具体说明
参数
[in] aPeerNodeId
对绑定目标的 64 位 ID 的引用。
返回值
WEAVE_NO_ERROR
成功时。
WEAVE_ERROR_INVALID_ARGUMENT
未明确指定绑定。

Init

WEAVE_ERROR Init(
  const uint64_t & aPeerNodeId,
  uint8_t aTransport
)

根据对等 ID 和传输初始化 Binding 对象。

具体说明
参数
[in] aPeerNodeId
对绑定目标的 64 位节点标识符的引用。
[in] aTransport
来自 WeaveTransportOption 的传输规范。
返回值
WEAVE_NO_ERROR
成功时。
WEAVE_ERROR_INVALID_ARGUMENT
未明确指定绑定。

Init

WEAVE_ERROR Init(
  const uint64_t & aServiceEpt,
  WeaveServiceManager *aServiceMgr,
  WeaveAuthMode aAuthMode
)

初始化到服务端点的 Binding 对象。

这就是绑定到 Nest 服务上特定端点的方式。这种绑定需要多阶段完成过程，其中可能包括填充或更新本地服务目录缓存。大多数情况下，此过程对应用是隐藏的，但这意味着，在发出使用（并完成）绑定的原始请求之后（有时是很长时间后），进程中后期产生的错误可能会通过相关的“confirm”回调进行传送。

具体说明
参数
[in] aServiceEpt
对相关 Weave Service 端点的 64 位标识符的引用。
[in] aServiceMgr
指向服务管理器实例的指针，用于在查找和连接服务层级时使用。
[in] aAuthMode
在连接时使用的身份验证模式。
返回值
WEAVE_NO_ERROR
成功时。
WEAVE_ERROR_INVALID_ARGUMENT
未明确指定绑定。

Init

WEAVE_ERROR Init(
  WeaveConnection *aConnection
)

使用 WeaveConnection 初始化 Binding 对象。

具体说明
参数
[in] aConnection
指向用作绑定基础的 WeaveConnection 的指针。
返回值
WEAVE_NO_ERROR
成功时。
WEAVE_ERROR_INVALID_ARGUMENT
未明确指定绑定。

IsComplete

bool IsComplete(
  void
)

检查绑定是否已完成。

具体说明
返回值
如果已完成，则为 true，否则为 false。
另请参阅：
CompleteRequest(ProtocolEngine *aEngine)

IsFree

bool IsFree(
  void
)

检查绑定是否免费。

在此上下文中“免费”仅仅表示“具有定义的对等节点 ID”。IsFree() 应视为“已对其调用 Free()，且自此之后未曾使用”。

具体说明
返回值
如果绑定为自由状态，则返回 true，否则返回 false。

UncompleteRequest

void UncompleteRequest(
  void
)

导致绑定不完整。

从根本上说，在对绑定调用此方法后，绑定应处于“未完成”状态，但更为明显的是，绑定本身中未包含的任何相关状态（例如 TCP 连接）也应清除。应用可以考虑在出现错误时调用 UncompleteRequest() 作为清理的一部分。

另请参阅：
UncompleteRequest(WEAVE_ERROR )

UncompleteRequest

void UncompleteRequest(
  WEAVE_ERROR aErr
)

导致绑定不完整。

从根本上说，在对绑定调用此方法后，绑定应处于“未完成”状态，但更为明显的是，绑定本身中未包含的任何相关状态（例如 TCP 连接）也应清除。应用可以考虑在出现错误时调用 UncompleteRequest() 作为清理的一部分。

具体说明
参数
[in] aErr
如果不是 WEAVE_NO_ERROR，则现有连接（如果有）将被取消，而不是正常关闭。
另请参阅：
UncompleteRequest(void)

~绑定

virtual  ~Binding(
  void
)

Binding 对象的析构函数。

清除所有内部状态，并在必要时关闭打开的连接。