extensions/common/api/hid.idl

   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.
  12 namespace 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     // The product name read from the device, if available.
  30     DOMString productName;
  31     // The serial number read from the device, if available.
  32     DOMString serialNumber;
  33     // Top-level collections from this device's report descriptors.
  34     HidCollectionInfo[] collections;
  35     // Top-level collection's maximum input report size.
  36     long maxInputReportSize;
  37     // Top-level collection's maximum output report size.
  38     long maxOutputReportSize;
  39     // Top-level collection's maximum feature report size.
  40     long maxFeatureReportSize;
  41     // Raw device report descriptor (not available on Windows).
  42     ArrayBuffer reportDescriptor;
  43   };
  44
  45   dictionary HidConnectInfo {
  46     // The opaque ID used to identify this connection in all other functions.
  47     long connectionId;
  48   };
  49
  50   [noinline_doc] dictionary DeviceFilter {
  51     // Device vendor ID.
  52     long? vendorId;
  53     // Device product ID, only checked only if the vendor ID matches.
  54     long? productId;
  55     // HID usage page identifier.
  56     long? usagePage;
  57     // HID usage identifier, checked only if the HID usage page matches.
  58     long? usage;
  59   };
  60
  61   dictionary GetDevicesOptions {
  62     [deprecated="Equivalent to setting $(ref:DeviceFilter.vendorId)."]
  63     long? vendorId;
  64     [deprecated="Equivalent to setting $(ref:DeviceFilter.productId)."]
  65     long? productId;
  66     // A device matching any given filter will be returned. An empty filter list
  67     // will return all devices the app has permission for.
  68     DeviceFilter[]? filters;
  69   };
  70
  71   dictionary DevicePromptOptions {
  72     // Allow the user to select multiple devices.
  73     boolean? multiple;
  74     // Filter the list of devices presented to the user. If multiple filters
  75     // are provided devices matching any filter will be displayed.
  76     DeviceFilter[]? filters;
  77   };
  78
  79   callback GetDevicesCallback = void (HidDeviceInfo[] devices);
  80   callback ConnectCallback = void (HidConnectInfo connection);
  81   callback DisconnectCallback = void ();
  82
  83   // |reportId|: The report ID or <code>0</code> if none.
  84   // |data|: The report data, the report ID prefix (if present) is removed.
  85   callback ReceiveCallback = void (long reportId, ArrayBuffer data);
  86
  87   // |data|: The report data, including a report ID prefix if one is sent by the
  88   // device.
  89   callback ReceiveFeatureReportCallback = void (ArrayBuffer data);
  90
  91   callback SendCallback = void();
  92
  93   interface Functions {
  94     // Enumerate connected HID devices.
  95     // |options|: The properties to search for on target devices.
  96     static void getDevices(GetDevicesOptions options,
  97                            GetDevicesCallback callback);
  98
  99     // Presents a device picker to the user and returns $(ref:HidDeviceInfo)
 100     // objects for the devices selected.
 101     // If the user cancels the picker devices will be empty. A user gesture
 102     // is required for the dialog to display. Without a user gesture, the
 103     // callback will run as though the user cancelled. If multiple filters are
 104     // provided devices matching any filter will be displayed.
 105     // |options|: Configuration of the device picker dialog box.
 106     // |callback|: Invoked with a list of chosen $(ref:Device)s.
 107     static void getUserSelectedDevices(optional DevicePromptOptions options,
 108                                        GetDevicesCallback callback);
 109
 110     // Open a connection to an HID device for communication.
 111     // |deviceId|: The $(ref:HidDeviceInfo.deviceId) of the device to open.
 112     static void connect(long deviceId,
 113                         ConnectCallback callback);
 114
 115     // Disconnect from a device. Invoking operations on a device after calling
 116     // this is safe but has no effect.
 117     // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
 118     static void disconnect(long connectionId,
 119                            optional DisconnectCallback callback);
 120
 121     // Receive the next input report from the device.
 122     // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
 123     static void receive(long connectionId,
 124                         ReceiveCallback callback);
 125
 126     // Send an output report to the device.
 127     //
 128     // <em>Note:</em> Do not include a report ID prefix in <code>data</code>.
 129     // It will be added if necessary.
 130     // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
 131     // |reportId|: The report ID to use, or <code>0</code> if none.
 132     // |data|: The report data.
 133     static void send(long connectionId,
 134                      long reportId,
 135                      ArrayBuffer data,
 136                      SendCallback callback);
 137
 138     // Request a feature report from the device.
 139     // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
 140     // |reportId|: The report ID, or <code>0</code> if none.
 141     static void receiveFeatureReport(long connectionId,
 142                                      long reportId,
 143                                      ReceiveFeatureReportCallback callback);
 144
 145     // Send a feature report to the device.
 146     //
 147     // <em>Note:</em> Do not include a report ID prefix in <code>data</code>.
 148     // It will be added if necessary.
 149     // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
 150     // |reportId|: The report ID to use, or <code>0</code> if none.
 151     // |data|: The report data.
 152     static void sendFeatureReport(long connectionId,
 153                                   long reportId,
 154                                   ArrayBuffer data,
 155                                   SendCallback callback);
 156   };
 157
 158   interface Events {
 159     // Event generated when a device is added to the system. Events are only
 160     // broadcast to apps and extensions that have permission to access the
 161     // device. Permission may have been granted at install time or when the user
 162     // accepted an optional permission (see $(ref:permissions.request)).
 163     static void onDeviceAdded(HidDeviceInfo device);
 164
 165     // Event generated when a device is removed from the system. See
 166     // $(ref:onDeviceAdded) for which events are delivered.
 167     // |deviceId|: The <code>deviceId</code> property of the device passed to
 168     // $(ref:onDeviceAdded).
 169     static void onDeviceRemoved(long deviceId);
 170   };
 171 };