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

Статья
08/08/2023

Подпрограмма 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

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

Flag	Значение
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 .

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

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

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

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

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

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 2000.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")
Правила соответствия DDI	HwStorPortProhibitedDIs(storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)