WdfUsbTargetPipeConfigContinuousReader 函数（wdfusb.h）

项目
02/07/2025

[适用于 KMDF 和 UMDF]

WdfUsbTargetPipeConfigContinuousReader 方法将框架配置为从指定的 USB 管道连续读取。

语法

NTSTATUS WdfUsbTargetPipeConfigContinuousReader(
  [in] WDFUSBPIPE                        Pipe,
  [in] PWDF_USB_CONTINUOUS_READER_CONFIG Config
);

参数

[in] Pipe

通过调用 WdfUsbInterfaceGetConfiguredPipe获取的框架管道对象的句柄。

[in] Config

指向调用方分配 WDF_USB_CONTINUOUS_READER_CONFIG 结构的指针。

返回值

如果作成功，WdfUsbTargetPipeConfigContinuousReader 返回STATUS_SUCCESS。否则，此方法可以返回以下值之一：

返回代码	描述
STATUS_INFO_LENGTH_MISMATCH	配置参数指定的 WDF_USB_CONTINUOUS_READER_CONFIG 结构的大小不正确。
STATUS_INVALID_PARAMETER	检测到无效参数。
STATUS_INSUFFICIENT_RESOURCES	内存不足。
STATUS_INVALID_DEVICE_REQUEST	管道的类型无效。
STATUS_INTEGER_OVERFLOW	HeaderLength、TransferLength或 TrailerLength 成员 WDF_USB_CONTINUOUS_READER_CONFIG 结构的成员，Config 参数指定了太大或无效的大小。
STATUS_INVALID_BUFFER_SIZE	读取缓冲区的大小不是管道最大数据包大小的倍数。

有关 WdfUsbTargetPipeConfigContinuousReader 方法可能返回的其他返回值的列表，请参阅 Framework 对象创建错误。

此方法还可以返回其他NTSTATUS 值。

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

言论

可以为大容量管道或中断管道配置连续读取器。管道必须具有输入终结点。

调用 WdfUsbTargetPipeConfigContinuousReader 以配置连续读取器后，驱动程序必须调用 WdfIoTargetStart 来启动读取器。若要停止读取器，驱动程序必须调用 WdfIoTargetStop。

通常，驱动程序从其 EvtDevicePrepareHardware 回调函数中调用 WdfUsbTargetPipeConfigContinuousReader。驱动程序应从其 EvtDeviceD0Entry 回调函数内调用 WdfIoTargetStart，并且应从其 EvtDeviceD0Exit 回调函数中调用 WdfIoTargetStop。

每当管道的 I/O 目标成功完成读取请求时，框架都会调用驱动程序的 EvtUsbTargetPipeReadComplete 回调函数。如果 I/O 目标在处理请求时报告失败，框架会在完成所有读取请求后调用驱动程序的 EvtUsbTargetPipeReadersFailed 回调函数。（因此，在执行 EvtUsbTargetPipeReadersFailed 回调函数时，将不会调用 EvtUsbTargetPipeReadlete 回调函数）。

如果未提供可选 EvtUsbTargetPipeReadersFailed 回调，则框架会通过发送另一个读取请求来响应失败的读取尝试。因此，如果总线处于不接受读取的状态，则框架会持续发送新请求以从失败的读取中恢复。

在驱动程序调用 WdfUsbTargetPipeConfigContinuousReader后，驱动程序无法使用 WdfUsbTargetPipeReadSynchronously 或 WdfRequestSend 向管道发送 I/O 请求，除非连续读取器已停止。若要停止读取器，驱动程序可以调用 WdfIoTargetStop 或从其 EvtUsbTargetPipeReadersFailed 回调函数返回 FALSE。如果驱动程序在读取器停止时 WdfUsbTargetPipeReadSynchronously 调用，则必须在 RequestOptions 参数的 Flags 成员中设置WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE标志。否则，请求将笔触，直到目标重新启动。

框架在其内部 URB中设置USBD_SHORT_TRANSFER_OK标志。设置此标志可让数据传输的最后一个数据包小于最大数据包大小。

有关 WdfUsbTargetPipeConfigContinuousReader 方法和 USB I/O 目标的详细信息，请参阅从管道读取。

例子

下面的代码示例初始化 WDF_USB_CONTINUOUS_READER_CONFIG 结构，并调用 WdfUsbTargetPipeConfigContinuousReader。

WDF_USB_CONTINUOUS_READER_CONFIG  contReaderConfig;
NTSTATUS  status;

WDF_USB_CONTINUOUS_READER_CONFIG_INIT(
                                      &contReaderConfig,
                                      OsrFxEvtUsbInterruptPipeReadComplete,
                                      DeviceContext,
                                      sizeof(UCHAR)
                                      );
status = WdfUsbTargetPipeConfigContinuousReader(
                                      Pipe,
                                      &contReaderConfig
                                      );

要求

要求	价值
目标平台	普遍
最低 KMDF 版本	1.0
最低 UMDF 版本	2.0
标头	wdfusb.h （包括 Wdfusb.h）
库	Wdf01000.sys（KMDF）：WUDFx02000.dll （UMDF）
IRQL	<=DISPATCH_LEVEL
DDI 符合性规则	DriverCreate（kmdf），FailD0EntryIoTargetState（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf），UsbContReader（kmdf），UsbKmdfIrql（kmdf），UsbKmdfIrql2（kmdf），UsbKmdfIrqlExplicit（kmdf）