UsbDevice UsbDevice UsbDevice UsbDevice Class

Represents a USB device. The object provides methods and properties that an app can use to find the device (in the system) with which the app wants to communicate, and sends IN and OUT control transfers to the device.

Syntax

Declaration

public sealed class UsbDevicepublic sealed class UsbDevicePublic NotInheritable Class UsbDevice

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. You can obtain that string from the Models section in the INF file. Alternatively, if WinUSB was loaded based on the compatible ID specified in the device descriptor, you can derive the identifiers from the Hardware Ids property in Device Manager. For example, if Hardware Id is "USB\VID_045E&PID_078E", vendor ID is "0x045E" and product Id is "0x078E".
  • The device interface GUID. You can obtain that GUID from the DeviceInterfaceGuids registry entry under this key: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(System.UInt32,System.UInt32). If you want to search by the device class, call GetDeviceClassSelector(Windows.Devices.Usb.UsbDeviceClass). Both calls retrieve formatted AQS strings.
  2. Pass the retrieved string to FindAllAsync(System.String). The call retrieves a DeviceInformationCollection object.
  3. Loop through the collection. Each iteration gets a DeviceInformation object.
  4. Get the 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(System.String) 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().

Examples

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

protected override async void OnLaunched1(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);

}

Properties summary

Gets an object that represents a USB configuration including all interfaces and their endpoints.

Gets the object that represents the default or the first interface in a USB configuration.

Gets the object that represents the USB device descriptor.

Methods summary

Releases the reference to the UsbDevice object that was previously obtained by calling FromIdAsync(System.String).

Starts an asynchronous operation that creates a UsbDevice object.

Gets an Advanced Query Syntax (AQS) string that the app can pass to FindAllAsync(System.String) in order to find a specific type of USB device.

Gets an Advanced Query Syntax (AQS) string, based on the device interface GUID identifier, specified by the app. The app passes the string to FindAllAsync(System.String) in order to find a specific type of USB device.

Gets an Advanced Query Syntax (AQS) string, based on vendor and product identifiers, specified by the app. The app passes the string to FindAllAsync(System.String) in order to find a specific type of USB device.

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 FindAllAsync(System.String) in order to find a specific type of USB device.

Starts a zero-length USB control transfer that reads from the default control endpoint of the device.

Starts a USB control transfer to receive data from the default control endpoint of the device.

Starts a zero-length USB control transfer that writes to the default control endpoint of the device.

Starts a USB control transfer to send data to the default control endpoint of the device.

Properties

  • Configuration
    Configuration
    Configuration
    Configuration

    Gets an object that represents a USB configuration including all interfaces and their endpoints.

    public UsbConfiguration Configuration { get; }public UsbConfiguration Configuration { get; }Public ReadOnly Property Configuration As UsbConfiguration

    Property Value

  • DefaultInterface
    DefaultInterface
    DefaultInterface
    DefaultInterface

    Gets the object that represents the default or the first interface in a USB configuration.

    public UsbInterface DefaultInterface { get; }public UsbInterface DefaultInterface { get; }Public ReadOnly Property DefaultInterface As UsbInterface

    Property Value

  • DeviceDescriptor
    DeviceDescriptor
    DeviceDescriptor
    DeviceDescriptor

    Gets the object that represents the USB device descriptor.

    public UsbDeviceDescriptor DeviceDescriptor { get; }public UsbDeviceDescriptor DeviceDescriptor { get; }Public ReadOnly Property DeviceDescriptor As UsbDeviceDescriptor

    Property Value

