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。 否则,此方法可以返回以下值之一:

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

USB 管道未设置用于批量传输或中断输入传输。

E_OUTOFMEMORY
框架尝试分配缓冲区失败。
ERROR_ARITHMETIC_OVERFLOW
TransferLength、HeaderLengthTrailerLength 参数指定了太大或无效的大小。
 

此方法可能会返回 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 回调函数。 (因此, OnReaderCompletion 回调函数在执行 OnReaderFailure 回调函数时不会调用。)

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

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

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

  • 如果将 NumPendingReads 设置为 NumPendingReads (如果驱动程序必须按照设备传送数据的确切顺序接收数据缓冲区),则将其设置为 NumPendingReads。

    如果框架对多个读取请求进行排队,驱动程序可能无法按照设备传送数据的顺序接收数据缓冲区。

  • 根据彻底的性能度量,将 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
Header wudfusb.h (包括 Wudfusb.h)
DLL WUDFx.dll

另请参阅

IPnpCallback::OnD0Entry

IPnpCallback::OnD0Exit

IPnpCallbackHardware::OnPrepareHardware

IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion

IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure

IWDFIoTargetStateManagement::Start

IWDFIoTargetStateManagement::Stop

IWDFUsbTargetPipe2