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
此方法会重新定位 Service Directory 缓存。
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
指向用于所有服务目录配置文件交换的交换管理器的指针。
[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() 操作已成功），则此方法会根据服务端点标识符返回目录条目。

此方法会公开 Service Directory 内部实现的详细信息，实现时应尽可能使用用于生成 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_Relocated 的状态报告时，应用可以调用 unresolve() 来清除缓存并取消连接请求。此方法通过在第一次调用 unresolve()，并在问题尚未解决时调用 reset()，简化了错误处理。

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

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

重新定位

void relocate(
  void
)

此方法会重新定位 Service Directory 缓存。

当服务端点返回状态代码为 kStatus_Relocated 的状态报告时，应用可以调用 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)

unresolve

void unresolve(
  WEAVE_ERROR aError
)

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

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

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

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

未解决

void unresolve(
  void
)

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

此方法会设置 Service Directory 缓存状态，以便在下次请求时，Service Manager 会发出 Service Directory 查询。

另请参阅：
unresolve(WEAVE_ERROR)

~WeaveServiceManager

 ~WeaveServiceManager(
  void
)

此方法会销毁 WeaveServiceManager 实例。