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
這個方法會重新定位 Service 目錄快取。
relocate(void)
void
這個方法會重新定位 Service 目錄快取。
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 Epoch 紀元時間起算的毫秒數。
[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，以及以 ID 形式傳入的應用程式狀態物件，取消連線要求。如果是最後一個連線要求，這個方法也會清除任何待處理的 Service 目錄連線狀態。

詳細說明
參數
[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
服務端點 ID (如 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 類型的函式指標，會在服務目錄要求開始時呼叫，允許應用程式程式碼標記時間，以便使用 Service Directory 通訊協定提供的時間同步處理作業。
[in] aServiceEndpointQueryEndWithTimeInfo
OnServiceEndpointQueryEndWithTimeInfo 類型的函式指標，會在收到 Service 目錄時呼叫，允許應用程式使用回應中提供的時間欄位與 Weave 服務進行同步處理。服務管理員收到包含時間資訊的回應後，就會發出這個回呼。在發出回呼前，必須先成功填入快取。
[in] aConnectBegin
OnConnectBegin 類型的函式指標會在連線建立之前立即呼叫，可讓應用程式觀察並視需要變更傳遞至 #WeaveConnection::Connect() 的引數。空值 (預設值) 會停用回呼。
傳回
如果函式引數無效，則為 WEAVE_ERROR_INVALID_ARGUMENT；否則，傳回 WEAVE_NO_ERROR。

lookup

WEAVE_ERROR lookup(
  uint64_t aServiceEp,
  HostPortList *outHostPortList
)

這個方法會查詢服務端點的目錄資訊。

如果 Service 目錄已解析 (即成功的 connect() 作業)，這個方法就會填入提供的 HostPortList 物件。

注意：HostPortList 會與 WeaveServiceManager 物件繫結，直到服務目錄快取清除，或直到查詢其他服務目錄為止，這個物件才會繼續有效。

詳細說明
參數
[in] aServiceEp
要查詢的服務端點 ID。
[out] outHostPortList
成功查詢目錄項目時，填入的 HostPortList 指標。不得為空值。
傳回值
WEAVE_NO_ERROR
失敗時，則會傳回相應的錯誤代碼。
WEAVE_ERROR_INVALID_SERVICE_EP
。
WEAVE_ERROR_INVALID_DIRECTORY_ENTRY_TYPE
if 目錄包含未知的目錄項目類型。

lookup

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

這個方法會查詢服務端點的目錄資訊。

如果服務目錄已解析 (例如成功執行 connect() 作業)，這個方法就會傳回指定服務端點 ID 的目錄項目。

這個方法可公開服務目錄內部實作的詳細資料，因此實作時應優先使用可產生 HostPortList 的方法。

詳細說明
參數
[in] aServiceEp
要查詢的服務端點 ID。
[out] aControlByte
指向寫入目錄項目控制位元組的位置指標。
[out] aDirectoryEntry
要導向目錄項目的指標指標。
傳回值
WEAVE_NO_ERROR
失敗時，則會傳回相應的錯誤代碼。
WEAVE_ERROR_INVALID_SERVICE_EP
。
WEAVE_ERROR_INVALID_DIRECTORY_ENTRY_TYPE
if 目錄包含未知的目錄項目類型。

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
)

這個方法會重新定位 Service 目錄快取。

服務端點傳回狀態碼為 kStatus_Relocations 的狀態報告時，應用程式可能會呼叫 unresolve() 以清除快取並取消連線要求。此方法會在首次呼叫 unresolve() 時簡化錯誤處理作業，如果問題尚未解決，則呼叫 reset()。

此方法版本 - 此處為回溯相容性，擷取並記錄錯誤，然後呼叫 relocate(void)。

詳細說明
參數
[in] aError
記錄錯誤。
另請參閱：
relocate(void)

重新定位

void relocate(
  void
)

這個方法會重新定位 Service 目錄快取。

服務端點傳回狀態碼為 kStatus_Relocations 的狀態報告時，應用程式可能會呼叫 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
)

這個方法會將服務管理員重設為初始狀態。

這個方法會重設所有服務管理員的狀態，包括通訊狀態、快取狀態，以及任何待處理連線要求的狀態。

另請參閱：
reset(WEAVE_ERROR)

未解決

void unresolve(
  WEAVE_ERROR aError
)

這個方法會撤銷服務目錄快取。

這個方法會設定 Service Directory 快取狀態，讓服務管理員在下次要求時發出 Service Directory 查詢。

此方法版本 - 此處為回溯相容性，擷取並記錄錯誤，然後呼叫 unresolve(void)。

詳細說明
參數
[in] aError
觸發這項作業的錯誤。
另請參閱：
unresolve(void)

未解決

void unresolve(
  void
)

這個方法會撤銷服務目錄快取。

這個方法會設定 Service Directory 快取狀態，讓服務管理員在下次要求時發出 Service Directory 查詢。

另請參閱：
unresolve(WEAVE_ERROR)

~WeaveServiceManager

 ~WeaveServiceManager(
  void
)

這個方法會刪除 WeaveServiceManager 執行個體。