chrome/common/extensions/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 usage pair. Each enumerated device interface exposes an array of
  10   // these objects. Values correspond to those defined by the
  11   // <a href="http://www.usb.org/developers/devclass_docs/HID1_11.pdf>
  12   // HID device class specification</a>.
  13   // |usage_page|: HID usage page identifier.
  14   // |usage|: Page-defined usage identifier.
  15   dictionary HidUsageAndPage {
  16     long usage_page;
  17     long usage;
  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   // |usages|: HID usage pairs exposed by underlying Top-level collections.
  26   dictionary HidDeviceInfo {
  27     long deviceId;
  28     long vendorId;
  29     long productId;
  30     HidUsageAndPage[] usages;
  31   };
  32
  33   // Returned by <code>connect</code> to represent a communication session with
  34   // an HID device. Must be closed with a call to <code>disconnect</code>.
  35   dictionary HidConnectInfo {
  36     long connectionId;
  37   };
  38
  39   // Searching criteria to enumerate devices with.
  40   dictionary GetDevicesOptions {
  41     long vendorId;
  42     long productId;
  43   };
  44
  45   callback GetDevicesCallback = void (HidDeviceInfo[] devices);
  46   callback ConnectCallback = void (HidConnectInfo connection);
  47   callback DisconnectCallback = void ();
  48
  49   // The callback to be invoked when a <code>receive</code> or
  50   // <code>receiveFeatureReport</code> call is finished.
  51   // |data|: The content of the report.
  52   callback ReceiveCallback = void (ArrayBuffer data);
  53   callback SendCallback = void();
  54
  55   interface Functions {
  56     // Enumerate all the connected HID devices specified by the vendorId/
  57     // productId/interfaceId tuple.
  58     // |options|: The properties to search for on target devices.
  59     // |callback|: Invoked with the <code>HidDeviceInfo</code> array on success.
  60     static void getDevices(GetDevicesOptions options,
  61                            GetDevicesCallback callback);
  62
  63     // Open a connection to an HID device for communication.
  64     // |deviceId|: The ID of the device to open.
  65     // |callback|: Invoked with an <code>HidConnectInfo</code>.
  66     static void connect(long deviceId,
  67                         ConnectCallback callback);
  68
  69     // Disconnect from a device. Invoking operations on a device after calling
  70     // this is safe but has no effect.
  71     // |connectionId|: The connection to close.
  72     // |callback|: The callback to invoke once the device is closed.
  73     static void disconnect(long connectionId,
  74                            optional DisconnectCallback callback);
  75
  76     // Receive an Input report from an HID device.
  77     //
  78     // Input reports are returned to the host through the INTERRUPT IN endpoint.
  79     // |connectionId|: The connection from which to receive a report.
  80     // |size|: The size of the Input report to receive.
  81     // |callback|: The callback to invoke with received report.
  82     static void receive(long connectionId,
  83                         long size,
  84                         ReceiveCallback callback);
  85
  86     // Send an Output report to an HID device.
  87     // <code>send</code> will send the data on the first OUT endpoint, if one
  88     // exists. If one does not exist, the report will be sent through the
  89     // Control endpoint.
  90     //
  91     // |connectionId|: The connection to which to send a report.
  92     // |reportId|: The report ID to use, or <code>0</code> if none.
  93     // |data|: The report data.
  94     // |callback|: The callback to invoke once the write is finished.
  95     static void send(long connectionId,
  96                      long reportId,
  97                      ArrayBuffer data,
  98                      SendCallback callback);
  99
 100     // Receive a Feature report from the device.
 101     //
 102     // |connectionId|: The connection to read Input report from.
 103     // |reportId|: The report ID, or zero if none.
 104     // |size|: The size of the Feature report to receive.
 105     // |callback|: The callback to invoke once the write is finished.
 106     static void receiveFeatureReport(long connectionId,
 107                                      long reportId,
 108                                      long size,
 109                                      ReceiveCallback callback);
 110
 111     // Send a Feature report to the device.
 112     //
 113     // Feature reports are sent over the Control endpoint as a Set_Report
 114     // transfer.
 115     // |connectionId|: The connection to read Input report from.
 116     // |reportId|: The report ID to use, or <code>0</code> if none.
 117     // |data|: The report data.
 118     // |callback|: The callback to invoke once the write is finished.
 119     static void sendFeatureReport(long connectionId,
 120                                   long reportId,
 121                                   ArrayBuffer data,
 122                                   SendCallback callback);
 123   };
 124 };