IFunctionDiscovery：：GetInstanceCollection 方法 (functiondiscoveryapi.h)

  • 项目

[函数发现可用于“要求”部分中指定的操作系统。 在后续版本中，它可能已更改或不可用。]

根据类别和子类别获取函数实例的指定集合。

语法

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

参数

[in] pszCategory

要枚举的类别的标识符。 请参阅 类别定义。

[in] pszSubCategory

要枚举的子类别的标识符。 请参阅 子类别定义。 此参数可以为 NULL。

[in] fIncludeAllSubCategories

如果 为 TRUE，此方法以递归方式枚举 pszCategory 中指定的类别的所有子类别，并返回包含 pszCategory 所有子类别中的函数实例的集合。

如果 为 FALSE，则此方法将自身限制为返回 pszCategory 指定的类别和 pszSubCategory 指定的子类别中的函数实例。

[out] ppIFunctionInstanceCollection

指向 IFunctionInstanceCollection 接口指针的指针，该指针接收包含所请求函数实例的函数实例集合。 如果未找到符合条件的函数实例，则集合为空。

返回值

可能的返回值包括但不限于以下内容。

返回代码/值 说明
S_OK
 该方法已成功完成。
E_INVALIDARG
 pszCategory 的值无效。 ppIFunctionInstanceCollection 参数中返回的值为 NULL。
E_OUTOFMEMORY
 方法无法分配执行此操作所需的内存。
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)
0x80070002
 pszCategory 或 pszSubCategory 的值未知。
E_PENDING
 调用针对异步返回结果的提供程序执行。

备注

某些函数发现提供程序使用 IFunctionDiscoveryNotification 接口返回其查询结果。 GetInstanceCollection 找不到以这种方式返回的函数实例，并且会失败并出现E_PENDING。 建议客户端使用 IFunctionDiscovery 接口的 CreateInstanceQuery 方法来查找此类提供程序的函数实例。

如果方法成功，但找不到与查询参数匹配的函数实例，则返回 S_OK ， ppFunctionInstanceCollection 指向空集合， (集合的 GetCount 方法返回 0) 。

子类别查询仅支持分层类别和某些提供程序类别。 注册表提供程序、PnP-X 关联提供程序和发布提供程序支持子类别查询。 自定义提供程序可以显式设计为支持子类别查询。 对于其他提供程序，可以使用查询约束筛选函数实例集合。 有关查询约束的列表，请参阅 约束定义。

示例

以下代码返回与 Microsoft.Networking.Devices 命名空间中的 SSDP 提供程序关联的函数实例。

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

请参阅 IFunctionInstanceQuery 上的接口约束，一次筛选多个接口或筛选不支持子类别查询的提供程序。

要求

   
最低受支持的客户端 Windows Vista [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 [仅限桌面应用]
目标平台 Windows
标头 functiondiscoveryapi.h
DLL FunDisc.dll

请参阅

IFunctionDiscovery