функция обратного вызова EVT_WDF_IO_QUEUE_IO_STOP (wdfio.h)
[Применимо к KMDF и UMDF]
Функция обратного вызова события EvtIoStop драйвера завершает, повторно отправляет или приостанавливает обработку указанного запроса, так как очередь ввода-вывода запроса останавливается.
Синтаксис
EVT_WDF_IO_QUEUE_IO_STOP EvtWdfIoQueueIoStop;
void EvtWdfIoQueueIoStop(
[in] WDFQUEUE Queue,
[in] WDFREQUEST Request,
[in] ULONG ActionFlags
)
{...}
Параметры
[in] Queue
Дескриптор объекта очереди платформы, связанного с запросом ввода-вывода.
[in] Request
Дескриптор объекта запроса платформы.
[in] ActionFlags
Побитовое ИЛИ одного или нескольких WDF_REQUEST_STOP_ACTION_FLAGS типизированных флагов, определяющих причину вызова функции обратного вызова и возможность отмены запроса.
Возвращаемое значение
None
Remarks
Драйвер регистрирует функцию обратного вызова EvtIoStop при вызове WdfIoQueueCreate. Дополнительные сведения о вызове WdfIoQueueCreate см. в разделе Создание очередей ввода-вывода.
Если драйвер регистрирует функцию обратного вызова EvtIoStop для очереди ввода-вывода, платформа вызывает ее, когда базовое устройство очереди покидает рабочее состояние (D0). Платформа вызывает функцию обратного вызова EvtIoStop для каждого запроса ввода-вывода, который драйвер не завершил, включая запросы, принадлежащие драйверу, и те, которые он перенаправил в целевой объект ввода-вывода.
В большинстве случаев функция обратного вызова EvtIoStopзавершает, отменяет или откладывает дальнейшую обработку запроса ввода-вывода.
Как правило, драйвер выполняет одно из следующих действий:
-
Если драйвер является владельцем запроса ввода-вывода, он вызывает WdfRequestUnmarkCancelable (если запрос можно отменить) и либо вызывает WdfRequestStopAcknowledge со значением Requeue TRUE, либо вызывает WdfRequestComplete со значением состояния завершения STATUS_SUCCESS или STATUS_CANCELLED.
Перед безопасным вызовом методов WdfRequestXxx драйвер должен убедиться, что его реализация EvtIoStop имеет монопольный доступ к запросу.
Для этого драйвер должен синхронизировать доступ к запросу, чтобы другие потоки не управляли запросом одновременно. Выбранный метод синхронизации будет зависеть от структуры драйвера.
Например, если запрос хранится в области общего контекста, обратный вызов EvtIoStop может получить внутреннюю блокировку драйвера, удалить запрос из общего контекста, а затем снять блокировку. На этом этапе обратный вызов EvtIoStop является владельцем запроса и может безопасно завершить или повторно подать запрос.
Кроме того, драйвер откладывает дальнейшую обработку запроса и вызывает WdfRequestStopAcknowledge со значением Requeue FALSE.
-
Если драйвер перенаправил запрос ввода-вывода в целевой объект ввода-вывода, он может вызвать WdfRequestCancelSentRequest , чтобы попытаться отменить запрос.
Или, если драйвер перенаправил запрос ввода-вывода в драйвер более низкого уровня в собственном стеке драйверов и платформа вызывает обратный вызов EvtIoStop драйвера со значением ActionFlagsWdfRequestStopActionSuspend, драйвер может вызвать WdfRequestStopAcknowledge со значением Requeue false. Перед этим драйвер должен убедиться, что выполняются следующие условия:
- Нижний драйвер перестает обрабатывать все незаполненные запросы ввода-вывода в ответ на получение IRP с установленной мощностью устройства (Dx).
- Функция обратного вызова CompletionRoutine драйвера может выполнять запросы, пока устройство находится в маломощном состоянии.
В этом случае платформа ожидает завершения указанного запроса перед перемещением устройства (или системы) в более низкое состояние питания или удалением устройства. Потенциально это бездействие может помешать системе войти в состояние гибернации или другое состояние с низким энергопотреблением системы. В крайних случаях это может привести к сбою системы с кодом проверки ошибок 9F.
Если флаг WdfRequestStopRequestCancelable установлен в параметре ActionFlags , драйвер должен вызвать WdfRequestUnmarkCancelable , прежде чем вызывать WdfRequestComplete для завершения (или отмены) запроса или WdfRequestStopAcknowledge для повторного отправки запроса.
Если драйвер пересылает запрос ввода-вывода из одного из своих обработчиков запросов и задает флаг WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET в структуре WDF_REQUEST_SEND_OPTIONS запроса, платформа не вызывает функцию обратного вызова EvtIoStop драйвера для этого запроса. Однако если драйвер пересылает тот же запрос ввода-вывода из другого потока, платформа может вызвать EvtIoStop для этого запроса.
Дополнительные сведения о функции обратного вызова EvtIoStop см. в статье Использование Power-Managed очередей ввода-вывода.
Эту функцию обратного вызова можно вызвать в IRQL <= DISPATCH_LEVEL, если для элемента ExecutionLevel устройства или структуры WDF_OBJECT_ATTRIBUTES драйвера не задано значение WdfExecutionLevelPassive.
Требования
| Требование | Значение |
|---|---|
| Целевая платформа | Универсальное |
| Минимальная версия KMDF | 1,0 |
| Минимальная версия UMDF | 2,0 |
| Верхняя часть | wdfio.h (включая Wdf.h) |
| IRQL | <= DISPATCH_LEVEL (см. раздел "Примечания") |