ObReferenceObjectByHandleWithTag 函数 (wdm.h)

项目
02/29/2024

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

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

[in] Tag

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

[out] Object

指向变量的指针，例程在该变量中写入指向对象的指针。下表列出了由可能的 ObjectType 参数值指定的 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。

返回值

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

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

注解

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

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

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

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

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

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

若要在 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)