SetupDiGetClassDevsExA 函数 (setupapi.h)

  • 项目

SetupDiGetClassDevsEx 函数返回包含本地或远程计算机请求的设备信息元素的设备信息集的句柄。

语法

WINSETUPAPI HDEVINFO SetupDiGetClassDevsExA(
  [in, optional] const GUID *ClassGuid,
  [in, optional] PCSTR      Enumerator,
  [in, optional] HWND       hwndParent,
  [in]           DWORD      Flags,
  [in, optional] HDEVINFO   DeviceInfoSet,
  [in, optional] PCSTR      MachineName,
                 PVOID      Reserved
);

参数

[in, optional] ClassGuid

指向设备安装类或设备接口类的 GUID 的指针。 此指针是可选的，可以为 NULL。 如果未使用 GUID 值来选择设备，请将 ClassGuid 设置为 NULL。 有关如何使用 ClassGuid 的详细信息，请参阅以下 “备注” 部分。

[in, optional] Enumerator

指向以 NULL 结尾的字符串的指针，该字符串指定：

  • 即插即用 (PnP) 枚举器的标识符 (ID) 。 此 ID 可以是枚举器的全局唯一标识符 (GUID) 或符号名称。 例如，“PCI”可用于指定 PCI PnP 枚举器。 PnP 枚举器符号名称的其他示例包括“USB”、“PCMCIA”和“SCSI”。
  • PnP 设备实例 ID。 指定 PnP 设备实例 ID 时，必须在 Flags 参数中设置DIGCF_DEVICEINTERFACE。
此指针是可选的，可以为 NULL。 如果未使用 枚举器 值来选择设备，请将 枚举器 设置为 NULL

有关如何设置 枚举器 值的详细信息，请参阅以下 “备注” 部分。

[in, optional] hwndParent

顶级窗口的句柄，用于与在设备信息集中安装设备实例关联的用户界面。 此句柄是可选的，可以为 NULL。

[in] Flags

DWORD 类型的变量，指定用于筛选添加到设备信息集的设备信息元素的控制选项。 此参数可以是以下一个或多个标志的按位 OR。 有关组合这些控件选项的详细信息，请参阅以下 “备注 ”部分。

DIGCF_ALLCLASSES

返回指定设备安装程序类或设备接口类的已安装设备的列表。

DIGCF_DEVICEINTERFACE

返回支持指定设备接口类的设备接口的设备。 如果 Enumerator 参数指定设备实例 ID，则必须在 Flags 参数中设置此标志。

DIGCF_DEFAULT

对于指定的设备接口类，仅返回与系统默认设备接口关联的设备（如果已设置）。

DIGCF_PRESENT

仅返回当前存在的设备。

DIGCF_PROFILE

仅返回属于当前硬件配置文件的设备。

[in, optional] DeviceInfoSet

SetupDiGetClassDevsEx 将请求的设备信息元素添加到的现有设备信息集的句柄。 此参数是可选的，可以设置为 NULL。 有关使用此参数的详细信息，请参阅以下 “备注” 部分。

[in, optional] MachineName

指向常量字符串的指针，该常量字符串包含设备所在的远程计算机的名称。 MachineName 的 NULL 值指定设备安装在本地计算机上。

注意

从Windows 8和Windows Server 2012开始，不支持使用此函数访问远程计算机，因为此功能已被删除。

Reserved

保留以供内部使用。 此参数必须设置为 NULL。

返回值

如果操作成功， SetupDiGetClassDevsEx 将返回 设备信息集 的句柄，该句柄包含与提供的参数匹配的所有已安装设备。 如果操作失败，函数将返回INVALID_HANDLE_VALUE。 要获得更多的错误信息，请调用 GetLastError。

注解

当不再需要 SetupDiDestroyDeviceInfoList 时，SetupDiGetClassDevsEx 的调用方必须删除返回的设备信息集。

如果 DeviceInfoSet 为 NULL， 则 SetupDiGetClassDevsEx 将创建包含检索到的设备信息元素的新设备信息集，并返回新设备信息集的句柄。 如果调用方请求函数检索 ClassGuid 参数提供的设备安装类的设备，该函数会将新设备信息集的设备设置类设置为提供的类 GUID。

如果 DeviceInfoSet 未设置为 NULL，则该函数会将检索到的设备信息元素添加到与提供的句柄关联的设备信息集，并返回提供的句柄。 如果 ClassGuid 提供设备安装类，则必须将所提供的设备信息集的设备设置类设置为提供的类 GUID。

设备安装程序类控制选项

使用以下筛选选项来控制 SetupDiGetClassDevsEx 是返回所有设备安装类的设备，还是仅返回指定设备安装程序类的设备：
  • 若要返回所有设备安装类的设备，请设置DIGCF_ALLCLASSES标志并将 ClassGuid 参数设置为 NULL。
  • 若要仅返回特定设备安装类的设备，请不要设置DIGCF_ALLCLASSES并使用 ClassGuid 提供设备安装类的 GUID。
