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

Статья
08/08/2023

Подпрограмма 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 .

Параметр ObjectType	Тип указателя объекта
*ExEventObjectType	PKEVENT
*ExSemaphoreObjectType	PKSEMAPHORE
*IoFileObjectType	PFILE_OBJECT
*PsProcessType	PEPROCESS или PKPROCESS
*PsThreadType	PETHREAD или PKTHREAD
*SeTokenObjectType	PACCESS_TOKEN
*TmEnlistmentObjectType	PKENLISTMENT
*TmResourceManagerObjectType	PKRESOURCEMANAGER
*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, запрошенный доступ сравнивается с правами доступа, которые есть у вызывающего объекта. Только драйверы самого высокого уровня могут безопасно указывать значение UserMode для параметра AccessMode .

Начиная с Windows 7, если AccessMode имеет значение KernelMode и дескриптор получается из адресного пространства пользователя, средство проверки драйверов выдает проверку ошибок C4, подкод F6.

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

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

Требования

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