src/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
  10   // Returned by <code>getDevices</code> functions to describes a connected HID
  11   // device. Use <code>connect</code> to connect to any of the returned devices.
  12   dictionary HidDeviceInfo {
  13     long deviceId;
  14     long vendorId;
  15     long productId;
  16   };
  17
  18   // Returned by <code>connect</code> to represent a communication session with
  19   // an HID device. Must be closed with a call to <code>disconnect</code>.
  20   dictionary HidConnectInfo {
  21     long connectionId;
  22   };
  23
  24   // Searching criteria to enumerate devices with.
  25   dictionary GetDevicesOptions {
  26     long vendorId;
  27     long productId;
  28   };
  29
  30   callback GetDevicesCallback = void (HidDeviceInfo[] devices);
  31   callback ConnectCallback = void (HidConnectInfo connection);
  32   callback DisconnectCallback = void ();
  33
  34   // The callback to be invoked when a <code>receive</code> or
  35   // <code>receiveFeatureReport</code> call is finished.
  36   // |data|: The content of the report.
  37   callback ReceiveCallback = void (ArrayBuffer data);
  38   callback SendCallback = void();
  39
  40   interface Functions {
  41     // Enumerate all the connected HID devices specified by the vendorId/
  42     // productId/interfaceId tuple.
  43     // |options|: The properties to search for on target devices.
  44     // |callback|: Invoked with the <code>HidDeviceInfo</code> array on success.
  45     static void getDevices(GetDevicesOptions options,
  46                            GetDevicesCallback callback);
  47
  48     // Open a connection to an HID device for communication.
  49     // |deviceId|: The ID of the device to open.
  50     // |callback|: Invoked with an <code>HidConnectInfo</code>.
  51     static void connect(long deviceId,
  52                         ConnectCallback callback);
  53
  54     // Disconnect from a device. Invoking operations on a device after calling
  55     // this is safe but has no effect.
  56     // |connectionId|: The connection to close.
  57     // |callback|: The callback to invoke once the device is closed.
  58     static void disconnect(long connectionId,
  59                            optional DisconnectCallback callback);
  60
  61     // Receive an Input report from an HID device.
  62     //
  63     // Input reports are returned to the host through the INTERRUPT IN endpoint.
  64     // |connectionId|: The connection from which to receive a report.
  65     // |size|: The size of the Input report to receive.
  66     // |callback|: The callback to invoke with received report.
  67     static void receive(long connectionId,
  68                         long size,
  69                         ReceiveCallback callback);
  70
  71     // Send an Output report to an HID device.
  72     // <code>send</code> will send the data on the first OUT endpoint, if one
  73     // exists. If one does not exist, the report will be sent through the
  74     // Control endpoint.
  75     //
  76     // |connectionId|: The connection to which to send a report.
  77     // |reportId|: The report ID to use, or <code>0</code> if none.
  78     // |data|: The report data.
  79     // |callback|: The callback to invoke once the write is finished.
  80     static void send(long connectionId,
  81                      long reportId,
  82                      ArrayBuffer data,
  83                      SendCallback callback);
  84
  85     // Receive a Feature report from the device.
  86     //
  87     // |connectionId|: The connection to read Input report from.
  88     // |reportId|: The report ID, or zero if none.
  89     // |size|: The size of the Feature report to receive.
  90     // |callback|: The callback to invoke once the write is finished.
  91     static void receiveFeatureReport(long connectionId,
  92                                      long reportId,
  93                                      long size,
  94                                      ReceiveCallback callback);
  95
  96     // Send a Feature report to the device.
  97     //
  98     // Feature reports are sent over the Control endpoint as a Set_Report
  99     // transfer.
 100     // |connectionId|: The connection to read Input report from.
 101     // |reportId|: The report ID to use, or <code>0</code> if none.
 102     // |data|: The report data.
 103     // |callback|: The callback to invoke once the write is finished.
 104     static void sendFeatureReport(long connectionId,
 105                                   long reportId,
 106                                   ArrayBuffer data,
 107                                   SendCallback callback);
 108   };
 109 };