IWDFUsbTargetPipe2：：ConfigureContinuousReader 方法（wudfusb.h）
[警告： UMDF 2 是最新版本的 UMDF，取代了 UMDF 1。 所有新的 UMDF 驱动程序都应使用 UMDF 2 编写。 没有将新功能添加到 UMDF 1，并且对较新版本的 Windows 10 上的 UMDF 1 的支持有限。 通用 Windows 驱动程序必须使用 UMDF 2。 有关详细信息，请参阅 UMDF入门 。]
ConfigureContinuousReader 方法将框架配置为从 USB 管道连续读取。
语法
HRESULT ConfigureContinuousReader(
[in] SIZE_T TransferLength,
[in] SIZE_T HeaderLength,
[in] SIZE_T TrailerLength,
[in] UCHAR NumPendingReads,
[in, optional] IUnknown *pMemoryCleanupCallbackInterface,
[in] IUsbTargetPipeContinuousReaderCallbackReadComplete *pOnCompletion,
[in, optional] PVOID pCompletionContext,
[in, optional] IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailure
);
参数
[in] TransferLength
可从设备接收的数据的最大长度（以字节为单位）。
[in] HeaderLength
从设备接收数据的缓冲区中的偏移量（以字节为单位）。 从偏移值开始，框架会将设备中的数据存储在读取缓冲区中。 换句话说，此空间位于 TransferLength大小的空间，框架在其中存储来自设备的数据。
[in] TrailerLength
尾随缓冲区空间的长度（以字节为单位）。 此空间遵循 TransferLength大小的空间，框架在其中存储来自设备的数据。
[in] NumPendingReads
框架将排队接收来自 I/O 目标的数据的读取请求数。 如果此值为零，框架将使用默认数量的读取请求。 如果指定的值大于允许的最大值，框架将使用允许的最大值。 有关 NumPendingReads 参数的详细信息，请参阅以下“备注”部分。
[in, optional] pMemoryCleanupCallbackInterface
指向框架用来访问可选 IObjectCleanup：：OnCleanup 回调函数的驱动程序提供的 IUnkown 接口的指针。 当框架解除分配读取缓冲区以处理连续读取作时，框架将调用回调函数。 此参数是可选的，可以 NULL。
[in] pOnCompletion
指向驱动程序提供的 IUsbTargetPipeContinuousReaderCallbackReadComplete 接口的指针，该接口提供 OnReaderCompletion 回调函数。
[in, optional] pCompletionContext
指向驱动程序定义的上下文信息的非类型化指针，框架将传递给驱动程序的 IUsbTargetPipeContinuousReaderCallbackReadComplete：：OnReaderCompletion 回调函数。
[in, optional] pOnFailure
指向驱动程序提供的 IUsbTargetPipeContinuousReaderCallbackReadersFailed 接口的指针，该接口提供 OnReaderFailure 回调函数。
返回值
ConfigureContinuousReader 如果作成功，则返回S_OK。 否则，此方法可以返回以下值之一：
| 返回代码 | 描述 |
|---|---|
|
驱动程序已为 USB 管道配置连续读取器。
USB 管道未为批量传输或中断输入传输设置。 |
|
框架尝试分配缓冲区失败。 |
|
TransferLength、HeaderLength或 TrailerLength 参数指定了太大或无效的大小。 |
此方法可能会返回 Winerror.h 包含的其他值之一。
言论
可以为大容量管道或中断管道配置连续读取器。 管道必须具有输入终结点。
调用 ConfigureContinuousReader 以配置连续读取器后，驱动程序必须调用 IWDFIoTargetStateManagement：：Start 来启动读取器。 若要停止读取器，驱动程序必须调用 IWDFIoTargetStateManagement：：Stop。
通常，驱动程序从其 IPnpCallbackHardware：：OnPrepareHardware 回调函数中调用 ConfigureContinuousReader。 驱动程序应从其 IPnpCallback：：OnD0Entry 回调函数内调用 IWDFIoTargetStateManagement：：Stop，并从其 IPnpCallback：：OnD0Exit 回调函数中调用 IWDFIoTargetStateManagement：：Stop。
每次管道的 I/O 目标成功完成读取请求时，框架都会调用驱动程序的 IUsbTargetPipeContinuousReaderCallbackReadComplete：：OnReaderCompletion 回调函数。 如果 I/O 目标在处理请求时报告失败，框架会在完成所有读取请求后调用驱动程序的 IUsbTargetPipeContinuousReaderCallbackReadersFailed：：OnReaderFailure 回调函数。 （因此，在执行 OnReaderFailure 回调函数时，将不会调用 OnReaderCompletion 回调函数。
使用以下准则为 NumPendingReads 参数选择值：
-
如果希望驱动程序使用框架的默认值，请将 NumPendingReads 设置为零。
默认值大于 1，为许多处理器配置上的许多设备提供合理的性能。
-
如果将 NumPendingReads 设置为 NumPendingReads（如果驱动程序按设备传送数据的确切顺序接收数据缓冲区很重要）。
如果框架对多个读取请求进行排队，驱动程序可能不会按照设备传送数据的顺序接收数据缓冲区。
-
根据全面的性能度量，将 NumPendingReads 设置为满足设备性能要求的数字。
首先，使用 NumPendingReads的默认值 （0） 测试设备。 测试应包括各种硬件配置，包括不同类型的处理器和数量，以及不同的 USB 主机控制器和 USB 配置。 然后，可以使用相同的测试来试验更高的值。 可能需要较高值的驱动程序是具有高中断率的设备，如果中断未快速提供服务，可能会丢失数据。
在驱动程序调用 ConfigureContinuousReader后，驱动程序无法使用 IWDFIoRequest：：Send 将 I/O 请求发送到管道，除非驱动程序的 IUsbTargetPipeContinuousReaderCallbackReadersFailed：：OnReaderFailure 回调函数被调用并返回 FALSE。
有关 ConfigureContinuousReader 方法和 USB I/O 目标的详细信息，请参阅 从 UMDF-USB 管道读取。
例子
下面的代码示例配置连续读取器。 在此示例中，最大缓冲区大小是驱动程序定义的缓冲区的大小。 标头和尾部缓冲区偏移量设置为零，挂起的读取作数设置为 2。 该示例使用目标管道的接口指针作为 pCompletionContext 参数，因此 OnReaderCompletion 回调函数可以确定读取作完成的管道。
HRESULT hr, hrQI;
IUsbTargetPipeContinuousReaderCallbackReadComplete *pOnCompletionCallback = NULL;
IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailureCallback= NULL;
IWDFUsbTargetPipe2 * pIUsbInterruptPipe2;
//
// Obtain interfaces.
//
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnCompletionCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnFailureCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = m_pIUsbInterruptPipe->QueryInterface(IID_PPV_ARGS(&pIUsbInterruptPipe2));
if (!SUCCEEDED(hrQI)) goto Error;
//
// Configure the reader.
//
hr = pIUsbInterruptPipe2->ConfigureContinuousReader(
sizeof(m_MyBuffer),
0,
0,
2,
NULL,
pOnCompletionCallback,
m_pIUsbTargetPipe,
pOnFailureCallback
);
...
要求
| 要求 | 价值 |
|---|---|
| 终止支持 | 在 UMDF 2.0 及更高版本中不可用。 |
| 目标平台 | 桌面 |
| 最低 UMDF 版本 | 1.9 |
| 标头 | wudfusb.h （包括 Wudfusb.h） |
| DLL | WUDFx.dll |
另请参阅
IPnpCallbackHardware：：OnPrepareHardware
IUsbTargetPipeContinuousReaderCallbackReadComplete：：OnReaderCompletion
IUsbTargetPipeContinuousReaderCallbackReadersFailed：：OnReaderFailure
IWDFIoTargetStateManagement：：Start