WdfIoTargetStop 函数 (wdfiotarget.h)
[适用于 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。
如果驱动程序为管道调用了 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) |