[Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions.]
Performs the query defined by IFunctionDiscovery::CreateInstanceQuery.
HRESULT Execute( IFunctionInstance **ppIFunctionInstance );
A pointer to an IFunctionInstance interface pointer that receives the requested function instance.
Possible return values include, but are not limited to, the following.
||The method completed successfully.|
||The ppIFunctionInstance parameter is NULL.|
||The method is unable to allocate the memory required to perform this operation.|
||The results to be returned by a provider will come through asynchronous notification.|
||The function instance represented by the specified ID does not exist on this computer.|
||The function instance could not be returned because the key corresponding to the function instance was deleted by another process. This error is returned by the registry provider if a key is deleted while query processing is taking place.|
||The function instance could not be returned because the key corresponding to the function instance could not be found. This error is returned by the registry provider when the provider could not find matching instances for an instance query.|
A predefined query is a query of a layered category. When a predefined query is executed, each provider that returns a function instance also returns an HRESULT value. The provider HRESULT values are aggregated, and the value returned by the Execute method reflects these aggregate results. Results are aggregated as follows:
- If all providers return S_OK, Execute returns S_OK.
- If at least one provider returns E_PENDING, and all other providers return either S_OK or E_PENDING, Execute returns E_PENDING.
- If all providers return an error value (that is, a value other than S_OK or E_PENDING), Execute returns the error value returned by the network provider that was last queried. Also, if the client's IFunctionDiscoveryNotification callback routine was provided to IFunctionDiscovery::CreateInstanceCollectionQuery, an OnError notification is sent for each provider. Each OnError notification contains the HRESULT returned by the provider.
- If at least one provider returns an error value, and all other providers return S_OK, Execute returns S_OK. OnError notification(s) are sent as described above.
- If at least one provider returns an error value, and at least one provider returns E_PENDING, Execute returns E_PENDING. OnError notification(s) are sent as described above.
This method must be must be invoked by the client program to retrieve data from the query object. When called, this method performs the following:
- Retrieves the function instance.
- Initiates the update notification mechanism if the address of the client program's IFunctionDiscoveryNotification callback routine is provided to IFunctionDiscovery::CreateInstanceQuery.
If Execute is called twice on the same query object, the first query is terminated before the second query executes.
|Minimum supported client||Windows Vista [desktop apps only]|
|Minimum supported server||Windows Server 2008 [desktop apps only]|