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 狀態 (表示已收到 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
相關服務的服務端點 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 類型的函式指標，允許應用程式使用回應中提供的時間欄位，與 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 物件繫結；這個標頭會持續有效，直到清除 Service Directory 快取，或到其他服務目錄查詢為止。

詳細資料
參數
[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
如果在設定過程中發生錯誤，就會發生錯誤。

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_Remanaged 的狀態報告時，應用程式可呼叫 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
觸發這項作業的錯誤。
另請參閱：
重設(避免)

重設

void reset(
  void
)

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

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

另請參閱：
重設(WEAVE_ERROR)

未解決

void unresolve(
  WEAVE_ERROR aError
)

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

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

此方法的版本是為確保回溯相容性，可接收並記錄錯誤，然後呼叫 unresolve(void)。

詳細資料
參數
[in] aError
觸發這項作業的錯誤。
另請參閱：
未解決(無效)

未解決

void unresolve(
  void
)

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

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

另請參閱：
未解決(WEAVE_ERROR)

~WeaveServiceManager

 ~WeaveServiceManager(
  void
)

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