HidDevice HidDevice HidDevice HidDevice Class

Definition

Represents a top-level collection and the corresponding device.

public : sealed class HidDevice : IHidDevice, IClosable
public sealed class HidDevice : IHidDevice, IDisposable
Public NotInheritable Class HidDevice Implements IHidDevice, IDisposable
// This class does not provide a public constructor.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The following example demonstrates how a UWP app built with XAML and C# uses the GetDeviceSelector method to create a selector for a specific HID device and then uses** FromIdAsync** method to open a connection to that device.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

using Windows.Devices.Enumeration;
using Windows.Devices.HumanInterfaceDevice;
using Windows.Storage;
using Windows.Storage.Streams;

namespace HidSampleCS
{
    class Enumeration
    {
        // Enumerate HID devices
        private async void EnumerateHidDevices()
        {
            UInt32 vendorId = 0x045E;
            UInt32 productId = 0x078F;
            UInt32 usagePage = 0xFF00;
            UInt32 usageId = 0x0001;

            // Create a selector that gets a HID device using VID/PID and a 
            // VendorDefined usage
            string selector = HidDevice.GetDeviceSelector(usagePage, usageId, 
                              vendorId, productId);

            // Enumerate devices using the selector
            var devices = await DeviceInformation.FindAllAsync(selector);

            if (devices.Count > 0)
            {
                // Open the target HID device
                HidDevice device = await HidDevice.FromIdAsync(devices.ElementAt(0).Id, 
                                   FileAccessMode.ReadWrite);

                // At this point the device is available to communicate with
                // So we can send/receive HID reports from it or 
                // query it for control descriptions
            }
            else
            {
                // There were no HID devices that met the selector criteria
                this.NotifyUser("MUTT HID device not found");
            }
        }
    }
}

Properties

ProductId ProductId ProductId ProductId

Gets the product identifier for the given HID device.

public : ushort ProductId { get; }
public ushort ProductId { get; }
Public ReadOnly Property ProductId As ushort
var ushort = hidDevice.productId;
Value
ushort ushort ushort ushort

The product identifier.

Remarks

Valid values are 0 through 0xFFFF.

UsageId UsageId UsageId UsageId

Gets the usage identifier for the given HID device.

public : ushort UsageId { get; }
public ushort UsageId { get; }
Public ReadOnly Property UsageId As ushort
var ushort = hidDevice.usageId;
Value
ushort ushort ushort ushort

The usage identifier.

UsagePage UsagePage UsagePage UsagePage

Gets the usage page of the top-level collection.

public : ushort UsagePage { get; }
public ushort UsagePage { get; }
Public ReadOnly Property UsagePage As ushort
var ushort = hidDevice.usagePage;
Value
ushort ushort ushort ushort

The usage page.

Remarks

The UsagePage of the top-level collection is retrieved from the HID report descriptor.

VendorId VendorId VendorId VendorId

Gets the vendor identifier for the given HID device.

public : ushort VendorId { get; }
public ushort VendorId { get; }
Public ReadOnly Property VendorId As ushort
var ushort = hidDevice.vendorId;
Value
ushort ushort ushort ushort

The vendor identifier.

Remarks

Valid values are 0 through 0xFFFF.

Version Version Version Version

Gets the version, or revision, number for the given HID device.

public : ushort Version { get; }
public ushort Version { get; }
Public ReadOnly Property Version As ushort
var ushort = hidDevice.version;
Value
ushort ushort ushort ushort

The version number.

Remarks

The version is retrieved from the device descriptor.

Valid values are 0 through 0xFFFF.

Methods

Close() Close() Close() Close()

Closes the connection between the host and the given HID device.

public : void Close()
This member is not implemented in C#
This member is not implemented in VB.Net
hidDevice.close();

CreateFeatureReport() CreateFeatureReport() CreateFeatureReport() CreateFeatureReport()

Creates the only, or default, feature report that the host will send to the device.

public : HidFeatureReport CreateFeatureReport()
public HidFeatureReport CreateFeatureReport()
Public Function CreateFeatureReport() As HidFeatureReport
var hidFeatureReport = hidDevice.createFeatureReport();
Returns
See Also

CreateFeatureReport(UInt16) CreateFeatureReport(UInt16) CreateFeatureReport(UInt16) CreateFeatureReport(UInt16)

