WdfIoTargetPurge 函数 （wdfiotarget.h）

[适用于 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

从先前调用 WdfDeviceGetIoTarget 或 WdfIoTargetCreate获取的本地或远程 I/O 目标对象的句柄，或者从专用 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。 例如，驱动程序可能执行以下作：

1. 调用 WdfIoTargetPurge 并指定 作 值 WdfIoTargetPurgeIo。
2. 确定目标是否应恢复处理 I/O 请求。
3. 如果目标应恢复，请调用 WdfIoTargetStart。 否则，请使用 WdfIoTargetPurgeIoAndWaitAction 值再次调用 WdfIoTargetPurge。

有关 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;
}

要求

另请参阅

WDF_IO_TARGET_PURGE_IO_ACTION

WdfIoTargetCreate

WdfIoTargetGetState

WdfIoTargetStart

WdfIoTargetStop