IFunctionInstanceCollectionQuery

カテゴリおよびサブカテゴリに基づく、関数インスタンスのコレクションに対する非同期クエリを実装します。

クエリオブジェクトからデータを取得する前に、クライアントプログラムは Execute メソッドを呼び出す必要があります。

クエリにクエリ制約を追加します。

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

リターンコード	説明
S_OK	メソッドは正常に完了しました。
E_OUTOFMEMORY	この操作の実行に必要なメモリを割り当てることができませんでした。

複数の制約を追加した場合、クエリを満たすにはすべての制約がサポートされている必要があります。

IFunctionInstanceCollectionQuery オブジェクトがすべてのサブカテゴリを含んでおり、かつ pszConstraintName パラメーターに FD_QUERYCONSTRAINT_PROVIDERINSTANCEID を指定して AddQueryConstraint メソッドを呼び出した場合、AddQueryConstraint はエラーで失敗します。このエラーを回避するには、すべてのサブカテゴリを含まない IFunctionInstanceCollectionQuery オブジェクトを作成してください。そのようなオブジェクトは、fIncludeAllSubCategories パラメーターに false を指定して CreateInstanceCollectionQuery を呼び出すことで作成できます。

クエリにプロパティ制約を追加します。

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

リターンコード	説明
S_OK	メソッドは正常に完了しました。
E_OUTOFMEMORY	この操作の実行に必要なメモリを割り当てることができませんでした。
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	クエリに指定された制約はサポートされていません。特定の VARENUM 型に対して制約がサポートされていないか、または VARENUM 型自体がまったくサポートされていません。

関数インスタンスがプロパティ制約に一致するのは、関数インスタンスの PKEY の PROPVARIANT 型が制約の PKEY の PROPVARIANT 型と一致し、かつ enumPropertyConstraint で指定された比較演算子を用いて関数インスタンスの PKEY 値が制約の PKEY 値と一致する場合のみです。

複数の制約を追加した場合、クエリを満たすにはすべての制約がサポートされている必要があります。

IFunctionDiscovery::CreateInstanceCollectionQuery で定義されたクエリを実行します。

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

リターンコード	説明
S_OK	メソッドは正常に完了しました。結果は ppIFunctonInstanceCollecton に同期的に返されます。
E_OUTOFMEMORY	この操作の実行に必要なメモリを割り当てることができませんでした。
E_PENDING	一部の結果は非同期通知によって返されます。詳細については解説を参照してください。

定義済みクエリとは、階層化された カテゴリ に対するクエリです。定義済みクエリが実行されると、関数インスタンスを返す各プロバイダーは HRESULT 値も返します。プロバイダーの HRESULT 値は集約され、Execute メソッドが返す値はこれらの集約結果を反映します。結果は次のように集約されます。

• すべてのプロバイダーが S_OK を返した場合、Execute は S_OK を返します。
• 少なくとも 1 つのプロバイダーが E_PENDING を返し、その他のすべてのプロバイダーが S_OK または E_PENDING のいずれかを返した場合、Execute は E_PENDING を返します。
• すべてのプロバイダーがエラー値（すなわち S_OK または E_PENDING 以外の値）を返した場合、Execute は最後にクエリされたネットワークプロバイダーが返したエラー値を返します。また、クライアントの IFunctionDiscoveryNotification コールバックルーチンが IFunctionDiscovery::CreateInstanceCollectionQuery に提供されていた場合、各プロバイダーについて OnError 通知が送信されます。各 OnError 通知には、プロバイダーが返した HRESULT が含まれます。
• 少なくとも 1 つのプロバイダーがエラー値を返し、その他のすべてのプロバイダーが S_OK を返した場合、Execute は S_OK を返します。OnError 通知は上記のとおり送信されます。
• 少なくとも 1 つのプロバイダーがエラー値を返し、かつ少なくとも 1 つのプロバイダーが E_PENDING を返した場合、Execute は E_PENDING を返します。OnError 通知は上記のとおり送信されます。

Execute が S_OK を返すと、ppIFunctionInstanceCollection にクエリの結果が格納されます。IFunctionDiscovery の CreateInstanceCollectionQuery メソッドに IFunctionDiscoveryNotification インターフェースが提供されている場合、結果への変更はそのインターフェースを介して通知されます。

Execute が E_PENDING を返すと、結果セットは IFunctionDiscovery の CreateInstanceCollectionQuery メソッドに提供された IFunctionDiscoveryNotification インターフェースを介して非同期に返されます。ppIFunctionInstanceCollection は NULL になる場合や、部分的な結果セットを含む場合があります。IFunctionDiscoveryNotification の OnEvent メソッドが FD_EVENTID_SEARCHCOMPLETE で呼び出された時点で列挙は完了します。FD_EVENTID_SEARCHCOMPLETE イベントを受信した後の追加の通知は、結果に対する更新です。

クエリオブジェクトからデータを取得する前に、クライアントプログラムはこのメソッドを呼び出す必要があります。呼び出されると、このメソッドは次の処理を行います。

1. 関数インスタンスコレクションオブジェクトを取得します。
2. IFunctionDiscovery::CreateInstanceCollectionQuery に渡されたカテゴリのプロバイダーにクエリを実行します。
3. カテゴリプロバイダーを取得します。
4. サブカテゴリデータを使用してカテゴリプロバイダーにクエリを実行し、クエリ制約を使用してコレクションを生成します。
5. クライアントプログラムの IFunctionDiscoveryNotification コールバックルーチンのアドレスが IFunctionDiscovery::CreateInstanceCollectionQuery に提供されている場合、更新通知メカニズムを開始します。
6. コレクションデータをキャッシュして戻ります。

Function Discovery のネットワークプロバイダーは、IFunctionDiscoveryNotification インターフェースを介してのみ関数インスタンスを返します。このメソッドが呼び出されても、関数インスタンスを直接返すことはありません。代わりに、Execute は完全に非同期な取得操作を開始し、結果が非同期に返されることを示すために E_PENDING を返すだけです。Function Discovery のネットワークプロバイダーから関数インスタンスを取得するには、通知を使用する必要があります。

#define global IID_IFunctionInstanceCollectionQuery "{57CC6FD2-C09A-4289-BB72-25F04142058E}"
#usecom global IFunctionInstanceCollectionQuery IID_IFunctionInstanceCollectionQuery "{}"
#comfunc global IFunctionInstanceCollectionQuery_AddQueryConstraint     3 wstr,wstr
#comfunc global IFunctionInstanceCollectionQuery_AddPropertyConstraint  4 var,var,int
#comfunc global IFunctionInstanceCollectionQuery_Execute                5 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。