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

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

Weave 服务目录的 manager 对象。

摘要

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（如果成功），否则加载过程将会取消。

StatusHandler

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 以及在请求时传入作为标识符的应用状态对象来取消连接请求。如果这是最后一个连接请求，此方法也会清除所有待处理的 Service Directory 连接状态。

具体说明
参数
[in] aServiceEp
要取消的请求的服务端点 ID。
[in] anAppState
提供给 connect() 调用的应用状态对象的指针。

clearCache

void clearCache(
  void
)

如果管理器处于 kServiceMgrState_Resolved 终端状态（表示收到了来自 Service Directory 端点的响应），则此方法会清除该管理器的状态和缓存。

connect

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
指向交换管理器的指针，用于所有服务目录配置文件交换。
[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_Reloaded 的状态报告时，应用就可以调用 unresolve() 来清除缓存并取消连接请求。此方法通过首次调用 unresolve()，并在问题尚未解决时调用 reset() 来简化错误处理。

这个版本的方法（在此处是为了实现向后兼容性）会先获取并记录错误，然后调用 relocate(void)。

具体说明
参数
[in] aError
记录错误。
另请参阅：
relocate(void)

搬迁

void relocate(
  void
)

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

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

另请参阅：
relocate(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
触发此操作的错误。
另请参阅：
reset(void)

重置

void reset(
  void
)

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

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

另请参阅：
reset(WEAVE_ERROR)

未解决

void unresolve(
  WEAVE_ERROR aError
)

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

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

此版本的方法（在此处是为了实现向后兼容性）会先获取并记录错误，然后调用 unresolve(void)。

具体说明
参数
[in] aError
触发此操作的错误。
另请参阅：
unresolve(void)

未解决

void unresolve(
  void
)

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

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

另请参阅：
unresolve(WEAVE_ERROR)

~WeaveServiceManager

 ~WeaveServiceManager(
  void
)

此方法会销毁 WeaveServiceManager 实例。