SetupDiGetClassDevsW 函数（setupapi.h）

项目
11/20/2024

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

语法

WINSETUPAPI HDEVINFO SetupDiGetClassDevsW(
  [in, optional] const GUID *ClassGuid,
  [in, optional] PCWSTR     Enumerator,
  [in, optional] HWND       hwndParent,
  [in]           DWORD      Flags
);

参数

[in, optional] ClassGuid

指向设备设置类的 GUID 的指针或设备接口类。此指针是可选的，可以 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

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

DIGCF_DEFAULT

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

DIGCF_PRESENT

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

DIGCF_PROFILE

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

返回值

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

言论

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

调用 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）
库	SetupAPI.lib
DLL	SetupAPI.dll
API 集	ext-ms-win-setupapi-classinstallers-l1-1-0（在 Windows 8 中引入）

另请参阅

设备信息集

设备实例 ID

SetupDiCreateDeviceInfoList

SetupDiDestroyDeviceInfoList

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevsEx

通过

SetupDiGetClassDevsW 函数（setupapi.h）

语法

参数

DIGCF_ALLCLASSES

DIGCF_DEVICEINTERFACE

DIGCF_DEFAULT

DIGCF_PRESENT

DIGCF_PROFILE

返回值

言论

设备安装程序类控制选项

设备接口类控制选项

例子

要求

另请参阅

反馈

其他资源

通过

SetupDiGetClassDevsW 函数 （setupapi.h）

语法

参数

DIGCF_ALLCLASSES

DIGCF_DEVICEINTERFACE

DIGCF_DEFAULT

DIGCF_PRESENT

DIGCF_PROFILE

返回值

言论

设备安装程序类控制选项

设备接口类控制选项

例子

要求

另请参阅

反馈

其他资源

SetupDiGetClassDevsW 函数（setupapi.h）