WdfIoTargetStop 函数 (wdfiotarget.h)

项目
08/08/2023

[适用于 KMDF 和 UMDF]

WdfIoTargetStop 方法停止向本地或远程 I/O 目标发送排队的请求。

语法

void WdfIoTargetStop(
  [in] WDFIOTARGET                  IoTarget,
  [in] WDF_IO_TARGET_SENT_IO_ACTION Action
);

参数

[in] IoTarget

本地或远程 I/O 目标对象的句柄，该对象是从上一次调用 WdfDeviceGetIoTarget 或 WdfIoTargetCreate 获取的，或者从专用 I/O 目标提供的方法获取的。

[in] Action

一个WDF_IO_TARGET_SENT_IO_ACTION类型的值，该值指定框架应如何处理驱动程序已发送到 I/O 目标的 I/O 请求（如果目标尚未完成请求）。

返回值

无

备注

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

如果驱动程序可以检测到可恢复的设备错误，你可能希望驱动程序调用 WdfIoTargetStop 以暂时停止发送请求，然后稍后调用 WdfIoTargetStart 以继续发送请求。

停止后，I/O 目标将继续接受新请求，但不会将排队的请求传送到相应的驱动程序。

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

如果驱动程序调用 WdfUsbTargetPipeConfigContinuousReader 为 USB 管道配置连续读取器，则驱动程序的 EvtDeviceD0Exit 回调函数必须调用 WdfIoTargetStop 来停止读取器。

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

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

驱动程序必须同步调用 WdfIoTargetStart 和 WdfIoTargetStop 。在驱动程序调用其中一个函数后，它不得在第一个调用返回之前调用任一函数。

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

调用 WdfIoTargetStop 并将 Action 值指定为 WdfIoTargetLeaveSentIoPending。
确定目标是否应继续处理 I/O 请求。
如果目标应恢复，请调用 WdfIoTargetStart。否则，请使用 Action 值为 WdfIoTargetCancelSentIo 再次调用 WdfIoTargetStop。

注意WdfIoTargetStop 不是线程安全的。从不同的线程同时调用 WdfIoTargetStop 是不安全的。

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

如果驱动程序为管道调用了 WdfUsbTargetPipeConfigContinuousReader ，则必须在 IRQL = PASSIVE_LEVEL调用 WdfIoTargetStop 。

如果驱动程序尚未调用 WdfUsbTargetPipeConfigContinuousReader，并且 WdfIoTargetStop 的 Action 参数为 WdfIoTargetLeaveSentIoPending，则可以在 IRQL <= DISPATCH_LEVEL调用 WdfIoTargetStop。否则，在 IRQL = PASSIVE_LEVEL 调用 WdfIoTargetStop 。

示例

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

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

    WdfIoTargetStop(
                    WdfUsbTargetPipeGetIoTarget(pDeviceContext->InterruptPipe),
                    WdfIoTargetCancelSentIo
                    );

    return STATUS_SUCCESS;
}

要求

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