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 // HID top-level collection attributes.
10 // Each enumerated device interface exposes an array of these objects.
11 // |usagePage|: HID usage page identifier.
12 // |usage|: Page-defined usage identifier.
13 // |reportIds|: Report IDs which belong to the collection and to its children.
14 dictionary HidCollectionInfo
{
20 // Returned by <code>getDevices</code> functions to describes a connected HID
21 // device. Use <code>connect</code> to connect to any of the returned devices.
22 // |deviceId|: Device opaque ID.
23 // |vendorId|: Vendor ID.
24 // |productId|: Product ID.
25 // |collections|: Top-level collections from this device's report descriptor.
26 // |maxInputReportSize|: Top-level collection's max input report size.
27 // |maxOutputReportSize|: Top-level collection's max output report size.
28 // |maxFeatureReportSize|: Top-level collection's max feature report size.
29 dictionary HidDeviceInfo
{
33 HidCollectionInfo
[] collections
;
34 long maxInputReportSize
;
35 long maxOutputReportSize
;
36 long maxFeatureReportSize
;
39 // Returned by <code>connect</code> to represent a communication session with
40 // an HID device. Must be closed with a call to <code>disconnect</code>.
41 dictionary HidConnectInfo
{
45 // Searching criteria to enumerate devices with.
46 dictionary GetDevicesOptions
{
51 callback GetDevicesCallback
= void (HidDeviceInfo
[] devices
);
52 callback ConnectCallback
= void (HidConnectInfo connection
);
53 callback DisconnectCallback
= void ();
55 // The callback to be invoked when a <code>receive</code> call is finished.
56 // |reportId|: The ID of the report.
57 // |data|: The content of the report.
58 callback ReceiveCallback
= void (long reportId
, ArrayBuffer data
);
60 // The callback to be invoked when a <code>receiveFeatureReport</code> call
62 // |data|: The content of the report.
63 callback ReceiveFeatureReportCallback
= void (ArrayBuffer data
);
65 // The callback to be invoked when a <code>send</code> or
66 // <code>sendFeatureReport</code> call is finished.
67 callback SendCallback
= void();
70 // Enumerate all the connected HID devices specified by the vendorId/
71 // productId/interfaceId tuple.
72 // |options|: The properties to search for on target devices.
73 // |callback|: Invoked with the <code>HidDeviceInfo</code> array on success.
74 static
void getDevices
(GetDevicesOptions options
,
75 GetDevicesCallback
callback);
77 // Open a connection to an HID device for communication.
78 // |deviceId|: The ID of the device to open.
79 // |callback|: Invoked with an <code>HidConnectInfo</code>.
80 static
void connect
(long deviceId
,
81 ConnectCallback
callback);
83 // Disconnect from a device. Invoking operations on a device after calling
84 // this is safe but has no effect.
85 // |connectionId|: The connection to close.
86 // |callback|: The callback to invoke once the device is closed.
87 static
void disconnect
(long connectionId
,
88 optional DisconnectCallback
callback);
90 // Receive an Input report from an HID device.
92 // Input reports are returned to the host through the INTERRUPT IN endpoint.
93 // |connectionId|: The connection from which to receive a report.
94 // |callback|: The callback to invoke with received report.
95 static
void receive
(long connectionId
,
96 ReceiveCallback
callback);
98 // Send an Output report to an HID device.
99 // <code>send</code> will send the data on the first OUT endpoint, if one
100 // exists. If one does not exist, the report will be sent through the
103 // |connectionId|: The connection to which to send a report.
104 // |reportId|: The report ID to use, or <code>0</code> if none.
105 // |data|: The report data.
106 // |callback|: The callback to invoke once the write is finished.
107 static
void send
(long connectionId
,
110 SendCallback
callback);
112 // Receive a Feature report from the device.
114 // |connectionId|: The connection to read Input report from.
115 // |reportId|: The report ID, or zero if none.
116 // |callback|: The callback to invoke once the write is finished.
117 static
void receiveFeatureReport
(long connectionId
,
119 ReceiveFeatureReportCallback
callback);
121 // Send a Feature report to the device.
123 // Feature reports are sent over the Control endpoint as a Set_Report
125 // |connectionId|: The connection to read Input report from.
126 // |reportId|: The report ID to use, or <code>0</code> if none.
127 // |data|: The report data.
128 // |callback|: The callback to invoke once the write is finished.
129 static
void sendFeatureReport
(long connectionId
,
132 SendCallback
callback);