1 // Copyright 2014 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 // Use the <code>chrome.hid</code> API to interact with connected HID devices.
6 // This API provides access to HID operations from within the context of an app.
7 // Using this API, apps can function as drivers for hardware devices.
9 // Errors generated by this API are reported by setting
10 // $(ref:runtime.lastError) and executing the function's regular callback. The
11 // callback's regular parameters will be undefined in this case.
13 dictionary HidCollectionInfo
{
14 // HID usage page identifier.
16 // Page-defined usage identifier.
18 // Report IDs which belong to the collection and to its children.
22 [noinline_doc
] dictionary HidDeviceInfo
{
29 // Top-level collections from this device's report descriptors.
30 HidCollectionInfo
[] collections
;
31 // Top-level collection's maximum input report size.
32 long maxInputReportSize
;
33 // Top-level collection's maximum output report size.
34 long maxOutputReportSize
;
35 // Top-level collection's maximum feature report size.
36 long maxFeatureReportSize
;
37 // Raw device report descriptor (not available on Windows).
38 ArrayBuffer reportDescriptor
;
41 dictionary HidConnectInfo
{
42 // The opaque ID used to identify this connection in all other functions.
46 [noinline_doc
] dictionary DeviceFilter
{
49 // Device product ID, only checked only if the vendor ID matches.
51 // HID usage page identifier.
53 // HID usage identifier, checked only if the HID usage page matches.
57 dictionary GetDevicesOptions
{
58 [deprecated
="Equivalent to setting $(ref:DeviceFilter.vendorId)."]
60 [deprecated
="Equivalent to setting $(ref:DeviceFilter.productId)."]
62 // A device matching any given filter will be returned. An empty filter list
63 // will return all devices the app has permission for.
64 DeviceFilter
[]? filters
;
67 callback GetDevicesCallback
= void (HidDeviceInfo
[] devices
);
68 callback ConnectCallback
= void (HidConnectInfo connection
);
69 callback DisconnectCallback
= void ();
71 // |reportId|: The report ID or <code>0</code> if none.
72 // |data|: The report data, the report ID prefix (if present) is removed.
73 callback ReceiveCallback
= void (long reportId
, ArrayBuffer data
);
75 // |data|: The report data, including a report ID prefix if one is sent by the
77 callback ReceiveFeatureReportCallback
= void (ArrayBuffer data
);
79 callback SendCallback
= void();
82 // Enumerate connected HID devices.
83 // |options|: The properties to search for on target devices.
84 static
void getDevices
(GetDevicesOptions options
,
85 GetDevicesCallback
callback);
87 // Open a connection to an HID device for communication.
88 // |deviceId|: The $(ref:HidDeviceInfo.deviceId) of the device to open.
89 static
void connect
(long deviceId
,
90 ConnectCallback
callback);
92 // Disconnect from a device. Invoking operations on a device after calling
93 // this is safe but has no effect.
94 // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
95 static
void disconnect
(long connectionId
,
96 optional DisconnectCallback
callback);
98 // Receive the next input report from the device.
99 // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
100 static
void receive
(long connectionId
,
101 ReceiveCallback
callback);
103 // Send an output report to the device.
105 // <em>Note:</em> Do not include a report ID prefix in <code>data</code>.
106 // It will be added if necessary.
107 // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
108 // |reportId|: The report ID to use, or <code>0</code> if none.
109 // |data|: The report data.
110 static
void send
(long connectionId
,
113 SendCallback
callback);
115 // Request a feature report from the device.
116 // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
117 // |reportId|: The report ID, or <code>0</code> if none.
118 static
void receiveFeatureReport
(long connectionId
,
120 ReceiveFeatureReportCallback
callback);
122 // Send a feature report to the device.
124 // <em>Note:</em> Do not include a report ID prefix in <code>data</code>.
125 // It will be added if necessary.
126 // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
127 // |reportId|: The report ID to use, or <code>0</code> if none.
128 // |data|: The report data.
129 static
void sendFeatureReport
(long connectionId
,
132 SendCallback
callback);
136 // Event generated when a device is added to the system. Events are only
137 // broadcast to apps and extensions that have permission to access the
138 // device. Permission may have been granted at install time or when the user
139 // accepted an optional permission (see $(ref:permissions.request)).
140 static
void onDeviceAdded
(HidDeviceInfo device
);
142 // Event generated when a device is removed from the system. See
143 // $(ref:onDeviceAdded) for which events are delivered.
144 // |deviceId|: The <code>deviceId</code> property of the device passed to
145 // $(ref:onDeviceAdded).
146 static
void onDeviceRemoved
(long deviceId
);