EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE callback function (wdfio.h)
[Applies to KMDF and UMDF]
A driver's EvtIoCanceledOnQueue event callback function informs the driver that it must complete an I/O request that the framework has removed from an I/O queue.
Syntax
EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE EvtWdfIoQueueIoCanceledOnQueue;
void EvtWdfIoQueueIoCanceledOnQueue(
[in] WDFQUEUE Queue,
[in] WDFREQUEST Request
)
{...}
Parameters
[in] Queue
A handle to an I/O queue object.
[in] Request
A handle to a request object.
Return value
None
Remarks
A driver registers an EvtIoCanceledOnQueue callback function when it calls the WdfIoQueueCreate method. For more information about calling WdfIoQueueCreate, see Creating I/O Queues.
If a driver registers an EvtIoCanceledOnQueue callback function for an I/O queue, the framework calls the callback function in the following situations:
- A request handler receives an I/O request from an I/O queue, the driver calls WdfRequestForwardToIoQueue, WdfRequestForwardToParentDeviceIoQueue, or WdfRequestRequeue to requeue the request to the I/O queue for which the EvtIoCanceledOnQueue callback function is registered, and the associated I/O operation is subsequently canceled.
- The driver's EvtIoInCallerContext callback function receives an I/O request, the driver calls WdfDeviceEnqueueRequest to pass the request back to the framework, the framework then places the request in the I/O queue for which the EvtIoCanceledOnQueue callback function is registered, and the associated I/O operation is subsequently canceled.
Typically, in EvtIoCanceledOnQueue, the driver completes the I/O request with a completion status of STATUS_CANCELLED.
In some cases, the driver might have previously requeued an I/O request to a manual queue, perhaps to wait for information. For example, in one of its request handlers, a driver might place an I/O request that is associated with a pending DMA transaction in a manual queue. In this case, the driver attempts to cancel the DMA transaction in its EvtIoCanceledOnQueue callback. Depending on the results of the cancel operation, the driver completes the request with an appropriate status, either in EvtIoCanceledOnQueue or later.
The framework does not call the driver's EvtIoCanceledOnQueue callback function for I/O requests that the framework has never delivered to the driver.
The framework calls an EvtIoCanceledOnQueue callback function as soon as it determines that an I/O request has been canceled, regardless of the dispatching method that the driver has set for the I/O queue. Therefore, the framework can call an EvtIoCanceledOnQueue callback function for:
- A request in a queue that uses sequential dispatching, even if the driver currently owns another request from the queue.
- A request in a queue for which the driver has set NumberOfPresentedRequests, even if the driver currently owns the maximum number of requests.
The EvtIoCanceledOnQueue callback function can be called at IRQL <= DISPATCH_LEVEL, unless the ExecutionLevel member of the device or driver's WDF_OBJECT_ATTRIBUTES structure is set to WdfExecutionLevelPassive.
If the IRQL is PASSIVE_LEVEL, the framework calls the callback function within a critical region.
Examples
To define an EvtIoCanceledOnQueue callback function, you must first provide a function declaration that identifies the type of callback function you’re defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it’s a requirement for writing drivers for the Windows operating system.
To define an EvtIoCanceledOnQueue callback function, you must first provide a function declaration that SDV and other verification tools require. The following example is taken from the PCMCIA Smart Card Driver sample.
EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE PscrEvtIoCanceledOnQueue;
In the PCMCIA Smart Card Driver sample, the driver uses a manual queue to store pending smart card notification requests. The driver provides an EvtIoCanceledOnQueue callback function in which the driver clears the notification field and completes the request.
_Use_decl_annotations_
VOID
PscrEvtIoCanceledOnQueue(
WDFQUEUE Queue,
WDFREQUEST Request
)
{
PDEVICE_EXTENSION DeviceExtension;
PSMARTCARD_EXTENSION smartcardExtension;
DeviceExtension = GetDeviceExtension(WdfIoQueueGetDevice(Queue));
smartcardExtension = (PSMARTCARD_EXTENSION) &DeviceExtension->SmartcardExtension;
//KdPrint(("Cancelled on queue 0x%x\n", WdfRequestWdmGetIrp(Request)));
InterlockedExchangePointer(
&(smartcardExtension->OsData->NotificationIrp),
NULL
);
WdfRequestComplete(Request, STATUS_CANCELLED);
}
The EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE function type is defined in the Wdfio.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for KMDF Drivers. For information about Use_decl_annotations, see Annotating Function Behavior.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Minimum KMDF version | 1.0 |
| Minimum UMDF version | 2.0 |
| Header | wdfio.h (include Wdf.h) |
| IRQL | <= DISPATCH_LEVEL (see Remarks section) |