EvtUsbTargetPipeReadersFailed function

[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 EvtUsbTargetPipeReadersFailed;

BOOLEAN EvtUsbTargetPipeReadersFailed(
  _In_  WDFUSBPIPE Pipe,
  _In_  NTSTATUS Status,
  _In_  USBD_STATUS UsbdStatus
)
{ ... }

Parameters

Pipe [in]

A handle to a framework pipe object.

Status [in]

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

UsbdStatus [in]

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.

Examples

To define an EvtUsbTargetPipeReadersFailed callback function, you must first provide a function declaration that identifies the type of callback function you’re defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it’s a requirement for writing drivers for the Windows operating system.

For example, to define an EvtUsbTargetPipeReadersFailed callback function that is named MyUsbTargetPipeReadersFailed, use the EVT_WDF_USB_READERS_FAILED type as shown in this code example:

To define an EvtUsbTargetPipeReadersFailed callback function that is named MyUsbTargetPipeReadersFailed, you must first provide a function declaration that SDV and other verification tools require, as follows:

EVT_WDF_USB_READERS_FAILED  MyUsbTargetPipeReadersFailed;

Then, implement your callback function as follows:

_Use_decl_annotations_
BOOLEAN
 MyUsbTargetPipeReadersFailed (
    WDFUSBPIPE  Pipe,
    NTSTATUS  Status,
    USBD_STATUS  UsbdStatus
    )
  {...}

The EVT_WDF_USB_READERS_FAILED function type is defined in the WdfUsb.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the EVT_WDF_USB_READERS_FAILED function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for KMDF Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

See also

EvtUsbTargetPipeReadComplete

WDF_USB_CONTINUOUS_READER_CONFIG

Send comments about this topic to Microsoft