Edit

Share via

IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure method (wudfusb.h)

  • Article

[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]

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

Syntax

BOOL OnReaderFailure(
  [in] IWDFUsbTargetPipe *pPipe,
  [in] HRESULT           hrStatus
);

Parameters

[in] pPipe

A pointer to the IWDFUsbTargetPipe interface for the USB pipe on which the driver has enabled a continuous reader.

[in] hrStatus

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

Return value

The OnReaderFailure event callback function must return a Boolean value. If the return value is TRUE, the framework resets the USB pipe and then restarts the continuous reader. If the callback function returns FALSE, the framework does not reset the device or restart the continuous reader.

Remarks

To register an OnReaderFailure callback function, your driver must provide a pointer to the driver's IUsbTargetPipeContinuousReaderCallbackReadersFailed interface when it calls IWDFUsbTargetPipe2::ConfigureContinuousReader.

If a driver has created a continuous reader for a USB pipe, the framework calls the driver's OnReaderFailure 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 IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion callback function.)

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

For information about how the framework synchronizes calls to the OnReaderFailure callback function with calls to other callback functions, see the Remarks section of IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion.

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

If a driver does not provide an OnReaderFailure 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 OnReaderFailure callback function and USB I/O targets, see Handling a USB I/O Target.

Requirements

Requirement Value
End of support Unavailable in UMDF 2.0 and later.
Target Platform Desktop
Minimum UMDF version 1.9
Header wudfusb.h (include Wudfusb.h)

See also

IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion

IUsbTargetPipeContinuousReaderCallbackReadersFailed