Expand Minimize

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:

Return codeDescription
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

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, FailD0EntryIoTargetState, KmdfIrql, KmdfIrql2, UsbContReader, UsbKmdfIrql, UsbKmdfIrql2

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

Show:
© 2014 Microsoft