Поделиться через

Функция SetupDiGetClassDevsW (setupapi.h)

  • Статья

Функция 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 PnP можно использовать "PCI". Другие примеры символьных имен для значений PnP включают "USB", "PCMCIA" и "SCSI".
  • Идентификатор экземпляра устройства PnP. При указании идентификатора экземпляра устройства PnP DIGCF_DEVICEINTERFACE необходимо задать в параметре Flags.
Этот указатель является необязательным и может иметь значение NULL. Если значение перечисления не используется для выбора устройств, задайте для перечислителя значение NULL.

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

[in, optional] hwndParent

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

[in] Flags

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

DIGCF_ALLCLASSES

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

DIGCF_DEVICEINTERFACE

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

DIGCF_DEFAULT

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

DIGCF_PRESENT

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

DIGCF_PROFILE

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

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

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

Комментарии

Вызывающий объект SetupDiGetClassDevs должен удалить возвращенный набор сведений об устройстве, если он больше не нужен, вызвав SetupDiDeкистрацияDeviceInfoList.

Вызовите 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, 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)

См. также раздел

Набор сведений об устройстве

Идентификаторы экземпляров устройств

SetupDiCreateDeviceInfoList

SetupDiDeкистраяDeviceInfoList

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevsEx