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) |