Edit

IFunctionDiscoveryProvider::Query method (functiondiscoveryprovider.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.]

Retrieves a collection of function instances that meet the specified constraints.

Syntax

HRESULT Query(
  [in]  IFunctionDiscoveryProviderQuery *pIFunctionDiscoveryProviderQuery,
  [out] IFunctionInstanceCollection     **ppIFunctionInstanceCollection
);

Parameters

[in] pIFunctionDiscoveryProviderQuery

A pointer to an IFunctionDiscoveryProviderQuery interface that contains parameters that define the query criteria.

[out] ppIFunctionInstanceCollection

A pointer to an IFunctionInstanceCollection interface that the provider should use to return function instances synchronously in response to the given query.

When you implement the Query method, you can set this parameter to NULL if your provider supports notifications, that is, your provider returns results asynchronously. Asynchronous results should be returned using the IFunctionDiscoveryNotification interface passed to the provider's Initialize method.

If the client application has not implemented notifications, it may pass a NULL parameter.

Return value

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

Return code Description
S_OK
 The method completed successfully and the results are being returned synchronously.
E_INVALIDARG
 The pIFunctionDiscoveryProviderQuery parameter is NULL.
E_PENDING
 The method completed successfully and the results are being returned asynchronously.

Remarks

An active query is terminated by Function Discovery with a call to the EndQuery method. Note that EndQuery will only be called if the client specified a IFunctionDiscoveryNotification interface for the query. If a IFunctionDiscoveryNotification was not provided, the query must be considered ended by the provider once the Query call is complete.

A client can re-execute a query at any time after the previous Query call has returned. The implementation of Query must be able to return an IFunctionInstanceCollection for the new query. EndQuery will only be called before a subsequent Query call when a client passed an IFunctionDiscoveryNotification interface passed to the provider's Initialize method.

If Query returns E_PENDING, the provider must call the OnEvent method of the IFunctionDiscoveryNotification interface with FD_EVENTID_SEARCHCOMPLETE to indicate that the enumeration of results is complete. Failure to send the FD_EVENTID_SEARCHCOMPLETE event can result in clients hanging indefinitely

Requirements

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

See also

IFunctionDiscoveryProvider