EVT_WDF_USB_READER_COMPLETION_ROUTINE callback function (wdfusb.h)
[Applies to KMDF and UMDF]
A driver's EvtUsbTargetPipeReadComplete event callback function informs the driver that a continuous reader has successfully completed a read request.
Syntax
EVT_WDF_USB_READER_COMPLETION_ROUTINE EvtWdfUsbReaderCompletionRoutine;
void EvtWdfUsbReaderCompletionRoutine(
[in] WDFUSBPIPE Pipe,
[in] WDFMEMORY Buffer,
[in] size_t NumBytesTransferred,
[in] WDFCONTEXT Context
)
{...}
Parameters
[in] Pipe
A handle to a framework pipe object.
[in] Buffer
A handle to a framework memory object that represents a buffer that contains data from the device.
[in] NumBytesTransferred
The number of bytes of data that are in the read buffer.
[in] Context
Driver-defined context information that the driver specified in the EvtUsbTargetPipeReadCompleteContext member of the pipe's WDF_USB_CONTINUOUS_READER_CONFIG structure.
Return value
None
Remarks
To register an EvtUsbTargetPipeReadComplete callback function, the driver must place the function's address in a WDF_USB_CONTINUOUS_READER_CONFIG structure.
If a driver has created a continuous reader for a USB pipe, the framework calls the driver's EvtUsbTargetPipeReadComplete callback function each time the driver's I/O target successfully completes a read request. The callback function is called at the IRQL at which the I/O target completed the read request, which is typically IRQL = DISPATCH_LEVEL, but no higher than DISPATCH_LEVEL. (If the I/O target does not successfully complete a request, the framework calls the driver's EvtUsbTargetPipeReadersFailed callback function.)
To access the buffer that contains data that was read from the device, the driver can call WdfMemoryGetBuffer. The framework writes the data into the buffer, after the header that is defined by the HeaderLength member of the WDF_USB_CONTINUOUS_READER_CONFIG structure. Note that the pointer that WdfMemoryGetBuffer returns points to the beginning of the header, but the EvtUsbTargetPipeReadComplete callback function's NumBytesTransferred parameter does not include the header's length.
By default, the framework deletes the buffer's memory object after the EvtUsbTargetPipeReadComplete callback function returns. However, you might want the memory object to remain valid after the callback function returns. For example, you might want your driver to store the object handle in the framework pipe object's context space so that the driver can process the memory object's contents after the callback function returns. To extend the lifetime of the memory object, the callback function must pass the memory object's handle to WdfObjectReference. Subsequently, the driver must call WdfObjectDereference so that the framework can delete the object.
The framework synchronizes calls to the EvtUsbTargetPipeReadComplete and EvtUsbTargetPipeReadersFailed callback functions according to the following rules:
- These callback functions do not run simultaneously for an individual USB pipe.
- If the driver creates multiple continuous readers for multiple USB pipes, with multiple EvtUsbTargetPipeReadComplete and EvtUsbTargetPipeReadersFailed callback functions, the multiple callback functions can run simultaneously.
- If the driver has specified the default NumPendingReads value or a value that is greater than 1, and if a read request completes while the EvtUsbTargetPipeReadComplete callback function is executing, the framework can call the EvtUsbTargetPipeReadComplete callback function again before the callback function returns.
- The framework does not synchronize these callback functions with any other callback functions.
The driver must call WdfObjectDereference when it has finished using the memory object. The framework can then call the driver's EvtDestroyCallback callback function (if provided) and delete the memory object.
For more information about the EvtUsbTargetPipeReadComplete callback function and USB I/O targets, see USB I/O Targets.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Minimum KMDF version | 1.0 |
| Minimum UMDF version | 2.0 |
| Header | wdfusb.h (include Wdf.h) |
| IRQL | <=DISPATCH_LEVEL (See Remarks section.) |