Edit

Working with USB Interfaces in UMDF 1.x Drivers

  • 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.

The archived UMDF 1 samples can be found in the Windows 11, version 22H2 - May 2022 Driver Samples Update.

For more info, see Getting Started with UMDF.

The framework represents each USB interface as a framework USB interface object. When a UMDF driver creates a framework USB device object, the framework creates a framework USB interface object for each USB interface that the device supports.

Most USB devices have only one interface, and the interface has only one alternative setting. Drivers for such devices typically do not need to use the object methods that the framework's USB interface object defines.

If a UMDF driver supports USB devices that provide multiple interfaces or alternate settings, interface object methods enable the driver to:

Obtaining UMDF-USB Interface Information

After a UMDF driver has called the IWDFUsbTargetFactory::CreateUsbTargetDevice method to create a UMDF-USB target device object, the driver can call the IWDFUsbTargetDevice::GetNumInterfaces method to obtain the number of USB interfaces that the device supports. Next, the driver can make calls to the IWDFUsbTargetDevice::RetrieveUsbInterface method to obtain pointers to the IWDFUsbInterface interfaces that expose the USB interfaces that the device supports. Then the driver can call the following methods that each USB interface object defines for obtaining information about the USB interface:

IWDFUsbInterface::GetInterfaceNumber
Obtains the USB interface number that is associated with a USB interface object.

IWDFUsbInterface::GetInterfaceDescriptor
Obtains that USB interface descriptor that is associated with one of the alternate settings of a USB interface.

IWDFUsbInterface::GetNumEndPoints
Obtains the number of endpoints (also known as pipes) that are associated with one of the alternate settings of a USB interface.

IWDFUsbInterface::GetConfiguredSettingIndex
Obtains an index value that identifies the alternate setting that is currently selected for a USB interface.

IWDFUsbInterface::RetrieveUsbPipeObject
Retrieves a pointer to the IWDFUsbTargetPipe interface that exposes the framework pipe object that is associated with a specified USB device interface and pipe index.

IWDFUsbInterface::GetWinUsbHandle
Obtains the WinUsb interface handle that is associated with a USB interface.

Selecting an Alternate Setting for a UMDF-USB Interface

The UMDF driver can call the IWDFUsbInterface::SelectSetting method to select an alternate setting for one of the USB interfaces that the device supports.

The device's alternate settings must be numbered contiguously, starting with zero.

Important   Selecting a setting invalidates any information about the interface and endpoints. Therefore, the driver should obtain this information again. The driver must also discard any USB pipe objects that it previously retrieved and recreate them.