EVT_WDF_IO_QUEUE_IO_STOP回调函数 (wdfio.h)

项目
08/08/2023

[适用于 KMDF 和 UMDF]

驱动程序的 EvtIoStop 事件回调函数完成、重新排队或暂停对指定请求的处理，因为请求的 I/O 队列正在停止。

语法

EVT_WDF_IO_QUEUE_IO_STOP EvtWdfIoQueueIoStop;

void EvtWdfIoQueueIoStop(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request,
  [in] ULONG ActionFlags
)
{...}

参数

[in] Queue

与 I/O 请求关联的框架队列对象的句柄。

[in] Request

框架请求对象的句柄。

[in] ActionFlags

一个或多个 WDF_REQUEST_STOP_ACTION_FLAGS类型标志的按位 OR，用于标识调用回调函数的原因以及请求是否可取消。

返回值

无

备注

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

如果驱动程序为 I/O 队列注册 EvtIoStop 回调函数，则当队列的基础设备离开其工作 (D0) 状态时，框架会调用它。框架针对驱动程序尚未完成的每个 I/O 请求调用 EvtIoStop 回调函数，包括驱动程序拥有的请求以及它已转发到 I/O 目标的请求。

在大多数情况下， EvtIoStop 回调函数完成、取消或推迟对 I/O 请求的进一步处理。

通常，驱动程序执行以下操作之一：

如果驱动程序拥有 I/O 请求，则调用 WdfRequestUnmarkCancelable (如果请求可取消) ，并且调用重新排队值为 TRUE 的 WdfRequestStopAcknowledge，或者调用完成状态值为 STATUS_SUCCESS 或 STATUS_CANCELLED 的 WdfRequestComplete。
在可以安全调用 WdfRequestXxx 方法之前，驱动程序必须确保其 EvtIoStop 的实现对请求具有独占访问权限。

为此，驱动程序必须同步对请求的访问，以防止其他线程同时操作请求。选择的同步方法将取决于驱动程序的设计。

例如，如果请求保存在共享上下文区域中， 则 EvtIoStop 回调可能会获取内部驱动程序锁，从共享上下文中删除请求，然后释放该锁。此时， EvtIoStop 回调拥有请求，并且可以安全地完成或重新排队请求。

或者，驱动程序会推迟对请求的进一步处理，并调用重新排队值为 FALSE 的 WdfRequestStopAcknowledge。
如果驱动程序已将 I/O 请求转发到 I/O 目标，则可以调用 WdfRequestCancelSentRequest 以尝试取消请求。
或者，如果驱动程序已将 I/O 请求转发到其自己的驱动程序堆栈中的较低级别驱动程序，并且框架使用 ActionFlags 值为 WdfRequestStopActionSuspend 调用驱动程序的 EvtIoStop 回调，则驱动程序可以使用重新排队值为 FALSE 调用 WdfRequestStopAcknowledge。在执行此操作之前，驱动程序应验证是否满足以下条件：
- 较低的驱动程序停止处理所有未完成的 I/O 请求，以响应接收设备设置电源 IRP (Dx) 。
- 驱动程序的 CompletionRoutine 回调函数可以在设备处于低功耗状态时完成请求。

对于保证在短时间内完成的请求，驱动程序可能会选择在 EvtIoStop 中不执行任何操作。

在这种情况下，框架将等到指定的请求完成，然后再将设备 (或系统) 移动到低功耗状态或删除设备。这种不作为可能会阻止系统进入其休眠状态或其他低系统电源状态。在极端情况下，它可能导致系统崩溃，并出现错误检查代码 9F。

如果在 ActionFlags 参数中设置了 WdfRequestStopRequestCancelable 标志，则驱动程序必须在调用 WdfRequestComplete 之前调用 WdfRequestUnmarkCancelable 以完成 (或取消) 请求或 WdfRequestStopAcknowledge 以重新排队请求。

如果驱动程序从其请求处理程序之一转发 I/O 请求，并在请求的 WDF_REQUEST_SEND_OPTIONS 结构中指定 WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET 标志，则框架不会为此请求调用驱动程序的 EvtIoStop 回调函数。但是，如果驱动程序从另一个线程转发相同的 I/O 请求，框架可能会为此请求调用 EvtIoStop 。

有关 EvtIoStop 回调函数的详细信息，请参阅使用 Power-Managed I/O 队列。

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