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

指向驱动程序提供的 IUnkown 接口的指针，框架使用该接口访问可选的 IObjectCleanup：：OnCleanup 回调函数。 框架在解除分配为处理连续读取操作而创建的读取缓冲区时调用回调函数。 此参数是可选的，可以为 NULL。

[in] pOnCompletion

指向驱动程序提供的 IUsbTargetPipeContinuousReaderCallbackReadComplete 接口的指针，该接口提供 OnReaderCompletion 回调函数。

[in, optional] pCompletionContext

指向驱动程序定义的上下文信息的非类型化指针，框架将该信息传递给驱动程序的 IUsbTargetPipeContinuousReaderCallbackReadComplete：：OnReaderCompletion 回调函数。

[in, optional] pOnFailure

指向驱动程序提供的 IUsbTargetPipeContinuousReaderCallbackReadersFailed 接口的指针，该接口提供 OnReaderFailure 回调函数。

返回值

如果操作成功，ConfigureContinuousReader 将返回S_OK。 否则，此方法可以返回以下值之一：

返回代码 说明
HRESULT_FROM_NT (STATUS_INVALID_DEVICE_STATE)
驱动程序已为 USB 管道配置连续读卡器。

USB 管道未设置为批量传输或中断输入传输。
E_OUTOFMEMORY
 框架分配缓冲区的尝试失败。
ERROR_ARITHMETIC_OVERFLOW
 TransferLength、HeaderLength 或 TrailerLength 参数指定的大小过大或无效。
 

此方法可能会返回 Winerror.h 包含的其他值之一。

注解

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

调用 ConfigureContinuousReader 以配置连续读取器后，驱动程序必须调用 IWDFIoTargetStateManagement：：Start 来启动读取器。 若要停止读取器，驱动程序必须调用 IWDFIoTargetStateManagement：：Stop。

通常，驱动程序从其 IPnpCallbackHardware：：OnPrepareHardware 回调函数中调用 ConfigureContinuousReader。 驱动程序应从其 IPnpCallback：：OnD0Entry 回调函数内调用 IWDFIoTargetStateManagement：：Start，并应从其 IPnpCallback：：OnD0Exit 回调函数中调用 IWDFIoTargetStateManagement：：Stop。

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

使用以下准则为 NumPendingReads 参数选择值：

  • 如果希望驱动程序使用框架的默认值，请将 NumPendingReads 设置为零。

    默认值大于 1，并且为许多处理器配置上的许多设备提供相当良好的性能。

  • 如果驱动程序必须按照设备传送数据的确切顺序接收数据缓冲区，请将 NumPendingReads 设置为 1。

    如果框架将多个读取请求排队，驱动程序接收数据缓冲区的顺序可能与设备传送数据的顺序不同。

  • 根据全面的性能度量值，将 NumPendingReads 设置为满足设备性能要求的数字。

    首先，使用 NumPendingReads 的默认值 (0) 测试设备。 测试应包括各种硬件配置，包括不同的处理器类型和数量，以及不同的 USB 主机控制器和 USB 配置。 然后，可以使用相同的测试来试验更高的值。 可能需要较高值的驱动程序是中断率较高的设备的驱动程序，如果未快速维护中断，则可能会丢失数据。

NumPendingReads 值过大可能会降低系统的性能。 应使用满足性能要求的最低值。 通常，大于 3 或 4 的值不会提高数据吞吐量。 但较高的值可能会降低高频率管道上的延迟或丢失数据的可能性。

驱动程序调用 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

另请参阅

IPnpCallback：：OnD0Entry

IPnpCallback：：OnD0Exit

IPnpCallbackHardware：：OnPrepareHardware

IUsbTargetPipeContinuousReaderCallbackReadComplete：：OnReaderCompletion

IUsbTargetPipeContinuousReaderCallbackReadersFailed：：OnReaderFailure

IWDFIoTargetStateManagement：：Start

IWDFIoTargetStateManagement：：Stop

IWDFUsbTargetPipe2