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
+    // 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
+    // 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.
+    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
+    // 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);
   };
 };