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

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

[out] Object

指向接收指向对象正文的指针的变量的指针。 下表包含指针类型。

ObjectType 参数 对象指针类型
*ExEventObjectType PKEVENT
*ExSemaphoreObjectType PKSEMAPHORE
*IoFileObjectType PFILE_OBJECT
*PsProcessType PEPROCESS 或 PKPROCESS
*PsThreadType PETHREAD 或 PKTHREAD
*SeTokenObjectType PACCESS_TOKEN
*TmEnlistmentObjectType PKENLISTMENT
*TmResourceManagerObjectType 2013 年 1 月 3 日
*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 参数返回到调用方。

如果 AccessModeUserMode,则请求的访问权限与对象的授予访问权限进行比较。 如果 AccessModeKernelMode,则句柄应源自内核地址空间。

从 Windows 7 开始,如果 AccessModeKernelMode ,并且从用户地址空间接收句柄, 驱动程序验证程序 会发出 bugcheck 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