WdfRequestCancelSentRequest function (wdfrequest.h)

Artikel
02/22/2024

[Applies to KMDF and UMDF]

The WdfRequestCancelSentRequest method attempts to cancel an I/O request that the caller previously submitted to an I/O target.

Syntax

BOOLEAN WdfRequestCancelSentRequest(
  [in] WDFREQUEST Request
);

Parameters

[in] Request

A handle to a framework request object.

Return value

WdfRequestCancelSentRequest returns TRUE if it successfully delivers the cancel request to the driver's I/O target. This method returns FALSE if the request has already been completed or canceled, or if the I/O target driver has not called WdfRequestMarkCancelable or WdfRequestMarkCancelableEx.

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

Remarks

A driver can call WdfRequestCancelSentRequest to attempt to cancel an I/O request that it previously had sent to an I/O target by calling WdfRequestSend.

If the request is in the I/O target's queue, the framework cancels the request. If the framework has already delivered the request to the I/O target's driver, and if that driver has called WdfRequestMarkCancelable or WdfRequestMarkCancelableEx to enable canceling, the framework calls that driver's EvtRequestCancel callback function. If the target's driver has not called WdfRequestMarkCancelable or WdfRequestMarkCancelableEx, the request is not canceled unless the request becomes cancelable.

If the driver has registered a CompletionRoutine callback function for the request, the framework calls the callback function after the request has been canceled.

Typically, if your driver calls WdfRequestCancelSentRequest, it must increment the request object's reference count. For more information, see Synchronizing Cancellation of Sent Requests.

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

Examples

The following code example is from the kmdf_fx2 sample driver. This example is an EvtIoStop callback function. Because this driver sends each request to its I/O target, the EvtIoStop callback function calls WdfRequestCancelSentRequest if the device has been removed.

VOID
OsrFxEvtIoStop(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN ULONG  ActionFlags
    )
{
    UNREFERENCED_PARAMETER(Queue);

    if (ActionFlags & WdfRequestStopActionSuspend) {
        WdfRequestStopAcknowledge(Request, FALSE);
    } else if (ActionFlags & WdfRequestStopActionPurge) {
        WdfRequestCancelSentRequest(Request);
    }
    return;
}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfrequest.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf), EvtIoStopCancel(kmdf), EvtIoStopCompleteOrStopAck(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Delen via