WdfRequestStopAcknowledge - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers
// wdfrequest.h

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

View the official Windows Driver Kit DDI reference

NtDoc

No description available.

Windows Driver Kit DDI reference (nf-wdfrequest-wdfrequeststopacknowledge)

WdfRequestStopAcknowledge function

Description

[Applies to KMDF and UMDF]

The WdfRequestStopAcknowledge method informs the framework that the driver has stopped processing a specified I/O request.

Parameters

Request [in]

A handle to a framework request object.

Requeue [in]

A Boolean value that, if TRUE, causes the framework to requeue the request into the queue so that the framework will deliver it to the driver again. If FALSE, the framework does not requeue the request. For more information, see the following Remarks section.

Remarks

A bug check occurs if the driver supplies an invalid object handle.

If a driver registers an EvtIoStop callback function for an I/O queue, the framework calls it when the queue's underlying device is leaving its working (D0) state. The framework calls the EvtIoStop callback function for every I/O request that the driver has not completed, including requests that the driver owns and those that it has forwarded to an I/O target. The driver must complete, cancel, or postpone processing of each request by doing one of the following:

If your driver calls WdfRequestStopAcknowledge, it must call this method from within its EvtIoStop callback function.

The framework does not allow the device to leave its working (D0) state until the driver has completed, canceled, or postponed every request that an EvtIoStop callback function receives. Potentially, this inaction can prevent a system from entering its hibernation state or another low system power state.

When a driver's EvtIoStop callback function calls WdfRequestStopAcknowledge, it can set the Requeue parameter to TRUE or FALSE:

If the driver had previously called WdfRequestMarkCancelable or WdfRequestMarkCancelableEx, it must call WdfRequestUnmarkCancelable before calling WdfRequestStopAcknowledge with Requeue set to TRUE.

Before calling WdfRequestStopAcknowledge, the driver's EvtIoStop callback function must stop all processing of the I/O request that requires accessing the underlying device, because the device is about to enter a low-power state.

For more information about the WdfRequestStopAcknowledge method, see Using Power-Managed I/O Queues.

Examples

If a driver calls WdfRequestStopAcknowledge with Requeue set to TRUE, it must previously call WdfRequestUnmarkCancelable.

The following code example is an EvtIoStop callback function that checks to see if a received request is cancelable and, if it is, calls WdfRequestUnmarkCancelable. If WdfRequestUnmarkCancelable returns STATUS_CANCELLED, the example just returns because the driver's EvtRequestCancel callback function will handle the request. Otherwise, the example calls WdfRequestStopAcknowledge and specifies TRUE so that the framework requeues the request when the underlying device returns to its working (D0) state.

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);
}

Typically, if a driver calls WdfRequestStopAcknowledge with Requeue set to FALSE, it leaves the request cancelable.

The following code example is an EvtIoStop callback function that calls WdfRequestStopAcknowledge and specifies FALSE so that the framework eventually calls the driver's EvtIoResume callback function, where the driver resumes processing of the request.

You might use code like this if it is acceptable to halt processing of a specific request and continue it later, rather than having the request redelivered and restarting processing from the beginning.

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);
}

See also

EvtIoStop

EvtRequestCancel

WdfRequestComplete