IoRegisterDeviceInterface 函数 (wdm.h)

  • 项目

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，它是使用设备接口实例作为按需创建的软件设备的占位符的总线驱动程序。 打开接口的实例时，I/O 管理器会将实例的引用字符串传递给驱动程序。 字符串成为接口实例名称的一部分， (作为追加的路径组件) 。 然后，驱动程序可以使用引用字符串来区分单个设备的同一类的两个接口实例。

在 Microsoft Windows 98/Me 系统上， ReferenceString 值不能超过 MAX_PATH 个字符。 Windows 2000 及更高版本的 Windows 没有长度限制。

[out] SymbolicLinkName

指向调用方分配的 Unicode 字符串结构的指针。 如果此例程成功，它将初始化 Unicode 字符串，并将包含内核模式路径的字符串缓冲区分配给指定设备接口类的实例的符号链接。

调用方必须将 SymbolicLinkName 视为不透明，并且不得将其反汇编。

调用方负责在不再需要时使用 RtlFreeUnicodeString 释放 SymbolicLinkName。

返回值

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

返回代码 说明
STATUS_INVALID_DEVICE_REQUEST
 参数无效。 可能包括 PhysicalDeviceObject 未指向有效的 PDO，或者 ReferenceString 字符串包含无效字符。

注解

IoRegisterDeviceInterface 注册设备接口类（如果之前尚未注册），并创建接口类的新实例。 驱动程序可以为给定设备多次调用此例程，以注册多个接口类并创建类的实例。 函数或筛选器驱动程序通常在其 AddDevice 例程中注册设备接口。 例如，容错卷驱动程序可能会为特定卷注册容错卷接口的实例和卷接口的实例。

如果以前尚未注册设备接口类，则 I/O 管理器会为其创建注册表项，以及在密钥下创建特定于实例的持久存储。 驱动程序可以使用 IoOpenDeviceInterfaceRegistryKey 访问此永久性存储。

驱动程序注册接口实例一次，然后调用 IoSetDeviceInterfaceState 以启用和禁用接口。

注册的接口在操作系统重启后仍然存在。 如果指定的接口已注册，则 I/O 管理器在 SymbolicLinkName 中传递其名称，并返回STATUS_OBJECT_NAME_EXISTS的信息性成功状态。

大多数驱动程序对设备接口实例使用 NULL 引用字符串。 如果驱动程序使用非 NULL 引用字符串，则必须执行其他工作，包括可能管理自己的命名空间和安全性。 公开设备接口的筛选器驱动程序必须使用 NULLReferenceString ，以避免与设备堆栈中的其他驱动程序冲突。

不再需要此例程的调用方即可删除设备接口的注册。 如有必要，可以从用户模式中删除设备接口注册。

IoRegisterDeviceInterface 的调用方必须在系统线程上下文中的 IRQL = PASSIVE_LEVEL 运行。

要求

要求 值
最低受支持的客户端 从 Windows 2000 开始可用。
目标平台 通用
标头 wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (请参阅“备注”部分)
DDI 符合性规则 HwStorPortProhibitedDDI (storport) ， IrqlIoPassive3 (wdm ) ，PowerIrpDDis (wdm)

另请参阅

IoGetDeviceInterfaces

IoOpenDeviceInterfaceRegistryKey

IoSetDeviceInterfaceState

RtlFreeUnicodeString