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

详细信息
参数
[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 管理器的指针，用于所有服务目录配置文件交换。
[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_Reusercontent 的状态报告时，应用可以调用 unresolve() 来清除缓存并取消连接请求。此方法会在第一次调用unresolve()（如果问题尚未解决）时调用reset()，简化了错误处理。

此版本的方法（此处用于实现向后兼容性）会接受并记录错误，然后调用 relocate(void)。

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

搬迁

void relocate(
  void
)

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

当服务端点返回状态代码为 kStatus_Reusercontent 的状态报告时，应用可以调用 unresolve() 来清除缓存并取消连接请求。此方法会在第一次调用unresolve()（如果问题尚未解决）时调用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
触发此操作的错误。
另请参阅：
reset(void)

重置

void reset(
  void
)

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

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

另请参阅：
重置(WEAVE_ERROR)

未解决

void unresolve(
  WEAVE_ERROR aError
)

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

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

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

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

未解决

void unresolve(
  void
)

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

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

另请参阅：
unresolve(WEAVE_ERROR)

~WeaveServiceManager

 ~WeaveServiceManager(
  void
)

此方法会销毁 WeaveServiceManager 实例。