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

Подпрограмма 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, если вызов выполнен успешно. Возможные возвращаемые значения ошибок:

Комментарии

Эта подпрограмма выполняет проверку доступа к указанному объекту. Если доступ может быть предоставлен, подпрограмма увеличивает число ссылок на объекты. Это приращение предотвращает удаление объекта, пока вызывающий объект использует объект . Если объект больше не нужен, вызывающий объект должен уменьшать количество ссылок, вызывая подпрограмму ObDereferenceObjectWithTag или ObDereferObjectDeferDeleteWithTag .

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

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

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

Требования

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

ACCESS_MASK

OBJECT_TYPE

ObDereferenceObjectDeferDeleteWithTag

ObDereferenceObjectWithTag

ObReferenceObjectByPointer

ZwClose