Bluetooth: add Device events, and cleanup JS API

chrome/common/extensions/api/bluetooth.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.bluetooth</code> API to connect to a Bluetooth
 // device. All functions report failures via chrome.runtime.lastError.
 namespace bluetooth {
   dictionary AdapterState {
     // The address of the adapter, in the format 'XX:XX:XX:XX:XX:XX'.
     DOMString address;
@@ skipping 86 matching lines @@
 
     // Simple Pairing Randomizer R.
     // Always 16 octets long.
     ArrayBuffer randomizer;
   };
 
   callback AdapterStateCallback = void(AdapterState result);
   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);
   callback ProfilesCallback = void(Profile[] result);
   callback ResultCallback = void ();
   callback ServicesCallback = void(ServiceRecord[] result);
   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.
     Device device;
   };
 
   // Options for the getServices function.
   dictionary GetServicesOptions {
     // The address of the device to inquire about. |deviceAddress| should be
     // in the format 'XX:XX:XX:XX:XX:XX'.
@@ skipping 34 matching lines @@
   dictionary SetOutOfBandPairingDataOptions {
     // The address of the remote device that the data should be associated
     // with. |deviceAddress| should be in the format 'XX:XX:XX:XX:XX:XX'.
     DOMString address;
 
     // The Out Of Band Pairing Data. If this is omitted, the data for the
     // device is cleared instead.
     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
     // Profile; if a channel or PSM is specified, the profile will be exported
     // in the host's SDP and GATT tables and advertised to other devices.
     static void addProfile(Profile profile, ResultCallback callback);
 
     // Unregisters the JavaScript application as an implementation for the given
     // Profile; only the uuid field of the Profile object is used.
     static void removeProfile(Profile profile, ResultCallback callback);
 
     // Get information about the Bluetooth adapter.
     // |callback| : Called with an AdapterState object describing the adapter
     //              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.
     static void getProfiles(GetProfilesOptions options,
                             ProfilesCallback callback);
 
     // Get a list of services provided by a device.
     static void getServices(GetServicesOptions options,
                             ServicesCallback callback);
 
@@ skipping 28 matching lines @@
     static void getLocalOutOfBandPairingData(
         OutOfBandPairingDataCallback callback);
 
     // Set the Out of Band Pairing data for a remote device.
     // Any previous Out Of Band Pairing Data for this device is overwritten.
     // |options|  : The options for this function.
     // |callback| : Called to indicate success or failure.
     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.
     // |callback| : Called to indicate success or failure.
     static void stopDiscovery(
         optional ResultCallback callback);
   };
 
   interface Events {
     // Fired when the state of the Bluetooth adapter changes.
     // |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);
   };
 };