Функция ObReferenceObjectByPointerWithTag (wdm.h)

Статья
02/27/2024

Подпрограмма 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. Этот параметр может иметь значение NULL, если accessMode имеет значение KernelMode. Если 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 или ObDereferObjectDeferDeleteWithTag .

Дополнительные сведения о ссылках на объекты см. в разделе Жизненный цикл объекта.

Подпрограмма ObReferenceObjectByPointer похожа на ObReferenceObjectByPointerWithTag, за исключением того, что она не позволяет вызывающему объекту записывать пользовательский тег. В Windows 7 и более поздних версиях Windows ObReferenceObjectByPointer всегда записывает значение тега по умолчанию (tlfD) в объект . Вызов ObReferenceObjectByPointer имеет тот же эффект, что и вызов ObReferenceObjectByPointerWithTag , указывающий Тег = 'tlfD'.

Чтобы просмотреть трассировку ссылок на объекты в средствах отладки Windows, используйте расширение отладчика режима ядра !obtrace . В Windows 7 расширение !obtrace улучшено для отображения тегов ссылки на объекты, если включена трассировка ссылок на объекты. По умолчанию трассировка ссылок на объекты отключена. Используйте редактор глобальных флагов (Gflags), чтобы включить трассировку ссылок на объекты. Дополнительные сведения см. в разделе Трассировка ссылок на объекты с тегами.

Требования

Требование	Значение
Минимальная версия клиента	Доступно в Windows 7 и более поздних версиях операционной системы Windows.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Правила соответствия DDI	HwStorPortProhibitedDIS(storport)