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

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

Weave サービス ディレクトリのマネージャー オブジェクト。

概要

Weave サービス マネージャーは、アプリケーションからディレクトリ サービスへのメイン インターフェースです。そのため、サービス エンドポイントに関連付けられているディレクトリ エントリの検索、そこで見つかった 1 つ以上のホスト名の DNS ルックアップ、接続の試行、接続のセキュリティ保護などに伴う複雑さが見えなくなります。また、サービス ディレクトリ情報のキャッシュを管理することもできます。

コンストラクタとデストラクタ
WeaveServiceManager(void)
このメソッドは、WeaveServiceManager インスタンスを初期化します。
~WeaveServiceManager(void)
このメソッドは、WeaveServiceManager インスタンスを破棄します。

パブリック タイプ
@303{
  kWeave_DefaultSendTimeout = 15000
} 		enum
OnConnectBegin)(struct ServiceConnectBeginArgs &args) nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager::OnConnectBegin
void(*
接続が確立される直前に行われるアプリのコールバック。
OnServiceEndpointQueryBegin)(void) nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager::OnServiceEndpointQueryBegin
void(*
Service Directory クエリの送信時刻をマークするためのアプリケーション コールバック。
OnServiceEndpointQueryEndWithTimeInfo)(uint64_t timeQueryReceiptMsec, uint32_t timeProcessMsec) nl::Weave::Profiles::ServiceDirectory::WeaveServiceManager::OnServiceEndpointQueryEndWithTimeInfo
void(*
Service ディレクトリのレスポンスから時間値を提供するアプリケーション コールバック。
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)

Service Directory クエリの送信時刻をマークするためのアプリケーション コールバック。

これは、サービス エンドポイントのクエリ リクエストを送信しようとしたときに呼び出されます。OnServiceEndpointQueryEnd と照合してメッセージのフライト時間を補正するために使用されます。

OnServiceEndpointQueryEndWithTimeInfo

void(* OnServiceEndpointQueryEndWithTimeInfo)(uint64_t timeQueryReceiptMsec, uint32_t timeProcessMsec)

Service ディレクトリのレスポンスから時間値を提供するアプリケーション コールバック。

Service Directory のクエリ レスポンスから時間情報を取得したときに呼び出されます。注: このコールバックは、レスポンスが正常に解析され、時間情報が含まれている場合にのみ発生します。

詳細
パラメータ
[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)

エラー条件とステータス条件のハンドラ。

サービス マネージャーのユーザーに、次の 2 つの方法のいずれかで接続リクエストを実行しようとしたときに問題が通知される場合があります。サービスからステータス レポートを受信するか、内部的に生成された 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() を呼び出す必要があります。

cancel

void cancel(
  uint64_t aServiceEp,
  void *aAppState
)

このメソッドは、接続リクエストをキャンセルします。

このメソッドは、リクエスト時に ID として渡されたサービス エンドポイント 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 で定義されている、対象のサービスのサービス エンドポイント ID。
[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
接続の確立の直前に呼び出され、#WeaveConnection::Connect() に渡された引数をアプリケーションが監視し、必要に応じて変更できる、OnConnectBegin 型の関数ポインタ。値が NULL（デフォルト）の場合、コールバックは無効になります。
戻り値
関数の引数が無効な場合は 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 へのポインタ。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() オペレーションが成功した場合、このメソッドはサービス エンドポイント 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_Relocations を含むステータス レポートを返した場合、アプリケーションは unresolve() を呼び出してキャッシュをクリアし、接続リクエストをキャンセルできます。このメソッドでは、最初に unresolve() を呼び出し、問題がまだ解決していない場合は reset() を呼び出すことで、エラー処理を簡素化しています。

このメソッドのバージョン（ここでは下位互換性のため）では、エラーを受け取ってログに記録してから、relocate(void) を呼び出します。

詳細
パラメータ
[in] aError
ログに記録されます。
関連項目:
relocate(void)

再配置

void relocate(
  void
)

このメソッドは、サービス ディレクトリのキャッシュを再配置します。

サービス エンドポイントがステータス コード kStatus_Relocations を含むステータス レポートを返した場合、アプリケーションは 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)

解決を解除

void unresolve(
  WEAVE_ERROR aError
)

このメソッドは、サービス ディレクトリのキャッシュを無効にします。

このメソッドは、次のリクエストでサービス マネージャーがサービス ディレクトリ クエリを発行するように、サービス ディレクトリのキャッシュ状態を設定します。

このバージョン（ここでは下位互換性のため）のメソッドは、エラーを受け取ってログに記録してから、unresolve(void) を呼び出します。

詳細
パラメータ
[in] aError
このオペレーションをトリガーしたエラー。
関連項目:
unresolve(void)

解決を解除

void unresolve(
  void
)

このメソッドは、サービス ディレクトリのキャッシュを無効にします。

このメソッドは、次のリクエストでサービス マネージャーがサービス ディレクトリ クエリを発行するように、サービス ディレクトリのキャッシュ状態を設定します。

関連情報:
unresolve(WEAVE_ERROR)

～ WeaveServiceManager

 ~WeaveServiceManager(
  void
)

このメソッドは、WeaveServiceManager インスタンスを破棄します。