此外，还可以使用以下筛选选项进一步限制返回的设备。
  • 若要仅返回系统中存在的设备，请设置DIGCF_PRESENT标志。
  • 若要仅返回属于当前硬件配置文件的设备，请设置DIGCF_PROFILE标志。
  • 若要仅返回特定 PnP 枚举器 的设备，请使用 Enumerator 参数提供枚举器的 GUID 或符号名称。 如果 Enumerator 为 NULL， 则 SetupDiGetClassDevsEx 将返回所有 PnP 枚举器的设备。

设备接口类控制选项

使用以下筛选选项来控制 SetupDiGetClassDevsEx 是返回支持任何设备接口类的设备还是仅返回支持指定设备接口类的设备：
  • 若要返回支持任何类的设备接口的设备，请设置 DIGCF_DEVICEINTERFACE 标志，设置 DIGCF_ALLCLASSES 标志，然后将 ClassGuid 设置为 NULL。 函数向设备信息集添加表示此类设备的设备信息元素，然后向设备信息元素添加包含设备支持的所有设备接口的设备接口列表。
  • 若要仅返回支持指定类的设备接口的设备，请设置 DIGCF_DEVICEINTERFACE 标志并使用 ClassGuid 参数提供设备接口类的类 GUID。 函数将表示此类设备的设备信息元素添加到设备信息集，然后将指定类的设备接口添加到该设备信息元素的设备接口列表。
此外，还可以使用以下筛选选项来控制 SetupDiGetClassDevsEx 是否仅返回支持设备接口类的系统默认接口的设备：
  • 若要仅返回支持系统默认接口的设备（如果已设置），请为指定的设备接口类设置DIGCF_DEVICEINTERFACE标志，设置DIGCF_DEFAULT标志，并使用 ClassGuid 提供设备接口类的类 GUID。 函数向设备信息集添加表示此类设备的设备信息元素，然后将系统默认接口添加到该设备信息元素的设备接口列表。
  • 若要返回支持未指定设备接口类的系统默认接口的设备，请设置DIGCF_DEVICEINTERFACE标志，设置DIGCF_ALLCLASSES标志，设置DIGCF_DEFAULT标志，并将 ClassGuid 设置为 NULL。 函数向设备信息集添加表示此类设备的设备信息元素，然后将系统默认接口添加到该设备信息元素的设备接口列表。
还可以将以下选项与其他选项结合使用，以进一步限制返回的设备。
  • 若要仅返回系统中存在的设备，请设置DIGCF_PRESENT标志。
  • 若要仅返回属于当前硬件配置文件的设备，请设置DIGCF_PROFILE标志。
  • 若要仅返回特定设备，请设置 DIGCF_DEVICEINTERFACE 标志，并使用 Enumerator 参数提供设备的设备实例 ID。 若要包括所有可能的设备，请将枚举器设置为 NULL。

检索支持设备接口类的设备安装程序类中的设备

安装程序可以使用 SetupDiGetClassDevsEx 检索支持指定设备接口类的特定设备安装程序类的设备列表。 例如，若要检索本地计算机上支持“装载设备”接口类中的设备接口且属于“Volume”设备安装程序类成员的所有设备的列表，安装程序应执行以下操作：
  1. 调用 SetupDiCreateDeviceInfoList ，为“Volume”设备安装程序类创建空设备信息集。 将 ClassGuid 设置为指向“Volume”设备安装类的类 GUID 的指针，并根据需要设置 hwndParent 。 为了响应此类调用，函数会将类型 HDEVINFO 的句柄返回到设备信息集。
  2. 使用以下设置调用 SetupDiGetClassDevsEx ：
    • 将 ClassGuid 设置为指向“装载的设备”设备接口类的类 GUID 的指针。
    • 将 “标志” 设置为“DIGCF_DEVICEINTERFACE”。
    • 将 DeviceInfoSet 设置为步骤 (1) 中获取的 HDEVINFO 句柄。
    • 根据需要将 hwndParent 设置为 NULL，并将其余参数设置为 NULL。
在此类型的操作中，如果设备的设备设置类与所提供的设备信息集相同，并且设备支持类与指定设备接口类相同的设备接口， 则 SetupDiGetClassDevsEx 将返回设备。

注意

setupapi.h 标头将 SetupDiGetClassDevsEx 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

要求 值
最低受支持的客户端 在 Microsoft Windows 2000 及更高版本的 Windows 中可用。
目标平台 桌面
标头 setupapi.h (包括 Setupapi.h)
Library Setupapi.lib

另请参阅

设备信息集

设备实例 ID

SetupDiCreateDeviceInfoListEx

SetupDiDestroyDeviceInfoList

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs