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

Статья
07/16/2024

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

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

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

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

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

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

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

Замечания

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

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

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

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

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

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

Вызывающие IoRegisterDeviceInterface должны выполняться в 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), IrqlIoPassive3(wdm), PowerIrpDDis(wdm)

См. также

IoGetDeviceInterfaces

IoOpenDeviceInterfaceRegistryKey

IoSetDeviceInterfaceState

RtlFreeUnicodeString

Поделиться через