WdfUsbTargetPipeConfigContinuousReader function (wdfusb.h)
[Applies to KMDF and UMDF]
The WdfUsbTargetPipeConfigContinuousReader method configures the framework to continuously read from a specified USB pipe.
NTSTATUS WdfUsbTargetPipeConfigContinuousReader( [in] WDFUSBPIPE Pipe, [in] PWDF_USB_CONTINUOUS_READER_CONFIG Config );
A handle to a framework pipe object that was obtained by calling WdfUsbInterfaceGetConfiguredPipe.
A pointer to a caller-allocated WDF_USB_CONTINUOUS_READER_CONFIG structure.
WdfUsbTargetPipeConfigContinuousReader returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method can return one of the following values:
||The size of the WDF_USB_CONTINUOUS_READER_CONFIG structure that the Config parameter specified was incorrect.|
||An invalid parameter was detected.|
||Insufficient memory was available.|
||The pipe's type was not valid.|
||The HeaderLength, TransferLength, or TrailerLength member of the WDF_USB_CONTINUOUS_READER_CONFIG structure that the Config parameter specified a size what was too large or otherwise invalid.|
||The size of the read buffer was not a multiple of the pipe's maximum packet size.|
For a list of other return values that the WdfUsbTargetPipeConfigContinuousReader method might return, see Framework Object Creation Errors.
This method also might return other NTSTATUS values.
A bug check occurs if the driver supplies an invalid object handle.
You can configure a continuous reader for a bulk pipe or an interrupt pipe. The pipe must have an input endpoint.
After calling WdfUsbTargetPipeConfigContinuousReader to configure a continuous reader, your driver must call WdfIoTargetStart to start the reader. To stop the reader, the driver must call WdfIoTargetStop.
Typically, a driver calls WdfUsbTargetPipeConfigContinuousReader from within its EvtDevicePrepareHardware callback function. The driver should call WdfIoTargetStart from within its EvtDeviceD0Entry callback function and should call WdfIoTargetStop from within its EvtDeviceD0Exit callback function.
Each time the pipe's I/O target successfully completes a read request, the framework calls the driver's EvtUsbTargetPipeReadComplete callback function. If the I/O target reports a failure while processing a request, the framework calls the driver's EvtUsbTargetPipeReadersFailed callback function after all read requests have been completed. (Therefore, the EvtUsbTargetPipeReadComplete callback function will not be called while the EvtUsbTargetPipeReadersFailed callback function is executing).
If you do not supply the optional EvtUsbTargetPipeReadersFailed callback, the framework responds to a failed read attempt by sending another read request. Therefore if the bus is in a state where it is not accepting reads, the framework continually sends new requests to recover from a failed read.
After a driver has called WdfUsbTargetPipeConfigContinuousReader, the driver cannot use WdfUsbTargetPipeReadSynchronously or WdfRequestSend to send I/O requests to the pipe unless the continuous reader has been stopped. To stop the reader, the driver can call WdfIoTargetStop or return FALSE from its EvtUsbTargetPipeReadersFailed callback function. If the driver calls WdfUsbTargetPipeReadSynchronously while the reader is stopped, it must set the WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE flag in the Flags member of the RequestOptions parameter. Otherwise the request will be pended until the target is restarted.
The framework sets the USBD_SHORT_TRANSFER_OK flag in its internal URB. Setting this flag allows the last packet of a data transfer to be less than the maximum packet size.
For more information about the WdfUsbTargetPipeConfigContinuousReader method and USB I/O targets, see Reading from a Pipe.
The following code example initializes a WDF_USB_CONTINUOUS_READER_CONFIG structure and calls WdfUsbTargetPipeConfigContinuousReader.
WDF_USB_CONTINUOUS_READER_CONFIG contReaderConfig; NTSTATUS status; WDF_USB_CONTINUOUS_READER_CONFIG_INIT( &contReaderConfig, OsrFxEvtUsbInterruptPipeReadComplete, DeviceContext, sizeof(UCHAR) ); status = WdfUsbTargetPipeConfigContinuousReader( Pipe, &contReaderConfig );
|Minimum KMDF version||1.0|
|Minimum UMDF version||2.0|
|Header||wdfusb.h (include Wdfusb.h)|
|Library||Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)|
|DDI compliance rules||DriverCreate(kmdf), FailD0EntryIoTargetState(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbContReader(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)|
Submit and view feedback for