Edit

Share via

IFunctionDiscovery::GetInstanceCollection 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.]

Gets the specified collection of function instances, based on category and subcategory.

Syntax

HRESULT GetInstanceCollection(
  [in]  const WCHAR                 *pszCategory,
  [in]  const WCHAR                 *pszSubCategory,
  [in]  BOOL                        fIncludeAllSubCategories,
  [out] IFunctionInstanceCollection **ppIFunctionInstanceCollection
);

Parameters

[in] pszCategory

The identifier of the category to be enumerated. See Category Definitions.

[in] pszSubCategory

The identifier of the subcategory to be enumerated. See Subcategory Definitions. This parameter can be NULL.

[in] fIncludeAllSubCategories

If TRUE, this method recursively enumerates 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 itself to returning function instances in the category specified by pszCategory and the subcategory specified by pszSubCategory.

[out] ppIFunctionInstanceCollection

A pointer to an IFunctionInstanceCollection interface pointer that receives the function instance collection containing the requested function instances. The collection is empty if no qualifying function instances are found.

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 is invalid. The value returned in ppIFunctionInstanceCollection 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.
E_PENDING
 The call was executed for a provider that returns results asynchronously.

Remarks

Some function discovery providers return their query results with the IFunctionDiscoveryNotification interface. GetInstanceCollection does not find function instances that are returned in this way and will fail with E_PENDING. It is recommended that clients use the CreateInstanceQuery method of the IFunctionDiscovery interface to find function instances for such providers.

If the method succeeds but no function instances were found that matched the query parameters, then S_OK is returned and ppFunctionInstanceCollection points to an empty collection (the collection's GetCount method returns 0).

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. For other providers, function instance collections can be filtered using query constraints. For a list of query constraints, see Constraint Definitions.

Examples

The following code returns the function instances associated with the SSDP provider in the Microsoft.Networking.Devices namespace.

hr = spDisco->GetInstanceCollection(FCTN_CATEGORY_NETWORKDEVICES,
                                   FCTN_SUBCAT_NETWORKDEVICES_SSDP, 
                                   FALSE, 
                                   &spFunctionInstanceCollection);

See interface constraints on IFunctionInstanceQuery to filter on multiple interfaces at one time or to filter on providers that do not support subcategory queries.

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

IFunctionDiscovery