IoGetDeviceObjectPointer 函数 (wdm.h)

项目
08/08/2023

IoGetDeviceObjectPointer 例程返回指向命名设备对象的堆栈中顶部对象的指针，以及指向相应文件对象的指针（如果可以授予对对象的请求访问权限）。

语法

NTSTATUS IoGetDeviceObjectPointer(
  [in]  PUNICODE_STRING ObjectName,
  [in]  ACCESS_MASK     DesiredAccess,
  [out] PFILE_OBJECT    *FileObject,
  [out] PDEVICE_OBJECT  *DeviceObject
);

参数

[in] ObjectName

指向缓冲区的指针，该缓冲区包含作为设备对象名称的 Unicode 字符串。

[in] DesiredAccess

指定表示所需访问权限的ACCESS_MASK 值。通常 ，DesiredAccess FILE_READ_DATA。很少指定FILE_WRITE_DATA或FILE_ALL_ACCESS访问权限。

[out] FileObject

指向表示用户模式代码的相应设备对象的文件对象的指针（如果调用成功）。

[out] DeviceObject

指向表示命名逻辑、虚拟或物理设备的设备对象的指针（如果调用成功）。

返回值

如果成功，IoGetDeviceObjectPointer 将返回STATUS_SUCCESS。可能的错误返回值包括以下状态代码：

STATUS_OBJECT_TYPE_MISMATCH

STATUS_INVALID_PARAMETER

STATUS_PRIVILEGE_NOT_HELD

STATUS_INSUFFICIENT_RESOURCES

STATUS_OBJECT_NAME_INVALID

注解

IoGetDeviceObjectPointer 在调用方与下一个较低级别的驱动程序之间建立“连接”。成功的调用方可以使用返回的设备对象指针来初始化其自己的设备对象。它还可用作 IoAttachDeviceToDeviceStack、 IoCallDriver 以及为较低级驱动程序创建 IRP 的任何例程的参数。返回的指针是 IoCallDriver 的必需参数。

此例程还返回指向相应文件对象的指针。卸载时，驱动程序可以取消引用文件对象，作为间接取消引用设备对象的一种方式。为此，驱动程序从其 Unload 例程调用 ObDereferenceObject ，传递 IoGetDeviceObjectPointer 返回的文件对象指针。未能在驱动程序的 Unload 例程中取消引用设备对象会阻止卸载下一个较低级别的驱动程序。但是，在卸载进程之前关闭文件对象的驱动程序必须在取消引用文件对象之前对设备对象执行额外的引用。否则，取消引用文件对象可能会导致设备对象的过早删除。

若要获取指向文件系统驱动程序堆栈中最高级别驱动程序的指针，驱动程序必须确保装载文件系统;否则，此例程将遍历存储设备堆栈。若要确保文件系统装载在存储设备上，驱动程序必须在 DesiredAccess 参数中指定适当的访问掩码，例如FILE_READ_DATA或FILE_WRITE_ATTRIBUTES。指定FILE_READ_ATTRIBUTES不会导致装载文件系统。

在任何较高级别的驱动程序通过成功调用此例程将自身链接到另一个驱动程序之后，较高级别的驱动程序必须将其设备对象中的 StackSize 字段设置为下一个较低级别驱动程序的设备对象加上一个的 StackSize 字段。

IoGetDeviceObjectPointer 的调用方必须在 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) 、 IrqlIoPassive5 (wdm) 、 PowerIrpDDis (wdm)