IFunctionDiscovery::CreateInstanceCollectionQuery method

[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(
  const WCHAR                      *pszCategory,
  const WCHAR                      *pszSubCategory,
  BOOL                             fIncludeAllSubCategories,
  IFunctionDiscoveryNotification   *pIFunctionDiscoveryNotification,
  FDQUERYCONTEXT                   *pfdqcQueryContext,
  IFunctionInstanceCollectionQuery **ppIFunctionInstanceCollectionQuery
);

Parameters

pszCategory

The category for the query. See Category Definitions.

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.

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.

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.

pfdqcQueryContext

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

ppIFunctionInstanceCollectionQuery

A pointer to the IFunctionInstanceCollectionQuery interface pointer.

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 value of pszCategory or pIID is invalid. The value returned in ppIFunctionInstanceCollectionQuery parameter is NULL.
E_OUTOFMEMORY
The method is unable to allocate the memory required to perform this operation.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)
0x80070002
The value of pszCategory or pszSubCategory is unknown.

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

   
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

IFunctionDiscovery