Функция WdfRequestStopAcknowledge (wdfrequest.h)

Статья
08/08/2023

[Относится к KMDF и UMDF]

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

Синтаксис

void WdfRequestStopAcknowledge(
  [in] WDFREQUEST Request,
  [in] BOOLEAN    Requeue
);

Параметры

[in] Request

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

[in] Requeue

Логическое значение, которое, если значение TRUE, приводит к тому, что платформа повторно отправляет запрос в очередь, чтобы платформа снова доставляла его драйверу. Если значение FALSE, платформа не отправляет запрос повторно. Дополнительные сведения см. в разделе "Примечания".

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

None

Remarks

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

Если драйвер регистрирует функцию обратного вызова EvtIoStop для очереди ввода-вывода, платформа вызывает ее, когда базовое устройство очереди выходит из состояния работы (D0). Платформа вызывает функцию обратного вызова EvtIoStop для каждого запроса ввода-вывода, который не был выполнен драйвером, включая запросы, принадлежащие драйверу, и те, которые он перенаправил в целевой объект ввода-вывода. Драйвер должен завершить, отменить или отложить обработку каждого запроса, выполнив одно из следующих действий:

Если драйвер является владельцем запроса, он может вызвать WdfRequestComplete , чтобы завершить или отменить запрос.
Если драйвер перенаправил запрос в целевой объект ввода-вывода, он может вызвать WdfRequestCancelSentRequest , чтобы попытаться отменить запрос.
Если драйвер откладывает обработку запроса, он должен вызвать WdfRequestStopAcknowledge.

Если драйвер вызывает WdfRequestStopAcknowledge, он должен вызвать этот метод из функции обратного вызова EvtIoStop .

Платформа не позволяет устройству покидать рабочее состояние (D0), пока драйвер не завершит, не отменит или не отложит каждый запрос, получаемый функцией обратного вызова EvtIoStop . Потенциально это бездействие может помешать системе войти в состояние гибернации или другое состояние с низким питанием системы.

Когда функция обратного вызова EvtIoStop драйвера вызывает WdfRequestStopAcknowledge, она может задать для параметра Requeueзначение TRUE или FALSE:

Если задать для параметра Requeue значение TRUE , платформа снова помещает запрос в очередь ввода-вывода.
Когда базовое устройство вернется в рабочее состояние (D0), платформа повторно выполнит запрос к драйверу.
Если задать для параметра Requeue значение FALSE , платформа не будет повторно отправлять запрос в очередь. Если драйвер является владельцем запроса, право собственности остается за драйвером. Если драйвер переадресовал запрос, он отвечает за обработку запроса после его завершения. Драйвер должен прекратить обработку ввода-вывода, требующую доступа к оборудованию.
Когда базовое устройство возвращается в рабочее состояние (D0), платформа вызывает функцию обратного вызова EvtIoResume драйвера, чтобы драйвер смог продолжить обработку запроса.

Если драйвер ранее вызывал WdfRequestMarkCancelable или WdfRequestMarkCancelableEx, он должен вызвать WdfRequestUnmarkCancelable перед вызовомWdfRequestStopAcknowledge с параметром requeue , равным TRUE.

Перед вызовом WdfRequestStopAcknowledge функция обратного вызова EvtIoStop драйвера должна остановить всю обработку запроса ввода-вывода, требующего доступа к базовому устройству, так как устройство вот-вот перейдет в состояние с низким энергопотреблением.

Дополнительные сведения о методе WdfRequestStopAcknowledge см. в статье Использование Power-Managed очередей ввода-вывода.

Примеры

Если драйвер вызывает WdfRequestStopAcknowledge , а для requeueзадано значение TRUE, он должен ранее вызвать WdfRequestUnmarkCancelable.

В следующем примере кода показана функция обратного вызова EvtIoStop , которая проверяет, является ли полученный запрос отмененным, и, если это так, вызывает WdfRequestUnmarkCancelable. Если WdfRequestUnmarkCancelable возвращает STATUS_CANCELLED, пример возвращает только потому, что функция обратного вызова EvtRequestCancel драйвера будет обрабатывать запрос. В противном случае в примере вызывается WdfRequestStopAcknowledge и указывается значение TRUE , чтобы платформа повторно возвращала запрос, когда базовое устройство возвращается в рабочее состояние (D0).

VOID
MyEvtIoStop(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN ULONG  ActionFlags
    )
{
    NTSTATUS status;

    // TODO: Take steps here to suspend and, if necessary, roll back any processing that has already occurred on this request

    if (ActionFlags & WdfRequestStopRequestCancelable) {
        status = WdfRequestUnmarkCancelable(Request);
        if (status == STATUS_CANCELLED) {
            return;
        }
    }

    // Inform framework that driver is postponing processing, cause framework to redeliver request when device returns to D0

    WdfRequestStopAcknowledge(Request, TRUE);
}

Как правило, если драйвер вызывает WdfRequestStopAcknowledge , а для параметра Requeueзадано значение FALSE, запрос остается отменяемым.

Следующий пример кода представляет собой функцию обратного вызова EvtIoStop , которая вызывает WdfRequestStopAcknowledge и задает значение FALSE , чтобы платформа в конечном итоге вызывала функцию обратного вызова EvtIoResume драйвера, где драйвер возобновляет обработку запроса.

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

VOID
MyEvtIoStop(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN ULONG  ActionFlags
    )
{

    //TODO: Take steps here to suspend processing of the request so it can be resumed when power returns
	 
    // Acknowledge the stop, but leave the request under driver's ownership.
    // Provide a corresponding EvtIoResume handler to resume processing when power returns

    WdfRequestStopAcknowledge(Request, FALSE);
}

Требования

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

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

EvtIoStop

EvtRequestCancel

WdfRequestComplete

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