WdfUsbTargetPipeConfigContinuousReader method

[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

Pipe [in]

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

Config [in]

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:

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

See also

EvtDeviceD0Entry

EvtDeviceD0Exit

EvtDevicePrepareHardware

EvtUsbTargetPipeReadComplete

EvtUsbTargetPipeReadersFailed

URB

WDF_USB_CONTINUOUS_READER_CONFIG

WDF_USB_CONTINUOUS_READER_CONFIG_INIT

WdfIoTargetStart

WdfIoTargetStop

WdfUsbInterfaceGetConfiguredPipe

Send comments about this topic to Microsoft