Introducing chrome.usb.getDevices/openDevice API

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.
 
 // Use the <code>chrome.usb</code> API to interact with connected USB
 // devices. This API provides access to USB operations from within the context
 // of an app. Using this API, apps can function as drivers for hardware devices.
 namespace usb {
 
   // Direction, Recipient, RequestType, and TransferType all map to their
   // namesakes within the USB specification.
   enum Direction {in, out};
   enum Recipient {device, _interface, endpoint, other};
   enum RequestType {standard, class, vendor, reserved};
   enum TransferType {control, interrupt, isochronous, bulk};
 
   // For isochronous mode, SynchronizationType and UsageType map to their
   // namesakes within the USB specification.
   enum SynchronizationType {asynchronous, adaptive, synchronous};
   enum UsageType {data, feedback, explicitFeedback};
 
-  // 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.
+  // A dictionary returned by |getDevices| to identify a connected device.

[asargent_no_longer_on_chrome, 2013/08/22 21:06:13]

optional suggestion: you can omit the "A dictionary" part from this comment,
since it's clear the thing just below the comment is a dictionary. E.g.


// Returned by |getDevices| to identify a connected device.

[Bei Zhang, 2013/08/23 22:52:00]

Done.

   dictionary Device {
+    // The id of the device. It remains unchanged until the device is unplugged.
+    long device;
+    long? vendorId;
+    long? productId;
+  };
+
+  // A dictionary returned by |openDevice| to be used for USB communication.

[asargent_no_longer_on_chrome, 2013/08/22 21:06:13]

same suggestion about "a dictionary".

Also, it might be useful to include something in the comment about the expected
lifetime that this data is valid. E.g. will I always get the same |handle| value
back for a given device, so that it's safe for developers to store this value in
persistently such as in indexedDB/chrome.storage.local/etc. ?  Or is it only
valid while the device is open, and after closeDevice or chrome restart it
becomes invalid?

[Bei Zhang, 2013/08/23 22:52:00]

Done.

+  dictionary DeviceHandle {
     long handle;
-    long vendorId;
-    long productId;
+    long? vendorId;
+    long? productId;

[asargent_no_longer_on_chrome, 2013/08/22 21:06:13]

Previously calls to findDevices would return a dictionary that always had these
two fields defined, right? If so then I don't think we can make them optional,
because that could break developer code. Can you just make them be 0 in the
situations where you would otherwise leave them undefined?

[Bei Zhang, 2013/08/23 22:52:00]

Done. Made a comment to explain it.

On 2013/08/22 21:06:13, Antony Sargent wrote:

   };
 
   dictionary EndpointDescriptor {
     long address;
     TransferType type;
     Direction direction;
     long maximumPacketSize;
 
     // Used for isochronous mode.
     SynchronizationType? synchronization;
@@ skipping 75 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;
   };
 
-  // FindDevicesOptions describes the properties of devices which are found and
-  // opened via findDevices.
-  dictionary FindDevicesOptions {
+  // Describes the properties of devices which are found via |getDevices| and
+  // |findDevices|.
+  dictionary EnumerateDevicesOptions {
+    long vendorId;
+    long productId;
+    long? interfaceId;
+  };
+
+  // Describes the properties of devices which are found via |getDevices| and
+  // |findDevices|.
+  dictionary EnumerateDevicesOptions2 {
     long vendorId;
     long productId;
     long? interfaceId;
   };
 
   callback VoidCallback = void ();
-  callback FindDevicesCallback = void (Device[] device);
+  callback GetDevicesCallback = void (Device[] device);
+  callback OpenDeviceCallback = void (DeviceHandle device);
+  callback FindDevicesCallback = void (DeviceHandle[] device);
   callback ListInterfacesCallback = void (InterfaceDescriptor[] descriptors);
   callback CloseDeviceCallback = void ();
   callback TransferCallback = void (TransferResultInfo info);
   callback ResetDeviceCallback = void(boolean result);
 
   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.
+    // Lists USB devices specified by vendorId/productId pair.
     // |options|: The properties to search for on target devices.
-    // |callback|: Invoked with the opened Device on success.
-    static void findDevices(FindDevicesOptions options,
-        FindDevicesCallback callback);
+    // |callback|: Invoked with the opened DeviceHandle on complete.
+    static void getDevices(EnumerateDevicesOptions options,
+                           GetDevicesCallback callback);
+
+    // Opens a USB device retured by getDevices.
+    // |callback|: Invoked with the opened DeviceHandle on complete.
+    static void openDevice(Device device, OpenDeviceCallback callback);
+
+    // Finds USB devices specified by the vendorId/productId pair and,
+    // if permissions allow, opens it for use.
+    // Only opened device handles are returned.
+    // Calling this method is equivalent to a |getDevices| followed by
+    // a series of |getDevices| calls.

[asargent_no_longer_on_chrome, 2013/08/22 21:06:13]

do you mean "a series of |openDevice| calls"?

[Bei Zhang, 2013/08/23 22:52:00]

Done.

+    // |options|: The properties to search for on target devices.
+    // |callback|: Invoked with the opened DeviceHandle on complete.
+    static void findDevices(EnumerateDevicesOptions2 options,
+                            FindDevicesCallback callback);

[asargent_no_longer_on_chrome, 2013/08/22 21:06:13]

Do we still want to have developers using findDevices in new code, or would we
rather have developers switch over to always just using getDevices/openDevice?

If we don't want them to use it anymore, we can say something in the comment
like "this is deprecated, please use getDevices/openDevice instead", or possibly
even mark it as [nodoc] to hide it in the documentation. 

[Bei Zhang, 2013/08/23 22:52:00]

This function might be handy to some developers. Since I have fixed all the
crashing due to the old findDevices, I will just leave it as is.

On 2013/08/22 21:06:13, Antony Sargent wrote:

[asargent_no_longer_on_chrome, 2013/08/23 23:57:01]

Ok

 
     // 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);
+    static void closeDevice(DeviceHandle device,
+                            optional CloseDeviceCallback callback);
 
     // Lists all the interfaces on the USB device.
     // |device|: The device from which the interfaces should be listed.
     // |callback|: The callback to invoke when the interfaces are enumerated.
-    static void listInterfaces(Device device,
-        ListInterfacesCallback callback);
+    static void listInterfaces(DeviceHandle device,
+                               ListInterfacesCallback 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 void claimInterface(Device device, long interfaceNumber,
-        VoidCallback callback);
+    static void claimInterface(DeviceHandle device, long interfaceNumber,
+                               VoidCallback callback);
 
     // 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 void releaseInterface(Device device, long interfaceNumber,
-        VoidCallback callback);
+    static void releaseInterface(DeviceHandle 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 void setInterfaceAlternateSetting(Device device,
-        long interfaceNumber, long alternateSetting, VoidCallback callback);
+    static void setInterfaceAlternateSetting(DeviceHandle 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);
+    static void controlTransfer(DeviceHandle device,
+                                ControlTransferInfo transferInfo,
+                                TransferCallback callback);
 
     // Performs a bulk transfer on the specified device.
     // |device|: An open device to make the transfer on.
     // |transferInfo|: The paramters to the transfer. See GenericTransferInfo.
     // |callback|: Invoked once the transfer has completed.
-    static void bulkTransfer(Device device, GenericTransferInfo transferInfo,
-        TransferCallback callback);
+    static void bulkTransfer(DeviceHandle device,
+                             GenericTransferInfo transferInfo,
+                             TransferCallback callback);
 
     // Performs an interrupt transfer on the specified device.
     // |device|: An open device to make the transfer on.
     // |transferInfo|: The paramters to the transfer. See GenericTransferInfo.
     // |callback|: Invoked once the transfer has completed.
-    static void interruptTransfer(Device device,
-        GenericTransferInfo transferInfo, TransferCallback callback);
+    static void interruptTransfer(DeviceHandle device,
+                                  GenericTransferInfo transferInfo,
+                                  TransferCallback callback);
 
     // 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);
+    static void isochronousTransfer(DeviceHandle device,
+                                    IsochronousTransferInfo transferInfo,
+                                    TransferCallback callback);
 
-    // Try to reset the USB device and restore the previous status.
-    //
+    // Tries to reset the USB device and restore the previous status.
     // If the reset fails, the given device will be closed and the USB device
-    // will appear to be disconected and reconnected.
-    // You must call <code>findDevice</code> again to acquire the device.
+    // will appear to be disconected and reconnected. That case you must call
+    // |getDevices| or |findDevices| again to acquire the device.
     //
     // |device|: An opened device to reset.
     // |callback|: Invoked once the device is reset with a boolean indicating
     // whether the reset is completed successfully.
-    static void resetDevice(Device device,
-        ResetDeviceCallback callback);
+    static void resetDevice(DeviceHandle device,
+                            ResetDeviceCallback callback);
   };
 };