Функция 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.
Дополнительные сведения о том, как задать значение перечислителя , см. в следующем разделе Примечаний .
[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 класса интерфейса устройства. Функция добавляет в набор сведений об устройстве элемент сведений об устройстве, представляющий такое устройство, а затем добавляет интерфейс устройства указанного класса в список интерфейсов устройств для этого элемента сведений об устройстве.
- Чтобы вернуть только устройство, поддерживающее интерфейс по умолчанию системы, если он задан, для указанного класса интерфейса устройства установите флаг 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).
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) |
См. также раздел
Идентификаторы экземпляров устройств
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по