функция обратного вызова EVT_WDF_OBJECT_CONTEXT_CLEANUP (wdfobject.h)
[Относится к KMDF и UMDF]
Функция обратного вызова события EvtCleanupCallback драйвера удаляет ссылки драйвера на объект, чтобы объект можно было удалить.
Синтаксис
EVT_WDF_OBJECT_CONTEXT_CLEANUP EvtWdfObjectContextCleanup;
void EvtWdfObjectContextCleanup(
[in] WDFOBJECT Object
)
{...}
Параметры
[in] Object
Дескриптор объекта платформы.
Возвращаемое значение
None
Remarks
Драйвер может указать функцию обратного вызова EvtCleanupCallback в структуре WDF_OBJECT_ATTRIBUTES . Эта структура используется в качестве входных данных для всех методов платформы, создающих объекты платформы, таких как WdfDeviceCreate.
Платформа вызывает функцию обратного вызова, когда платформа или драйвер пытается удалить объект.
Если драйвер вызвал WdfObjectReference , чтобы увеличить число ссылок объекта, драйвер должен предоставить функцию обратного вызова EvtCleanupCallback , которая вызывает WdfObjectDereference. Этот вызов гарантирует, что количество ссылок объекта уменьшается до нуля, и в результате платформа может вызвать функцию обратного вызова EvtDe соответствииCallback драйвера, а затем удалить объект.
Если драйвер предоставляет функцию обратного вызова EvtCleanupCallback и функцию обратного вызова EvtDegradCallback для объекта, платформа сначала вызывает функцию обратного вызова EvtCleanupCallback .
После того как платформа вызывает функцию обратного вызова EvtCleanupCallback объекта, драйвер может получить доступ к объекту только из функции обратного вызова EvtDegradCallback . Однако драйвер не должен пытаться вызывать методы для объекта из его EvtDe составнойCallback.
Когда драйвер создает объект, он иногда выделяет буферы памяти для конкретного объекта и сохраняет указатели буфера в пространстве контекста объекта. Функция обратного вызова EvtCleanupCallback или EvtDegradCallback драйвера может освободить эти буферы памяти.
Как правило, если драйвер не вызывает WdfObjectReference для объекта, функция обратного вызова EvtCleanupCallback объекта может освободить выделение контекста объекта. В этом случае драйверу не требуется функция обратного вызова EvtDebaseCallback для объекта .
При удалении объекта платформа также удаляет дочерние элементы объекта. За одним исключением, платформа вызывает подпрограммы EvtCleanupCallback дочерних объектов перед вызовом их родительских объектов, поэтому драйверы гарантируют, что родительский объект по-прежнему существует при выполнении подпрограммы EvtCleanupCallback дочернего объекта.
Исключение из этого гарантированного порядка применяется к запросам ввода-вывода, которые драйвер выполняет в DISPATCH_LEVEL. Если такой объект запроса ввода-вывода имеет один или несколько дочерних элементов, подпрограммы EvtCleanupCallback которых должны вызываться по PASSIVE_LEVEL, родительский запрос может быть удален до одного или нескольких его дочерних элементов. Объект требует очистки в PASSIVE_LEVEL, если ему нужно ждать завершения или если он обращается к выстраивной памяти.
Если драйвер пытается удалить такой объект (или родительский объект такого объекта) во время его выполнения в DISPATCH_LEVEL, платформа помещает EvtCleanupCallback в очередь к рабочему элементу для последующей обработки на PASSIVE_LEVEL а затем вызывает обратный вызов очистки для родительского объекта, не определяя, запущены ли обратные вызовы для дочерних элементов.
Чтобы избежать проблем, которые могут возникнуть в результате такого поведения, драйверы не должны устанавливать объект запроса в качестве родительского объекта для любого объекта, требующего очистки на PASSIVE_LEVEL. По умолчанию родительским элементом для большинства объектов является WDFDEVICE, поэтому драйверы должны просто принять значение по умолчанию. Как правило, если объект WDFDEVICE передается в качестве параметра (напрямую или как часть структуры) в метод, создающий объект, WDFDEVICE является родительским объектом по умолчанию. Полный список родительских элементов по умолчанию см. в разделе Сводка по объектам платформы.
Если приведенное выше исключение не применяется, платформа вызывает функции обратного вызова EvtCleanupCallback дочернего объекта перед вызовом функции обратного вызова EvtCleanupCallback родительского объекта. Затем, если количество ссылок дочернего элемента равно нулю, платформа вызывает функцию обратного вызова EvtDebackCallback дочернего объекта. Наконец, если число ссылок родительского объекта равно нулю, платформа вызывает функцию обратного вызова EvtDehoodCallback родительского объекта.
Дополнительные сведения об удалении объектов платформы см. в разделе Жизненный цикл объектов платформы.
Как правило, платформа вызывает функцию обратного вызова EvtCleanupCallback в IRQL <= DISPATCH_LEVEL. Однако платформа вызывает функцию обратного вызова в IRQL = PASSIVE_LEVEL в следующих ситуациях:
- Тип дескриптора объекта — WDFDEVICE, WDFDRIVER, WDFDPC, WDFINTERRUPT, WDFIOTARGET, WDFQUEUE, WDFSTRING, WDFTIMER или WDFWORKITEM.
- Тип дескриптора объекта — WDFMEMORY или WDFLOOKASIDE, а драйвер указал PagedPool для параметра PoolTypeв значение WdfMemoryCreate или WdfLookasideListCreate.
Аналогичным образом, когда объект таймера удаляется явным образом или из-за удаления родительского объекта таймера, перед вызовом функции обратного вызова EvtCleanupCallback таймера платформа ожидает, пока не будут возвращены все экземпляры функции обратного вызова события EvtTimerFunc таймера.
Начиная с версии 1.9 платформы, файл заголовка wdfroletypes.h содержит некоторые альтернативные, зависящие от типа объекта типы функций для функции обратного вызова EvtCleanupCallback . Эти альтернативные типы помогают средствам проверки определить, правильно ли драйвер использует функцию обратного вызова. Используйте следующую таблицу, чтобы определить, какой тип функции использовать.
| Тип объекта | Тип функции |
|---|---|
| Объект устройства | EVT_WDF_DEVICE_CONTEXT_CLEANUP |
| Объект очереди ввода-вывода | EVT_WDF_IO_QUEUE_CONTEXT_CLEANUP_CALLBACK |
| File - объект | EVT_WDF_FILE_CONTEXT_CLEANUP_CALLBACK |
| Все прочие объекты | EVT_WDF_OBJECT_CONTEXT_CLEANUP |
Требования
| Требование | Значение |
|---|---|
| Целевая платформа | Универсальное |
| Минимальная версия KMDF | 1,0 |
| Минимальная версия UMDF | 2,0 |
| Верхняя часть | wdfobject.h (включая Wdf.h) |
| IRQL | См. раздел "Примечания". |