blob: 3b81b2b573ff9c569a7131bb0b76de5dca4bffa5 [file] [log] [blame]
// 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;
// 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;
};
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;
};
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);
// 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);
};
};