chrome.hid: enrich model with report IDs

chrome/common/extensions/api/hid.idl

 // 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
+  // HID usage pair. 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;
   };
 
+  // HID top-level collection attributes.
+  // Each enumerated device interface exposes an array of these objects.
+  // |usage|: Collection's usage pair.
+  // |reportIds|: Report IDs which belong to the collection and to its children.
+  dictionary HidCollectionInfo {
+    HidUsageAndPage usage;

[Ken Rockot(use gerrit already), 2014/06/19 19:29:56]

nit: I think I'd prefer the API consumer to be able to just say
"collection.usage" and "collection.usage_page" rather than
"collection.usage.usage" and "collection.usage.usage_page". Could you just
inline the usage and usage_page fields within HidCollectionInfo?

I think it makes sense for the C++ code to keep a separate struct for this data
as it does now, but the API could expose it without the extra level of
indirection.

[jracle (use Gerrit), 2014/06/19 21:39:36]

Sure. Agree.

On 2014/06/19 19:29:56, Ken Rockot wrote:

+    long[] reportIds;
+  };
+
   // 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.
+  // |collections|: Top-level collections from this device's report descriptor.
+  // |maxInputReportSize|: Top-level collection's max input report size.

[Ken Rockot(use gerrit already), 2014/06/19 19:29:56]

Tangent: Could each HidCollectionInfo struct also include information about max
report sizes for each specific collection?

[jracle (use Gerrit), 2014/06/19 21:39:36]

This one is more problematic, since apart from linux where we need to compute
max report size ourselves, device APIs aggregate them. We need max report size
to allocate sufficient buffer size for read/write.

On 2014/06/19 19:29:56, Ken Rockot wrote:

+  // |maxOutputReportSize|: Top-level collection's max output report size.
+  // |maxFeatureReportSize|: Top-level collection's max feature report size.
   dictionary HidDeviceInfo {
     long deviceId;
     long vendorId;
     long productId;
-    HidUsageAndPage[] usages;
+    HidCollectionInfo[] collections;
+    long maxInputReportSize;
+    long maxOutputReportSize;
+    long maxFeatureReportSize;
   };
 
   // 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 {
@@ skipping 74 matching lines @@
     // |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);
   };
 };