SetupDiGetClassDevsA 函数 (setupapi.h)

项目
03/04/2024

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

语法

WINSETUPAPI HDEVINFO SetupDiGetClassDevsA(
  const GUID *ClassGuid,
  PCSTR      Enumerator,
  HWND       hwndParent,
  DWORD      Flags
);

参数

ClassGuid

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

Enumerator

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

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

此指针是可选的，可以为 NULL。如果未使用枚举值来选择设备，请将 枚举器 设置为 NULL

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

hwndParent

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

Flags

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

DIGCF_ALLCLASSES

返回所有设备安装类或所有设备接口类的已安装设备列表。

DIGCF_DEVICEINTERFACE

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

DIGCF_DEFAULT

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

DIGCF_PRESENT

仅返回系统中当前存在的设备。

DIGCF_PROFILE

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

返回值

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

注解

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

调用 SetupDiGetClassDevsEx 以检索远程计算机上的类的设备。

设备设置类控件选项

使用以下筛选选项来控制 SetupDiGetClassDevs 是返回所有设备安装类的设备，还是仅返回指定设备安装类的设备：

若要返回所有设备安装类的设备，请设置 DIGCF_ALLCLASSES 标志，并将 ClassGuid 参数设置为 NULL。
若要仅返回特定设备安装类的设备，请不要设置DIGCF_ALLCLASSES，并使用 ClassGuid 提供设备安装类的 GUID。

此外，可以结合使用以下筛选选项，以进一步限制返回哪些设备：

若要仅返回系统中存在的设备，请设置 DIGCF_PRESENT 标志。
若要仅返回属于当前硬件配置文件的设备，请设置DIGCF_PROFILE标志。
若要仅返回特定 PnP 枚举器的设备，请使用 枚举器 参数提供枚举器的 GUID 或符号名称。如果 枚举器 为 NULL， 则 SetupDiGetClassDevs 将返回所有 PnP 枚举器的设备。

设备接口类控件选项

使用以下筛选选项来控制 SetupDiGetClassDevs 是返回支持任何设备接口类的设备，还是仅返回支持指定设备接口类的设备：

若要返回支持任何类的设备接口，请设置DIGCF_DEVICEINTERFACE标志，设置DIGCF_ALLCLASSES标志，并将 ClassGuid 设置为 NULL。函数向设备信息集添加表示此类设备的设备信息元素，然后向设备信息元素添加包含设备支持的所有设备接口的设备接口列表。
若要仅返回支持指定类的设备接口，请设置DIGCF_DEVICEINTERFACE标志并使用 ClassGuid 参数提供设备接口类的类 GUID。函数向设备信息集添加表示此类设备的设备信息元素，然后将指定类的设备接口添加到该设备信息元素的设备接口列表。

此外，还可以使用以下筛选选项来控制 SetupDiGetClassDevs 是否仅返回支持设备接口类系统默认接口的设备：

若要仅返回支持系统默认接口的设备（如果已设置），请为指定的设备接口类设置DIGCF_DEVICEINTERFACE标志，设置DIGCF_DEFAULT标志，并使用 ClassGuid 提供设备接口类的类 GUID。函数向设备信息集添加表示此类设备的设备信息元素，然后将系统默认接口添加到该设备信息元素的设备接口列表。
若要为未指定的设备接口类返回支持系统默认接口的设备，请设置DIGCF_DEVICEINTERFACE标志、DIGCF_ALLCLASSES标志、DIGCF_DEFAULT标志，并将 ClassGuid 设置为 NULL。函数向设备信息集添加表示此类设备的设备信息元素，然后将系统默认接口添加到该设备信息元素的设备接口列表。

还可以将以下选项与其他选项结合使用，以进一步限制返回的设备：

若要仅返回系统中存在的设备，请设置 DIGCF_PRESENT 标志。
若要仅返回属于当前硬件配置文件的设备，请设置DIGCF_PROFILE标志。
若要仅返回特定设备，请设置DIGCF_DEVICEINTERFACE标志并使用枚举器参数提供设备的设备实例 ID。若要包含所有可能的设备，请将枚举器设置为 NULL。

示例

下面是有关如何使用 SetupDiGetClassDevs 函数的一些示例。

示例 1： 生成系统中所有设备的列表，包括当前不存在的设备。

Handle = SetupDiGetClassDevs(NULL, NULL, NULL, DIGCF_ALLCLASSES);

示例 2： 生成系统中存在的所有设备的列表。

Handle = SetupDiGetClassDevs(NULL, NULL, NULL, DIGCF_ALLCLASSES | DIGCF_PRESENT);

示例 3： 从网络适配器设备设置类生成系统中存在的所有设备的列表。

Handle = SetupDiGetClassDevs(&GUID_DEVCLASS_NET, NULL, NULL, DIGCF_PRESENT);

示例 4： 生成系统中已从存储卷设备接口类启用接口的所有设备的列表。

Handle = SetupDiGetClassDevs(&GUID_DEVINTERFACE_VOLUME, NULL, NULL, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE);

示例 5： 生成系统中存在但不属于任何已知设备设置类的所有设备的列表，这些设备 (Windows Vista 及更高版本的 Windows) 。

注意不能将 ClassGuid 参数设置为 GUID_DEVCLASS_UNKNOWN以检测具有未知安装类的设备。相反，必须遵循此示例。

DeviceInfoSet = SetupDiGetClassDevs(
                                    NULL,
                                    NULL,
                                    NULL,
                                    DIGCF_ALLCLASSES | DIGCF_PRESENT);

ZeroMemory(&DeviceInfoData, sizeof(SP_DEVINFO_DATA));
DeviceInfoData.cbSize = sizeof(SP_DEVINFO_DATA);
DeviceIndex = 0;
    
while (SetupDiEnumDeviceInfo(
                             DeviceInfoSet,
                             DeviceIndex,
                             &DeviceInfoData)) {
    DeviceIndex++;

    if (!SetupDiGetDeviceProperty(
                                  DeviceInfoSet,
                                  &DeviceInfoData,
                                  &DEVPKEY_Device_Class,
                                  &PropType,
                                  (PBYTE)&DevGuid,
                                  sizeof(GUID),
                                  &Size,
                                  0) || PropType != DEVPROP_TYPE_GUID) {

        Error = GetLastError();

        if (Error == ERROR_NOT_FOUND) {
            \\
            \\ This device has an unknown device setup class.
            \\
            }
        }                 
    }

if (DeviceInfoSet) {
    SetupDiDestroyDeviceInfoList(DeviceInfoSet);
    }

注意

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

要求

要求	值
最低受支持的客户端	在 Microsoft Windows 2000 及更高版本的 Windows 中可用。
目标平台	DesktopFor universal、call CM_Get_Device_ID_ListFor universal、call CM_Get_Device_Interface_List
标头	setupapi.h (包括 SetupAPI.h)
Library	SetupAPI.lib
DLL	SetupAPI.dll
API 集	Windows 10版本 10.0.1439 (3 中引入的 ext-ms-win-setupapi-classinstallers-l1-1-2)