Update USB extension API with suggestions from review.

chrome/common/extensions/api/usb.idl

 // Copyright (c) 2012 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.
 
 namespace usb {
 
+  // Direction, Recipient and RequestType all map to their namesakes within the
+  // USB specification with the exception of the "iface" value which, for
+  // technical reasons, maps to "interface".

[Matt Perry, 2012/12/14 18:50:16]

That's... odd. We control this API, why can't we just use "interface" instead of
"iface"?

[Garret Kelly, 2012/12/14 18:56:21]

"interface" is a reserved word in IDL.

[Matt Perry, 2012/12/14 19:05:31]

Oh, lame :(. I wonder if we can fix our IDL parser to allow that in an enum.

Antony, any idea?

+  enum Direction {in, out};
+  enum Recipient {device, iface, endpoint, other};
+  enum RequestType {standard, class, vendor, reserved};
+
   // A Device encapsulates everything that is needed to communicate with a USB
   // device. They are returned by findDevice calls and have all of their
   // fields populated before being returned.
   dictionary Device {
     long handle;
     long vendorId;
     long productId;
   };
 
   // ControlTransferInfo represents that parameters to a single USB control
   // transfer.
   dictionary ControlTransferInfo {
-    // The direction of this transfer. Must be one of either in or out.
-    DOMString direction;
+    // The direction of this transfer.
+    Direction direction;
 
-    // The intended recipient for this transfer. Must be one of device,
-    // interface, endpoint, or other.
-    DOMString recipient;
+    // The intended recipient for this transfer.
+    Recipient recipient;
 
-    // The type of this request. Must be one of standard, class, vendor,
-    // or reserved.
-    DOMString requestType;
+    // The type of this request.
+    RequestType requestType;
 
     long request;
     long value;
     long index;
 
     // If this transfer is an input transfer, then this field must be set to
     // indicate the expected data length. If this is an output transfer, then
     // this field is ignored.
     long? length;
 
     // The data payload carried by this transfer. If this is an output tranfer
     // then this field must be set.
     ArrayBuffer? data;
   };
 
   // GenericTransferInfo is used by both bulk and interrupt transfers to
   // specify the parameters of the transfer.
   dictionary GenericTransferInfo {
-    // The direction of this transfer. Must be one of in or out.
-    DOMString direction;
+    // The direction of this transfer.
+    Direction direction;
 
     long endpoint;
 
     // If this is an input transfer then this field indicates the size of the
     // input buffer. If this is an output transfer then this field is ignored.
     long? length;
 
     // If this is an output transfer then this field must be populated.
     // Otherwise, it will be ignored.
     ArrayBuffer? data;
@@ skipping 18 matching lines @@
   dictionary TransferResultInfo {
     // A value of 0 indicates that the transfer was a success. Other values
     // indicate failure.
     long? resultCode;
 
     // If the transfer was an input transfer then this field will contain all
     // of the input data requested.
     ArrayBuffer? data;
   };
 
-  dictionary FindDevicesOptions {};
+  // FindDevicesOptions describes the properties of devices which are found and
+  // opened via findDevices.
+  dictionary FindDevicesOptions {
+    long vendorId;
+    long productId;
+  };
 
   callback VoidCallback = void ();
-
   callback FindDevicesCallback = void (Device[] device);
   callback CloseDeviceCallback = void ();
   callback TransferCallback = void (TransferResultInfo info);
 
   interface Functions {
     // Finds the first instance of the USB device specified by the vendorId/
     // productId pair and, if permissions allow, opens it for use.
     // Upon successfully opening a device the callback is invoked with a
     // populated Device object. On failure, the callback is invoked with null.
-    // |vendorId|: The vendor ID of the USB device to find.
-    // |productId|: The product ID of the USB device to find.
+    // |options|: The properties to search for on target devices.
     // |callback|: Invoked with the opened Device on success.
-    static void findDevices(long vendorId, long productId,
-        FindDevicesOptions options, FindDevicesCallback callback);
+    static void findDevices(FindDevicesOptions options,
+        FindDevicesCallback callback);
 
     // Closes an open device instance. Invoking operations on a device after it
     // has been closed is a safe operation, but causes no action to be taken.
     // |device|: The device to close.
     // |callback|: The callback to invoke once the device is closed.
     static void closeDevice(Device device,
         optional CloseDeviceCallback callback);
 
     // Claims an interface on the specified USB device.
     // |device|: The device on which the interface is to be claimed.
     // |interface|: The interface number to be claimed.
     // |callback|: The callback to invoke once the interface is claimed.
-    static long claimInterface(Device device, long interfaceNumber,
+    static void claimInterface(Device device, long interfaceNumber,
         VoidCallback callback);

[Matt Perry, 2012/12/14 18:50:16]

Are you planning on passing the error value to the callback as
chrome.extension.lastError?

[Garret Kelly, 2012/12/14 18:56:21]

Since these operations can't ever fail I'm inclined not to.

 
     // Releases a claim to an interface on the provided device.
     // |device|: The device on which the interface is to be released.
     // |interface|: The interface number to be released.
     // |callback|: The callback to invoke once the interface is released.
-    static long releaseInterface(Device device, long interfaceNumber,
+    static void releaseInterface(Device device, long interfaceNumber,
         VoidCallback callback);
 
     // Selects an alternate setting on a previously claimed interface on a
     // device.
     // |device|: The device on which the interface settings are to be set.
     // |interface|: The interface number to be set.
     // |alternateSetting|: The alternate setting to set.
     // |callback|: The callback to invoke once the interface setting is set.
-    static long setInterfaceAlternateSetting(Device device,
+    static void setInterfaceAlternateSetting(Device device,
         long interfaceNumber, long alternateSetting, VoidCallback callback);
 
     // Performs a control transfer on the specified device. See the
     // ControlTransferInfo structure for the parameters required to make a
     // transfer.
     // |device|: An open device to make the transfer on.
     // |transferInfo|: The parameters to the transfer. See ControlTransferInfo.
     // |callback|: Invoked once the transfer has completed.
     static void controlTransfer(Device device,
         ControlTransferInfo transferInfo, TransferCallback callback);
@@ skipping 15 matching lines @@
     // Performs an isochronous transfer on the specific device.
     // |device|: An open device to make the transfer on.
     // |transferInfo|: The parameters to the transfer. See
     // IsochronousTransferInfo.
     // |callback|: Invoked once the transfer has been completed.
     static void isochronousTransfer(Device device,
         IsochronousTransferInfo transferInfo,
         TransferCallback callback);
   };
 };