Функция 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

Указывает режим доступа, используемый для проверка доступа. Он должен иметь значение UserMode или KernelMode. Драйверы всегда должны указывать UserMode для дескрипторов, получаемых из адресного пространства пользователя.

[in] Tag

Задает четырехбайтовое значение настраиваемого тега. Дополнительные сведения см. в разделе "Примечания".

[out] Object

Указатель на переменную, в которую подпрограмма записывает указатель на объект . В следующей таблице перечислены типы указателей объектов , которые обозначены возможными значениями параметров ObjectType .

Структуры, на которые ссылаются типы указателей, являются непрозрачными, и драйверы не могут получить доступ к членам структуры. Поскольку структуры непрозрачны, PEPROCESS эквивалентен PKPROCESS, а PETHREAD — PKTHREAD.

[out, optional] HandleInformation

Драйверы устанавливают для этого параметра значение NULL.

Возвращаемое значение

ObReferenceObjectByHandleWithTag возвращает STATUS_SUCCESS, если вызов выполнен успешно. Возможные возвращаемые значения ошибок:

Комментарии

Эта подпрограмма выполняет проверку доступа указанного дескриптора объекта. Если доступ может быть предоставлен, подпрограмма увеличивает число ссылок на объекты и предоставляет указатель на вызывающий объект. Этот приращение предотвращает удаление объекта, пока вызывающий объект использует объект . Если объект больше не нужен, вызывающий объект должен уменьшать количество ссылок, вызывая подпрограмму 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), чтобы включить трассировку ссылок на объекты. Дополнительные сведения см. в разделе Трассировка ссылок на объекты с тегами.

Требования

См. также раздел

ACCESS_MASK

OBJECT_TYPE

ObDereferenceObjectDeferDeleteWithTag

ObDereferenceObjectWithTag

ObReferenceObjectByHandle

ZwClose