IFunctionInstanceQuery::Execute method (functiondiscoveryapi.h)

  • Article

[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.

Syntax

HRESULT Execute(
  [out] IFunctionInstance **ppIFunctionInstance
);

Parameters

[out] ppIFunctionInstance

A pointer to an IFunctionInstance interface pointer that receives the requested function instance.

Return value

Possible return values include, but are not limited to, the following.

Return code/value Description
S_OK
 The method completed successfully.
E_INVALIDARG
 The ppIFunctionInstance parameter is NULL.
E_OUTOFMEMORY
 The method is unable to allocate the memory required to perform this operation.
E_PENDING
 The results to be returned by a provider will come through asynchronous notification.
HRESULT_FROM_WIN32(ERROR_OBJECT_NOT_FOUND)
0x800710d8
 The function instance represented by the specified ID does not exist on this computer.
HRESULT_FROM_WIN32(ERROR_KEY_DELETED)
0x800703fa
 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.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)
0x80070002
 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.

Remarks

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:

  1. Retrieves the function instance.
  2. Initiates the update notification mechanism if the address of the client program's IFunctionDiscoveryNotification callback routine is provided to IFunctionDiscovery::CreateInstanceQuery.
Function Discovery network providers only return function instances through the IFunctionDiscoveryNotification interface. They return no function instances directly when this method is invoked. Instead, Execute simply initiates an entirely asynchronous retrieval operation and returns E_PENDING to indicate that the results will be returned asynchronously. Notifications must be used to retrieve function instances from Function Discovery network providers.

If Execute is called twice on the same query object, the first query is terminated before the second query executes.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header functiondiscoveryapi.h
DLL FunDisc.dll

See also

Function Discovery Queries

IFunctionInstanceQuery