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

Статья
03/15/2023

Функция setupDiGetClassDevsEx возвращает дескриптор набор сведений об устройстве, содержащий запрошенные элементы сведений об устройстве для локального или удаленного компьютера.

Синтаксис

WINSETUPAPI HDEVINFO SetupDiGetClassDevsExW(
  [in, optional] const GUID *ClassGuid,
  [in, optional] PCWSTR     Enumerator,
  [in, optional] HWND       hwndParent,
  [in]           DWORD      Flags,
  [in, optional] HDEVINFO   DeviceInfoSet,
  [in, optional] PCWSTR     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

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

DIGCF_DEFAULT

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

DIGCF_PRESENT

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

DIGCF_PROFILE

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

[in, optional] DeviceInfoSet

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

[in, optional] MachineName

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

Осторожность

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

Reserved

Зарезервировано для внутреннего использования. Этот параметр должен иметь значение NULL.

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

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

Замечания

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

Если DeviceInfoSetNULL, 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 (include Setupapi.h)
библиотеки	Setupapi.lib