Bluetooth: add Device events, and cleanup JS API

chrome/common/extensions/api/bluetooth.idl

Index: chrome/common/extensions/api/bluetooth.idl
diff --git a/chrome/common/extensions/api/bluetooth.idl b/chrome/common/extensions/api/bluetooth.idl
index 747be425901d5d811ee712ed82b8a0b0dc04439d..a339b8d19b49500b8ae062c00a8815e2f1d02343 100644
--- a/chrome/common/extensions/api/bluetooth.idl
+++ b/chrome/common/extensions/api/bluetooth.idl
@@ -104,7 +104,6 @@ namespace bluetooth {
   callback AddressCallback = void (DOMString result);
   callback BooleanCallback = void (boolean result);
   callback DataCallback = void (optional ArrayBuffer result);
-  callback DeviceCallback = void (Device device);
   callback DevicesCallback = void (Device[] result);
   callback NameCallback = void (DOMString result);
   callback OutOfBandPairingDataCallback = void (OutOfBandPairingData data);
@@ -114,18 +113,6 @@ namespace bluetooth {
   callback SizeCallback = void (long result);
   callback SocketCallback = void (Socket result);
 
-  // Options for the getDevices function. If |profile| is not provided, all
-  // devices known to the system are returned.
-  dictionary GetDevicesOptions {
-    // Only devices providing |profile| will be returned.
-    Profile? profile;
-
-    // Called for each matching device.  Note that a service discovery request
-    // must be made to each non-matching device before it can be definitively
-    // excluded.  This can take some time.
-    DeviceCallback deviceCallback;
-  };
-
   // Options for the getProfiles function.
   dictionary GetProfilesOptions {
     // The remote Bluetooth device to retrieve the exported profiles list from.
@@ -180,12 +167,6 @@ namespace bluetooth {
     OutOfBandPairingData? data;
   };
 
-  // Options for the startDiscovery function.
-  dictionary StartDiscoveryOptions {
-    // Called for each device that is discovered.
-    DeviceCallback deviceCallback;
-  };
-
   // These functions all report failures via chrome.runtime.lastError.
   interface Functions {
     // Registers the JavaScript application as an implementation for the given
@@ -202,15 +183,10 @@ namespace bluetooth {
     //              state.
     static void getAdapterState(AdapterStateCallback callback);
 
-    // Get a bluetooth devices known to the system.  Known devices are either
-    // currently paired, or have been paired in the past.
-    // |options|  : Controls which devices are returned and provides
-    //              |deviceCallback|, which is called for each matching device.
+    // Get a list of bluetooth devices known to the system, including paired

[miket_OOO, 2014/03/05 21:30:09]

Because this will become a part of public docs, style matters more. Please
capitalize Bluetooth for consistency & correctness.

[keybuk, 2014/03/06 21:33:44]

Done.

+    // and recently discovered devices.
     // |callback| : Called when the search is completed.
-    //              |options.deviceCallback| will not be called after
-    //              |callback| has been called.
-    static void getDevices(GetDevicesOptions options,
-                           ResultCallback callback);
+    static void getDevices(DevicesCallback callback);
 
     // Returns the set of exported profiles for the device specified in options.
     // This function will not initiate a connection to the remote device.
@@ -259,14 +235,16 @@ namespace bluetooth {
     static void setOutOfBandPairingData(SetOutOfBandPairingDataOptions options,
                                         optional ResultCallback callback);
 
-    // Start discovery. Discovered devices will be returned via the
-    // |onDeviceDiscovered| callback.  Discovery will fail to start if it is
-    // already in progress.  Discovery can be resource intensive: stopDiscovery
+    // Start discovery. Newly discovered devices will be returned via the
+    // onDeviceAdded event, previously discovered devices already known to

[miket_OOO, 2014/03/05 21:30:09]

delete comma, start new sentence.

[keybuk, 2014/03/06 21:33:44]

Done.

+    // the adapter must be obtained using getDevices and will only be updated
+    // using the |onDeviceChanged| event if information about them changes.
+    //
+    // Discovery will fail to start if this application has already called
+    // startDiscovery.  Discovery can be resource intensive: stopDiscovery
     // should be called as soon as possible.
-    // |options|  : The options for this function.
     // |callback| : Called to indicate success or failure.
     static void startDiscovery(
-        StartDiscoveryOptions options,
         optional ResultCallback callback);
 
     // Stop discovery.
@@ -280,6 +258,17 @@ namespace bluetooth {
     // |state| : The new state of the adapter.
     static void onAdapterStateChanged(AdapterState state);
 
+    // Fired when information about a new Bluetooth Device is available.

[miket_OOO, 2014/03/05 21:30:09]

lowercase device. If you meant Device as in the class name, then Bluetooth is
redundant.

+    static void onDeviceAdded(Device device);
+
+    // Fired when information about a known Bluetooth Device has changed.
+    static void onDeviceChanged(Device device);
+
+    // Fired when a Bluetooth Device that was previously discovered has been
+    // out of range for long enough to be considered unavailable again, and

[miket_OOO, 2014/03/05 21:30:09]

This would be more useful and readable if the more common case were listed
first. I'll defer to you because you're the domain expert, but I'm guessing
device removal is the more common case.

[keybuk, 2014/03/06 21:33:44]

Done.

+    // when a paired device is removed.
+    static void onDeviceRemoved(Device device);
+
     // Fired when a connection has been made for a registered profile.
     // |socket| : The socket for the connection.
     static void onConnection(Socket socket);