WdfUsbTargetPipeConfigContinuousReader function (wdfusb.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfUsbTargetPipeConfigContinuousReader method configures the framework to continuously read from a specified USB pipe.

Syntax

NTSTATUS WdfUsbTargetPipeConfigContinuousReader(
  [in] WDFUSBPIPE                        Pipe,
  [in] PWDF_USB_CONTINUOUS_READER_CONFIG Config
);

Parameters

[in] Pipe

A handle to a framework pipe object that was obtained by calling WdfUsbInterfaceGetConfiguredPipe.

[in] Config

A pointer to a caller-allocated WDF_USB_CONTINUOUS_READER_CONFIG structure.

Return value

WdfUsbTargetPipeConfigContinuousReader returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method can return one of the following values:

Return code	Description
STATUS_INFO_LENGTH_MISMATCH	The size of the WDF_USB_CONTINUOUS_READER_CONFIG structure that the Config parameter specified was incorrect.
STATUS_INVALID_PARAMETER	An invalid parameter was detected.
STATUS_INSUFFICIENT_RESOURCES	Insufficient memory was available.
STATUS_INVALID_DEVICE_REQUEST	The pipe's type was not valid.
STATUS_INTEGER_OVERFLOW	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.
STATUS_INVALID_BUFFER_SIZE	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.

Remarks

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.

Examples

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
                                      );

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfusb.h (include Wdfusb.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf), FailD0EntryIoTargetState(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbContReader(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Share via