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.
4
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.
8//
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.
12namespace hid {
13  dictionary HidCollectionInfo {
14    // HID usage page identifier.
15    long usagePage;
16    // Page-defined usage identifier.
17    long usage;
18    // Report IDs which belong to the collection and to its children.
19    long[] reportIds;
20  };
21
22  [noinline_doc] dictionary HidDeviceInfo {
23    // Opaque device ID.
24    long deviceId;
25    // Vendor ID.
26    long vendorId;
27    // Product ID.
28    long productId;
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  };
38
39  dictionary HidConnectInfo {
40    // The opaque ID used to identify this connection in all other functions.
41    long connectionId;
42  };
43
44  [noinline_doc] dictionary DeviceFilter {
45    // Device vendor ID.
46    long? vendorId;
47    // Device product ID, only checked only if the vendor ID matches.
48    long? productId;
49    // HID usage page identifier.
50    long? usagePage;
51    // HID usage identifier, checked only if the HID usage page matches.
52    long? usage;
53  };
54
55  dictionary GetDevicesOptions {
56    [deprecated="Equivalent to setting $(ref:DeviceFilter.vendorId)."]
57    long? vendorId;
58    [deprecated="Equivalent to setting $(ref:DeviceFilter.productId)."]
59    long? productId;
60    // A device matching any given filter will be returned. An empty filter list
61    // will return all devices the app has permission for.
62    DeviceFilter[]? filters;
63  };
64
65  callback GetDevicesCallback = void (HidDeviceInfo[] devices);
66  callback ConnectCallback = void (HidConnectInfo connection);
67  callback DisconnectCallback = void ();
68
69  // |reportId|: The report ID or <code>0</code> if none.
70  // |data|: The content of the report.
71  callback ReceiveCallback = void (long reportId, ArrayBuffer data);
72
73  // |data|: The content of the report.
74  callback ReceiveFeatureReportCallback = void (ArrayBuffer data);
75
76  callback SendCallback = void();
77
78  interface Functions {
79    // Enumerate connected HID devices.
80    // |options|: The properties to search for on target devices.
81    static void getDevices(GetDevicesOptions options,
82                           GetDevicesCallback callback);
83
84    // Open a connection to an HID device for communication.
85    // |deviceId|: The $(ref:HidDeviceInfo.deviceId) of the device to open.
86    static void connect(long deviceId,
87                        ConnectCallback callback);
88
89    // Disconnect from a device. Invoking operations on a device after calling
90    // this is safe but has no effect.
91    // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
92    static void disconnect(long connectionId,
93                           optional DisconnectCallback callback);
94
95    // Receive the next input report from the device.
96    // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
97    static void receive(long connectionId,
98                        ReceiveCallback callback);
99
100    // Send an output report to the device.
101    // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
102    // |reportId|: The report ID to use, or <code>0</code> if none.
103    // |data|: The report data.
104    static void send(long connectionId,
105                     long reportId,
106                     ArrayBuffer data,
107                     SendCallback callback);
108
109    // Request a feature report from the device.
110    // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
111    // |reportId|: The report ID, or <code>0</code> if none.
112    static void receiveFeatureReport(long connectionId,
113                                     long reportId,
114                                     ReceiveFeatureReportCallback callback);
115
116    // Send a feature report to the device.
117    // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
118    // |reportId|: The report ID to use, or <code>0</code> if none.
119    // |data|: The report data.
120    static void sendFeatureReport(long connectionId,
121                                  long reportId,
122                                  ArrayBuffer data,
123                                  SendCallback callback);
124  };
125};
126