// 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.
//
// Errors generated by this API are reported by setting
// $(ref:runtime.lastError) and executing the function's regular callback. The
// callback's regular parameters will be undefined in this case.
namespace hid {
  dictionary HidCollectionInfo {
    // HID usage page identifier.
    long usagePage;
    // Page-defined usage identifier.
    long usage;
    // Report IDs which belong to the collection and to its children.
    long[] reportIds;
  };

  [noinline_doc] dictionary HidDeviceInfo {
    // Opaque device ID.
    long deviceId;
    // Vendor ID.
    long vendorId;
    // Product ID.
    long productId;
    // The product name read from the device, if available.
    DOMString productName;
    // The serial number read from the device, if available.
    DOMString serialNumber;
    // Top-level collections from this device's report descriptors.
    HidCollectionInfo[] collections;
    // Top-level collection's maximum input report size.
    long maxInputReportSize;
    // Top-level collection's maximum output report size.
    long maxOutputReportSize;
    // Top-level collection's maximum feature report size.
    long maxFeatureReportSize;
    // Raw device report descriptor (not available on Windows).
    ArrayBuffer reportDescriptor;
  };

  dictionary HidConnectInfo {
    // The opaque ID used to identify this connection in all other functions.
    long connectionId;
  };

  [noinline_doc] dictionary DeviceFilter {
    // Device vendor ID.
    long? vendorId;
    // Device product ID, only checked only if the vendor ID matches.
    long? productId;
    // HID usage page identifier.
    long? usagePage;
    // HID usage identifier, checked only if the HID usage page matches.
    long? usage;
  };

  dictionary GetDevicesOptions {
    [deprecated="Equivalent to setting $(ref:DeviceFilter.vendorId)."]
    long? vendorId;
    [deprecated="Equivalent to setting $(ref:DeviceFilter.productId)."]
    long? productId;
    // A device matching any given filter will be returned. An empty filter list
    // will return all devices the app has permission for.
    DeviceFilter[]? filters;
  };

  dictionary DevicePromptOptions {
    // Allow the user to select multiple devices.
    boolean? multiple;
    // Filter the list of devices presented to the user. If multiple filters
    // are provided devices matching any filter will be displayed.
    DeviceFilter[]? filters;
  };

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

  // |reportId|: The report ID or <code>0</code> if none.
  // |data|: The report data, the report ID prefix (if present) is removed.
  callback ReceiveCallback = void (long reportId, ArrayBuffer data);

  // |data|: The report data, including a report ID prefix if one is sent by the
  // device.
  callback ReceiveFeatureReportCallback = void (ArrayBuffer data);

  callback SendCallback = void();

  interface Functions {
    // Enumerate connected HID devices.
    // |options|: The properties to search for on target devices.
    static void getDevices(GetDevicesOptions options,
                           GetDevicesCallback callback);

    // Presents a device picker to the user and returns $(ref:HidDeviceInfo)
    // objects for the devices selected.
    // If the user cancels the picker devices will be empty. A user gesture
    // is required for the dialog to display. Without a user gesture, the
    // callback will run as though the user cancelled. If multiple filters are
    // provided devices matching any filter will be displayed.
    // |options|: Configuration of the device picker dialog box.
    // |callback|: Invoked with a list of chosen $(ref:Device)s.
    static void getUserSelectedDevices(optional DevicePromptOptions options,
                                       GetDevicesCallback callback);

    // Open a connection to an HID device for communication.
    // |deviceId|: The $(ref:HidDeviceInfo.deviceId) of the device to open.
    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 <code>connectionId</code> returned by $(ref:connect).
    static void disconnect(long connectionId,
                           optional DisconnectCallback callback);

    // Receive the next input report from the device.
    // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
    static void receive(long connectionId,
                        ReceiveCallback callback);

    // Send an output report to the device.
    //
    // <em>Note:</em> Do not include a report ID prefix in <code>data</code>.
    // It will be added if necessary.
    // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
    // |reportId|: The report ID to use, or <code>0</code> if none.
    // |data|: The report data.
    static void send(long connectionId,
                     long reportId,
                     ArrayBuffer data,
                     SendCallback callback);

    // Request a feature report from the device.
    // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
    // |reportId|: The report ID, or <code>0</code> if none.
    static void receiveFeatureReport(long connectionId,
                                     long reportId,
                                     ReceiveFeatureReportCallback callback);

    // Send a feature report to the device.
    //
    // <em>Note:</em> Do not include a report ID prefix in <code>data</code>.
    // It will be added if necessary.
    // |connectionId|: The <code>connectionId</code> returned by $(ref:connect).
    // |reportId|: The report ID to use, or <code>0</code> if none.
    // |data|: The report data.
    static void sendFeatureReport(long connectionId,
                                  long reportId,
                                  ArrayBuffer data,
                                  SendCallback callback);
  };

  interface Events {
    // Event generated when a device is added to the system. Events are only
    // broadcast to apps and extensions that have permission to access the
    // device. Permission may have been granted at install time or when the user
    // accepted an optional permission (see $(ref:permissions.request)).
    static void onDeviceAdded(HidDeviceInfo device);

    // Event generated when a device is removed from the system. See
    // $(ref:onDeviceAdded) for which events are delivered.
    // |deviceId|: The <code>deviceId</code> property of the device passed to
    // $(ref:onDeviceAdded).
    static void onDeviceRemoved(long deviceId);
  };
};