nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager

#include <src/lib/profiles/service-directory/ServiceDirectory.h>

Weave 服务目录的管理器对象。

摘要

Weave 服务管理器是应用目录服务的主界面。因此，它会查找查找与服务端点关联的目录条目、对在其中发现的一个或多个主机名执行 DNS 查找、尝试连接、确保连接等操作所进行的复杂操作。它还可以管理服务目录信息的缓存。

构造函数和构造函数
WeaveServiceManager(void)
此方法会初始化 WeaveServiceManager 实例。
~WeaveServiceManager(void)
此方法会销毁 WeaveServiceManager 实例。

公共类型
@303{
  kWeave_DefaultSendTimeout = 15000
} 		枚举
OnConnectBegin)(struct ServiceConnectBeginArgs &args) nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager::OnConnectBegin
void(*
在连接建立之前进行的应用回调。
OnServiceEndpointQueryBegin)(void) nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager::OnServiceEndpointQueryBegin
void(*
用于标记传出服务目录查询的时间的应用回调。
OnServiceEndpointQueryEndWithTimeInfo)(uint64_t timeQueryReceiptMsec, uint32_t timeProcessMsec) nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager::OnServiceEndpointQueryEndWithTimeInfo
void(*
用于从服务目录响应传递时间值的应用回调函数。
RootDirectoryAccessor)(uint8_t *aDirectory, uint16_t aLength) nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager::RootDirectoryAccessor
根目录信息的存取器函数。
StatusHandler)(void *anAppState, WEAVE_ERROR anError, StatusReport *aStatusReport) nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager::StatusHandler
void(*
错误和状态条件的处理程序。

公共函数
SetConnectBeginCallback(OnConnectBegin aConnectBegin)
void
设置要在连接建立之前调用的回调函数。
cancel(uint64_t aServiceEp, void *aAppState)
void
此方法会取消连接请求。
clearCache(void)
void
此方法会清除管理器在终端 kServiceMgrState_Resolved 状态下的状态和缓存，这意味着已收到来自 Service Directory 端点的响应。
connect(uint64_t aServiceEp, WeaveAuthMode aAuthMode, void *aAppState, StatusHandler aStatusHandler, WeaveConnection::ConnectionCompleteFunct aConnectionCompleteHandler, const uint32_t aConnectTimeoutMsecs, const InterfaceId aConnectIntf)
此方法请求连接到 Weave 服务。
init(WeaveExchangeManager *aExchangeMgr, uint8_t *aCache, uint16_t aCacheLen, RootDirectoryAccessor aAccessor, WeaveAuthMode aDirAuthMode, OnServiceEndpointQueryBegin aServiceEndpointQueryBegin, OnServiceEndpointQueryEndWithTimeInfo aServiceEndpointQueryEndWithTimeInfo, OnConnectBegin aConnectBegin)
此方法会初始化服务管理器对象。
lookup(uint64_t aServiceEp, HostPortList *outHostPortList)
此方法用于查找服务端点的目录信息。
lookup(uint64_t aServiceEp, uint8_t *aControlByte, uint8_t **aDirectoryEntry)
此方法用于查找服务端点的目录信息。
onConnectionClosed(WEAVE_ERROR aError)
void
此方法可处理关联的 Weave 交换上下文所报告的连接关闭事件。
onConnectionComplete(WEAVE_ERROR aError)
void
此方法可处理服务端点查询事务的连接完成事件。
onResponseReceived(uint32_t aProfileId, uint8_t aMsgType, PacketBuffer *aMsg)
void
此方法可处理与目录服务的对话中的任何响应消息。
onResponseTimeout(void)
void
此方法可处理超时事件，即未收到目录服务的任何响应。
relocate(WEAVE_ERROR aError)
void
此方法会重新定位服务目录缓存。
relocate(void)
void
此方法会重新定位服务目录缓存。
replaceOrAddCacheEntry(uint16_t port, const char *hostName, uint8_t hostLen, uint64_t serviceEndpointId)
在目录列表开头添加主机名和端口 ID 的覆盖目录条目。
reset(WEAVE_ERROR aError)
void
此方法会将服务管理器重置为其初始状态。
reset(void)
void
此方法会将服务管理器重置为其初始状态。
unresolve(WEAVE_ERROR aError)
void
此方法会使服务目录缓存失效。
unresolve(void)
void
此方法会使服务目录缓存失效。

类
nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager::ConnectRequest

此类表示由服务管理器管理的单个事务。

公共类型

@303

 @303
属性
kWeave_DefaultSendTimeout

在交换上下文超时之前，必须收到目录查询的响应毫秒数。

OnConnectBegin

void(* OnConnectBegin)(struct ServiceConnectBeginArgs &args)

在连接建立之前进行的应用回调。

应用可以使用此回调来观察和选择性地更改在建立服务连接过程中传递到 #WeaveConnection::Connect() 的参数。此回调将在以下情况下来调用：连接到目标服务端点，以及在必须执行目录查询时连接到 Service Directory 端点。

OnServiceEndpointQueryBegin

void(* OnServiceEndpointQueryBegin)(void)

用于标记传出服务目录查询的时间的应用回调。

当即将发送服务端点查询请求时，系统会调用此方法。此字段与 OnServiceEndpointQueryEnd 匹配，以补偿消息排期时间。

OnServiceEndpointQueryEndWithTimeInfo

void(* OnServiceEndpointQueryEndWithTimeInfo)(uint64_t timeQueryReceiptMsec, uint32_t timeProcessMsec)

用于从服务目录响应传递时间值的应用回调函数。

当我们从服务目录查询响应中获取时间信息时，会调用此方法。请注意，仅当成功解析响应并且包含时间信息时，才会发生此回调

详细信息
参数
[in] timeQueryReceiptMsec
从服务器端收到 POSIX 周期时查询的毫秒数。
[in] timeProcessMsec
处理此查询所用的毫秒数。

RootDirectoryAccessor

WEAVE_ERROR(* RootDirectoryAccessor)(uint8_t *aDirectory, uint16_t aLength)

根目录信息的存取器函数。

您必须从某个位置开始，对于服务目录，您必须首先创建一个存根目录，该目录包含您可以用来访问其他所有服务器的服务器地址。由于此类信息的处理和出处可能会因设备而异，因此我们在此提供一个存取器回调。

详细信息
参数
[out] aDirectory
指向缓冲区的指针，用于写入目录信息。
[in] aLength
给定缓冲区的长度（以字节为单位）。
返回值
如果成功，则返回 WEAVE_NO_ERROR，否则加载进程将会中止。

状态处理程序

void(* StatusHandler)(void *anAppState, WEAVE_ERROR anError, StatusReport *aStatusReport)

错误和状态条件的处理程序。

服务管理器用户可能在尝试通过两种方式之一执行连接请求时收到通知。它可能会收到服务的状态报告，也可能会收到内部生成的 WEAVE_ERROR。无论哪种情况，信息都会经由此回调。

详细信息
参数
[in] anAppState
指向传递到相应 conect() 调用的应用对象的指针。
[in] anError
Weave 错误代码，指示尝试执行连接请求时发生的错误。如果没有出现错误，并且有状态报告可供查看，此值应为 WEAVE_NO_ERROR。
[in] aStatusReport
指向远程目录服务生成的状态报告的指针。如果没有状态报告且在前一个参数中传递内部错误，则此参数应为 NULL。

公共函数

SetConnectBeginCallback

void SetConnectBeginCallback(
  OnConnectBegin aConnectBegin
)

设置要在连接建立之前调用的回调函数。

详细信息
参数
[in] aConnectBegin
指向回调函数的指针。值 NULL 会停用回调。

WeaveServiceManager

 WeaveServiceManager(
  void
)

此方法会初始化 WeaveServiceManager 实例。

请注意，必须调用 init() 以进一步初始化此实例。

取消

void cancel(
  uint64_t aServiceEp,
  void *aAppState
)

此方法会取消连接请求。

此方法会在给定服务端点 ID 和在请求时作为标识符传入的应用状态对象取消连接请求。如果是最后一个连接请求，则此方法也会清除所有待处理的服务目录连接状态。

详细信息
参数
[in] aServiceEp
正在取消的请求的服务端点 ID。
[in] anAppState
指向提供给 connect() 调用的应用状态对象的指针。

clearCache

void clearCache(
  void
)

此方法会清除管理器在终端 kServiceMgrState_Resolved 状态下的状态和缓存，这意味着已收到来自 Service Directory 端点的响应。

连接

WEAVE_ERROR connect(
  uint64_t aServiceEp,
  WeaveAuthMode aAuthMode,
  void *aAppState,
  StatusHandler aStatusHandler,
  WeaveConnection::ConnectionCompleteFunct aConnectionCompleteHandler,
  const uint32_t aConnectTimeoutMsecs,
  const InterfaceId aConnectIntf
)

此方法请求连接到 Weave 服务。

这是顶级连接调用。考虑到服务端点和身份验证模式，它本质上会生成与 Weave 服务的安全连接，或者尝试终止。

只有在成功调用 init() 之后才能调用此方法，而且连接请求可能会被 cancel() 取消。

在本地缓存中填充来自默认预配的数据或目录服务的行程之前，可以调用此方法。服务管理器只需在确定缓存内容之前将请求加入队列。

详细信息
参数
[in] aServiceEp
相关服务的服务端点标识符，如 ServiceDirectory.h 中所定义。
[in] aAuthMode
连接到相关服务时要使用的身份验证模式。
[in] aAppState
指向应用状态对象的指针，作为参数传递给回调。
[in] aStatusHandler
在连接完成之前发生错误时调用的回调函数。
[in] aConnectionCompleteHandler
要在请求的连接完成时调用的回调函数。请注意，连接可能会失败，并显示 Weave 错误代码。
[in] aConnectTimeoutMsecs
可选的 TCP 连接超时（以毫秒为单位）。
[in] aConnectIntf
需要建立连接的可选接口。
返回值
如果成功，则返回 WEAVE_NO_ERROR；否则，会显示相应的错误代码。

init

WEAVE_ERROR init(
  WeaveExchangeManager *aExchangeMgr,
  uint8_t *aCache,
  uint16_t aCacheLen,
  RootDirectoryAccessor aAccessor,
  WeaveAuthMode aDirAuthMode,
  OnServiceEndpointQueryBegin aServiceEndpointQueryBegin,
  OnServiceEndpointQueryEndWithTimeInfo aServiceEndpointQueryEndWithTimeInfo,
  OnConnectBegin aConnectBegin
)

此方法会初始化服务管理器对象。

要使用服务管理器对象，必须对其进行初始化。成功调用此方法后，客户端可以开始调用 connect()、lookup() 和其他方法。

详细信息
参数
[in] aExchangeMgr
指向 Exchange 管理器的指针，该交换管理器用于所有 Service Directory 配置文件交换。
[in] aCache
指向可用于缓存目录信息的缓冲区的指针。
[in] aCacheLen
缓存的长度（以字节为单位）。
[in] aAccessor
ServiceDirectory.h 中所调用的回调，该回调将加载根目录作为目录查找的起点。
[in] aDirAuthMode
与目录服务通信时使用的身份验证模式。
[in] aServiceEndpointQueryBegin
一个类型为 OnServiceEndpointQueryBegin 的函数指针，在服务目录请求开始时调用；如果应用指针想要使用服务目录协议提供的时间同步，则可使用它来标记时间。
[in] aServiceEndpointQueryEndWithTimeInfo
一个类型为 OnServiceEndpointQueryEndWithTimeInfo 的函数指针，收到服务目录时调用，允许应用使用响应中给出的时间字段与 Weave 服务同步。此回调将在服务管理器收到包含时间信息的响应之后进行。在进行回调之前，缓存应该已经填充成功。
[in] aConnectBegin
类型为 OnConnectBegin 的函数指针，在连接建立之前被调用，可让应用观察并视需要更改传递给 #WeaveConnection::Connect() 的参数。值为 NULL（默认值）会停用回调。
返回值
如果函数参数无效，则返回 WEAVE_ERROR_INVALID_ ARGUMENT；否则为 WEAVE_NO_ERROR。

lookup

WEAVE_ERROR lookup(
  uint64_t aServiceEp,
  HostPortList *outHostPortList
)

此方法用于查找服务端点的目录信息。

如果服务目录已解析（即，如果 connect() 操作成功），此方法将填充提供的 HostPortList 对象。

注意：HostPortList 与 WeaveServiceManager 对象绑定；在服务目录缓存被清除或进行其他服务目录查询之前，此对象一直有效。

详细信息
参数
[in] aServiceEp
要查询的服务端点的标识符。
[out] outHostPortList
指向 HostPortList 的指针，将在成功查找目录条目后填充。不得为 NULL。
返回值
WEAVE_NO_ERROR
否则返回相应的错误代码。
WEAVE_ERROR_INVALID_SERVICE_EP
如果找不到指定的服务端点。
WEAVE_ERROR_INVALID_DIRECTORY_ENTRY_TYPE
如果目录包含未知目录条目类型，则会发生该错误。

lookup

WEAVE_ERROR lookup(
  uint64_t aServiceEp,
  uint8_t *aControlByte,
  uint8_t **aDirectoryEntry
)

此方法用于查找服务端点的目录信息。

如果服务目录已解析（即，如果 connect() 操作成功），此方法将返回一个服务端点标识符对应的目录条目。

此方法会公开服务目录内部实现的详情，实现方法应优先使用生成 HostPortList 的此方法的变体。

详细信息
参数
[in] aServiceEp
要查询的服务端点的标识符。
[out] aControlByte
指向写入目录条目控制字节的位置的指针。
[out] aDirectoryEntry
指向目录条目的指针。
返回值
WEAVE_NO_ERROR
否则返回相应的错误代码。
WEAVE_ERROR_INVALID_SERVICE_EP
如果找不到指定的服务端点。
WEAVE_ERROR_INVALID_DIRECTORY_ENTRY_TYPE
如果目录包含未知目录条目类型，则会发生该错误。

onConnectionClosed

void onConnectionClosed(
  WEAVE_ERROR aError
)

此方法可处理关联的 Weave 交换上下文所报告的连接关闭事件。

详细信息
参数
[in] aError
显示连接关闭的原因的 Weave 错误。

onConnectionComplete

void onConnectionComplete(
  WEAVE_ERROR aError
)

此方法可处理服务端点查询事务的连接完成事件。

有几种可能性。首先，连接可能失败了，在这种情况下，我们就完成了。否则，连接实际上已经完成，我们要做的是打开交换上下文并发送目录查询。

详细信息
参数
[in] aError
如果连接设置过程中出现任何错误，则会显示 Weave 错误。

onResponseReceived

void onResponseReceived(
  uint32_t aProfileId,
  uint8_t aMsgType,
  PacketBuffer *aMsg
)

此方法可处理与目录服务的对话中的任何响应消息。

详细信息
参数
[in] aProfileId
此传入消息的个人资料 ID。
[in] aMsgType
此消息中特定于个人资料的类型。
[in] aMsg
此消息的内容。

onResponseTimeout

void onResponseTimeout(
  void
)

此方法可处理超时事件，即未收到目录服务的任何响应。

搬迁

void relocate(
  WEAVE_ERROR aError
)

此方法会重新定位服务目录缓存。

当服务端点返回状态代码 kStatus_Relocations 时的状态报告，应用可以调用 unparse() 来清除缓存并取消连接请求。此方法会在首次调用 unparse() 时简化错误处理，如果问题尚未解决，则会调用 reset()。

此版本的方法（此处为向后兼容性）会采用并记录一个错误，然后调用 relocate(void)。

详细信息
参数
[in] aError
错误。
另请参阅：
relocate(void)

搬迁

void relocate(
  void
)

此方法会重新定位服务目录缓存。

当服务端点返回状态代码 kStatus_Relocations 时的状态报告，应用可以调用 unparse() 来清除缓存并取消连接请求。此方法会在首次调用 unparse() 时简化错误处理，如果问题尚未解决，则会调用 reset()。

另请参阅：
重新定位(WEAVE_ERROR)

replaceOrAddCacheEntry

WEAVE_ERROR replaceOrAddCacheEntry(
  uint16_t port,
  const char *hostName,
  uint8_t hostLen,
  uint64_t serviceEndpointId
)

在目录列表开头添加主机名和端口 ID 的覆盖目录条目。

重置

void reset(
  WEAVE_ERROR aError
)

此方法会将服务管理器重置为其初始状态。

此方法会重置所有服务管理器状态，包括通信状态、缓存状态和任何待处理连接请求的状态。

此版本的方法（此处为向后兼容性）会采用并记录一个错误，然后调用 reset(void)。

详细信息
参数
[in] aError
触发此操作的错误。
另请参阅：
重置（无效）

重置

void reset(
  void
)

此方法会将服务管理器重置为其初始状态。

此方法会重置所有服务管理器状态，包括通信状态、缓存状态和任何待处理连接请求的状态。

另请参阅：
重置（WEAVE_ERROR）

取消解析

void unresolve(
  WEAVE_ERROR aError
)

此方法会使服务目录缓存失效。

此方法可设置服务目录缓存状态，以便服务管理器在下次请求时发出服务目录查询。

此版本的方法（此处为向后兼容性）会采用并记录一个错误，然后调用 unparse(void)。

详细信息
参数
[in] aError
触发此操作的错误。
另请参阅：
unparse(void)

取消解析

void unresolve(
  void
)

此方法会使服务目录缓存失效。

此方法可设置服务目录缓存状态，以便服务管理器在下次请求时发出服务目录查询。

另请参阅：
未解析(WEAVE_ERROR)

~WeaveServiceManager

 ~WeaveServiceManager(
  void
)

此方法会销毁 WeaveServiceManager 实例。