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。
有关如何设置 枚举器 值的详细信息，请参阅以下 备注 部分。
[in, optional] hwndParent
要用于在设备信息集中安装设备实例的用户界面的顶级窗口的句柄。 此句柄是可选的，可以 NULL。
[in] Flags
类型为 DWORD 的变量，指定用于筛选添加到设备信息集的设备信息元素的控制选项。 此参数可以是以下一个或多个标志的按位 OR。 有关合并这些控件选项的详细信息，请参阅以下 备注 部分。
DIGCF_ALLCLASSES
返回指定设备安装类或设备接口类的已安装设备列表。
DIGCF_DEVICEINTERFACE
返回支持指定设备接口类的设备。 如果 枚举器 参数指定 设备实例 ID，则必须在 标志 参数中设置此标志。
DIGCF_DEFAULT
仅为指定的设备接口类返回与系统默认设备接口关联的设备（如果已设置设备接口）。
DIGCF_PRESENT
仅返回当前存在的设备。
DIGCF_PROFILE
仅返回属于当前硬件配置文件一部分的设备。
[in, optional] DeviceInfoSet
[in, optional] MachineName
指向包含设备所在远程计算机名称的常量字符串的指针。
谨慎
从 Windows 8 和 Windows Server 2012 开始，不支持使用此函数访问远程计算机，因为此功能已被删除。
Reserved
保留供内部使用。 此参数必须设置为 NULL。
返回值
如果操作成功，SetupDiGetClassDevsEx 将句柄返回到 设备信息集，其中包含与提供的参数匹配的所有已安装设备。 如果操作失败，该函数将返回INVALID_HANDLE_VALUE。 若要获取扩展的错误信息，请调用 GetLastError。
言论
SetupDiGetClassDevsEx 调用 SetupDiDestroyDeviceInfoList不再需要返回的设备信息时，必须删除返回的设备信息。
如果 DeviceInfoSetNULL，SetupDiGetClassDevsEx 将创建包含检索到的设备信息元素的新设备信息集，并将句柄返回到新设备信息集。 如果调用方请求函数检索由 ClassGuid 参数提供的设备安装类的设备，该函数会将新设备信息集的设备安装类设置为提供的类 GUID。
如果 DeviceInfoSet 未设置为 NULL，则该函数会将检索的设备信息元素添加到与提供的句柄关联的设备信息集，并返回提供的句柄。 如果 ClassGuid 提供设备设置类，则提供的设备信息集的设备设置类必须设置为提供的类 GUID。
设备安装程序类控制选项
使用以下筛选选项来控制 SetupDiGetClassDevsEx 返回所有设备设置类的设备，还是仅返回指定设备设置类的设备：- 若要返回所有设备设置类的设备，请设置DIGCF_ALLCLASSES标志，并将 ClassGuid 参数设置为 NULL。
- 若要仅返回特定设备设置类的设备，请不要设置DIGCF_ALLCLASSES并使用 ClassGuid 来提供设备设置类的 GUID。
- 若要仅返回系统中存在的设备，请设置DIGCF_PRESENT标志。
- 若要仅返回属于当前硬件配置文件的设备，请设置DIGCF_PROFILE标志。
- 若要仅返回特定 PnP 枚举器 的设备，请使用 枚举器 参数来提供枚举器的 GUID 或符号名称。如果 枚举器为 NULL，SetupDiGetClassDevsEx 返回所有 PnP 枚举器的设备。
设备接口类控制选项
使用以下筛选选项来控制 SetupDiGetClassDevsEx 返回支持任何设备接口类的设备还是仅支持指定设备接口类的设备：- 若要返回支持任何类的设备接口，请设置DIGCF_DEVICEINTERFACE标志、设置DIGCF_ALLCLASSES标志，并将 ClassGuid 设置为 NULL。 该函数添加到设备信息集表示此类设备的设备信息元素，然后将设备信息元素添加到设备信息元素，该列表包含设备支持的所有设备接口。
- 若要仅返回支持指定类的设备接口，请设置DIGCF_DEVICEINTERFACE标志并使用 ClassGuid 参数提供设备接口类的类 GUID。 该函数添加到设备信息集表示此类设备的设备信息元素，然后将指定类的设备接口添加到该设备信息元素的设备接口列表中。
- 若要仅返回支持系统默认接口的设备，如果为指定设备接口类设置了设备接口类，请设置DIGCF_DEVICEINTERFACE标志，设置DIGCF_DEFAULT标志，并使用 ClassGuid 提供设备接口类的类 GUID。 该函数添加到设备信息集表示此类设备的设备信息元素，然后将系统默认接口添加到该设备信息元素的设备接口列表。
- 若要返回支持未指定设备接口类的系统默认接口的设备，请设置DIGCF_DEVICEINTERFACE标志，设置DIGCF_ALLCLASSES标志，设置DIGCF_DEFAULT标志，并将 ClassGuid 设置为 NULL。 该函数添加到设备信息集表示此类设备的设备信息元素，然后将系统默认接口添加到该设备信息元素的设备接口列表。
- 若要仅返回系统中存在的设备，请设置DIGCF_PRESENT标志。
- 若要仅返回属于当前硬件配置文件的设备，请设置DIGCF_PROFILE标志。
- 若要仅返回特定设备，请设置DIGCF_DEVICEINTERFACE标志，并使用 枚举器 参数提供设备设备实例 ID。若要包括所有可能的设备，请将 枚举器 设置为 NULL。
检索支持设备接口类的设备安装类中的设备
安装程序可以使用 SetupDiGetClassDevsEx 检索支持指定设备接口类的特定设备安装类的设备列表。 例如，若要检索本地计算机上的所有设备列表，这些设备支持“已装载设备”接口类中的设备接口，并且这些设备是“Volume”设备安装类的成员，安装程序应执行以下操作：- 调用 SetupDiCreateDeviceInfoList 为“Volume”设备安装类创建空设备信息集。 ClassGuid 设置为指向“Volume”设备设置类的类 GUID 的指针，并根据需要设置 hwndParent。 为了响应此类调用，该函数将向设备信息集返回 HDEVINFO 类型的句柄。
- 使用以下设置调用 SetupDiGetClassDevsEx：
- ClassGuid 设置为指向“已装载设备”设备接口类类的类 GUID 的指针。
- 将 标志 设置为DIGCF_DEVICEINTERFACE。
- 将 DeviceInfoSet 设置为在步骤 （1） 中获取的 HDEVINFO 句柄。
- 根据需要设置 hwndParent，其余参数设置为 NULL。
注意
setupapi.h 标头将 SetupDiGetClassDevsEx 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | Microsoft Windows 2000 及更高版本的 Windows 中可用。 |
| 目标平台 | 桌面 |
| 标头 | setupapi.h （包括 Setupapi.h） |
| 库 | Setupapi.lib |