IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion method (wudfusb.h)

Article
10/21/2021

[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]

A driver's OnReaderCompletion event callback function informs the driver that a continuous reader has successfully completed a read request.

Syntax

void OnReaderCompletion(
  [in] IWDFUsbTargetPipe *pPipe,
  [in] IWDFMemory        *pMemory,
  [in] SIZE_T            NumBytesTransferred,
  [in] PVOID             Context
);

Parameters

[in] pPipe

A pointer to the IWDFUsbTargetPipe interface for the USB pipe on which the driver has enabled a continuous reader.

[in] pMemory

A pointer to the IWDFMemory interface for a read buffer that contains data that was read from the USB pipe.

[in] NumBytesTransferred

The number of bytes that the read buffer contains.

[in] Context

A pointer to driver-supplied context information that the driver provided when it previously called IWDFUsbTargetPipe2::ConfigureContinuousReader.

Return value

None

Remarks

To register an IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion callback function, your driver must provide a pointer to the driver's IUsbTargetPipeContinuousReaderCallbackReadComplete interface when it calls IWDFUsbTargetPipe2::ConfigureContinuousReader.

If a driver has created a continuous reader for a USB pipe, the framework calls the driver's OnReaderCompletion callback function each time the driver's I/O target successfully completes a read request. If the I/O target does not successfully complete a request, the framework calls the driver's IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure callback function.

To access the buffer that contains data that was read from the device, the driver can call IWDFMemory::GetDataBuffer. The framework writes the data into the buffer, after the header that is defined by the HeaderLength parameter of IWDFUsbTargetPipe2::ConfigureContinuousReader. Note that the pointer that IWDFMemory::GetDataBuffer returns points to the beginning of the header, but the OnReaderCompletion callback function's NumBytesTransferred parameter does not include the header's length.

By default, the framework deletes the buffer's memory object after the OnReaderCompletion 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 memory object's interface pointer 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 call the buffer's IWDFMemory::AddRef method. Subsequently, the driver must call the buffer's IWDFMemory::Release method so that the framework can delete the object.

The framework synchronizes calls to the OnReaderCompletion and IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure 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 OnReaderCompletion and OnReaderFailure callback functions, the multiple callback functions can run simultaneously.
If the driver has specified the default NumPendingReads value when it calls IWDFUsbTargetPipe2::ConfigureContinuousReader (or if it specifies any NumPendingReads value that is greater than 1), and if a read request completes while the OnReaderCompletion callback function is executing, the framework can call the OnReaderCompletion callback function again before the callback function returns.
The framework does not synchronize these callback functions with any other callback functions.

When your driver calls IWDFUsbTargetPipe2::ConfigureContinuousReader, it can specify an IObjectCleanup::OnCleanup callback function. The framework will call that callback function when it attempts to delete the memory object, after the OnReaderCompletion callback function returns.

For more information about the OnReaderCompletion callback function and USB I/O targets, see Handling a USB I/O Target.

Requirements

Requirement	Value
End of support	Unavailable in UMDF 2.0 and later.
Target Platform	Desktop
Minimum UMDF version	1.9
Header	wudfusb.h (include Wudfusb.h)