ObReferenceObjectByPointerWithTag 函数 (wdm.h)

项目
03/18/2023

ObReferenceObjectByPointerWithTag 例程递增指定对象的引用计数，并将四字节标记值写入对象以支持对象引用跟踪。

语法

NTSTATUS ObReferenceObjectByPointerWithTag(
  [in]           PVOID           Object,
  [in]           ACCESS_MASK     DesiredAccess,
  [in, optional] POBJECT_TYPE    ObjectType,
  [in]           KPROCESSOR_MODE AccessMode,
  [in]           ULONG           Tag
);

参数

[in] Object

指向对象的指针。调用方在创建对象时获取此指针，或者在打开对象后从之前对 ObReferenceObjectByHandleWithTag 例程的调用获取此指针。

[in] DesiredAccess

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

[in, optional] ObjectType

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

[in] AccessMode

指示用于访问检查的访问模式。将此参数设置为以下 MODE 枚举值之一：

UserMode
KernelMode

较低级别的驱动程序应指定 KernelMode。

[in] Tag

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

返回值

如果调用成功，ObReferenceObjectByPointerWithTag 将返回STATUS_SUCCESS。可能的错误返回值包括以下内容：

返回代码	说明
STATUS_OBJECT_TYPE_MISMATCH	ObjectType 参数为 Object 参数指向的对象指定错误的对象类型，或者 ObjectType 为 NULL，但 AccessMode 为 UserMode。

注解

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

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

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

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

要求

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