EVT_WDF_USB_READER_COMPLETION_ROUTINE - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
// wdfusb.h
EVT_WDF_USB_READER_COMPLETION_ROUTINE EvtWdfUsbReaderCompletionRoutine;
VOID EvtWdfUsbReaderCompletionRoutine(
[in] WDFUSBPIPE Pipe,
[in] WDFMEMORY Buffer,
[in] size_t NumBytesTransferred,
[in] WDFCONTEXT Context
)
{...}
View the official Windows Driver Kit DDI referenceNo description available.
[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.
Pipe [in]A handle to a framework pipe object.
Buffer [in]A handle to a framework memory object that represents a buffer that contains data from the device.
NumBytesTransferred [in]The number of bytes of data that are in the read buffer.
Context [in]Driver-defined context information that the driver specified in the EvtUsbTargetPipeReadCompleteContext member of the pipe's WDF_USB_CONTINUOUS_READER_CONFIG structure.
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:
In the BufferAttributes member of the WDF_USB_CONTINUOUS_READER_CONFIG structure, your driver can specify EvtCleanupCallback and EvtDestroyCallback callback functions for the memory object. If you specify an EvtCleanupCallback callback function, the framework will call that callback function when it attempts to delete the memory object, after the EvtUsbTargetPipeReadComplete callback function returns. If the EvtUsbTargetPipeReadComplete callback function has called WdfObjectReference, the EvtCleanupCallback callback function (if provided) must not call WdfObjectDereference.
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.
WDF_USB_CONTINUOUS_READER_CONFIG