Функция 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, которая указывает:

Идентификатор (идентификатор) перечислителя Plug and Play (PnP) . Этот идентификатор может быть глобальным уникальным идентификатором (GUID) или символьным именем. Например, "PCI" можно использовать для указания значения PCI PnP. Другие примеры символьных имен для значений PnP включают "USB", "PCMCIA" и "SCSI".
Идентификаторэкземпляра устройства PnP. При указании идентификатора экземпляра устройства PnP DIGCF_DEVICEINTERFACE необходимо задать в параметре Flags.

Этот указатель необязателен и может быть null. Если значение перечисления не используется для выбора устройств, задайте перечислителя значение NULL

Дополнительные сведения о том, как задать значение перечислителя, см. в следующем разделе Примечания.

[in, optional] hwndParent

Дескриптор окна верхнего уровня, который будет использоваться для пользовательского интерфейса, связанного с установкой экземпляра устройства в наборе сведений об устройстве. Этот дескриптор является необязательным и может быть null.

[in] Flags

Переменная типа DWORD, указывающая параметры управления, которые фильтруют элементы сведений об устройстве, добавляемые в набор сведений об устройстве. Этот параметр может быть битовой или более нулевым или более следующих флагов. Дополнительные сведения об объединении этих флагов см. в следующем разделе примечания.

DIGCF_ALLCLASSES

Возвращает список установленных устройств для всех классов установки устройств или всех классов интерфейса устройства.

DIGCF_DEVICEINTERFACE

Возвращает устройства, поддерживающие интерфейсы устройств для указанных классов интерфейсов устройств. Этот флаг должен быть задан в параметре флагов , если параметр перечислителя указывает идентификаторэкземпляра устройства .

DIGCF_DEFAULT

Возвращает только устройство, связанное с системным интерфейсом устройства по умолчанию, если оно задано для указанных классов интерфейса устройства.

DIGCF_PRESENT

Возвращает только устройства, которые в настоящее время присутствуют в системе.

DIGCF_PROFILE

Возвращает только устройства, которые являются частью текущего профиля оборудования.

Возвращаемое значение

Если операция выполнена успешно, SetupDiGetClassDevs возвращает дескриптор набор сведений об устройстве, содержащий все установленные устройства, соответствующие заданным параметрам. Если операция завершается ошибкой, функция возвращает INVALID_HANDLE_VALUE. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.

Замечания

Вызывающий объект SetupDiGetClassDevs должен удалить возвращенный набор сведений об устройстве, если он больше не нужен путем вызова SetupDiDeskDeviceInfoList.

Вызовите 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 и используйте параметр перечислителя , чтобы указать идентификатор экземпляра устройства устройства. Чтобы включить все возможные устройства, задайте перечислителя значение 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 в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно в Microsoft Windows 2000 и более поздних версиях Windows.
целевая платформа	DesktopFor universal, вызов CM_Get_Device_ID_ListFor универсальный, вызов CM_Get_Device_Interface_List
заголовка	setupapi.h (include SetupAPI.h)
библиотеки	SetupAPI.lib
DLL	SetupAPI.dll
набор API	ext-ms-win-setupapi-classinstallers-l1-1-0 (представлено в Windows 8)