// Copyright 2014 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Use the <code>chrome.hid</code> API to interact with connected HID devices.
// This API provides access to HID operations from within the context of an app.
// Using this API, apps can function as drivers for hardware devices.
namespace hid {
  // HID usage pair. Each enumerated device interface exposes an array of
  // these objects. Values correspond to those defined by the
  // <a href="http://www.usb.org/developers/devclass_docs/HID1_11.pdf>
  // HID device class specification</a>.
  // |usage_page|: HID usage page identifier.
  // |usage|: Page-defined usage identifier.
  dictionary HidUsageAndPage {
    long usage_page;
    long usage;
  };

  // Returned by <code>getDevices</code> functions to describes a connected HID
  // device. Use <code>connect</code> to connect to any of the returned devices.
  // |deviceId|: Device opaque ID.
  // |vendorId|: Vendor ID.
  // |productId|: Product ID.
  // |usages|: HID usage pairs exposed by underlying Top-level collections.
  dictionary HidDeviceInfo {
    long deviceId;
    long vendorId;
    long productId;
    HidUsageAndPage[] usages;
  };

  // Returned by <code>connect</code> to represent a communication session with
  // an HID device. Must be closed with a call to <code>disconnect</code>.
  dictionary HidConnectInfo {
    long connectionId;
  };

  // Searching criteria to enumerate devices with.
  dictionary GetDevicesOptions {
    long vendorId;
    long productId;
  };

  callback GetDevicesCallback = void (HidDeviceInfo[] devices);
  callback ConnectCallback = void (HidConnectInfo connection);
  callback DisconnectCallback = void ();

  // The callback to be invoked when a <code>receive</code> or
  // <code>receiveFeatureReport</code> call is finished.
  // |data|: The content of the report.
  callback ReceiveCallback = void (ArrayBuffer data);
  callback SendCallback = void();

  interface Functions {
    // Enumerate all the connected HID devices specified by the vendorId/
    // productId/interfaceId tuple.
    // |options|: The properties to search for on target devices.
    // |callback|: Invoked with the <code>HidDeviceInfo</code> array on success.
    static void getDevices(GetDevicesOptions options,
                           GetDevicesCallback callback);

    // Open a connection to an HID device for communication.
    // |deviceId|: The ID of the device to open.
    // |callback|: Invoked with an <code>HidConnectInfo</code>.
    static void connect(long deviceId,
                        ConnectCallback callback);

    // Disconnect from a device. Invoking operations on a device after calling
    // this is safe but has no effect.
    // |connectionId|: The connection to close.
    // |callback|: The callback to invoke once the device is closed.
    static void disconnect(long connectionId,
                           optional DisconnectCallback callback);

    // Receive an Input report from an HID device.
    //
    // Input reports are returned to the host through the INTERRUPT IN endpoint.
    // |connectionId|: The connection from which to receive a report.
    // |size|: The size of the Input report to receive.
    // |callback|: The callback to invoke with received report.
    static void receive(long connectionId,
                        long size,
                        ReceiveCallback callback);

    // Send an Output report to an HID device.
    // <code>send</code> will send the data on the first OUT endpoint, if one
    // exists. If one does not exist, the report will be sent through the
    // Control endpoint.
    //
    // |connectionId|: The connection to which to send a report.
    // |reportId|: The report ID to use, or <code>0</code> if none.
    // |data|: The report data.
    // |callback|: The callback to invoke once the write is finished.
    static void send(long connectionId,
                     long reportId,
                     ArrayBuffer data,
                     SendCallback callback);

    // Receive a Feature report from the device.
    //
    // |connectionId|: The connection to read Input report from.
    // |reportId|: The report ID, or zero if none.
    // |size|: The size of the Feature report to receive.
    // |callback|: The callback to invoke once the write is finished.
    static void receiveFeatureReport(long connectionId,
                                     long reportId,
                                     long size,
                                     ReceiveCallback callback);

    // Send a Feature report to the device.
    //
    // Feature reports are sent over the Control endpoint as a Set_Report
    // transfer.
    // |connectionId|: The connection to read Input report from.
    // |reportId|: The report ID to use, or <code>0</code> if none.
    // |data|: The report data.
    // |callback|: The callback to invoke once the write is finished.
    static void sendFeatureReport(long connectionId,
                                  long reportId,
                                  ArrayBuffer data,
                                  SendCallback callback);
  };
};