Separate usb device handle from usb device. (deprecate)

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, 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 <code>Device</code> uniquely identifies a connected USB device.
+  // They are returned by <code>findDevices</code> calls and the
+  // <code>device</code> field remains consistent for the same device.
   dictionary Device {
-    long handle;
+    long device;
     long vendorId;
     long productId;
   };
 
+  // A <code>DeviceHandle</code> encapsulates everything needed to communicate
+  // with a USB device.
+  // They are returned by <code>openDevice</code> calls.
+  dictionary DeviceHandle {
+    long handle;
+  };

[asargent_no_longer_on_chrome, 2013/06/06 21:57:29]

Because this API is now released to stable, we can't change the input arguments
or structure of result data we pass to callbacks because it would break
backwards compatibility. 

We can add functions with new names, or add new fields to existing dictionaries,
etc. and mark old functions or field names as nodoc to deprecate them, but an
invariant is that code written against the currently specified API before your
change must continue to run correctly.

+
   dictionary EndpointDescriptor {
     long address;
     TransferType type;
     Direction direction;
     long maximumPacketSize;
 
     // Used for isochronous mode.
     SynchronizationType? synchronization;
     UsageType? usage;
 
@@ skipping 83 matching lines @@
   // FindDevicesOptions describes the properties of devices which are found and
   // opened via findDevices.
   dictionary FindDevicesOptions {
     long vendorId;
     long productId;
     long? interfaceId;
   };
 
   callback VoidCallback = void ();
   callback FindDevicesCallback = void (Device[] device);
+  callback OpenDeviceCallback = void (DeviceHandle handle);
   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.
+    // Finds all instances of the USB devices specified by the vendorId/
+    // productId pair.
+    //
+    // Upon successfully enumerate the USB devices, the callback will be called
+    // with an array of <code>Device</code> dictionaries.
+    // On failure, the callback is invoked with null.
+    //
     // |options|: The properties to search for on target devices.
-    // |callback|: Invoked with the opened Device on success.
+    // |callback|: Invoked after the enumeration completes.
     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.
+    // Create a <code>DeviceHandle</code> for further operations.
+    //
+    // Multiple <code>DeviceHandle</code>s can be created for a same USB Device
+    // and it is possible to use those handles independently with the device
+    // support.
+    //
+    // Developers are responsible to call <code>closeDevice</code> to close
+    // the handle, otherwise the device handle will not be closed even if there
+    // is no reference to the <code>DeviceHandle</code> object.
+    // |device|: The device to be opened.
+    // |callback|: Invoked with the created <code>DeviceHandle</code>.
+    static void openDevice(Device device,
+                           OpenDeviceCallback callback);
+
+    // Closes an device handle. This operation does not effect other handles
+    // of the same device.
+    // |handle|: The device handle to close.
     // |callback|: The callback to invoke once the device is closed.
-    static void closeDevice(Device device,
+    static void closeDevice(DeviceHandle handle,
         optional CloseDeviceCallback callback);
 
     // Lists all the interfaces on the USB device.
-    // |device|: The device from which the interfaces should be listed.
+    // |handle|: The handle of the device from which the interfaces should be
+    // listed.
     // |callback|: The callback to invoke when the interfaces are enumerated.
-    static void listInterfaces(Device device,
+    static void listInterfaces(DeviceHandle handle,
         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,
+    static void claimInterface(DeviceHandle handle, 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.
+    // |handle|: The handle of 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,
+    static void releaseInterface(DeviceHandle handle, 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.
+    // |handle|: The handle of 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,
+    static void setInterfaceAlternateSetting(DeviceHandle handle,
         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.
+    // |handle|: An device handle 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,
+    static void controlTransfer(DeviceHandle handle,
         ControlTransferInfo transferInfo, TransferCallback callback);
 
     // Performs a bulk transfer on the specified device.
-    // |device|: An open device to make the transfer on.
+    // |handle|: An device handle 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,
+    static void bulkTransfer(DeviceHandle handle, GenericTransferInfo transferInfo,
         TransferCallback callback);
 
     // Performs an interrupt transfer on the specified device.
-    // |device|: An open device to make the transfer on.
+    // |handle|: An device handle 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,
+    static void interruptTransfer(DeviceHandle handle,
         GenericTransferInfo transferInfo, TransferCallback callback);
 
     // Performs an isochronous transfer on the specific device.
-    // |device|: An open device to make the transfer on.
+    // |handle|: An device handle 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,
+    static void isochronousTransfer(DeviceHandle handle,
         IsochronousTransferInfo transferInfo,
         TransferCallback callback);
 
     // Try 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.
     //
-    // |device|: An opened device to reset.
+    // |handle|: An device handle to reset.
     // |callback|: Invoked once the device is reset with a boolean indicating
     // whether the reset is completed successfully.
-    static void resetDevice(Device device,
+    static void resetDevice(DeviceHandle handle,
         ResetDeviceCallback callback);
   };
 };