Creates a feature report, identified by the reportId parameter, that the host will send to the device.

public : HidFeatureReport CreateFeatureReport(unsigned short reportId)
public HidFeatureReport CreateFeatureReport(UInt16 reportId)
Public Function CreateFeatureReport(reportId As UInt16) As HidFeatureReport
var hidFeatureReport = hidDevice.createFeatureReport(reportId);
Parameters
reportId
unsigned short UInt16 UInt16 UInt16

Identifies the report being created.

Returns
See Also

CreateOutputReport() CreateOutputReport() CreateOutputReport() CreateOutputReport()

Creates the only, or default, output report that the host will send to the device.

public : HidOutputReport CreateOutputReport()
public HidOutputReport CreateOutputReport()
Public Function CreateOutputReport() As HidOutputReport
var hidOutputReport = hidDevice.createOutputReport();
Returns
See Also

CreateOutputReport(UInt16) CreateOutputReport(UInt16) CreateOutputReport(UInt16) CreateOutputReport(UInt16)

Creates an output report, identified by the reportId parameter, that the host will send to the device.

public : HidOutputReport CreateOutputReport(unsigned short reportId)
public HidOutputReport CreateOutputReport(UInt16 reportId)
Public Function CreateOutputReport(reportId As UInt16) As HidOutputReport
var hidOutputReport = hidDevice.createOutputReport(reportId);
Parameters
reportId
unsigned short UInt16 UInt16 UInt16

Identifies the report being created.

Returns
See Also

Dispose() 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
void Dispose()

FromIdAsync(String, FileAccessMode) FromIdAsync(String, FileAccessMode) FromIdAsync(String, FileAccessMode) FromIdAsync(String, FileAccessMode)

Opens a handle to the device identified by the deviceId parameter. The access type is specified by the accessMode parameter.

public : static IAsyncOperation<HidDevice> FromIdAsync(Platform::String deviceId, FileAccessMode accessMode)
public static IAsyncOperation<HidDevice> FromIdAsync(String deviceId, FileAccessMode accessMode)
Public Static Function FromIdAsync(deviceId As String, accessMode As FileAccessMode) As IAsyncOperation( Of HidDevice )
Windows.Devices.HumanInterfaceDevice.HidDevice.fromIdAsync(deviceId, accessMode).done( /* Your success and error handlers */ );
Parameters
deviceId
Platform::String String String String

The DeviceInformation ID that identifies the HID device.

accessMode
FileAccessMode FileAccessMode FileAccessMode FileAccessMode

Specifies the access mode. The supported access modes are Read and ReadWrite.

Returns

Remarks

The first time this method is invoked by a store app, it should be called from a UI thread in order to display the consent prompt. After the user has granted consent, the method can be invoked from any application thread.

The manifest for your app must declare a specific HID device capability before you invoke this method; and, this capability must map to the capabilities of the target device.

If there is no declaration in the manifest, or, if the declaration specifies a device not supported by the HID API, this method fails with an error of E_ACCESSDENIED.

GetBooleanControlDescriptions(HidReportType, UInt16, UInt16) GetBooleanControlDescriptions(HidReportType, UInt16, UInt16) GetBooleanControlDescriptions(HidReportType, UInt16, UInt16) GetBooleanControlDescriptions(HidReportType, UInt16, UInt16)

Retrieves the descriptions of the boolean controls for the given HID device.

public : IVectorView<HidBooleanControlDescription> GetBooleanControlDescriptions(HidReportType reportType, unsigned short usagePage, unsigned short usageId)
public IReadOnlyList<HidBooleanControlDescription> GetBooleanControlDescriptions(HidReportType reportType, UInt16 usagePage, UInt16 usageId)
Public Function GetBooleanControlDescriptions(reportType As HidReportType, usagePage As UInt16, usageId As UInt16) As IReadOnlyList<HidBooleanControlDescription>( Of HidBooleanControlDescription )
var iVectorView = hidDevice.getBooleanControlDescriptions(reportType, usagePage, usageId);
Parameters
reportType
HidReportType HidReportType HidReportType HidReportType

Specifies the type of report for which the control descriptions are requested.

usagePage
unsigned short UInt16 UInt16 UInt16

Identifies the usage page associated with the controls.

usageId
unsigned short UInt16 UInt16 UInt16

