EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE回调函数 (wdfio.h)

  • 项目

[适用于 KMDF 和 UMDF]

驱动程序的 EvtIoCanceledOnQueue 事件回调函数通知驱动程序它必须完成框架已从 I/O 队列中删除的 I/O 请求。

语法

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE EvtWdfIoQueueIoCanceledOnQueue;

void EvtWdfIoQueueIoCanceledOnQueue(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request
)
{...}

参数

[in] Queue

I/O 队列对象的句柄。

[in] Request

请求对象的句柄。

返回值

无

备注

驱动程序在调用 WdfIoQueueCreate 方法时注册 EvtIoCanceledOnQueue 回调函数。 有关调用 WdfIoQueueCreate 的详细信息，请参阅 创建 I/O 队列。

如果驱动程序为 I/O 队列注册 EvtIoCanceledOnQueue 回调函数，框架会在以下情况下调用回调函数：

在框架调用 EvtIoCanceledOnQueue 回调函数后，驱动程序 拥有 请求对象，并且必须使用相应的状态代码 （ 在 EvtIoCanceledOnQueue 或更高版本中）完成请求。 当框架调用 EvtIoCanceledOnQueue 时，请求仍与 I/O 队列相关联，但驱动程序无法重新排队请求。 即使驱动程序未在 EvtIoCanceledOnQueue 中完成请求，请求的所有权仍由驱动程序拥有。 如果驱动程序在 EvtIoCanceledOnQueue 返回后完成请求，则无法调用 WdfIoQueueFindRequest 和 WdfIoQueueRetrieveFoundRequest 来重新获取请求的所有权，因为驱动程序已拥有请求的所有权。

通常，在 EvtIoCanceledOnQueue 中，驱动程序 完成 I/O 请求 ，完成状态为STATUS_CANCELLED。

在某些情况下，驱动程序之前可能已将 I/O 请求重新排队到手动队列，可能是为了等待信息。 例如，在其某个 请求处理程序中，驱动程序可能会将与挂起的 DMA 事务关联的 I/O 请求置于手动队列中。 在这种情况下，驱动程序尝试在其 EvtIoCanceledOnQueue 回调中取消 DMA 事务。 根据取消操作的结果，驱动程序将在 EvtIoCanceledOnQueue 或更高版本中以适当的状态完成请求。

对于框架从未传递给驱动程序的 I/O 请求，框架不会调用驱动程序的 EvtIoCanceledOnQueue 回调函数。

框架在确定已取消 I/O 请求后立即调用 EvtIoCanceledOnQueue 回调函数，而不考虑驱动程序为 I/O 队列设置的 调度方法 。 因此，框架可以为以下项调用 EvtIoCanceledOnQueue 回调函数：

  • 队列中使用 顺序调度的请求，即使驱动程序当前拥有队列中的另一个请求也是如此。
  • 队列中的请求，驱动程序已为其设置了 NumberOfPresentedRequests，即使驱动程序当前拥有最大请求数也是如此。
有关 EvtIoCanceledOnQueue 回调函数的详细信息，请参阅 取消 I/O 请求。

可以在 IRQL <= DISPATCH_LEVEL调用 EvtIoCanceledOnQueue 回调函数，除非设备或驱动程序的WDF_OBJECT_ATTRIBUTES结构的 ExecutionLevel 成员设置为 WdfExecutionLevelPassive。

如果 IRQL PASSIVE_LEVEL，框架会在 关键区域内调用回调函数。

示例

若要定义 EvtIoCanceledOnQueue 回调函数，必须首先提供一个函数声明，用于标识要定义的回调函数的类型。 Windows 为驱动程序提供一组回调函数类型。 使用回调函数类型声明函数有助于 驱动程序代码分析、 静态驱动程序验证程序 (SDV) 和其他验证工具查找错误，并且这是编写适用于 Windows 操作系统的驱动程序的要求。

若要定义 EvtIoCanceledOnQueue 回调函数，必须首先提供 SDV 和其他验证工具所需的函数声明。 以下示例取自 PCMCIA 智能卡驱动程序 示例。

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE PscrEvtIoCanceledOnQueue;

在 PCMCIA 智能卡驱动程序示例中，驱动程序使用手动队列来存储挂起的智能卡通知请求。 驱动程序提供 EvtIoCanceledOnQueue 回调函数，其中驱动程序清除通知字段并完成请求。

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

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE函数类型在 Wdfio.h 头文件中定义。 若要在运行代码分析工具时更准确地识别错误，请务必将 Use_decl_annotations 注释添加到函数定义。 Use_decl_annotations批注可确保使用应用于头文件中EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE函数类型的注释。 有关函数声明要求的详细信息，请参阅 使用 KMDF 驱动程序的函数角色类型声明函数。 有关 Use_decl_annotations的信息，请参阅 批注函数行为。

要求

要求 值
目标平台 通用
最低 KMDF 版本 1.0
最低 UMDF 版本 2.0
标头 wdfio.h (包括 Wdf.h)
IRQL <= DISPATCH_LEVEL (请参阅备注部分)

另请参阅

WdfIoQueueCreate

WdfRequestForwardToIoQueue