Working with USB Pipes in UMDF 1.x Drivers

[This topic applies to UMDF 1.x.]

The framework represents each pipe in a USB interface as a framework USB pipe object. When a driver configures a USB device, the framework creates a framework USB pipe object for each pipe in each selected interface. Pipe object methods enable a driver to:

Obtaining UMDF-USB Pipe Information

After a UMDF driver calls the IWDFUsbInterface::RetrieveUsbPipeObject method to obtain a pointer to the IWDFUsbTargetPipe interface for a USB pipe object, the driver can call the following methods that the USB pipe object defines for obtaining information about the USB pipe:

IWDFUsbTargetPipe::GetInformation

Retrieves information about a USB pipe and its endpoint.

IWDFUsbTargetPipe::GetType

Returns the type of a USB pipe.

IWDFUsbTargetPipe::IsInEndPoint

Determines whether a USB pipe is connected to an input endpoint.

IWDFUsbTargetPipe::IsOutEndPoint

Determines whether a USB pipe is connected to an output endpoint.

IWDFUsbTargetPipe::RetrievePipePolicy

Retrieves a WinUsb pipe policy.

Reading from a UMDF-USB Pipe

To read data from a USB input pipe, your driver can use either (or both) of the following techniques:

Writing to a UMDF-USB Pipe

To write data to a USB output pipe, a UMDF driver can first call the IWDFIoTarget::FormatRequestForWrite method to build a write request. Then the driver can call the IWDFIoRequest::Send method to send the request asynchronously.

Stopping, Flushing, and Resetting a UMDF-USB Pipe

A UMDF driver can call the following methods to stop, flush, or reset a USB pipe:

IWDFUsbTargetPipe::Abort

Synchronously sends a request to stop all pending transfers on a USB pipe.

IWDFUsbTargetPipe::Flush

Synchronously sends a request to discard any data that WinUsb saved when the device returned more data than the client requested.

IWDFUsbTargetPipe::Reset

Synchronously sends a request to reset a USB pipe.

Setting Policy for a UMDF-USB Pipe

A UMDF driver can call the IWDFUsbTargetPipe::SetPipePolicy method to control the behavior that is used by WinUsb for a USB pipe (for example, time-outs, handling short packets, and other behaviors).

Handling Pipe Errors

If your driver's USB target completes an I/O request with an error status value, your driver should do the following:

  1. Call IWDFIoTargetStateManagement::Stop with the WdfIoTargetCancelSentIo flag set. This call stops the pipe and cancels any additional I/O requests that the driver has sent to the USB target, if the target has not completed the requests.

  2. Call IWDFUsbTargetPipe::Abort to send an abort request to the pipe.

  3. Call IWDFUsbTargetPipe::Reset to send a reset request to the pipe.

  4. Call IWDFIoTargetStateManagement::Start to restart the pipe.

  5. Resend the I/O request that failed, and all I/O requests that followed the failed request.

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft