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