Identifies the usage associated with the controls.

Returns
IVectorView<HidBooleanControlDescription> IReadOnlyList<HidBooleanControlDescription> IReadOnlyList<HidBooleanControlDescription> IReadOnlyList<HidBooleanControlDescription>

A vector of HidBooleanControlDescription objects.

Remarks

Boolean controls are simple controls that return On/Off values. (They are sometimes referred to as button controls.)

GetDeviceSelector(UInt16, UInt16) GetDeviceSelector(UInt16, UInt16) GetDeviceSelector(UInt16, UInt16) GetDeviceSelector(UInt16, UInt16)

Retrieves an Advanced Query Syntax (AQS) string based on the given usagePage and usageId.

public : static Platform::String GetDeviceSelector(unsigned short usagePage, unsigned short usageId)
public static string GetDeviceSelector(UInt16 usagePage, UInt16 usageId)
Public Static Function GetDeviceSelector(usagePage As UInt16, usageId As UInt16) As string
var string = Windows.Devices.HumanInterfaceDevice.HidDevice.getDeviceSelector(usagePage, usageId);
Parameters
usagePage
unsigned short UInt16 UInt16 UInt16

Specifies the usage page of the top-level collection for the given HID device.

usageId
unsigned short UInt16 UInt16 UInt16

Specifies the usage identifier of the top-level collection for the given HID device.

Returns
Platform::String string string string

An Advanced Query Syntax (AQS) string that represents a device selector.

See Also

GetDeviceSelector(UInt16, UInt16, UInt16, UInt16) GetDeviceSelector(UInt16, UInt16, UInt16, UInt16) GetDeviceSelector(UInt16, UInt16, UInt16, UInt16) GetDeviceSelector(UInt16, UInt16, UInt16, UInt16)

Retrieves an Advanced Query Syntax (AQS) string based on the given usagePage, usageId, vendorId, and productId.

public : static Platform::String GetDeviceSelector(unsigned short usagePage, unsigned short usageId, unsigned short vendorId, unsigned short productId)
public static string GetDeviceSelector(UInt16 usagePage, UInt16 usageId, UInt16 vendorId, UInt16 productId)
Public Static Function GetDeviceSelector(usagePage As UInt16, usageId As UInt16, vendorId As UInt16, productId As UInt16) As string
var string = Windows.Devices.HumanInterfaceDevice.HidDevice.getDeviceSelector(usagePage, usageId, vendorId, productId);
Parameters
usagePage
unsigned short UInt16 UInt16 UInt16

Specifies the usage page of the top-level collection for the given HID device.

usageId
unsigned short UInt16 UInt16 UInt16

Specifies the usage identifier of the top-level collection for the given HID device.

vendorId
unsigned short UInt16 UInt16 UInt16

Identifies the device vendor.

productId
unsigned short UInt16 UInt16 UInt16

Identifies the product.

Returns
Platform::String string string string

An Advanced Query Syntax (AQS) string that represents a device selector.

See Also

GetFeatureReportAsync() GetFeatureReportAsync() GetFeatureReportAsync() GetFeatureReportAsync()

Asynchronously retrieves the first, or default, feature report from the given HID device.

public : IAsyncOperation<HidFeatureReport> GetFeatureReportAsync()
public IAsyncOperation<HidFeatureReport> GetFeatureReportAsync()
Public Function GetFeatureReportAsync() As IAsyncOperation( Of HidFeatureReport )
Windows.Devices.HumanInterfaceDevice.HidDevice.getFeatureReportAsync().done( /* Your success and error handlers */ );
Returns

Remarks

This instance of the method retrieves the first available feature report.

See Also

GetFeatureReportAsync(UInt16) GetFeatureReportAsync(UInt16) GetFeatureReportAsync(UInt16) GetFeatureReportAsync(UInt16)

Asynchronously retrieves a feature report, identified by the reportId parameter, for the given HID device.

public : IAsyncOperation<HidFeatureReport> GetFeatureReportAsync(unsigned short reportId)
public IAsyncOperation<HidFeatureReport> GetFeatureReportAsync(UInt16 reportId)
Public Function GetFeatureReportAsync(reportId As UInt16) As IAsyncOperation( Of HidFeatureReport )
Windows.Devices.HumanInterfaceDevice.HidDevice.getFeatureReportAsync(reportId).done( /* Your success and error handlers */ );
Parameters
reportId
unsigned short UInt16 UInt16 UInt16