Methods

  • Close()
    Close()
    Close()
    Close()

    Releases the reference to the UsbDevice object that was previously obtained by calling FromIdAsync(System.String).

    public void Close()public void Close()Public Function Close() As void
  • FromIdAsync(System.String)
    FromIdAsync(System.String)
    FromIdAsync(System.String)
    FromIdAsync(System.String)

    Starts an asynchronous operation that creates a UsbDevice object.

    public static IAsyncOperation<UsbDevice> FromIdAsync(System.String deviceId)public static IAsyncOperation<UsbDevice> FromIdAsync(System.String deviceId)Public Static Function FromIdAsync(deviceId As System.String) As IAsyncOperation( Of UsbDevice )

    Parameters

    • deviceId
      System.String
      System.String
      System.String
      System.String

      The device instance path of the device. To obtain that value, get the Id property value.

    Returns

  • GetDeviceClassSelector(Windows.Devices.Usb.UsbDeviceClass)
    GetDeviceClassSelector(Windows.Devices.Usb.UsbDeviceClass)
    GetDeviceClassSelector(Windows.Devices.Usb.UsbDeviceClass)
    GetDeviceClassSelector(Windows.Devices.Usb.UsbDeviceClass)

    Gets an Advanced Query Syntax (AQS) string that the app can pass to FindAllAsync(System.String) in order to find a specific type of USB device.

    public static string GetDeviceClassSelector(Windows.Devices.Usb.UsbDeviceClass usbClass)public static string GetDeviceClassSelector(Windows.Devices.Usb.UsbDeviceClass usbClass)Public Static Function GetDeviceClassSelector(usbClass As Windows.Devices.Usb.UsbDeviceClass) As string

    Parameters

    Returns

    • string
      string
      string
      string

      String formatted as an AQS query.

    Remarks

    You can search for a UsbDevice in the enumerated collection of devices by specifying class code, sub class code, or protocol code. To do this,

    1. Create a UsbDeviceClass object by specifying ClassCode, SubclassCode, and ProtocolCode property values. Alternatively, you can call the constructor by specifying a particular UsbDeviceClasses property.
    2. Call GetDeviceClassSelector(Windows.Devices.Usb.UsbDeviceClass) and pass that new class. The call retrieves an AQS string.
    3. Call FindAllAsync(System.String) and pass the string to get the UsbDevice object.

    Examples

    protected override async void OnLaunched(LaunchActivatedEventArgs args)
    {
        byte deviceClass = 0xf0;
        byte deviceSubclass = 0x01;
    
        var myDevices = await Windows.Devices.Enumeration.DeviceInformation.FindAllAsync(
                              UsbDevice.GetDeviceClassSelector(
                              new UsbDeviceClass() {
                              Class = deviceClass, Subclass = deviceSubclass }));
    
        UsbDevice device = null;
    
        foreach (var device in myDevices)
        {
            if (IsMyDevice(device))
            {
                device = await UsbDevice.FromIdAsync(device.Id);
            }
        }
    
        if (device == null)
        {
            ShowError("Usb device not found");
            return;
        }
    
    }
    
  • GetDeviceSelector(System.Guid)
    GetDeviceSelector(System.Guid)
    GetDeviceSelector(System.Guid)
    GetDeviceSelector(System.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 FindAllAsync(System.String) in order to find a specific type of USB device.

    public static string GetDeviceSelector(System.Guid winUsbInterfaceClass)public static string GetDeviceSelector(System.Guid winUsbInterfaceClass)Public Static Function GetDeviceSelector(winUsbInterfaceClass As System.Guid) As string

    Parameters

    • winUsbInterfaceClass
      System.Guid
      System.Guid
      System.Guid
      System.Guid

      The device interface GUID exposed by the Winusb.sys driver. See the remarks section.

    Returns

    • string
      string
      string
      string

      String formatted as an AQS query.

    Remarks

    You can obtain the device interface GUID from the DeviceInterfaceGuids registry entry under this key:HKEY_LOCAL_MACHINE*System\CurrentControlSet\Enum\USB\<Device Identifier>\<Instance Identifier>\Device Parameters*

  • GetDeviceSelector(System.UInt32,System.UInt32)
    GetDeviceSelector(System.UInt32,System.UInt32)
    GetDeviceSelector(System.UInt32,System.UInt32)
    GetDeviceSelector(System.UInt32,System.UInt32)

    Gets an Advanced Query Syntax (AQS) string, based on vendor and product identifiers, specified by the app. The app passes the string to FindAllAsync(System.String) in order to find a specific type of USB device.

    public static string GetDeviceSelector(System.UInt32 vendorId,System.UInt32 productId)public static string GetDeviceSelector(System.UInt32 vendorId,System.UInt32 productId)Public Static Function GetDeviceSelector(vendorId As System.UInt32,productId As System.UInt32) As string

    Parameters

    • vendorId
      System.UInt32
      System.UInt32
      System.UInt32
      System.UInt32

      Specifies the vendor identifier for the device as assigned by the USB specification committee. Possible values are 0 through 0xffff.

    • productId
      System.UInt32
      System.UInt32
      System.UInt32
      System.UInt32

      Specifies the product identifier. This value is assigned by the manufacturer and is device-specific. Possible values are 0 through 0xffff.

    Returns

    • string
      string
      string
      string

      String formatted as an AQS query.

  • GetDeviceSelector(System.UInt32,System.UInt32,System.Guid)
    GetDeviceSelector(System.UInt32,System.UInt32,System.Guid)
    GetDeviceSelector(System.UInt32,System.UInt32,System.Guid)
    GetDeviceSelector(System.UInt32,System.UInt32,System.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 FindAllAsync(System.String) in order to find a specific type of USB device.

    public static string GetDeviceSelector(System.UInt32 vendorId,System.UInt32 productId,System.Guid winUsbInterfaceClass)public static string GetDeviceSelector(System.UInt32 vendorId,System.UInt32 productId,System.Guid winUsbInterfaceClass)Public Static Function GetDeviceSelector(vendorId As System.UInt32,productId As System.UInt32,winUsbInterfaceClass As System.Guid) As string

    Parameters

    • vendorId
      System.UInt32
      System.UInt32
      System.UInt32
      System.UInt32

      Specifies the vendor identifier for the device as assigned by the USB specification committee. Possible values are 0 through 0xffff.

    • productId
      System.UInt32
      System.UInt32
      System.UInt32
      System.UInt32

      Specifies the product identifier. This value is assigned by the manufacturer and is device-specific. Possible values are 0 through 0xffff.

    • winUsbInterfaceClass
      System.Guid
      System.Guid
      System.Guid
      System.Guid

      The device interface GUID exposed by the Winusb.sys driver. See the remarks section.

    Returns

    • string
      string
      string
      string

      String formatted as an AQS query.

    Remarks

    You can obtain the device interface GUID from the DeviceInterfaceGuids registry entry under this key:HKEY_LOCAL_MACHINE*System\CurrentControlSet\Enum\USB\<Device Identifier>\<Instance Identifier>\Device Parameters*

  • SendControlInTransferAsync(Windows.Devices.Usb.UsbSetupPacket)
    SendControlInTransferAsync(Windows.Devices.Usb.UsbSetupPacket)
    SendControlInTransferAsync(Windows.Devices.Usb.UsbSetupPacket)
    SendControlInTransferAsync(Windows.Devices.Usb.UsbSetupPacket)

    Starts a zero-length USB control transfer that reads from the default control endpoint of the device.

    public IAsyncOperation<IBuffer> SendControlInTransferAsync(Windows.Devices.Usb.UsbSetupPacket setupPacket)public IAsyncOperation<IBuffer> SendControlInTransferAsync(Windows.Devices.Usb.UsbSetupPacket setupPacket)Public Function SendControlInTransferAsync(setupPacket As Windows.Devices.Usb.UsbSetupPacket) As IAsyncOperation( Of IBuffer )

    Parameters

    Returns

  • SendControlInTransferAsync(Windows.Devices.Usb.UsbSetupPacket,Windows.Storage.Streams.IBuffer)
    SendControlInTransferAsync(Windows.Devices.Usb.UsbSetupPacket,Windows.Storage.Streams.IBuffer)
    SendControlInTransferAsync(Windows.Devices.Usb.UsbSetupPacket,Windows.Storage.Streams.IBuffer)
    SendControlInTransferAsync(Windows.Devices.Usb.UsbSetupPacket,Windows.Storage.Streams.IBuffer)

    Starts a USB control transfer to receive data from the default control endpoint of the device.

    public IAsyncOperation<IBuffer> SendControlInTransferAsync(Windows.Devices.Usb.UsbSetupPacket setupPacket,Windows.Storage.Streams.IBuffer buffer)public IAsyncOperation<IBuffer> SendControlInTransferAsync(Windows.Devices.Usb.UsbSetupPacket setupPacket,Windows.Storage.Streams.IBuffer buffer)Public Function SendControlInTransferAsync(setupPacket As Windows.Devices.Usb.UsbSetupPacket,buffer As Windows.Storage.Streams.IBuffer) As IAsyncOperation( Of IBuffer )

    Parameters

    Returns

  • SendControlOutTransferAsync(Windows.Devices.Usb.UsbSetupPacket)
    SendControlOutTransferAsync(Windows.Devices.Usb.UsbSetupPacket)
    SendControlOutTransferAsync(Windows.Devices.Usb.UsbSetupPacket)
    SendControlOutTransferAsync(Windows.Devices.Usb.UsbSetupPacket)

    Starts a zero-length USB control transfer that writes to the default control endpoint of the device.

    public IAsyncOperation<uint> SendControlOutTransferAsync(Windows.Devices.Usb.UsbSetupPacket setupPacket)public IAsyncOperation<uint> SendControlOutTransferAsync(Windows.Devices.Usb.UsbSetupPacket setupPacket)Public Function SendControlOutTransferAsync(setupPacket As Windows.Devices.Usb.UsbSetupPacket) As IAsyncOperation( Of uint )

    Parameters

    Returns

  • SendControlOutTransferAsync(Windows.Devices.Usb.UsbSetupPacket,Windows.Storage.Streams.IBuffer)
    SendControlOutTransferAsync(Windows.Devices.Usb.UsbSetupPacket,Windows.Storage.Streams.IBuffer)
    SendControlOutTransferAsync(Windows.Devices.Usb.UsbSetupPacket,Windows.Storage.Streams.IBuffer)
    SendControlOutTransferAsync(Windows.Devices.Usb.UsbSetupPacket,Windows.Storage.Streams.IBuffer)

    Starts a USB control transfer to send data to the default control endpoint of the device.

    public IAsyncOperation<uint> SendControlOutTransferAsync(Windows.Devices.Usb.UsbSetupPacket setupPacket,Windows.Storage.Streams.IBuffer buffer)public IAsyncOperation<uint> SendControlOutTransferAsync(Windows.Devices.Usb.UsbSetupPacket setupPacket,Windows.Storage.Streams.IBuffer buffer)Public Function SendControlOutTransferAsync(setupPacket As Windows.Devices.Usb.UsbSetupPacket,buffer As Windows.Storage.Streams.IBuffer) As IAsyncOperation( Of uint )

    Parameters

    Returns

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.DualApiPartitionAttribute
Windows.Foundation.Metadata.ContractVersionAttribute

Details

Assembly

Windows.Devices.Usb.dll