Usb​Device Usb​Device Usb​Device Class

Definition

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.

public sealed class UsbDevice : IUsbDevice, IClosablepublic sealed class UsbDevice : IUsbDevice, IDisposablePublic NotInheritable Class UsbDevice Implements IUsbDevice, IDisposable
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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

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

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
Value
UsbConfiguration UsbConfiguration UsbConfiguration

A UsbConfiguration object that contains information about a USB configuration including the configuration descriptor and array of all USB interfaces in that configuration.

Attributes

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
Value
UsbInterface UsbInterface UsbInterface

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

Attributes

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
Value
UsbDeviceDescriptor UsbDeviceDescriptor UsbDeviceDescriptor

A UsbDeviceDescriptor that represents the USB device descriptor.

Attributes

Methods

Close() Close() Close()

Releases the reference to the UsbDevice object that was previously obtained by calling FromIdAsync.

public void Close()This member is not implemented in C#This member is not implemented in VB.Net
Attributes

Dispose() Dispose() Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

This member is not implemented in C++void Dispose()Sub Dispose
Attributes

FromIdAsync(String) FromIdAsync(String) FromIdAsync(String)

Starts an asynchronous operation that creates a UsbDevice object.

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

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

Returns

Returns an IAsyncOperation(UsbDevice) object that returns the results of the operation.

Attributes

GetDeviceClassSelector(UsbDeviceClass) GetDeviceClassSelector(UsbDeviceClass) 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.

public static PlatForm::String GetDeviceClassSelector(UsbDeviceClass usbClass)public static string GetDeviceClassSelector(UsbDeviceClass usbClass)Public Static Function GetDeviceClassSelector(usbClass As UsbDeviceClass) As string
Parameters
usbClass
UsbDeviceClass UsbDeviceClass UsbDeviceClass

A UsbDeviceClass object for the device class specified by the app.

Returns
string string string

String formatted as an AQS query.

Attributes

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 and pass that new class. The call retrieves an AQS string.
  3. Call FindAllAsync 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(Guid) GetDeviceSelector(Guid) 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.

public static PlatForm::String GetDeviceSelector(Guid winUsbInterfaceClass)public static string GetDeviceSelector(Guid winUsbInterfaceClass)Public Static Function GetDeviceSelector(winUsbInterfaceClass As Guid) As string
Parameters
winUsbInterfaceClass
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 formatted as an AQS query.

Attributes

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(UInt32, UInt32) GetDeviceSelector(UInt32, UInt32) 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.

public static PlatForm::String GetDeviceSelector(UInt32 vendorId, UInt32 productId)public static string GetDeviceSelector(UInt32 vendorId, UInt32 productId)Public Static Function GetDeviceSelector(vendorId As UInt32, productId As UInt32) As string
Parameters
vendorId
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

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 formatted as an AQS query.

Attributes

GetDeviceSelector(UInt32, UInt32, Guid) GetDeviceSelector(UInt32, UInt32, Guid) 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.

public static PlatForm::String GetDeviceSelector(UInt32 vendorId, UInt32 productId, Guid winUsbInterfaceClass)public static string GetDeviceSelector(UInt32 vendorId, UInt32 productId, Guid winUsbInterfaceClass)Public Static Function GetDeviceSelector(vendorId As UInt32, productId As UInt32, winUsbInterfaceClass As Guid) As string
Parameters
vendorId
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

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

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

Returns
string string string

String formatted as an AQS query.

Attributes

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(UsbSetupPacket) SendControlInTransferAsync(UsbSetupPacket) SendControlInTransferAsync(UsbSetupPacket)

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

public IAsyncOperation<IBuffer> SendControlInTransferAsync(UsbSetupPacket setupPacket)public IAsyncOperation<IBuffer> SendControlInTransferAsync(UsbSetupPacket setupPacket)Public Function SendControlInTransferAsync(setupPacket As UsbSetupPacket) As IAsyncOperation( Of IBuffer )
Parameters
setupPacket
UsbSetupPacket UsbSetupPacket UsbSetupPacket

A UsbSetupPacket object that contains the setup packet for the control transfer.

Returns

Returns an IAsyncOperation(IBuffer) object that returns the results of the operation.

Attributes

SendControlInTransferAsync(UsbSetupPacket, IBuffer) SendControlInTransferAsync(UsbSetupPacket, IBuffer) SendControlInTransferAsync(UsbSetupPacket, IBuffer)

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

public IAsyncOperation<IBuffer> SendControlInTransferAsync(UsbSetupPacket setupPacket, IBuffer buffer)public IAsyncOperation<IBuffer> SendControlInTransferAsync(UsbSetupPacket setupPacket, IBuffer buffer)Public Function SendControlInTransferAsync(setupPacket As UsbSetupPacket, buffer As IBuffer) As IAsyncOperation( Of IBuffer )
Parameters
setupPacket
UsbSetupPacket UsbSetupPacket UsbSetupPacket

A UsbSetupPacket object that contains the setup packet for the control transfer.

buffer
IBuffer IBuffer IBuffer

A caller-supplied buffer that contains transfer data.

Returns

Returns an IAsyncOperation(IBuffer) object that returns the results of the operation.

Attributes

SendControlOutTransferAsync(UsbSetupPacket) SendControlOutTransferAsync(UsbSetupPacket) SendControlOutTransferAsync(UsbSetupPacket)

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

public IAsyncOperation<uint> SendControlOutTransferAsync(UsbSetupPacket setupPacket)public IAsyncOperation<uint> SendControlOutTransferAsync(UsbSetupPacket setupPacket)Public Function SendControlOutTransferAsync(setupPacket As UsbSetupPacket) As IAsyncOperation( Of uint )
Parameters
setupPacket
UsbSetupPacket UsbSetupPacket UsbSetupPacket

A UsbSetupPacket object that contains the setup packet for the control transfer.

Returns

Returns an IAsyncOperation(UInt32) object that returns the results of the operation.

Attributes

SendControlOutTransferAsync(UsbSetupPacket, IBuffer) SendControlOutTransferAsync(UsbSetupPacket, IBuffer) SendControlOutTransferAsync(UsbSetupPacket, IBuffer)

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

public IAsyncOperation<uint> SendControlOutTransferAsync(UsbSetupPacket setupPacket, IBuffer buffer)public IAsyncOperation<uint> SendControlOutTransferAsync(UsbSetupPacket setupPacket, IBuffer buffer)Public Function SendControlOutTransferAsync(setupPacket As UsbSetupPacket, buffer As IBuffer) As IAsyncOperation( Of uint )
Parameters
setupPacket
UsbSetupPacket UsbSetupPacket UsbSetupPacket

A UsbSetupPacket object that contains the setup packet for the control transfer.

buffer
IBuffer IBuffer IBuffer

A caller-supplied buffer that contains the transfer data.

Returns

Returns an IAsyncOperation(UInt32) object that returns the results of the operation.

Attributes

See Also