HidDevice HidDevice HidDevice HidDevice Class

Represents a top-level collection and the corresponding device.

Syntax

Declaration

public sealed class HidDevicepublic sealed class HidDevicePublic NotInheritable Class HidDevicepublic sealed class HidDevice

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 summary

Gets the product identifier for the given HID device.

Gets the usage identifier for the given HID device.

Gets the usage page of the top-level collection.

Gets the vendor identifier for the given HID device.

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

Methods summary

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Events summary

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

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 ushortpublic ushort ProductId { get; }

    Property 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 ushortpublic ushort UsageId { get; }

    Property 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 ushortpublic ushort UsagePage { get; }

    Property 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 ushortpublic ushort VendorId { get; }

    Property 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 ushortpublic ushort Version { get; }

    Property 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()public void Close()Public Function Close() As voidpublic void 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 HidFeatureReportpublic HidFeatureReport CreateFeatureReport()

    Returns

  • 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(UInt16 reportId)public HidFeatureReport CreateFeatureReport(UInt16 reportId)Public Function CreateFeatureReport(reportId As UInt16) As HidFeatureReportpublic HidFeatureReport CreateFeatureReport(UInt16 reportId)

    Parameters

    • reportId
      System.UInt16
      System.UInt16
      System.UInt16
      System.UInt16

      Identifies the report being created.

    Returns

  • 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 HidOutputReportpublic HidOutputReport CreateOutputReport()

    Returns

  • 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(UInt16 reportId)public HidOutputReport CreateOutputReport(UInt16 reportId)Public Function CreateOutputReport(reportId As UInt16) As HidOutputReportpublic HidOutputReport CreateOutputReport(UInt16 reportId)

    Parameters

    • reportId
      System.UInt16
      System.UInt16
      System.UInt16
      System.UInt16

      Identifies the report being created.

    Returns

  • 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(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 )public static IAsyncOperation<HidDevice> FromIdAsync(String deviceId, FileAccessMode accessMode)

    Parameters

    Returns

    • A HidDevice object.

    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, 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 )public IVectorView<HidBooleanControlDescription> GetBooleanControlDescriptions(HidReportType reportType, UInt16 usagePage, UInt16 usageId)

    Parameters

    • reportType

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

    • usagePage
      System.UInt16
      System.UInt16
      System.UInt16
      System.UInt16

      Identifies the usage page associated with the controls.

    • usageId
      System.UInt16
      System.UInt16
      System.UInt16
      System.UInt16

      Identifies the usage associated with the controls.

    Returns

    • 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 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 stringpublic static string GetDeviceSelector(UInt16 usagePage, UInt16 usageId)

    Parameters

    • usagePage
      System.UInt16
      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
      System.UInt16

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

    Returns

    • string
      string
      string
      string

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

  • 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 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 stringpublic static string GetDeviceSelector(UInt16 usagePage, UInt16 usageId, UInt16 vendorId, UInt16 productId)

    Parameters

    • usagePage
      System.UInt16
      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
      System.UInt16

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

    • vendorId
      System.UInt16
      System.UInt16
      System.UInt16
      System.UInt16

      Identifies the device vendor.

    • productId
      System.UInt16
      System.UInt16
      System.UInt16
      System.UInt16

      Identifies the product.

    Returns

    • string
      string
      string
      string

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

  • 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 )public IAsyncOperation<HidFeatureReport> GetFeatureReportAsync()

    Returns

    • A HidFeatureReport object.

    Remarks

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

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

    Parameters

    • reportId
      System.UInt16
      System.UInt16
      System.UInt16
      System.UInt16

      Identifies the requested feature report.

    Returns

    • A HidFeatureReport object.

  • 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 )public IAsyncOperation<HidInputReport> GetInputReportAsync()

    Returns

    • A HidInputReport object.

    Remarks

    This instance of the method retrieves an input report.

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

    Parameters

    • reportId
      System.UInt16
      System.UInt16
      System.UInt16
      System.UInt16

      Identifies the requested input report.

    Returns

    • A HidInputReport object.

  • 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, 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 )public IVectorView<HidNumericControlDescription> GetNumericControlDescriptions(HidReportType reportType, UInt16 usagePage, UInt16 usageId)

    Parameters

    • reportType

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

    • usagePage
      System.UInt16
      System.UInt16
      System.UInt16
      System.UInt16

      Identifies the usage page associated with the controls.

    • usageId
      System.UInt16
      System.UInt16
      System.UInt16
      System.UInt16

      Identifies the usage associated with the controls.

    Returns

    • 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<uint> SendFeatureReportAsync(HidFeatureReport featureReport)public IAsyncOperation<uint> SendFeatureReportAsync(HidFeatureReport featureReport)Public Function SendFeatureReportAsync(featureReport As HidFeatureReport) As IAsyncOperation( Of uint )public IAsyncOperation<uint> SendFeatureReportAsync(HidFeatureReport featureReport)

    Parameters

    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<uint> SendOutputReportAsync(HidOutputReport outputReport)public IAsyncOperation<uint> SendOutputReportAsync(HidOutputReport outputReport)Public Function SendOutputReportAsync(outputReport As HidOutputReport) As IAsyncOperation( Of uint )public IAsyncOperation<uint> SendOutputReportAsync(HidOutputReport outputReport)

    Parameters

    Returns

    • Specifies the count of bytes written to the device.

Events

  • InputReportReceived
    InputReportReceived
    InputReportReceived
    InputReportReceived

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

    public event TypedEventHandler InputReportReceivedpublic event TypedEventHandler InputReportReceivedPublic Event InputReportReceivedpublic event TypedEventHandler InputReportReceived

    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.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

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

Details

Assembly

Windows.Devices.HumanInterfaceDevice.dll