Edit

Working with USB Devices 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 device as a framework USB device object. A UMDF driver must create a framework USB device object before the driver can access the framework's support for USB I/O targets. UMDF provides USB device object methods that enable a UMDF driver to:

Creating a UMDF-USB Device Object

To use the framework's USB I/O target capabilities, a UMDF driver must first obtain a pointer to the IWDFUsbTargetFactory interface. To obtain the pointer, the driver must call the QueryInterface method of the device's IWDFDevice interface. The following code example shows how to call QueryInterface to obtain the pointer:

hr = pdevice->QueryInterface(IID_IWDFUsbTargetFactory, (LPVOID*)&ppUsbTargetFactory);

The driver must next call the IWDFUsbTargetFactory::CreateUsbTargetDevice method to create a USB I/O target object for the device. After the driver creates the USB I/O target, the driver can send requests to the I/O target. Typically, drivers call IWDFUsbTargetFactory::CreateUsbTargetDevice from within an IPnpCallbackHardware::OnPrepareHardware callback function.

After the driver calls IWDFUsbTargetFactory::CreateUsbTargetDevice, the driver can obtain USB device information (for example, USB descriptors for the device, USB interfaces, and interface endpoints). The USB descriptors are described in the USB specification.

Obtaining UMDF-USB Device Information

After a UMDF driver calls the IWDFUsbTargetFactory::CreateUsbTargetDevice method to create a UMDF-USB target device object, the driver can call the following methods that the USB target device object defines for obtaining information about a USB device:

IWDFUsbTargetDevice::RetrieveDescriptor
Obtains a device's USB device descriptor.

IWDFUsbTargetDevice::GetNumInterfaces
Obtains the number of USB interfaces that the device supports.

IWDFUsbTargetDevice::RetrieveUsbInterface
Obtains a pointer to a IWDFUsbInterface interface that exposes one of the USB interfaces that the device supports.

IWDFUsbTargetDevice::RetrieveDeviceInformation
Retrieves capability information that is associated with a USB device.

IWDFUsbTargetDevice::RetrievePowerPolicy
Retrieves a WinUsb power policy.

IWDFUsbTargetDevice::GetWinUsbHandle
Obtains the WinUsb interface handle that is associated with the I/O target device object.

Sending a Control Transfer to a UMDF-USB Device Object

A UMDF driver can call the IWDFUsbTargetDevice::FormatRequestForControlTransfer method to format an I/O request that describes a standard, device-class-specific, or vendor-specific USB control transfer. The driver can then call the IWDFIoRequest::Send method to send the request synchronously or asynchronously.

Setting Power Policy for a UMDF-USB Device

A UMDF driver can call the IWDFUsbTargetDevice::SetPowerPolicy method to set the power policy that is used by WinUsb for a USB device. The power policy for a USB device effects changes to power management states for the device.