Макрос ObDereferenceObjectWithTag (wdm.h)

Статья
03/18/2023

Подпрограмма ObDereferenceObjectWithTag уменьшает количество ссылок указанного объекта и записывает значение четырехбайтового тега в объект для поддержки трассировки ссылок на объекты.

Синтаксис

void ObDereferenceObjectWithTag(
  [in]  a,
  [in]  t
);

Параметры

[in] a

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

[in] t

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

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

None

Remarks

ObDereferenceObjectWithTag возвращает значение, зарезервированное для использования системой. Драйверы должны рассматривать это значение как VOID.

Драйвер режима ядра вызывает эту подпрограмму для уменьшения числа ссылок объекта на один. Если объект был создан как временный (то есть флаг OBJ_PERMANENT не был указан при создании объекта), а количество ссылок достигает нуля, диспетчер объектов удаляет объект.

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

Объект является постоянным , если он был создан с указанным флагом атрибута объекта OBJ_PERMANENT. (Дополнительные сведения об атрибутах объекта см. в разделе InitializeObjectAttributes.) Постоянный объект создается с начальным числом ссылок, равного 1, поэтому объект не удаляется, когда драйвер удаляет последнюю ссылку на объект.

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

Вызовите ObDereferenceObjectWithTag.
Получите дескриптор объекта . При необходимости вызовите соответствующую подпрограмму ZwOpenXxx или ZwCreateXxx , чтобы получить дескриптор объекта.
Вызовите ZwMakeTemporaryObject с дескриптором, полученным на шаге 2.
Вызовите ZwClose с дескриптором, полученным на шаге 2.

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

Например, такая взаимоблокировка может возникнуть, если obDereferenceObjectWithTag используется для разыменования объекта диспетчера транзакций ядра (KTM), когда драйвер более высокого уровня в стеке драйверов удерживает блокировку.

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

Подпрограмма ObDereferenceObject похожа на ObDereferenceObjectWithTag, за исключением того, что она не позволяет вызывающему объекту записывать настраиваемый тег. В Windows 7 и более поздних версиях Windows ObDereferenceObject всегда записывает значение тега по умолчанию ('tlfD') в объект . Вызов ObDereferenceObject имеет тот же эффект, что и вызов ObDereferenceObjectWithTag , указывающий Тег = '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)