<!--
{
  "availability" : [
    "macOS: 15.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "CoreHID",
  "identifier" : "/documentation/CoreHID/HIDDeviceClient",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Core HID"
    ],
    "preciseIdentifier" : "s:7CoreHID15HIDDeviceClientC"
  },
  "title" : "HIDDeviceClient"
}
-->

# HIDDeviceClient

A client of a physical or virtual HID compatible peripheral.

```
actor HIDDeviceClient
```

## Overview

A human interface device (HID) is a computer peripheral intended to provide direction to the system from human input. The specification is a broad, industry-wide standard, maintained by the USB Implementers Forum. For more details, see [Human Interface Devices (HID) Specifications and Tools](https://www.usb.org/hid).

A [`HIDDeviceClient`](/documentation/CoreHID/HIDDeviceClient) is a connection to one HID device on the system. It’s created using a [`HIDDeviceClient.DeviceReference`](/documentation/CoreHID/HIDDeviceClient/DeviceReference-swift.struct), received from a [`HIDDeviceManager`](/documentation/CoreHID/HIDDeviceManager). A [`HIDDeviceClient.DeviceReference`](/documentation/CoreHID/HIDDeviceClient/DeviceReference-swift.struct) is a simple reference to a specific HID device. The HID peripheral can be a USB device like a wired mouse, a Bluetooth device like a wireless keyboard, an onboard sensor like an accelerometer, or even a software based, virtual peripheral created using [`HIDVirtualDevice`](/documentation/CoreHID/HIDVirtualDevice).

A [`HIDDeviceClient`](/documentation/CoreHID/HIDDeviceClient) receives device notifications, such as input HID reports that are dispatched from the device in response to human input (like a keyboard key press) in [`monitorNotifications(reportIDsToMonitor:elementsToMonitor:)`](/documentation/CoreHID/HIDDeviceClient/monitorNotifications(reportIDsToMonitor:elementsToMonitor:)). It sends get and set reports to the device to retrieve information or configure device functionality using [`dispatchSetReportRequest(type:id:data:timeout:)`](/documentation/CoreHID/HIDDeviceClient/dispatchSetReportRequest(type:id:data:timeout:)). [`dispatchGetReportRequest(type:id:timeout:)`](/documentation/CoreHID/HIDDeviceClient/dispatchGetReportRequest(type:id:timeout:)). It monitors or updates specific pieces of the HID report using [`HIDElement`](/documentation/CoreHID/HIDElement).

## Topics

### Create a device client

[`init?(deviceReference: HIDDeviceClient.DeviceReference)`](/documentation/CoreHID/HIDDeviceClient/init(deviceReference:))

Creates a client for a HID device.

[`struct DeviceReference`](/documentation/CoreHID/HIDDeviceClient/DeviceReference-swift.struct)

A reference to a HID device on the system.

[`let deviceReference: HIDDeviceClient.DeviceReference`](/documentation/CoreHID/HIDDeviceClient/deviceReference-swift.property)

The reference to the HID device used to create the  HID client device.

### Get device information

[`let descriptor: Data`](/documentation/CoreHID/HIDDeviceClient/descriptor)

The HID specification compliant report descriptor for the associated HID device.

[`let deviceUsages: [HIDUsage]`](/documentation/CoreHID/HIDDeviceClient/deviceUsages)

A convenient list of all the usages that the device supports.

[`var isBuiltIn: Bool`](/documentation/CoreHID/HIDDeviceClient/isBuiltIn)

A Boolean value that determines whether the device is built-in to the system or an external peripheral.

[`var localizationCode: HIDDeviceLocalizationCode`](/documentation/CoreHID/HIDDeviceClient/localizationCode)

A location code that specifies the HID compliant localization code, if there is one.

[`var locationID: UInt64?`](/documentation/CoreHID/HIDDeviceClient/locationID)

The location ID for the device, if there is one.

[`var manufacturer: String?`](/documentation/CoreHID/HIDDeviceClient/manufacturer)

The manufacturer of the device, if known.

[`var modelNumber: String?`](/documentation/CoreHID/HIDDeviceClient/modelNumber)

The model number for the device, if known.

[`let primaryUsage: HIDUsage`](/documentation/CoreHID/HIDDeviceClient/primaryUsage)

The HID specification compliant usage for the device.

[`var product: String?`](/documentation/CoreHID/HIDDeviceClient/product)

The product name for the device, if known.

[`let productID: UInt32`](/documentation/CoreHID/HIDDeviceClient/productID)

The product ID for the device.

[`var serialNumber: String?`](/documentation/CoreHID/HIDDeviceClient/serialNumber)

The serial number of the device, if known.

[`var transport: HIDDeviceTransport?`](/documentation/CoreHID/HIDDeviceClient/transport)

The data transport for the device.

[`var uniqueID: String?`](/documentation/CoreHID/HIDDeviceClient/uniqueID)

A unique ID for the device, if there is one.

[`let vendorID: UInt32`](/documentation/CoreHID/HIDDeviceClient/vendorID)

The vendor ID for the device.

[`var versionNumber: UInt64?`](/documentation/CoreHID/HIDDeviceClient/versionNumber)

The version of the device, if known.

[`var elements: [HIDElement]`](/documentation/CoreHID/HIDDeviceClient/elements)

All HID elements associated with the device.

### Interact with the device

[`func dispatchGetReportRequest(type: HIDReportType, id: HIDReportID?, timeout: Duration?) async throws -> Data`](/documentation/CoreHID/HIDDeviceClient/dispatchGetReportRequest(type:id:timeout:))

Send a get report request to the device over the transport.

[`func dispatchSetReportRequest(type: HIDReportType, id: HIDReportID?, data: Data, timeout: Duration?) async throws`](/documentation/CoreHID/HIDDeviceClient/dispatchSetReportRequest(type:id:data:timeout:))

Send a set report request to the device over the transport.

[`func seizeDevice() throws`](/documentation/CoreHID/HIDDeviceClient/seizeDevice())

Attempt to obtain the device so that this client is the only active client.

### Monitor device notifications

[`func monitorNotifications(reportIDsToMonitor: [ClosedRange<HIDReportID>], elementsToMonitor: [HIDElement]) -> AsyncThrowingStream<HIDDeviceClient.Notification, any Error>`](/documentation/CoreHID/HIDDeviceClient/monitorNotifications(reportIDsToMonitor:elementsToMonitor:))

Creates an asynchronous that receives notifications about the associated device.

[`enum Notification`](/documentation/CoreHID/HIDDeviceClient/Notification)

Notifications for a HID device.

### Update element values

[`func updateElements([any HIDElementUpdate], timeout: Duration?) async -> HIDDeviceClient.HIDElementUpdateResult`](/documentation/CoreHID/HIDDeviceClient/updateElements(_:timeout:))

Provide new update values for, or request current values from, lists of elements.

[`struct RequestElementUpdate`](/documentation/CoreHID/HIDDeviceClient/RequestElementUpdate)

A request to pull the current value from a list of HID elements

[`struct ProvideElementUpdate`](/documentation/CoreHID/HIDDeviceClient/ProvideElementUpdate)

A structure that provides values for a list of HID elements.

[`struct HIDElementUpdateResult`](/documentation/CoreHID/HIDDeviceClient/HIDElementUpdateResult)

A class to hold the results of an element update.

### Structures

[`struct UnsafeProperty`](/documentation/CoreHID/HIDDeviceClient/UnsafeProperty)

A wrapper around an object to facilitate working with subscripts.

### Subscripts

[`subscript(String) -> HIDDeviceClient.UnsafeProperty?`](/documentation/CoreHID/HIDDeviceClient/subscript(_:))

Get or set a property from the device.

## Relationships

### Conforms To

[`Equatable`](/documentation/Swift/Equatable)

[`Sendable`](/documentation/Swift/Sendable)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`Actor`](/documentation/Swift/Actor)

[`Copyable`](/documentation/Swift/Copyable)

[`Hashable`](/documentation/Swift/Hashable)

[`Escapable`](/documentation/Swift/Escapable)

[`SendableMetatype`](/documentation/Swift/SendableMetatype)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)