IFunctionDiscovery::CreateInstanceCollectionQuery method (functiondiscoveryapi.h)

[Function Discovery is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions.]

Creates a query for a collection of specific function instances.

Syntax

HRESULT CreateInstanceCollectionQuery(
  [in]      const WCHAR                      *pszCategory,
  [in]      const WCHAR                      *pszSubCategory,
  [in]      BOOL                             fIncludeAllSubCategories,
  [in]      IFunctionDiscoveryNotification   *pIFunctionDiscoveryNotification,
  [in, out] FDQUERYCONTEXT                   *pfdqcQueryContext,
  [out]     IFunctionInstanceCollectionQuery **ppIFunctionInstanceCollectionQuery
);

Parameters

[in] pszCategory

The category for the query. See Category Definitions.

[in] pszSubCategory

The subcategory for the query. See Subcategory Definitions. This parameter can be NULL.

Subcategory queries are only supported for layered categories and some provider categories. The Registry Provider, the PnP-X association provider, and the publication provider support subcategory queries. Custom providers can be explicitly designed to support subcategory queries. This means the pszSubCategory parameter should be set to a non-NULL value only when the pszCategory parameter is set to FCTN_CATEGORY_REGISTRY, FCTN_CATEGORY_PUBLICATION, FCTN_CATEGORY_PNPXASSOCIATION, or a custom category value defined for either a layered category or a custom provider supporting subcategory queries.

[in] fIncludeAllSubCategories

If TRUE, this method recursively creates a query for all the subcategories of the category specified in pszCategory, returning a collection containing function instances from all the subcategories of pszCategory.

If FALSE, this method restricts the created query to returning function instances in the category specified by pszCategory and the subcategory specified by pszSubCategory.

[in] pIFunctionDiscoveryNotification

A pointer to the IFunctionDiscoveryNotification interface implemented by the calling application. This parameter can be NULL. This pointer is valid until the returned query object is released.

[in, out] pfdqcQueryContext

A pointer to the context in which the query was created. The type FDQUERYCONTEXT is defined as a DWORDLONG.

[out] ppIFunctionInstanceCollectionQuery

A pointer to the IFunctionInstanceCollectionQuery interface pointer.

Return value

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

Remarks

If pIFunctionDiscoveryNotification is specified, it enables the Function Discovery change notification process. This parameter can be NULL. However, it is required for network providers since they do not return synchronous results. Function Discovery network providers only return instances through the IFunctionDiscoveryNotification interface.

This method only initializes the query call. The Execute method of the IFunctionInstanceCollectionQuery interface returned in ppIFunctionInstanceCollectionQuery must be called to perform the query and return any data.

Requirements

See also

Function Discovery Queries

IFunctionDiscovery