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

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

返回值

无

备注

若要注册 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 回调函数。
  • 框架不会将这些回调函数与任何其他回调函数同步。
在 WDF_USB_CONTINUOUS_READER_CONFIG 结构的 BufferAttributes 成员中，驱动程序可以为内存对象指定 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