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

Статья
03/15/2023

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

Идентификатор перечислителя 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

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

DIGCF_DEFAULT

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

DIGCF_PRESENT

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

DIGCF_PROFILE

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

[in, optional] DeviceInfoSet

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

[in, optional] MachineName

Указатель на константную строку, содержащую имя удаленного компьютера, на котором находятся устройства. Значение NULL для MachineName указывает, что устройство установлено на локальном компьютере.

Внимание!

Использование этой функции для доступа к удаленным компьютерам не поддерживается начиная с Windows 8 и Windows Server 2012, так как эта функция была удалена.

Reserved

Зарезервировано для внутреннего использования. Для этого параметра необходимо задать значение NULL.

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

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

Если DeviceInfoSet имеет значение NULL, 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 класса интерфейса устройства. Функция добавляет в набор сведений об устройстве элемент сведений об устройстве, представляющий такое устройство, а затем добавляет интерфейс устройства указанного класса в список интерфейсов устройств для этого элемента сведений об устройстве.

Кроме того, можно использовать следующие параметры фильтрации, чтобы указать, возвращает ли SetupDiGetClassDevsEx только устройства, поддерживающие системный интерфейс по умолчанию для классов интерфейсов устройств:

Чтобы вернуть только устройство, поддерживающее интерфейс по умолчанию системы, если он задан, для указанного класса интерфейса устройства установите флаг DIGCF_DEVICEINTERFACE, установите флаг DIGCF_DEFAULT и используйте ClassGuid для предоставления GUID класса интерфейса устройства. Функция добавляет в набор сведений об устройстве элемент сведений об устройстве, представляющий такое устройство, а затем добавляет системный интерфейс по умолчанию в список интерфейсов устройств для этого элемента сведений об устройстве.
Чтобы вернуть устройство, поддерживающее системный интерфейс по умолчанию для неопределенного класса интерфейса устройства, установите флаг DIGCF_DEVICEINTERFACE, установите флаг DIGCF_ALLCLASSES, установите флаг DIGCF_DEFAULT и задайте для ClassGuidзначение NULL. Функция добавляет в набор сведений об устройстве элемент сведений об устройстве, представляющий такое устройство, а затем добавляет системный интерфейс по умолчанию в список интерфейсов устройств для этого элемента сведений об устройстве.

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

Чтобы вернуть только те устройства, которые присутствуют в системе, установите флаг DIGCF_PRESENT.
Чтобы вернуть только устройства, которые являются частью текущего профиля оборудования, установите флаг DIGCF_PROFILE.
Чтобы вернуть только определенное устройство, установите флаг DIGCF_DEVICEINTERFACE и используйте параметр Перечислитель , чтобы указать идентификатор экземпляра устройства. Чтобы включить все возможные устройства, задайте для перечислителязначение NULL.

Получение устройств в классе настройки устройства, поддерживающем класс интерфейса устройства

Установщик может использовать SetupDiGetClassDevsEx для получения списка устройств определенного класса установки устройств, поддерживающих интерфейс устройства указанного класса интерфейса устройства. Например, чтобы получить список всех устройств на локальном компьютере, которые поддерживают интерфейс устройства в классе интерфейса "подключенное устройство" и являются членами класса настройки устройства Volume, установщик должен выполнить следующие операции:

Вызовите SetupDiCreateDeviceInfoList , чтобы создать пустой набор сведений об устройстве для класса настройки устройства Volume. Присвойте ClassGuid указатель на GUID класса для класса настройки устройства Volume и задайте hwndParent соответствующим образом. В ответ на такой вызов функция вернет дескриптор типа HDEVINFO в набор сведений об устройстве.
Вызовите SetupDiGetClassDevsEx со следующими параметрами:
- Присвойте ClassGuid указатель на GUID класса класса "подключенное устройство" класса интерфейса устройства.
- Установите флажки DIGCF_DEVICEINTERFACE.
- Задайте для DeviceInfoSet дескриптор HDEVINFO, полученный на шаге (1).
- Задайте hwndParent соответствующим образом, а для остальных параметров задайте значение NULL.

В операции этого типа SetupDiGetClassDevsEx возвращает устройство, если класс настройки устройства совпадает с предоставленным набором сведений об устройстве и если устройство поддерживает интерфейс устройства, класс которого совпадает с указанным классом интерфейса устройства.

Примечание

Заголовок setupapi.h определяет SetupDiGetClassDevsEx в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Доступно в Microsoft Windows 2000 и более поздних версиях Windows.
Целевая платформа	Персональный компьютер
Верхняя часть	setupapi.h (включая Setupapi.h)
Библиотека	Setupapi.lib