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.
 
 // 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 <code>Device</code> uniquely identifies a connected USB device.
+  // They are returned by <code>getDevices</code> calls and the
+  // <code>device</code> field remains consistent for the same device.
   dictionary Device {
+    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;
     long vendorId;
     long productId;
   };
 
   dictionary EndpointDescriptor {
     long address;
     TransferType type;
     Direction direction;
     long maximumPacketSize;
@@ skipping 78 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 {
+  // GetDevicesOptions describes the properties of devices which are found and
+  // opened via getDevices.
+  dictionary GetDevicesOptions {
     long vendorId;
     long productId;
     long? interfaceId;
   };
 
   callback VoidCallback = void ();
-  callback FindDevicesCallback = void (Device[] device);
+  callback GetDevicesCallback = void (Device[] devices);
+  callback FindDevicesCallback = void (DeviceHandle[] handles);
+  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.
+    // Get all instances of the USB devices specified by the vendorId/
+    // productId pair.
+    //
+    // Upon successfully enumeration, the callback will be called with an array
+    // of <code>Device</code> objects. <code>Device</code> objects can further 
+    // be opened by <code>openDevice</code> before any communication takes
+    // place.
+    //
     // |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 after the enumeration completes.
+    static void getDevices(GetDevicesOptions options,
+                           GetDevicesCallback 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.
+    // Open all instances of the USB devices specified by the vendorId/
+    // productId pair.
+    //
+    // Upon successfully enumeration, the callback will be called with an array
+    // of <code>DeviceHandle</code> objects. Developer is responsible to call
+    // <code>closeDevice</code> on every <code>DeviceHandle</code>, otherwise
+    // the USB device will not be closed even if the app not long possess any
+    // reference to the <code>DeviceHanlde</code> object.
+    //
+    // |options|: The properties to search for on target devices.
+    // |callback|: Invoked after the enumeration completes.
+    static void findDevices(GetDevicesOptions options,
+                            FindDevicesCallback callback);
+
+    // 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);
   };
 };