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   };
  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 report data, the report ID prefix (if present) is removed.
  71   callback ReceiveCallback = void (long reportId, ArrayBuffer data);
  72
  73   // |data|: The report data, including a report ID prefix if one is sent by the
  74   // device.
  75   callback ReceiveFeatureReportCallback = void (ArrayBuffer data);
  76
  77   callback SendCallback = void();
  78
  79   interface Functions {
  80     // Enumerate connected HID devices.
  81     // |options|: The properties to search for on target devices.
  82     static void getDevices(GetDevicesOptions options,
  83                            GetDevicesCallback callback);
  84
  85     // Open a connection to an HID device for communication.
  86     // |deviceId|: The $(ref:HidDeviceInfo.deviceId) of the device to open.
  87     static void connect(long deviceId,
  88                         ConnectCallback callback);
  89
  90     // Disconnect from a device. Invoking operations on a device after calling
  91     // this is safe but has no effect.
  92     // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
  93     static void disconnect(long connectionId,
  94                            optional DisconnectCallback callback);
  95
  96     // Receive the next input report from the device.
  97     // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
  98     static void receive(long connectionId,
  99                         ReceiveCallback callback);
 100
 101     // Send an output report to the device.
 102     //
 103     // <em>Note:</em> Do not include a report ID prefix in <code>data</code>.
 104     // It will be added if necessary.
 105     // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
 106     // |reportId|: The report ID to use, or <code>0</code> if none.
 107     // |data|: The report data.
 108     static void send(long connectionId,
 109                      long reportId,
 110                      ArrayBuffer data,
 111                      SendCallback callback);
 112
 113     // Request a feature report from the device.
 114     // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
 115     // |reportId|: The report ID, or <code>0</code> if none.
 116     static void receiveFeatureReport(long connectionId,
 117                                      long reportId,
 118                                      ReceiveFeatureReportCallback callback);
 119
 120     // Send a feature report to the device.
 121     //
 122     // <em>Note:</em> Do not include a report ID prefix in <code>data</code>.
 123     // It will be added if necessary.
 124     // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
 125     // |reportId|: The report ID to use, or <code>0</code> if none.
 126     // |data|: The report data.
 127     static void sendFeatureReport(long connectionId,
 128                                   long reportId,
 129                                   ArrayBuffer data,
 130                                   SendCallback callback);
 131   };
 132 };