Identifies the requested feature report.

Returns
See Also

GetInputReportAsync() GetInputReportAsync() GetInputReportAsync() GetInputReportAsync()

Asynchronously retrieves the default, or first, input report from the given HID device.

public : IAsyncOperation<HidInputReport> GetInputReportAsync()
public IAsyncOperation<HidInputReport> GetInputReportAsync()
Public Function GetInputReportAsync() As IAsyncOperation( Of HidInputReport )
Windows.Devices.HumanInterfaceDevice.HidDevice.getInputReportAsync().done( /* Your success and error handlers */ );
Returns

Examples

Here, we retrieve an input report (inputReport) and get the content of the report in the handler for the InputReportReceived event, triggered when the asynchronous call completes.

HidInputReport inputReport = await device.GetInputReportAsync();
.
.
.
private void InputReportReceived(
    HidDevice sender, 
    HidInputReportReceivedEventArgs args)
    {
        HidInputReport inputReport = args.Report;
        IBuffer buffer = inputReport.Data;
        DataReader dr = DataReader.FromBuffer(buffer);
        byte[] bytes = new byte[inputReport.Data.Length];
        dr.ReadBytes(bytes);

        String inputReportContent = 
           System.Text.Encoding.ASCII.GetString(bytes);
    }

Remarks

When this method completes, the InputReportReceived event is triggered.

To access the content of the input report, you must set up a listener for the InputReportReceived event and get the Report property of HidInputReportReceivedEventArgs object in the event handler.

See Also

GetInputReportAsync(UInt16) GetInputReportAsync(UInt16) GetInputReportAsync(UInt16) GetInputReportAsync(UInt16)

Asynchronously retrieves an input report, identified by the reportId parameter, from the given HID device.

public : IAsyncOperation<HidInputReport> GetInputReportAsync(unsigned short reportId)
public IAsyncOperation<HidInputReport> GetInputReportAsync(UInt16 reportId)
Public Function GetInputReportAsync(reportId As UInt16) As IAsyncOperation( Of HidInputReport )
Windows.Devices.HumanInterfaceDevice.HidDevice.getInputReportAsync(reportId).done( /* Your success and error handlers */ );
Parameters
reportId
unsigned short UInt16 UInt16 UInt16

Identifies the requested input report.

Returns

Examples

Here, we retrieve an input report (inputReport) and get the content of the report in the handler for the InputReportReceived event, triggered when the asynchronous call completes.

HidInputReport inputReport = await device.GetInputReportAsync();
.
.
.
private void InputReportReceived(
    HidDevice sender, 
    HidInputReportReceivedEventArgs args)
    {
        HidInputReport inputReport = args.Report;
        IBuffer buffer = inputReport.Data;
        DataReader dr = DataReader.FromBuffer(buffer);
        byte[] bytes = new byte[inputReport.Data.Length];
        dr.ReadBytes(bytes);

        String inputReportContent = 
           System.Text.Encoding.ASCII.GetString(bytes);
    }

Remarks

When this method completes, the InputReportReceived event is triggered.

To access the content of the input report, you must set up a listener for the InputReportReceived event and get the Report property of HidInputReportReceivedEventArgs object in the event handler.

See Also

GetNumericControlDescriptions(HidReportType, UInt16, UInt16) GetNumericControlDescriptions(HidReportType, UInt16, UInt16) GetNumericControlDescriptions(HidReportType, UInt16, UInt16) GetNumericControlDescriptions(HidReportType, UInt16, UInt16)

Retrieves the descriptions of the numeric controls for the given HID device.

public : IVectorView<HidNumericControlDescription> GetNumericControlDescriptions(HidReportType reportType, unsigned short usagePage, unsigned short usageId)
public IReadOnlyList<HidNumericControlDescription> GetNumericControlDescriptions(HidReportType reportType, UInt16 usagePage, UInt16 usageId)
Public Function GetNumericControlDescriptions(reportType As HidReportType, usagePage As UInt16, usageId As UInt16) As IReadOnlyList<HidNumericControlDescription>( Of HidNumericControlDescription )
var iVectorView = hidDevice.getNumericControlDescriptions(reportType, usagePage, usageId);
Parameters
reportType
HidReportType HidReportType HidReportType HidReportType

