IFunctionDiscovery

このインターフェイスは、クライアントプログラムが関数インスタンスを検出したり、カテゴリの既定の関数インスタンスを取得したり、Function Discovery の既定値を登録できるようにするなど、高度な Function Discovery クエリオブジェクトを作成したりするために使用されます。

カテゴリとサブカテゴリに基づいて、指定された関数インスタンスのコレクションを取得します。

戻り値には、以下のものが含まれますが、これらに限定されません。

一部の Function Discovery プロバイダーは、クエリ結果を IFunctionDiscoveryNotification インターフェイスで返します。GetInstanceCollection はこの方法で返される関数インスタンスを検出できず、E_PENDING で失敗します。このようなプロバイダーの関数インスタンスを検出するには、クライアントは IFunctionDiscovery インターフェイスの CreateInstanceQuery メソッドを使用することをお勧めします。

メソッドは成功したものの、クエリパラメーターに一致する関数インスタンスが見つからなかった場合は、S_OK が返され、ppFunctionInstanceCollection は空のコレクションを指します(コレクションの GetCount メソッドは 0 を返します)。

サブカテゴリクエリは、階層化カテゴリと一部のプロバイダーカテゴリでのみサポートされます。Registry Provider、PnP-X アソシエーションプロバイダー、およびパブリケーションプロバイダーはサブカテゴリクエリをサポートします。カスタムプロバイダーは、サブカテゴリクエリをサポートするように明示的に設計できます。その他のプロバイダーでは、クエリ制約を使用して関数インスタンスコレクションをフィルターできます。クエリ制約の一覧については、Constraint Definitions を参照してください。

例

次のコードは、Microsoft.Networking.Devices 名前空間の SSDP プロバイダーに関連付けられた関数インスタンスを返します。

hr = spDisco->GetInstanceCollection(FCTN_CATEGORY_NETWORKDEVICES,
                                   FCTN_SUBCAT_NETWORKDEVICES_SSDP, 
                                   FALSE, 
                                   &spFunctionInstanceCollection);

複数のインターフェイスを一度にフィルターするか、サブカテゴリクエリをサポートしないプロバイダーをフィルターするには、IFunctionInstanceQuery のインターフェイス制約を参照してください。

識別子に基づいて、指定された関数インスタンスを取得します。

戻り値には、以下のものが含まれますが、これらに限定されません。

一部の Function Discovery プロバイダーは、クエリ結果を IFunctionDiscoveryNotification インターフェイスで返します。GetInstance はこの方法で返される関数インスタンスを検出できず、E_PENDING で失敗します。このようなプロバイダーの関数インスタンスを検出するには、クライアントは IFunctionDiscovery インターフェイスの CreateInstanceQuery メソッドを使用することをお勧めします。

特定の関数インスタンスのコレクションに対するクエリを作成します。

戻り値には、以下のものが含まれますが、これらに限定されません。

pIFunctionDiscoveryNotification を指定すると、Function Discovery の変更通知プロセスが有効になります。このパラメーターは NULL にできます。ただし、ネットワークプロバイダーは同期的な結果を返さないため、ネットワークプロバイダーでは必須です。Function Discovery のネットワークプロバイダーは、IFunctionDiscoveryNotification インターフェイスを通じてのみインスタンスを返します。

このメソッドはクエリ呼び出しを初期化するだけです。クエリを実行してデータを返すには、ppIFunctionInstanceCollectionQuery で返される IFunctionInstanceCollectionQuery インターフェイスの Execute メソッドを呼び出す必要があります。

特定の関数インスタンスに対するクエリを作成します。

戻り値には、以下のものが含まれますが、これらに限定されません。

Function Discovery のネットワークプロバイダーは、IFunctionDiscoveryNotification インターフェイスを通じてのみインスタンスを返します。

このメソッドはクエリ呼び出しを初期化するだけです。クエリを実行してデータを返すには、ppIFunctionInstanceQuery で返される IFunctionInstanceQuery インターフェイスの Execute メソッドを呼び出す必要があります。

関数インスタンスを作成または変更します。

戻り値には、以下のものが含まれますが、これらに限定されません。

このメソッドは、指定されたカテゴリとサブカテゴリに対して新しい関数インスタンスを一時的に作成します。カテゴリを実装するプロバイダーは、IFunctionDiscoveryProviderFactory::CreateInstance メソッドを使用して、新しく作成された関数インスタンスに関連付けられたメタデータを永続化する責任があります。

関連付けられたプロパティストアに値が 1 つもない場合、関数インスタンスはレジストリに書き込まれません。プロパティストアの値を確認するには、IFunctionInstance::OpenPropertyStore メソッドを使用してください。

指定されたカテゴリとサブカテゴリに対して関数インスタンスが既に存在する場合、既存のレジストリエントリが上書きされます。AddInstance メソッドは S_OK を返します。Function Discovery の変更通知プロセスは、enumQueryUpdateAction を QUA_CHANGE に設定して、呼び出し側アプリケーションの IFunctionDiscoveryNotification::OnUpdate メソッドを呼び出します。

レジストリプロバイダーを使用して関数インスタンスを追加または削除するには、HKEY_LOCAL_MACHINE\SYSTEM レジストリキーを変更するためのアクセス権(Administrator または Power User アクセス)が必要です。

カテゴリとサブカテゴリに基づいて、指定された関数インスタンスを削除します。

戻り値には、以下のものが含まれますが、これらに限定されません。

レジストリプロバイダーを使用して関数インスタンスを追加または削除するには、HKEY_LOCAL_MACHINE\SYSTEM レジストリキーを変更するためのアクセス権(Administrator または Power User アクセスレベル)が必要です。関数インスタンスをシステム全体から削除するには、ユーザーは Administrator アクセス権を持っている必要があります。