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