src/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 namespace hid {
   9   // HID top-level collection attributes.
  10   // Each enumerated device interface exposes an array of these objects.
  11   // |usagePage|: HID usage page identifier.
  12   // |usage|: Page-defined usage identifier.
  13   // |reportIds|: Report IDs which belong to the collection and to its children.
  14   dictionary HidCollectionInfo {
  15     long usagePage;
  16     long usage;
  17     long[] reportIds;
  18   };
  19
  20   // Returned by <code>getDevices</code> functions to describes a connected HID
  21   // device. Use <code>connect</code> to connect to any of the returned devices.
  22   // |deviceId|: Device opaque ID.
  23   // |vendorId|: Vendor ID.
  24   // |productId|: Product ID.
  25   // |collections|: Top-level collections from this device's report descriptor.
  26   // |maxInputReportSize|: Top-level collection's max input report size.
  27   // |maxOutputReportSize|: Top-level collection's max output report size.
  28   // |maxFeatureReportSize|: Top-level collection's max feature report size.
  29   dictionary HidDeviceInfo {
  30     long deviceId;
  31     long vendorId;
  32     long productId;
  33     HidCollectionInfo[] collections;
  34     long maxInputReportSize;
  35     long maxOutputReportSize;
  36     long maxFeatureReportSize;
  37   };
  38
  39   // Returned by <code>connect</code> to represent a communication session with
  40   // an HID device. Must be closed with a call to <code>disconnect</code>.
  41   dictionary HidConnectInfo {
  42     long connectionId;
  43   };
  44
  45   // Searching criteria to enumerate devices with.
  46   dictionary GetDevicesOptions {
  47     long vendorId;
  48     long productId;
  49   };
  50
  51   callback GetDevicesCallback = void (HidDeviceInfo[] devices);
  52   callback ConnectCallback = void (HidConnectInfo connection);
  53   callback DisconnectCallback = void ();
  54
  55   // The callback to be invoked when a <code>receive</code> call is finished.
  56   // |reportId|: The ID of the report.
  57   // |data|: The content of the report.
  58   callback ReceiveCallback = void (long reportId, ArrayBuffer data);
  59
  60   // The callback to be invoked when a <code>receiveFeatureReport</code> call
  61   // is finished.
  62   // |data|: The content of the report.
  63   callback ReceiveFeatureReportCallback = void (ArrayBuffer data);
  64
  65   // The callback to be invoked when a <code>send</code> or
  66   // <code>sendFeatureReport</code> call is finished.
  67   callback SendCallback = void();
  68
  69   interface Functions {
  70     // Enumerate all the connected HID devices specified by the vendorId/
  71     // productId/interfaceId tuple.
  72     // |options|: The properties to search for on target devices.
  73     // |callback|: Invoked with the <code>HidDeviceInfo</code> array on success.
  74     static void getDevices(GetDevicesOptions options,
  75                            GetDevicesCallback callback);
  76
  77     // Open a connection to an HID device for communication.
  78     // |deviceId|: The ID of the device to open.
  79     // |callback|: Invoked with an <code>HidConnectInfo</code>.
  80     static void connect(long deviceId,
  81                         ConnectCallback callback);
  82
  83     // Disconnect from a device. Invoking operations on a device after calling
  84     // this is safe but has no effect.
  85     // |connectionId|: The connection to close.
  86     // |callback|: The callback to invoke once the device is closed.
  87     static void disconnect(long connectionId,
  88                            optional DisconnectCallback callback);
  89
  90     // Receive an Input report from an HID device.
  91     //
  92     // Input reports are returned to the host through the INTERRUPT IN endpoint.
  93     // |connectionId|: The connection from which to receive a report.
  94     // |callback|: The callback to invoke with received report.
  95     static void receive(long connectionId,
  96                         ReceiveCallback callback);
  97
  98     // Send an Output report to an HID device.
  99     // <code>send</code> will send the data on the first OUT endpoint, if one
 100     // exists. If one does not exist, the report will be sent through the
 101     // Control endpoint.
 102     //
 103     // |connectionId|: The connection to which to send a report.
 104     // |reportId|: The report ID to use, or <code>0</code> if none.
 105     // |data|: The report data.
 106     // |callback|: The callback to invoke once the write is finished.
 107     static void send(long connectionId,
 108                      long reportId,
 109                      ArrayBuffer data,
 110                      SendCallback callback);
 111
 112     // Receive a Feature report from the device.
 113     //
 114     // |connectionId|: The connection to read Input report from.
 115     // |reportId|: The report ID, or zero if none.
 116     // |callback|: The callback to invoke once the write is finished.
 117     static void receiveFeatureReport(long connectionId,
 118                                      long reportId,
 119                                      ReceiveFeatureReportCallback callback);
 120
 121     // Send a Feature report to the device.
 122     //
 123     // Feature reports are sent over the Control endpoint as a Set_Report
 124     // transfer.
 125     // |connectionId|: The connection to read Input report from.
 126     // |reportId|: The report ID to use, or <code>0</code> if none.
 127     // |data|: The report data.
 128     // |callback|: The callback to invoke once the write is finished.
 129     static void sendFeatureReport(long connectionId,
 130                                   long reportId,
 131                                   ArrayBuffer data,
 132                                   SendCallback callback);
 133   };
 134 };