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

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

Weave 服務目錄的 Manager 物件。

摘要

Weave 服務管理工具是應用程式與目錄服務的主要介面。因此，如果查詢和服務端點相關的目錄項目，查詢與服務端點相關的目錄項目、在其找到的一或多個主機名稱上執行 DNS 查詢、嘗試連線、確保連線安全等，會隱藏複雜功能。也可能管理 Service Directory 資訊的快取。

建構函式和解構函式
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 狀態 (表示已收到來自服務目錄端點的回應)，這個方法會清除管理員的狀態和快取。
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

在 Ad Exchange 情境逾時前，目錄查詢必須收到回應的毫秒數。

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
指向由遠端目錄服務產生的狀態報告。如果沒有狀態報告，且先前引數傳遞內部錯誤，則此引數應為空值。

公開函式

SetConnectBeginCallback

void SetConnectBeginCallback(
  OnConnectBegin aConnectBegin
)

設定回呼函式，以便在連線建立前立即呼叫。

詳細資料
參數
[in] aConnectBegin
回呼函式的指標。值為 NULL 時，系統會停用回呼。

WeaveServiceManager

 WeaveServiceManager(
  void
)

這個方法會初始化 WeaveServiceManager 例項。

請注意，您必須呼叫 init()，才能進一步初始化這個例項。

取消

void cancel(
  uint64_t aServiceEp,
  void *aAppState
)

這個方法會取消連線要求。

此方法會根據服務端點 ID 和在要求時傳入的應用程式狀態物件，以 ID 取消連線要求。如果這是最後的連線要求，這個方法也會清除所有待處理的服務目錄連線狀態。

詳細資料
參數
[in] aServiceEp
要求的服務端點 ID (已取消)。
[in] anAppState
指向應用程式狀態物件的指標，該物件會傳遞給 connect() 呼叫。

clearCache

void clearCache(
  void
)

如果狀態為終端 kServiceMgrState_Resolved 狀態 (表示已收到來自服務目錄端點的回應)，這個方法會清除管理員的狀態和快取。

連線

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 的函式指標，會在服務目錄要求開始時呼叫，並允許應用程式程式碼標記時間，以便使用服務目錄通訊協定提供的時間同步處理功能。
[in] aServiceEndpointQueryEndWithTimeInfo
收到服務目錄時，系統會呼叫 OnServiceEndpointQueryEndWithTimeInfo 類型的函式指標，允許應用程式使用回應中提供的時間欄位，與 Weave 服務同步。服務管理員收到含有時間資訊的回應後，就會執行這個回呼。快取應該已經填入成功，然後才會進行回呼。
[in] aConnectBegin
這是 OnConnectBegin 類型的函式指標，會在連線建立前立即呼叫，並允許應用程式觀察及選擇性變更傳遞至 #WeaveConnection::Connect() 的引數。如果值為空值 (預設值)，則會停用回呼。
傳回
如果函式引數無效，則為 WEAVE_ERROR_INVALID_ARGUMENT；否則為 WEAVE_NO_ERROR。

lookup

WEAVE_ERROR lookup(
  uint64_t aServiceEp,
  HostPortList *outHostPortList
)

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

如果服務目錄已解析 (也就是 connect() 作業已成功執行)，這個方法就會填入提供的 HostPortList 物件。

注意：HostPortList 會繫結至 WeaveServiceManager 物件；在服務目錄快取清除或發生其他服務目錄查詢前，這個物件會保持有效。

詳細資料
參數
[in] aServiceEp
要查詢的服務端點 ID。
[out] outHostPortList
指向 HostPortList 的指標，會在成功查詢目錄項目時填入。不得為空值。
傳回值
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() 作業已成功執行)，則此方法會傳回服務端點 ID 的相關目錄項目。

這個方法會公開服務目錄的內部實作項目詳細資料，實作項目應盡量使用此方法的變化版本，以產生 HostPortList。

詳細資料
參數
[in] aServiceEp
要查詢的服務端點 ID。
[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_Remanaged 的狀態報告時，應用程式可呼叫 unresolve() 以清除快取並取消連線要求。這個方法會在第一次呼叫 unresolve() 時簡化錯誤處理，如果問題尚未解決，則會呼叫 reset()。

這個方法版本 (為了回溯相容性而提供) 會擷取及記錄錯誤，然後呼叫 relocate(void)。

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

重新定位

void relocate(
  void
)

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

當服務端點傳回狀態報告時，狀態碼為 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
)

這個方法會使服務目錄快取無效。

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

這個方法的版本 (為了回溯相容性而提供) 會擷取及記錄錯誤，然後呼叫 unresolve(void)。

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

unresolve

void unresolve(
  void
)

這個方法會使服務目錄快取無效。

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

另請參閱：
unresolve(WEAVE_ERROR)

~WeaveServiceManager

 ~WeaveServiceManager(
  void
)

這個方法會銷毀 WeaveServiceManager 執行個體。