Specifies the type of report for which the control descriptions are requested.

usagePage
unsigned short UInt16 UInt16 UInt16

Identifies the usage page associated with the controls.

usageId
unsigned short UInt16 UInt16 UInt16

Identifies the usage associated with the controls.

Returns
IVectorView<HidNumericControlDescription> IReadOnlyList<HidNumericControlDescription> IReadOnlyList<HidNumericControlDescription> IReadOnlyList<HidNumericControlDescription>

A vector of HidNumericControlDescription objects.

SendFeatureReportAsync(HidFeatureReport) SendFeatureReportAsync(HidFeatureReport) SendFeatureReportAsync(HidFeatureReport) SendFeatureReportAsync(HidFeatureReport)

Sends an feature report asynchronously from the host to the device.

public : IAsyncOperation<unsigned int> SendFeatureReportAsync(HidFeatureReport featureReport)
public IAsyncOperation<uint> SendFeatureReportAsync(HidFeatureReport featureReport)
Public Function SendFeatureReportAsync(featureReport As HidFeatureReport) As IAsyncOperation( Of uint )
Windows.Devices.HumanInterfaceDevice.HidDevice.sendFeatureReportAsync(featureReport).done( /* Your success and error handlers */ );
Parameters
featureReport
HidFeatureReport HidFeatureReport HidFeatureReport HidFeatureReport

The feature report which the host sends to the device.

Returns

The result of the asynchronous operation.

SendOutputReportAsync(HidOutputReport) SendOutputReportAsync(HidOutputReport) SendOutputReportAsync(HidOutputReport) SendOutputReportAsync(HidOutputReport)

Sends an output report asynchronously from the host to the device.

public : IAsyncOperation<unsigned int> SendOutputReportAsync(HidOutputReport outputReport)
public IAsyncOperation<uint> SendOutputReportAsync(HidOutputReport outputReport)
Public Function SendOutputReportAsync(outputReport As HidOutputReport) As IAsyncOperation( Of uint )
Windows.Devices.HumanInterfaceDevice.HidDevice.sendOutputReportAsync(outputReport).done( /* Your success and error handlers */ );
Parameters
outputReport
HidOutputReport HidOutputReport HidOutputReport HidOutputReport

The output report which the host sends to the device.

Returns

Specifies the count of bytes written to the device.

Events

InputReportReceived InputReportReceived InputReportReceived InputReportReceived

Establishes an event listener to handle input reports issued by the device when either GetInputReportAsync() or GetInputReportAsync(System.UInt16 reportId) is called.

public : event TypedEventHandler InputReportReceived<HidDevice, HidInputReportReceivedEventArgs>
public event TypedEventHandler InputReportReceived<HidDevice, HidInputReportReceivedEventArgs>
Public Event TypedEventHandler InputReportReceived( Of ( Of HidDevice ), ( Of HidInputReportReceivedEventArgs ))
function onInputReportReceived(eventArgs){/* Your code */}


hidDevice.addEventListener("inputReportReceived", onInputReportReceived);
hidDevice.removeEventListener("inputReportReceived", onInputReportReceived);

Examples

Here, we retrieve an input report (inputReport) and get the content of the report in the handler for the InputReportReceived event, triggered when the asynchronous call completes.

HidInputReport inputReport = await device.GetInputReportAsync();
.
.
.
private void InputReportReceived(
    HidDevice sender, 
    HidInputReportReceivedEventArgs args)
    {
        HidInputReport inputReport = args.Report;
        IBuffer buffer = inputReport.Data;
        DataReader dr = DataReader.FromBuffer(buffer);
        byte[] bytes = new byte[inputReport.Data.Length];
        dr.ReadBytes(bytes);

        String inputReportContent = 
           System.Text.Encoding.ASCII.GetString(bytes);
    }

Remarks

This method waits for the device to interrupt the host when it has data to send. Internally, the HID WinRT API sends a IOCTL read request to a lower driver in the stack.

The IOCTL is translated by the HID minidriver into a protocol-specific request. For a USB device, the minidriver translates this into an INTERRUPT IN request. And, for an I2C device that is running over the Microsoft HID-I2C miniport driver, the minidriver will wait for the device to assert an interrupt.