Функция WdfObjectReferenceActual (wdfobject.h)

Статья
08/08/2023

[Применимо к KMDF и UMDF]

Метод WdfObjectReferenceActual увеличивает число ссылок для указанного объекта платформы и присваивает ссылке значение тега, номер строки и имя файла.

Синтаксис

void WdfObjectReferenceActual(
  [in]           WDFOBJECT Handle,
  [in, optional] PVOID     Tag,
  [in]           LONG      Line,
  [in]           PCCH      File
);

Параметры

[in] Handle

Дескриптор объекта платформы.

[in, optional] Tag

Определенное драйвером значение, которое платформа сохраняет в качестве тега идентификации для ссылки на объект.

[in] Line

Числовое значение, представляющее номер строки в исходном файле драйвера.

[in] File

Указатель на константную строку символов, завершающуюся null, которая представляет имя исходного файла драйвера. Этот параметр является необязательным и может иметь значение NULL.

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

None

Remarks

Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Если драйвер вызывает WdfObjectReferenceActual для увеличения числа ссылок, драйвер должен вызвать WdfObjectDereferenceActual для уменьшения счетчика.

Вызов WdfObjectReferenceActual или WdfObjectReferenceWithTag вместо WdfObjectReference предоставляет дополнительные сведения (значение тега, номер строки и имя файла) отладчикам Майкрософт. WdfObjectReferenceActual позволяет драйверу указать номер строки и имя файла, а WdfObjectReferenceWithTag использует текущий номер строки и имя файла драйвера.

Вы можете просмотреть значения тега, номера строки и имени файла с помощью расширения отладчика !wdftagtracker . Расширение отладчика отображает значение тега как указатель и ряд символов. Дополнительные сведения о расширениях отладчика см. в разделе Отладка драйвера KMDF.

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

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

Примеры

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

WdfObjectReferenceActual(
                         object,
                         pTag,
                         line,
                         FILE_NAME
                         );

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdfobject.h (включая Wdf.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Правила соответствия DDI	DriverCreate(kmdf)

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

WdfObjectReference

Поделиться через