| UID | title | description | old-location | tech.root | ms.date | keywords | ms.keywords | req.header | req.include-header | req.target-type | req.target-min-winverclnt | req.target-min-winversvr | req.kmdf-ver | req.umdf-ver | req.ddi-compliance | req.unicode-ansi | req.idl | req.max-support | req.namespace | req.assembly | req.type-library | req.lib | req.dll | req.irql | targetos | req.typenames | f1_keywords | topic_type | api_type | api_location | api_name | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
NF:wudfusb.IWDFUsbTargetPipe2.ConfigureContinuousReader |
IWDFUsbTargetPipe2::ConfigureContinuousReader (wudfusb.h) |
The ConfigureContinuousReader method configures the framework to continuously read from a USB pipe. |
wdf\iwdfusbtargetpipe2_configurecontinuousreader.htm |
wdf |
02/26/2018 |
|
ConfigureContinuousReader, ConfigureContinuousReader method, ConfigureContinuousReader method,IWDFUsbTargetPipe2 interface, IWDFUsbTargetPipe2 interface,ConfigureContinuousReader method, IWDFUsbTargetPipe2.ConfigureContinuousReader, IWDFUsbTargetPipe2::ConfigureContinuousReader, UMDFUSBref_fbf1e16d-97a6-43c4-b667-a4715769009b.xml, umdf.iwdfusbtargetpipe2_configurecontinuousreader, wdf.iwdfusbtargetpipe2_configurecontinuousreader, wudfusb/IWDFUsbTargetPipe2::ConfigureContinuousReader |
wudfusb.h |
Wudfusb.h |
Desktop |
1.9 |
Unavailable in UMDF 2.0 and later. |
WUDFx.dll |
Windows |
|
|
|
|
|
[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.]
The ConfigureContinuousReader method configures the framework to continuously read from a USB pipe.
The maximum length, in bytes, of data that can be received from the device.
An offset, in bytes, into the buffer that receives data from the device. The framework will store data from the device in a read buffer, beginning at the offset value. In other words, this space precedes the TransferLength-sized space in which the framework stores data from the device.
The length, in bytes, of a trailing buffer space. This space follows the TransferLength-sized space in which the framework stores data from the device.
The number of read requests that the framework will queue to receive data from the I/O target. If this value is zero, the framework uses a default number of read requests. If the specified value is greater than the permitted maximum value, the framework uses the permitted maximum value. For more information about the NumPendingReads parameter, see the following Remarks section.
A pointer to a driver-supplied IUnkown interface that the framework uses to access an optional IObjectCleanup::OnCleanup callback function. The framework calls the callback function when it deallocates the read buffer that it creates to handle the continuous read operation. This parameter is optional and can be NULL.
A pointer to a driver-supplied IUsbTargetPipeContinuousReaderCallbackReadComplete interface that provides an OnReaderCompletion callback function.
An untyped pointer to driver-defined context information that the framework passes to the driver's IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion callback function.
A pointer to a driver-supplied IUsbTargetPipeContinuousReaderCallbackReadersFailed interface that provides an OnReaderFailure callback function.
ConfigureContinuousReader returns S_OK if the operation succeeds. Otherwise, this method can return one of the following values:
| Return code | Description |
|---|---|
|
The driver has already configured a continuous reader for the USB pipe.
The USB pipe is not set up for bulk or interrupt input transfers. |
|
The framework's attempt to allocate a buffer failed. |
|
The TransferLength, HeaderLength, or TrailerLength parameter specified a size that was too large or otherwise invalid. |
This method might return one of the other values that Winerror.h contains.
You can configure a continuous reader for a bulk pipe or an interrupt pipe. The pipe must have an input endpoint.
After calling ConfigureContinuousReader to configure a continuous reader, your driver must call IWDFIoTargetStateManagement::Start to start the reader. To stop the reader, the driver must call IWDFIoTargetStateManagement::Stop.
Typically, a driver calls ConfigureContinuousReader from within its IPnpCallbackHardware::OnPrepareHardware callback function. The driver should call IWDFIoTargetStateManagement::Start from within its IPnpCallback::OnD0Entry callback function and should call IWDFIoTargetStateManagement::Stop from within its IPnpCallback::OnD0Exit callback function.
Each time the pipe's I/O target successfully completes a read request, the framework calls the driver's IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion callback function. If the I/O target reports a failure while processing a request, the framework calls the driver's IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure callback function after all read requests have been completed. (Therefore, the OnReaderCompletion callback function will not be called while the OnReaderFailure callback function is executing.)
Use the following guidelines to choose a value for the NumPendingReads parameter:
-
Set NumPendingReads to zero if you want your driver to use the framework's default value.
The default value is greater than one and provides reasonably good performance for many devices on many processor configurations.
-
Set NumPendingReads to one if it is important that your driver receive data buffers in the exact order in which the device delivers the data.
If the framework queues more than one read request, the driver might not receive the data buffers in same the order in which the device delivers the data.
-
Set NumPendingReads to a number that meets the performance requirements for your device, based on thorough performance measurements.
First, test your device with the default value (0) for NumPendingReads. Your tests should include various hardware configurations, including different types and numbers of processors, and different USB host controllers and USB configurations. You can then experiment with higher values, using the same tests. A driver that might require a higher value is one for a device that has a high interrupt rate, where data can be lost if interrupts are not serviced rapidly.
After a driver has called ConfigureContinuousReader, the driver cannot use IWDFIoRequest::Send to send I/O requests to the pipe unless the driver's IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure callback function is called and returns FALSE.
For more information about the ConfigureContinuousReader method and USB I/O targets, see Reading from a UMDF-USB Pipe.
The following code example configures a continuous reader. In this example, the maximum buffer size is the size of a driver-defined buffer. The header and trailer buffer offsets are set to zero, and the number of pending read operations is set to two. The example uses the target pipe's interface pointer for the pCompletionContext parameter, so the OnReaderCompletion callback function can determine the pipe on which the read operation was completed.
HRESULT hr, hrQI;
IUsbTargetPipeContinuousReaderCallbackReadComplete *pOnCompletionCallback = NULL;
IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailureCallback= NULL;
IWDFUsbTargetPipe2 * pIUsbInterruptPipe2;
//
// Obtain interfaces.
//
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnCompletionCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnFailureCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = m_pIUsbInterruptPipe->QueryInterface(IID_PPV_ARGS(&pIUsbInterruptPipe2));
if (!SUCCEEDED(hrQI)) goto Error;
//
// Configure the reader.
//
hr = pIUsbInterruptPipe2->ConfigureContinuousReader(
sizeof(m_MyBuffer),
0,
0,
2,
NULL,
pOnCompletionCallback,
m_pIUsbTargetPipe,
pOnFailureCallback
);
...
IPnpCallbackHardware::OnPrepareHardware
IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion
IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure
IWDFIoTargetStateManagement::Start