ObReferenceObjectByHandle 函数 (wdm.h)

  • 项目

ObReferenceObjectByHandle 例程在对象句柄上提供访问验证，如果可以授予访问权限，则返回指向对象正文的相应指针。

语法

NTSTATUS ObReferenceObjectByHandle(
  [in]            HANDLE                     Handle,
  [in]            ACCESS_MASK                DesiredAccess,
  [in, optional]  POBJECT_TYPE               ObjectType,
  [in]            KPROCESSOR_MODE            AccessMode,
  [out]           PVOID                      *Object,
  [out, optional] POBJECT_HANDLE_INFORMATION HandleInformation
);

参数

[in] Handle

指定对象的打开句柄。

[in] DesiredAccess

指定对 对象的请求访问类型。 此字段的解释取决于对象类型。 请勿使用任何通用访问权限。 有关详细信息，请参阅 ACCESS_MASK。

[in, optional] ObjectType

指向对象类型的指针。 ObjectType 可以是 *ExEventObjectType、 *ExSemaphoreObjectType、 *IoFileObjectType、 *PsProcessType、 *PsThreadType、 *SeTokenObjectType、 *TmEnlistmentObjectType、 *TmResourceManagerObjectType、 *TmTransactionManagerObjectType 或 *TmTransactionObjectType。

如果 ObjectType 不为 NULL，则操作系统将验证提供的对象类型是否与 Handle 指定的对象类型匹配。

[in] AccessMode

指定要用于访问检查的访问模式。 它必须是 UserMode 或 KernelMode。 驱动程序应始终为从用户地址空间接收的句柄指定 UserMode 。

[out] Object

指向变量的指针，该变量接收指向对象主体的指针。 下表包含指针类型。

ObjectType 参数 对象指针类型
*ExEventObjectType PKEVENT
*ExSemaphoreObjectType PKSEMAPHORE
*IoFileObjectType PFILE_OBJECT
*PsProcessType PEPROCESS 或 PKPROCESS
*PsThreadType PETHREAD 或 PKTHREAD
*SeTokenObjectType PACCESS_TOKEN
*TmEnlistmentObjectType PKENLISTMENT
*TmResourceManagerObjectType 二十一月二十日
*TmTransactionManagerObjectType PKTM
*TmTransactionObjectType PKTRANSACTION

指针类型引用的结构不透明，驱动程序无法访问结构成员。 由于结构不透明，PEPROCESS 等效于 PKPROCESS，PETHREAD 等效于 PKTHREAD。

[out, optional] HandleInformation

驱动程序将此设置为 NULL。

返回值

如果调用成功，ObReferenceObjectByHandle 将返回STATUS_SUCCESS。 可能的返回值包括以下错误代码：

返回代码 说明
STATUS_OBJECT_TYPE_MISMATCH ObjectType 参数为 Handle 参数标识的对象指定错误的对象类型。
STATUS_ACCESS_DENIED 无法向调用方授予对 对象的请求访问权限。
STATUS_INVALID_HANDLE Handle 参数不是有效的对象句柄。

注解

从对象表条目检索指向对象正文的指针，并通过 Object 参数返回给调用方。

如果 AccessMode 为 UserMode，则请求的访问权限与对象授予的访问权限进行比较。 如果 AccessMode 是 KernelMode，则句柄应源自内核地址空间。

从 Windows 7 开始，如果 AccessMode 为 KernelMode 并且从用户地址空间接收句柄， 驱动程序验证程序 会发出 bug 检查 C4，子代码 F6。

如果调用成功，则指向对象正文的指针将返回到调用方，并且指针引用计数递增。 递增此计数可防止在引用指针时删除对象。 调用方必须使用 ObDereferenceObject 立即递减引用计数，只要使用 对象。

要求

要求 值
最低受支持的客户端 从 Windows 2000 开始可用。
目标平台 通用
标头 wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 符合性规则 HwStorPortProhibitedDDI (storport) 、 IrqlObPassive (wdm) 、 TargetRelationNeedsRef (wdm)

另请参阅

ACCESS_MASK

ObDereferenceObject

ObReferenceObject

ObReferenceObjectByPointer