ObReferenceObjectByHandleWithTag 函数 (wdm.h)

ObReferenceObjectByHandleWithTag 例程递增由指定句柄标识的对象引用计数,并将四字节标记值写入对象以支持对象引用跟踪

语法

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

参数

[in] Handle

指定对象的打开句柄。

[in] DesiredAccess

指定对调用方请求的对象的访问类型。 此参数是 ACCESS_MASK类型的位掩码。 此字段的解释取决于对象类型。 请勿使用任何通用访问权限。

[in, optional] ObjectType

指向指定对象类型的不透明结构的指针。 此参数指向 OBJECT_TYPE 结构。 将 ObjectType 设置为 NULL 或以下指针值之一,这些值在 Wdm.h 头文件中声明:*ExEventObjectType, *ExSemaphoreObjectType*IoFileObjectType、*PsProcessType、*PsThreadType、*SeTokenObjectType、*TmEnlistmentObjectType、*TmResourceManagerObjectType、*TmTransactionManagerObjectType 或 *TmTransactionObjectType。 如果 ObjectType 不是 NULL,则例程将验证所提供的对象类型是否与 Handle 参数所指定对象的对象类型匹配。

[in] AccessMode

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

[in] Tag

指定四字节自定义标记值。 有关更多信息,请参见下面的“备注”部分。

[out] Object

指向例程将指针写入对象的变量的指针的指针的指针。 下表列出了 对象指针类型 ,这些类型由可能的 ObjectType 参数值指定。

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

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

[out, optional] HandleInformation

驱动程序将此参数设置为 NULL

返回值

如果调用成功,ObReferenceObjectByHandleWithTag 将返回STATUS_SUCCESS。 可能的错误返回值包括:

返回代码 说明
STATUS_OBJECT_TYPE_MISMATCH ObjectType 参数为 Handle 参数标识的对象指定错误的对象类型。
STATUS_ACCESS_DENIED 调用方没有对象所需的访问权限。
STATUS_INVALID_HANDLE 指定的句柄无效。

备注

此例程访问指定对象句柄的验证。 如果可以授予访问权限,则例程会递增对象引用计数,并提供指向调用方的对象指针。 此增量可防止在调用方使用该对象时删除该对象。 当不再需要对象时,调用方应通过调用 ObDereferenceObjectWithTagObDereferenceObjectDeferDeleteWithTag 例程来递减引用计数。

有关对象引用的详细信息,请参阅 对象的生命周期

ObReferenceObjectByHandleWithTag 不会关闭或使 Handle 参数指定的对象句柄无效。 不再需要句柄时,调用方可以通过调用 ZwClose 例程来关闭句柄。

如果 AccessMode 参数值为 KernelMode,则始终允许请求的访问。 如果 AccessModeUserMode,则请求的访问权限与调用方对对象的访问权限进行比较。 只有最高级别驱动程序可以安全地指定 AccessMode 参数的 UserMode 值。

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

ObReferenceObjectByHandle 例程类似于 ObReferenceObjectByHandleWithTag,只是它不允许调用方将自定义标记写入对象。 在 Windows 7 及更高版本的 Windows 中, ObReferenceObjectByHandle 始终向对象写入默认标记值 ('tlfD') 。 对 ObReferenceObjectByHandle 的调用与调用 ObReferenceObjectByHandleWithTag 的效果相同,该 调用指定 Tag = 'tlfD'。

若要在 Windows 调试工具中查看对象引用跟踪,请使用 !obtrace 内核模式调试器扩展。 如果启用了对象引用跟踪,则会增强 !obtrace 扩展以显示对象引用标记。 默认情况下,对象引用跟踪处于关闭状态。 使用 全局标志编辑器 (Gflags) 启用对象引用跟踪。 有关详细信息,请参阅 带有标记的对象引用跟踪

要求

   
最低受支持的客户端 在 Windows 7 及更高版本的 Windows 操作系统中可用。
目标平台 通用
标头 wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h、Fltkernel.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 符合性规则 HwStorPortProhibitedDDI (storport)

另请参阅

ACCESS_MASK

OBJECT_TYPE

ObDereferenceObjectDeferDeleteWithTag

ObDereferenceObjectWithTag

ObReferenceObjectByHandle

ZwClose