Функция IoGetDeviceInterfaces (wdm.h)

Статья
02/07/2025

Подпрограмма IoGetDeviceInterfaces возвращает список экземпляров интерфейса устройства определенного класса интерфейса устройства (например, всех устройств в системе, поддерживающих интерфейс HID).

Синтаксис

NTSTATUS IoGetDeviceInterfaces(
  [in]           const GUID     *InterfaceClassGuid,
  [in, optional] PDEVICE_OBJECT PhysicalDeviceObject,
  [in]           ULONG          Flags,
  [out]          PZZWSTR        *SymbolicLinkList
);

Параметры

[in] InterfaceClassGuid

Указатель на GUID класса, указывающий класс интерфейса устройства. Идентификаторы GUID для класса должны находиться в файле заголовка для конкретного устройства.

[in, optional] PhysicalDeviceObject

Указатель на необязательный PDO, который сужает поиск только к экземплярам интерфейса устройства, представленным PDO.

[in] Flags

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

Флаг	Значение
DEVICE_INTERFACE_INCLUDE_NONACTIVE	Возвращает отключенные экземпляры интерфейса устройства в дополнение к включенным экземплярам интерфейса.

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

Драйвер обычно задает флаг DEVICE_INTERFACE_INCLUDE_NONACTIVE, чтобы найти отключенные экземпляры интерфейса, которые драйвер должен включить. Например, установщик классов для устройства, возможно, был направлен INF-файлом для регистрации одного или нескольких экземпляров интерфейса для устройства. Экземпляры интерфейса будут зарегистрированы, но недоступны для использования, пока они не включены драйвером (с помощью IoSetDeviceInterfaceState). Чтобы сузить список экземпляров интерфейса, возвращенных только тем, которые предоставляются заданным устройством, драйвер может указать PhysicalDeviceObject.

[out] SymbolicLinkList

Указатель на широкий символьный указатель, на который подпрограмма, если она успешно, записывает базовый адрес буфера, содержащий список строк Юникода. Эти строки представляют собой символьные имена ссылок, которые определяют экземпляры интерфейса устройства, соответствующие критериям поиска. Каждая строка Юникода в списке завершается null; Конец всего списка помечается дополнительным символом NULL. Подпрограмма выделяет буфер для этих строк из страницной системной памяти. Вызывающий объект отвечает за освобождение буфера (вызывая процедуру ExFreePool), когда она больше не нужна.

Если экземпляры интерфейса устройства не соответствуют критериям поиска, эта подпрограмма возвращает STATUS_SUCCESS, а строка содержит один символ NULL.

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

IoGetDeviceInterfaces возвращает STATUS_SUCCESS, если вызов выполнен успешно. Возможные значения возвращаемых ошибок включают следующие значения.

Возвращаемый код	Описание
STATUS_INVALID_DEVICE_REQUEST	Возможно, указывает, что PhysicalDeviceObject не был допустимым указателем PDO.

Замечания

IoGetDeviceInterfaces возвращает список экземпляров интерфейса устройства, соответствующих критериям поиска. Компонент режима ядра обычно вызывает эту подпрограмму, чтобы получить список всех включенных экземпляров интерфейса устройства определенного класса интерфейса устройства. Такой компонент может получить указатель на файловый объект или объект устройства для интерфейса, вызвав подпрограмму IoGetDeviceObjectPointer или ZwCreateFile. Указатель объекта устройства, возвращаемый IoGetDeviceObjectPointer указывает на верхнюю часть стека устройств для устройства и может использоваться в вызовах к подпрограмме IoCallDriver.

Если имеется интерфейс по умолчанию для запрошенного класса интерфейса устройства, он отображается сначала в СимвольныеlinkList. Интерфейсы по умолчанию можно задать в пользовательском режиме, но не в режиме ядра.

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

Символьные ссылки для экземпляров интерфейса устройства можно использовать в системной загрузке.

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

Вызывающие IoGetDeviceInterfaces должны выполняться в IRQL = PASSIVE_LEVEL в контексте системного потока.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно начиная с Windows 2000.
целевая платформа	Всеобщий
заголовка	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")
правил соответствия DDI	HwStorPortProhibitedDDIs(storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)