EVT_WDF_USB_READERS_FAILED callback function (wdfusb.h)

Article
10/21/2021

[Applies to KMDF and UMDF]

A driver's EvtUsbTargetPipeReadersFailed event callback function informs the driver that a continuous reader has reported an error while processing a read request.

Syntax

EVT_WDF_USB_READERS_FAILED EvtWdfUsbReadersFailed;

BOOLEAN EvtWdfUsbReadersFailed(
  [in] WDFUSBPIPE Pipe,
  [in] NTSTATUS Status,
  [in] USBD_STATUS UsbdStatus
)
{...}

Parameters

[in] Pipe

A handle to a framework pipe object.

[in] Status

The NTSTATUS value that the pipe's I/O target returned.

[in] UsbdStatus

The USBD_STATUS-typed status value that the pipe's I/O target returned.

Return value

The EvtUsbTargetPipeReadersFailed event callback function returns a Boolean value that, if TRUE, causes the framework to reset the USB pipe and then restart the continuous reader. If this function returns FALSE, the framework does not reset the device or restart the continuous reader.

Remarks

To register an EvtUsbTargetPipeReadersFailed callback function, the driver must place the function's address in a WDF_USB_CONTINUOUS_READER_CONFIG structure. For information about when to add this function pointer, see the Remarks section of WDF_USB_CONTINUOUS_READER_CONFIG_INIT.

If a driver has created a continuous reader for a USB pipe, the framework calls the driver's EvtUsbTargetPipeReadersFailed callback function if the driver's I/O target reports an error when it completes a read request. (If the I/O target successfully completes the request, the framework calls the driver's EvtUsbTargetPipeReadComplete callback function.)

Before the framework calls a driver's EvtUsbTargetPipeReadersFailed callback function, it tries to cancel all in-progress read requests. No read requests are in progress when the framework calls the EvtUsbTargetPipeReadersFailed callback function. The framework does not queue any additional read requests until the EvtUsbTargetPipeReadersFailed callback function returns.

For information about how the framework synchronizes calls to the EvtUsbTargetPipeReadersFailed callback function with calls to other callback functions, see the Remarks section of EvtUsbTargetPipeReadComplete.

The EvtUsbTargetPipeReadersFailed callback function must not call WdfIoTargetStop to stop the continuous reader's USB target. (In fact, calling WdfIoTargetStop in an EvtUsbTargetPipeReadersFailed callback function causes a deadlock.) In addition, the callback function must not call WdfIoTargetStart to restart the continuous reader. Instead, the framework restarts the reader if the callback function returns TRUE. For more information about when to call WdfIoTargetStart and WdfIoTargetStop for a continuous reader, see Working with USB Pipes.

If a driver does not provide an EvtUsbTargetPipeReadersFailed callback function and the driver's I/O target reports an error, the framework resets the USB pipe and restarts the continuous reader.

For more information about the EvtUsbTargetPipeReadersFailed callback function and USB I/O targets, see USB I/O Targets.

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfusb.h (include Wdf.h)
IRQL	PASSIVE_LEVEL