WdfIoTargetPurge 函数 (wdfiotarget.h)

项目
08/08/2023

[适用于 KMDF 和 UMDF]

WdfIoTargetPurge 方法取消排队到本地、远程或专用 I/O 目标的所有 I/O 请求，并阻止任何新的 I/O 请求排队。方法还尝试取消已离开 I/O 目标的队列并输入较低驱动程序的 I/O 请求。

语法

void WdfIoTargetPurge(
  [in] WDFIOTARGET                   IoTarget,
  [in] WDF_IO_TARGET_PURGE_IO_ACTION Action
);

参数

[in] IoTarget

本地或远程 I/O 目标对象的句柄，该对象是从先前调用 WdfDeviceGetIoTarget 或 WdfIoTargetCreate 获取的，或者从专用 I/O 目标（如 WdfUsbTargetPipeGetIoTarget）提供的方法获取的。

[in] Action

一个WDF_IO_TARGET_PURGE_IO_ACTION类型的值，该值指示框架是否应等待从 WdfIoTargetPurge 返回，直到所有传递的请求都完成或取消。

返回值

无

备注

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

如果驱动程序之前已调用 WdfUsbTargetPipeConfigContinuousReader，则必须在 IRQL = PASSIVE_LEVEL调用 WdfIoTargetPurge 。如果驱动程序尚未调用 WdfUsbTargetPipeConfigContinuousReader，并且 WdfIoTargetPurge 的 Action 参数为 WdfIoTargetPurgeIo，则可以在 IRQL <= DISPATCH_LEVEL调用 WdfIoTargetPurge。否则，必须在 IRQL = PASSIVE_LEVEL调用 WdfIoTargetPurge 。

若要使 WdfIoTargetPurge 成为同步调用，驱动程序可以设置 Action 参数的 WdfIoTargetPurgeIoAndWait 值。在这种情况下， WdfIoTargetPurge 将等待返回，直到所有传递的请求都完成或取消。

驱动程序调用 WdfIoTargetPurge 后，它仍然可以通过在请求的WDF_REQUEST_SEND_OPTIONS结构中设置 WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE 标志来向目标发送请求。例如，驱动程序可能会在驱动程序调用 WdfIoTargetPurge 后，向设备发送请求，例如重置 USB 管道的请求 (请参阅 WdfUsbTargetPipeResetSynchronously) 。

当驱动程序调用 WdfIoTargetPurge 时，框架不会尝试取消或等待以前使用 WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE 标志或请求WDF_REQUEST_SEND_OPTIONS结构中的 WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET 标志发送到目标的 I /O 请求。

驱动程序清除 I/O 队列后，可以通过调用 WdfIoTargetStart 来重启队列。

驱动程序必须同步调用 WdfIoTargetStart、 WdfIoTargetStop 和 WdfIoTargetPurge 。驱动程序调用其中一个函数后，在上一次调用返回之前不得调用任何其他函数。

驱动程序可以多次调用 WdfIoTargetPurge ，而无需调用 WdfIoTargetStart。例如，驱动程序可能会执行以下操作：

调用 WdfIoTargetPurge 并指定操作值 WdfIoTargetPurgeIo。
确定目标是否应继续处理 I/O 请求。
如果目标应恢复，请调用 WdfIoTargetStart。否则，请再次调用 WdfIoTargetPurge，其操作值为 WdfIoTargetPurgeIoAndWait。

有关 I/O 目标状态的详细信息，请参阅控制常规 I/O 目标的状态。

有关 I/O 目标的详细信息，请参阅使用 I/O 目标。

示例

下面的代码示例演示了如果驱动程序使用 USB 管道的连续读取器， EvtDeviceD0Exit 回调函数如何调用 WdfIoTargetPurge。

NTSTATUS
MyEvtDeviceD0Exit(
    IN  WDFDEVICE Device,
    IN  WDF_POWER_DEVICE_STATE TargetState
)
{
    PDEVICE_CONTEXT  pDeviceContext;
    pDeviceContext = GetMyDeviceContext(Device);

    WdfIoTargetPurge(
                    WdfUsbTargetPipeGetIoTarget(pDeviceContext->InterruptPipe),
                    WdfIoTargetPurgeIoAndWait
                    );

    return STATUS_SUCCESS;
}

要求

要求	值
目标平台	通用
最低 KMDF 版本	1.11
最低 UMDF 版本	2.0
标头	wdfiotarget.h (包括 Wdf.h)
Library	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	请参见“备注”部分。
DDI 符合性规则	DriverCreate (kmdf)