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

Статья
08/08/2023

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

Синтаксис

NTSTATUS IoRegisterDeviceInterface(
  [in]           PDEVICE_OBJECT  PhysicalDeviceObject,
  [in]           const GUID      *InterfaceClassGuid,
  [in, optional] PUNICODE_STRING ReferenceString,
  [out]          PUNICODE_STRING SymbolicLinkName
);

Параметры

[in] PhysicalDeviceObject

Указатель на PDO для устройства.

[in] InterfaceClassGuid

Указатель на GUID класса, который идентифицирует регистримую функциональность (класс интерфейса устройства).

[in, optional] ReferenceString

При необходимости указывает на UNICODE_STRING. Строка не должна содержать символы-разделители пути ("/" или "\"). Драйверы функций обычно указывают значение NULL для этого параметра. Драйверы фильтров должны указывать значение NULL.

Ссылочные строки используются только несколькими драйверами автобуса, например swenum, который является драйвером автобуса, который использует экземпляры интерфейса устройства в качестве заполнителей для программных устройств, созданных по требованию. При открытии экземпляра интерфейса диспетчер ввода-вывода передает эталонную строку экземпляра драйверу. Строка становится частью имени экземпляра интерфейса (как добавленный компонент пути). Затем драйвер может использовать ссылочную строку для различения двух экземпляров интерфейса одного класса для одного устройства.

В системах Microsoft Windows 98/Me значение ReferenceString не может превышать MAX_PATH символов. В Windows 2000 и более поздних версиях Windows не существует ограничений по длине.

[out] SymbolicLinkName

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

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

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

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

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

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

IoRegisterDeviceInterface регистрирует класс интерфейса устройства, если он еще не был зарегистрирован, и создает новый экземпляр класса интерфейса. Драйвер может вызывать эту подпрограмму несколько раз для данного устройства, чтобы зарегистрировать несколько классов интерфейса и создать экземпляры классов. Драйвер функции или фильтра обычно регистрирует интерфейсы устройств в своей процедуре AddDevice . Например, отказоустойчивый драйвер тома может зарегистрировать экземпляр отказоустойчивого интерфейса тома и экземпляр интерфейса тома для определенного тома.

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

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

Зарегистрированные интерфейсы сохраняются при перезагрузках операционной системы. Если указанный интерфейс уже зарегистрирован, диспетчер ввода-вывода передает свое имя в SymbolicLinkName и возвращает информационное состояние успешного выполнения STATUS_OBJECT_NAME_EXISTS.

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

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

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

Требования

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

См. также раздел

IoGetDeviceInterfaces

IoOpenDeviceInterfaceRegistryKey

IoSetDeviceInterfaceState

RtlFreeUnicodeString