Hid​Device Hid​Device Hid​Device Class

Definition

Represents a top-level collection and the corresponding device.

public sealed class HidDevice : IHidDevice, IClosablepublic sealed class HidDevice : IHidDevice, IDisposablePublic NotInheritable Class HidDevice Implements IHidDevice, IDisposable
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 Windows Store 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

Gets the product identifier for the given HID device.

public ushort ProductId { get; }public ushort ProductId { get; }Public ReadOnly Property ProductId As ushort
Value
ushort ushort ushort

The product identifier.

Attributes

Remarks

Valid values are 0 through 0xFFFF.

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

The usage identifier.

Attributes

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

The usage page.

Attributes

Remarks

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

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

The vendor identifier.

Attributes

Remarks

Valid values are 0 through 0xFFFF.

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

The version number.

Attributes

Remarks

The version is retrieved from the device descriptor.

Valid values are 0 through 0xFFFF.

Methods

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
Attributes

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
Returns
Attributes

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(UInt16 reportId)public HidFeatureReport CreateFeatureReport(UInt16 reportId)Public Function CreateFeatureReport(reportId As UInt16) As HidFeatureReport
Parameters
reportId
System.UInt16 System.UInt16 System.UInt16

Identifies the report being created.

Returns
Attributes

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
Returns

A HidOutputReport object.

Attributes

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(UInt16 reportId)public HidOutputReport CreateOutputReport(UInt16 reportId)Public Function CreateOutputReport(reportId As UInt16) As HidOutputReport
Parameters
reportId
System.UInt16 System.UInt16 System.UInt16

Identifies the report being created.

Returns

A HidOutputReport object.

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, 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(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 )
Parameters
deviceId
System.String System.String System.String

The DeviceInformation ID that identifies the HID device.

accessMode
FileAccessMode FileAccessMode FileAccessMode

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

Returns

A HidDevice object.

Attributes

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)

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

public IVectorView<HidBooleanControlDescription> GetBooleanControlDescriptions(HidReportType reportType, UInt16 usagePage, UInt16 usageId)public IVectorView<HidBooleanControlDescription> GetBooleanControlDescriptions(HidReportType reportType, UInt16 usagePage, UInt16 usageId)Public Function GetBooleanControlDescriptions(reportType As HidReportType, usagePage As UInt16, usageId As UInt16) As IVectorView( Of HidBooleanControlDescription )
Parameters
reportType
HidReportType HidReportType HidReportType

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

usagePage
System.UInt16 System.UInt16 System.UInt16

Identifies the usage page associated with the controls.

usageId
System.UInt16 System.UInt16 System.UInt16

Identifies the usage associated with the controls.

Returns

A vector of HidBooleanControlDescription objects.

Attributes

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)

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

public static PlatForm::String GetDeviceSelector(UInt16 usagePage, UInt16 usageId)public static string GetDeviceSelector(UInt16 usagePage, UInt16 usageId)Public Static Function GetDeviceSelector(usagePage As UInt16, usageId As UInt16) As string
Parameters
usagePage
System.UInt16 System.UInt16 System.UInt16

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

usageId
System.UInt16 System.UInt16 System.UInt16

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

Returns
string string string

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

Attributes

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(UInt16 usagePage, UInt16 usageId, UInt16 vendorId, UInt16 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
Parameters
usagePage
System.UInt16 System.UInt16 System.UInt16

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

usageId
System.UInt16 System.UInt16 System.UInt16

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

vendorId
System.UInt16 System.UInt16 System.UInt16

Identifies the device vendor.

productId
System.UInt16 System.UInt16 System.UInt16

Identifies the product.

Returns
string string string

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

Attributes

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 )
Returns

A HidFeatureReport object.

Attributes

Remarks

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

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(UInt16 reportId)public IAsyncOperation<HidFeatureReport> GetFeatureReportAsync(UInt16 reportId)Public Function GetFeatureReportAsync(reportId As UInt16) As IAsyncOperation( Of HidFeatureReport )
Parameters
reportId
System.UInt16 System.UInt16 System.UInt16

Identifies the requested feature report.

Returns

A HidFeatureReport object.

Attributes

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 )
Returns

A HidInputReport object.

Attributes

Remarks

This instance of the method retrieves an input report.

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(UInt16 reportId)public IAsyncOperation<HidInputReport> GetInputReportAsync(UInt16 reportId)Public Function GetInputReportAsync(reportId As UInt16) As IAsyncOperation( Of HidInputReport )
Parameters
reportId
System.UInt16 System.UInt16 System.UInt16

Identifies the requested input report.

Returns

A HidInputReport object.

Attributes

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, UInt16 usagePage, UInt16 usageId)public IVectorView<HidNumericControlDescription> GetNumericControlDescriptions(HidReportType reportType, UInt16 usagePage, UInt16 usageId)Public Function GetNumericControlDescriptions(reportType As HidReportType, usagePage As UInt16, usageId As UInt16) As IVectorView( Of HidNumericControlDescription )
Parameters
reportType
HidReportType HidReportType HidReportType

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

usagePage
System.UInt16 System.UInt16 System.UInt16

Identifies the usage page associated with the controls.

usageId
System.UInt16 System.UInt16 System.UInt16

Identifies the usage associated with the controls.

Returns

A vector of HidNumericControlDescription objects.

Attributes

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

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

public IAsyncOperation<uint> SendFeatureReportAsync(HidFeatureReport featureReport)public IAsyncOperation<uint> SendFeatureReportAsync(HidFeatureReport featureReport)Public Function SendFeatureReportAsync(featureReport As HidFeatureReport) As IAsyncOperation( Of uint )
Parameters
featureReport
HidFeatureReport HidFeatureReport HidFeatureReport

The feature report which the host sends to the device.

Returns

The result of the asynchronous operation.

Attributes

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

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

public IAsyncOperation<uint> SendOutputReportAsync(HidOutputReport outputReport)public IAsyncOperation<uint> SendOutputReportAsync(HidOutputReport outputReport)Public Function SendOutputReportAsync(outputReport As HidOutputReport) As IAsyncOperation( Of uint )
Parameters
outputReport
HidOutputReport HidOutputReport HidOutputReport

The output report which the host sends to the device.

Returns

Specifies the count of bytes written to the device.

Attributes

Events

InputReportReceived InputReportReceived InputReportReceived

Establishes an event listener which handles input reports issued by the device.

public event TypedEventHandler InputReportReceivedpublic event TypedEventHandler InputReportReceivedPublic Event InputReportReceived
Attributes

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.