IFunctionInstanceQuery

カテゴリとサブカテゴリに基づく関数インスタンスの非同期クエリを実装します。

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

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

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

戻り値のコード/値	説明
S_OK	メソッドは正常に完了しました。
E_INVALIDARG	ppIFunctionInstance パラメーターが NULL です。
E_OUTOFMEMORY	この操作の実行に必要なメモリをメソッドが割り当てられません。
E_PENDING	プロバイダーが返す結果は非同期通知を通じて到着します。
HRESULT_FROM_WIN32(ERROR_OBJECT_NOT_FOUND) 0x800710d8	指定された ID で表される関数インスタンスは、このコンピューター上に存在しません。
HRESULT_FROM_WIN32(ERROR_KEY_DELETED) 0x800703fa	関数インスタンスに対応するキーが別のプロセスによって削除されたため、関数インスタンスを返せませんでした。このエラーは、クエリ処理中にキーが削除された場合にレジストリプロバイダーによって返されます。
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) 0x80070002	関数インスタンスに対応するキーが見つからなかったため、関数インスタンスを返せませんでした。このエラーは、インスタンスクエリに一致するインスタンスをレジストリプロバイダーが見つけられなかった場合に返されます。

事前定義クエリとは、階層化されたカテゴリに対するクエリです。事前定義クエリが実行されると、関数インスタンスを返す各プロバイダーは 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 通知は上記のとおり送信されます。

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

1. 関数インスタンスを取得します。
2. クライアントプログラムの IFunctionDiscoveryNotification コールバックルーチンのアドレスが IFunctionDiscovery::CreateInstanceQuery に指定されている場合、更新通知メカニズムを開始します。

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

同じクエリオブジェクトに対して Execute が 2 回呼び出された場合、2 番目のクエリが実行される前に最初のクエリが終了されます。

#define global IID_IFunctionInstanceQuery "{6242BC6B-90EC-4B37-BB46-E229FD84ED95}"
#usecom global IFunctionInstanceQuery IID_IFunctionInstanceQuery "{}"
#comfunc global IFunctionInstanceQuery_Execute  3 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。