IoRegisterDeviceInterface例程

IoRegisterDeviceInterface例程

IoRegisterDeviceInterface例程注册设备接口类(如果以前未注册), 并创建接口类的新实例, 驱动程序随后可以启用应用程序或其他系统组件。

语法

NTSTATUS IoRegisterDeviceInterface(
  _In_           PDEVICE_OBJECT  PhysicalDeviceObject,
  _In_     const GUID            *InterfaceClassGuid,
  _In_opt_       PUNICODE_STRING ReferenceString,
  _Out_          PUNICODE_STRING SymbolicLinkName
);

参数

• PhysicalDeviceObject [in]
  　　指向设备 PDO 的指针。
• InterfaceClassGuid [in]
  　　指向类 GUID 的指针, 标识注册的功能 (设备接口类)。
• ReferenceString [in, 可选]
  　　(可选) 指向 UNICODE_STRING。该字符串不能包含任何路径分隔符字符 (“/” 或 “\”)。函数驱动程序通常为该参数指定NULL 。筛选器驱动程序必须指定NULL.
  　　引用字符串仅由少数总线驱动程序使用, 例如swenum, 它是一种总线驱动程序, 它使用设备接口实例作为按需创建的软件设备的占位符。当接口的实例打开时, i/o 管理器将实例的引用字符串传递给驱动程序。该字符串将成为接口实例名称的一部分 (作为附加的路径组件)。然后, 驱动程序可以使用引用字符串对单个设备的同一类的两个接口实例进行区分。
  　　在 Microsoft Windows 98/Me 系统上, ReferenceString值不能长于 MAX_PATH 字符。windows 2000 和更高版本的窗口没有长度限制。
• SymbolicLinkName [out]
  　　指向调用方分配的 Unicode 字符串结构的指针。如果此例程成功, 它将初始化 Unicode 字符串, 并将包含内核模式路径的字符串缓冲区分配给指定设备接口类的实例的符号链接。
  　　调用方必须将SymbolicLinkName视为不透明, 并且不能对其进行反汇编。
  　　调用方负责在不再需要 RtlFreeUnicodeString 时释放SymbolicLinkName 。

返回值

IoRegisterDeviceInterface 如果调用成功, 则返回 STATUS_SUCCESS。可能的错误返回值包括以下内容.

返回代码	描述
STATUS_INVALID_DEVICE_REQUEST	参数无效。可能包括PhysicalDeviceObject没有指向有效的 PDO, 或者ReferenceString字符串包含无效字符。

摘要

　　IoRegisterDeviceInterface 注册设备接口类 (如果它以前未注册), 并创建接口类的新实例。对于给定设备, 驱动程序可以多次调用此例程来注册多个接口类并创建类的实例。函数或筛选器驱动程序通常在其 添加 例程中注册设备接口。例如, 容错卷驱动程序可能会注册容错卷接口的实例和特定卷的卷接口实例.
　　如果以前未注册设备接口类, 则 i/o 管理器将为其创建一个注册表项, 并在该键下使用实例特定的持久存储。驱动程序可以使用 IoOpenDeviceInterfaceRegistryKey 访问此持久性存储.
　　驱动程序注册一个接口实例一次, 然后调用 IoSetDeviceInterfaceState 以启用和禁用该接口。
　　已注册的接口在操作系统重新启动时保持不变。如果指定的接口已注册, 则 i/o 管理器在SymbolicLinkName中传递其名称, 并返回信息成功状态 STATUS_OBJECT_NAME_EXISTS。
　　大多数驱动程序对设备接口实例使用NULL引用字符串。如果驱动程序使用非NULL引用字符串, 则它必须执行其他工作, 包括可能管理其自己的命名空间和安全性。公开设备接口的筛选器驱动程序必须使用NULL ReferenceString来避免与设备堆栈中的其他驱动程序发生冲突。
　　此例程的调用方不需要在不再需要设备接口时移除注册。如果需要, 可以从用户模式中删除设备接口注册。
　　IoRegisterDeviceInterface的调用方必须在系统线程的上下文中运行 IRQL = PASSIVE_LEVEL。

要求

Target platform	Universal
Version	Available starting with Windows 2000.
Header	Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (see Remarks section)
DDI compliance rules	IrqlIoPassive3, PowerIrpDDis, HwStorPortProhibitedDDIs

另请参阅

IoGetDeviceInterfaces
IoOpenDeviceInterfaceRegistryKey
IoSetDeviceInterfaceState
RtlFreeUnicodeString