UsbDevice Class

Definition

Namespace:

Windows.Devices.Usb

Represents a USB device. The object provides methods and properties that an app can use to enumerate WinUSB devices and send IN and OUT control transfers.

public ref class UsbDevice sealed : IClosable

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
class UsbDevice final : IClosable

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
public sealed class UsbDevice : System.IDisposable

Public NotInheritable Class UsbDevice
Implements IDisposable

Inheritance

Object Platform::Object IInspectable UsbDevice

Attributes

ContractVersionAttribute MarshalingBehaviorAttribute

Implements

IClosable IDisposable

Windows requirements

Device family	Windows 10 (introduced in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduced in v1.0)

Examples

This example code shows how to get the UsbDevice object by specifying the vendor/product Id.

protected override async void OnLaunched(LaunchActivatedEventArgs args)
{
    UInt32 vid = 0x045E;
    UInt32 pid = 0x078F;

    string aqs = UsbDevice.GetDeviceSelector(vid, pid);

    var myDevices = await Windows.Devices.Enumeration.DeviceInformation.FindAllAsync(aqs, null);

    if (myDevices.Count == 0)
    {
        ShowError("Device not found!");
        return;
    }

    UsbDevice device = await UsbDevice.FromIdAsync(myDevices[0].Id);

    // Send a control transfer. 

    UsbSetupPacket initSetupPacket = new UsbSetupPacket() 
    { 
        Request = initRequest,
        RequestType = new UsbControlRequestType()
        {
            Recipient = UsbControlRecipient.DefaultInterface,

            ControlTransferType = UsbControlTransferType.Vendor 
        }
    };

   await device.SendOutControlTransferAsync(initSetupPacket);
}

Remarks

Before getting a reference to the UsbDevice object, you must have one of these identifiers:

• The vendor and product identifiers for the physical device. Those identifiers are part of the hardware ID string. Alternatively, you can derive the identifiers from the Hardware Ids property in Device Manager. For example, if the Hardware Id is USB\VID_045E&PID_078E, the vendor ID is 0x045E and product Id is 0x078E.
• The device interface GUID. You can obtain that GUID from the DeviceInterfaceGuids registry entry under: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Enum\USB\<Device Identifier>\<Instance Identifier>\Device Parameters
• The device's class, subclass, and protocol codes. You can obtain that information from the CompatibleIds registry entry, found under the Device Parameters key.

To get the UsbDevice object:

1. Get the Advanced Query Syntax (AQS) string that contains search criteria for finding the device in the enumerated device collection. If you want to search by the vendor ID/product ID or the device interface GUID, call GetDeviceSelector. If you want to search by the device class, call GetDeviceClassSelector. Both calls retrieve formatted AQS strings.
2. Pass the retrieved string to FindAllAsync. The call retrieves a DeviceInformationCollection object.
3. Loop through the collection. Each iteration gets a DeviceInformation object.
4. Get the DeviceInformation.Id property value. The string value is the device instance path. For example, \\?\USB#VID_045E&PID_078F#6&1b8ff026&0&5#{dee824ef-729b-4a0e-9c14-b7117d33a817}.
5. Call FromIdAsync by passing the device instance string and get the UsbDevice object. You can then use the UsbDevice object to perform other operations, such as sending a control transfer. When the app has finished using the UsbDevice object, the app must release it by calling Close.

Properties

Configuration	Gets an object that represents a USB configuration including all interfaces and their endpoints.
DefaultInterface	Gets the object that represents the default or the first interface in a USB configuration.
DeviceDescriptor	Gets the object that represents the USB device descriptor.

Methods

Close()	Releases the reference to the UsbDevice object that was previously obtained by calling FromIdAsync.
Dispose()	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
FromIdAsync(String)	Starts an asynchronous operation that creates a UsbDevice object.
GetDeviceClassSelector(UsbDeviceClass)	Gets an Advanced Query Syntax (AQS) string that the app can pass to DeviceInformation.FindAllAsync in order to find a specific type of USB device.
GetDeviceSelector(Guid)	Gets an Advanced Query Syntax (AQS) string, based on the device interface GUID identifier, specified by the app. The app passes the string to DeviceInformation.FindAllAsync in order to find a specific type of USB device.
GetDeviceSelector(UInt32, UInt32, Guid)	Gets an Advanced Query Syntax (AQS) string, based on vendor, product, and device interface GUID identifiers, specified by the app. The app passes the string to DeviceInformation.FindAllAsync in order to find a specific type of USB device.
GetDeviceSelector(UInt32, UInt32)	Gets an Advanced Query Syntax (AQS) string, based on vendor and product identifiers, specified by the app. The app passes the string to DeviceInformation.FindAllAsync in order to find a specific type of USB device.
SendControlInTransferAsync(UsbSetupPacket, IBuffer)	Starts a USB control transfer to receive data from the default control endpoint of the device.
SendControlInTransferAsync(UsbSetupPacket)	Starts a zero-length USB control transfer that reads from the default control endpoint of the device.
SendControlOutTransferAsync(UsbSetupPacket, IBuffer)	Starts a USB control transfer to send data to the default control endpoint of the device.
SendControlOutTransferAsync(UsbSetupPacket)	Starts a zero-length USB control transfer that writes to the default control endpoint of the device.

See also

• Custom USB device sample (Windows 10)