ObOpenObjectByPointer 函数 (ntifs.h)

项目
03/05/2024

ObOpenObjectByPointer 函数打开指针引用的对象，并返回该对象的句柄。

语法

NTSTATUS ObOpenObjectByPointer(
  [in]           PVOID           Object,
  [in]           ULONG           HandleAttributes,
  [in, optional] PACCESS_STATE   PassedAccessState,
  [in]           ACCESS_MASK     DesiredAccess,
  [in, optional] POBJECT_TYPE    ObjectType,
  [in]           KPROCESSOR_MODE AccessMode,
  [out]          PHANDLE         Handle
);

参数

[in] Object

指向要打开的对象的指针。

[in] HandleAttributes

指定对象句柄所需属性的标志的位掩码。如果调用方未在系统进程上下文中运行，则这些标志必须包含OBJ_KERNEL_HANDLE。此参数是可选的，可以为零。否则，它是以下一个或多个值的 OR 组合。

标志	含义
OBJ_EXCLUSIVE	将打开对象以独占访问。如果设置了此标志，并且对 ObOpenObjectByPointer 的调用成功，则无法在句柄关闭之前共享该对象，并且无法再次打开该对象。此标志与 OBJ_INHERIT 标志不兼容。此标志对文件对象无效。
OBJ_FORCE_ACCESS_CHECK	即使对象是在内核模式下打开的，也要对对象强制实施所有访问检查。如果指定了此标志，则忽略 AccessMode 参数的值。
OBJ_INHERIT	句柄可由当前进程的子进程继承。此标志与 OBJ_EXCLUSIVE 标志不兼容。
OBJ_KERNEL_HANDLE	只能在内核模式下访问句柄。如果调用方未在系统进程上下文中运行，则必须指定此标志。

[in, optional] PassedAccessState

指向 ACCESS_STATE 结构的指针，该结构包含对象的主题上下文、授予的访问权限类型和剩余的所需访问类型。此参数是可选的，可以为 NULL。在创建调度例程中，可以在 IrpSp-Parameters.Create.SecurityContext-AccessState>> 中找到此指针，其中 IrpSp 是指向调用方在 IRP 中自己的堆栈位置的指针。 (有关详细信息，请参阅 IRP_MJ_CREATE.)

[in] DesiredAccess

ACCESS_MASK 指定对对象的所需访问权限的值。此参数是可选的，可以为零。

[in, optional] ObjectType

指向对象类型的指针。如果 AccessMode 的值为 KernelMode，则此参数是可选的，可以为 NULL。否则，它必须是 *ExEventObjectType、*ExSemaphoreObjectType、*IoFileObjectType、*PsThreadType、*SeTokenObjectType 或 *CmKeyObjectType。

注意

使用 Windows XP 支持 使用 SeTokenObjectType 对象类型，并且支持使用 Windows 7 盯着 CmKeyObjectType 对象类型。

[in] AccessMode

要用于访问检查的访问模式。此参数是必需的，必须为 UserMode 或 KernelMode：

如果 AccessMode 为 KernelMode，则系统始终允许所请求的访问，而不管之前设置驱动程序 (的任何受限访问，例如，在之前调用POB_PRE_OPERATION_CALLBACK回调) 中限制访问。
如果 AccessMode 为 UserMode，则请求的访问权限与对象授予的访问权限进行比较。

[out] Handle

指向调用方分配的变量的指针，该变量接收对象的句柄。

返回值

ObOpenObjectByPointer 返回STATUS_SUCCESS或相应的 NTSTATUS 值，如以下值之一：

返回代码	说明
STATUS_ACCESS_DENIED	调用方没有打开对象句柄所需的访问权限。这是错误代码。
STATUS_INSUFFICIENT_RESOURCES	ObOpenObjectByPointer 遇到池分配失败。这是错误代码。
STATUS_INVALID_PARAMETER	在 HandleAttributes 参数中指定了无效的标志值。这是错误代码。
STATUS_OBJECT_TYPE_MISMATCH	Object 参数指向的对象不属于 ObjectType 参数中指定的类型。这是错误代码。
STATUS_PRIVILEGE_NOT_HELD	调用方没有创建具有 DesiredAccess 参数中指定的访问权限的句柄所需的权限。这是错误代码。
STATUS_QUOTA_EXCEEDED	调用方在内存配额不足以分配对象句柄的进程上下文中运行。这是错误代码。
STATUS_UNSUCCESSFUL	无法创建对象句柄。这是错误代码。

注解

如果 Object 参数指向文件对象 (即FILE_OBJECT结构) ，则只能在为文件对象创建至少一个句柄之后调用 ObOpenObjectByPointer 。调用方可以检查 Object 参数指向的FILE_OBJECT结构的 Flags 成员。如果设置了FO_HANDLE_CREATED标志，这意味着已为文件对象创建了一个或多个句柄，因此可以安全地调用 ObOpenObjectByPointer。

通过调用 ObOpenObjectByPointer 获取的任何句柄最终都必须通过调用 ZwClose 释放。

在系统进程以外的进程上下文中运行的驱动程序例程必须在 HandleAttributes 参数中设置OBJ_KERNEL_HANDLE标志。这会将 ObOpenObjectByPointer 返回的句柄的使用限制为在内核模式下运行的进程。否则，运行驱动程序的上下文中的进程可以访问句柄。