WdfUsbTargetPipeConfigContinuousReader 函数 (wdfusb.h)

项目
02/29/2024

[适用于 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	指定的 Config 参数不正确WDF_USB_CONTINUOUS_READER_CONFIG结构的大小。
STATUS_INVALID_PARAMETER	检测到无效的参数。
STATUS_INSUFFICIENT_RESOURCES	可用内存不足。
STATUS_INVALID_DEVICE_REQUEST	管道的类型无效。
STATUS_INTEGER_OVERFLOW	Config 参数指定的大小过大或无效的 WDF_USB_CONTINUOUS_READER_CONFIG 结构的 HeaderLength、TransferLength 或 TrailerLength 成员。
STATUS_INVALID_BUFFER_SIZE	读取缓冲区的大小不是管道最大数据包大小的倍数。

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

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

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

注解

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

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

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

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

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

驱动程序调用 WdfUsbTargetPipeConfigContinuousReader 后，驱动程序无法使用 WdfUsbTargetPipeReadSynchronously 或 WdfRequestSend 将 I/O 请求发送到管道，除非连续读取器已停止。若要停止读取器，驱动程序可以调用 WdfIoTargetStop 或从其 EvtUsbTargetPipeReadersFailed 回调函数返回 FALSE。如果在读取器停止时驱动程序调用 WdfUsbTargetPipeReadSynchronous，则必须在 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)
Library	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)