通过

EVT_WDF_USB_READER_COMPLETION_ROUTINE回调函数 （wdfusb.h）

[适用于 KMDF 和 UMDF]

驱动程序的 EvtUsbTargetPipeReadComplete 事件回调函数通知驱动程序连续读取器已成功完成读取请求。

语法

EVT_WDF_USB_READER_COMPLETION_ROUTINE EvtWdfUsbReaderCompletionRoutine;

VOID EvtWdfUsbReaderCompletionRoutine(
  [in] WDFUSBPIPE Pipe,
  [in] WDFMEMORY Buffer,
  [in] size_t NumBytesTransferred,
  [in] WDFCONTEXT Context
)
{...}

参数

[in] Pipe

框架管道对象的句柄。

[in] Buffer

框架内存对象的句柄，表示包含来自设备的数据的缓冲区。

[in] NumBytesTransferred

读取缓冲区中的数据字节数。

[in] Context

EvtUsbTargetPipeReadCompleteContext 中指定的驱动程序定义的上下文信息 管道 WDF_USB_CONTINUOUS_READER_CONFIG 结构的成员。

返回值

没有

言论

若要注册 EvtUsbTargetPipeReadComplete 回调函数，驱动程序必须将函数的地址置于 WDF_USB_CONTINUOUS_READER_CONFIG 结构中。

如果驱动程序为 USB 管道创建了连续读取器，则框架会在驱动程序的 I/O 目标成功完成读取请求时调用驱动程序的 EvtUsbTargetPipeReadComplete 回调函数。 回调函数在 I/O 目标完成读取请求的 IRQL 中调用，该请求通常是 IRQL = DISPATCH_LEVEL，但不超过 DISPATCH_LEVEL。 （如果 I/O 目标未成功完成请求，框架将调用驱动程序的 EvtUsbTargetPipeReadersFailed 回调函数。

若要访问包含从设备读取数据的缓冲区，驱动程序可以调用 WdfMemoryGetBuffer。 框架将数据写入缓冲区，在 WDF_USB_CONTINUOUS_READER_CONFIG 结构 HeaderLength 成员定义的标头之后。 请注意，WdfMemoryGetBuffer 返回指向标头开头的指针，但 EvtUsbTargetPipeReadComplete 回调函数的 NumBytesTransferred 参数 不包含标头的长度。

默认情况下，框架在 EvtUsbTargetPipeReadComplete 回调函数返回后删除缓冲区的内存对象。 但是，你可能希望内存对象在回调函数返回后保持有效。 例如，你可能希望驱动程序将对象句柄存储在框架管道对象的上下文空间中，以便驱动程序可以在回调函数返回后处理内存对象的内容。 若要延长内存对象的生存期，回调函数必须将内存对象的句柄传递给 WdfObjectReference。 随后，驱动程序必须调用 WdfObjectDereference，以便框架可以删除对象。

框架根据以下规则同步对 EvtUsbTargetPipeReadComplete 和 EvtUsbTargetPipeReadersFailed 回调函数的调用：

  • 这些回调函数不会为单个 USB 管道同时运行。
  • 如果驱动程序为多个 USB 管道创建多个连续读取器，则多个 EvtUsbTargetPipeReadComplete 和 EvtUsbTargetPipeReadersFailed 回调函数，则多个回调函数可以同时运行。
  • 如果驱动程序指定了默认 NumPendingReads 值或大于 1 的值，并且读取请求在 EvtUsbTargetPipeReadComplete 回调函数执行时完成，则框架可以在回调函数返回之前再次调用 EvtUsbTargetPipeReadComplete 回调函数。
  • 框架不会将这些回调函数与任何其他回调函数同步。
在 BufferAttributesWDF_USB_CONTINUOUS_READER_CONFIG 结构的成员中，驱动程序可以为内存对象指定 EvtCleanupCallback 和 EvtDestroyCallback 回调函数。 如果指定 EvtCleanupCallback 回调函数，则框架将在尝试删除内存对象时调用该回调函数，EvtUsbTargetPipeReadComplete 回调函数返回。 如果 EvtUsbTargetPipeReadComplete 回调函数调用 WdfObjectReference，则 EvtCleanupCallback 回调函数（如果提供）不得调用 WdfObjectDereference。

驱动程序在使用完内存对象后，必须调用 WdfObjectDereference。 然后，框架可以调用驱动程序的 EvtDestroyCallback 回调函数（如果提供），并删除内存对象。

有关 EvtUsbTargetPipeReadComplete 回调函数和 USB I/O 目标的详细信息，请参阅 USB I/O 目标。

要求

要求 价值
目标平台 普遍
最低 KMDF 版本 1.0
最低 UMDF 版本 2.0
标头 wdfusb.h （包括 Wdf.h）
IRQL <=DISPATCH_LEVEL（请参阅“备注”部分）。

另请参阅

EvtUsbTargetPipeReadersFailed

WDF_USB_CONTINUOUS_READER_CONFIG

WdfMemoryGetBuffer