WdfRequestMarkCancelable - NtDoc

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

VOID WdfRequestMarkCancelable(
  [in] WDFREQUEST             Request,
  [in] PFN_WDF_REQUEST_CANCEL EvtRequestCancel
);

View the official Windows Driver Kit DDI reference

NtDoc

No description available.

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

WdfRequestMarkCancelable function

Description

[Applies to KMDF and UMDF]

The WdfRequestMarkCancelable method enables cancellation of a specified I/O request.

Parameters

Request [in]

A handle to a framework request object.

EvtRequestCancel [in]

A pointer to a driver-defined EvtRequestCancel callback function, which the framework calls if it cancels the I/O request.

Remarks

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

After your driver has received an I/O request from the framework, the driver can call WdfRequestMarkCancelable or, starting with KMDF version 1.9, WdfRequestMarkCancelableEx to make the request cancelable.

When calling WdfRequestMarkCancelable, your driver must specify an EvtRequestCancel callback function. The framework calls the callback function if the I/O manager or another driver is attempting to cancel the I/O request.

Choosing between WdfRequestMarkCancelable and WdfRequestMarkCancelableEx

If your driver uses the framework's automatic synchronization, the driver can call either WdfRequestMarkCancelable or WdfRequestMarkCancelableEx.

If the driver does not use automatic synchronization, it must call WdfRequestMarkCancelableEx instead of WdfRequestMarkCancelable for the following reasons:

Processing a request after enabling cancellation

After a driver calls WdfRequestMarkCancelable to enable canceling, the request remains cancelable while the driver owns the request object, unless the driver calls WdfRequestUnmarkCancelable.

If a driver has called WdfRequestMarkCancelable, and if the driver's EvtRequestCancel callback function has not executed and called WdfRequestComplete, the driver must call WdfRequestUnmarkCancelable before it calls WdfRequestComplete outside of the EvtRequestCancel callback function.

If the driver calls WdfRequestForwardToIoQueue to forward the request to a different queue, the following rules apply:

For more information about WdfRequestMarkCancelable, see Canceling I/O Requests.

Examples

The following code example shows parts of two callback functions:

The driver must use the framework's automatic synchronization.

VOID
MyEvtIoRead(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
...
    // Perform request-specific work here
    // (such as creating subrequests
    // to send to an I/O target).
...
    WdfRequestMarkCancelable(
                             Request,
                             MyEvtRequestCancel
                             );
    }
...
}
VOID
MyEvtRequestCancel(
    IN WDFREQUEST  Request
    )
{
    // Remove request-specific work here, because
    // we don't want the work to be done if the
    // request was canceled.

    WdfRequestComplete(
                       Request,
                       STATUS_CANCELLED
                       );
}

See also

EvtRequestCancel

WdfRequestComplete

WdfRequestForwardToIoQueue

WdfRequestMarkCancelableEx

WdfRequestUnmarkCancelable