Bluetooth Extension API: Add a discovery API

chrome/common/extensions/api/experimental_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.
 
 // Bluetooth API.
 // TODO(bryeung): mark this API as ChromeOS only (see crbug.com/119398).
 
 [nodoc] namespace experimental.bluetooth {
   dictionary Device {
     DOMString address;
@@ skipping 83 matching lines @@
     static void getOutOfBandPairingData(OutOfBandPairingDataCallback callback);
 
     // Set the Out of Band Pairing data for the bluetooth device at |address|.
     // |address|  : The bluetooth address of the device sending the data.
     // |data|     : The data.
     // |callback| : Called to indicate success or failure.
     static void setOutOfBandPairingData(
         DOMString address,
         OutOfBandPairingData data,
         optional ResultCallback callback);
+
+    // Start discovery.  Discovered devices will be returned via the
+    // onDeviceDiscovered event.  Note that discovery can be resource
+    // intensive.  stopDiscovery should be called as soon as is convenient.
+    static void startDiscovery();

[asargent_no_longer_on_chrome, 2012/06/14 18:23:55]

FYI, another approach we could take is to have this function take a parameter
which is an event listener function, instead of having a "global" event of
onDeviceDiscovered.

See the onEvent option of the tts.speak method, or the onclick option of the
contextMenus.create method, for examples of this style.

http://code.google.com/chrome/extensions/tts.html#method-speak
http://code.google.com/chrome/extensions/contextMenus.html#method-create


I don't think you necessarily need to change this, but perhaps keep it in mind
and think about whether it would make writing code against the API a little
easier/clearer or not. For example, compare these 2  code snippets:

chrome.bluetooth.startDiscovery({onDiscovered:function(device) {
  // do something with device
  chrome.bluetooth.stopDiscovery();
}});


versus:


chrome.bluetooth.onDeviceDiscovered.addListener(function(device) {
  // do something with device
  chrome.bluetooth.stopDiscovery();  
})
chrome.bluetooth.startDiscovery();

+
+    // Stop discovery.
+    static void stopDiscovery();

[asargent_no_longer_on_chrome, 2012/06/14 18:23:55]

nit: startDiscovery and stopDiscovery should probably both take a optional
ResultCallback parameter. It looks like you send back an indication of error in
some cases in the .cc file.

   };
 
   interface Events {
     // Fired when the availability of bluetooth on the system changes.
     // |available| : True if bluetooth is available, false otherwise.
     static void onAvailabilityChanged(boolean available);
 
+    // Fired when a new device is discovered.  This event will only be fired
+    // after a call to startDiscovery(), and before any subsequent call to
+    // stopDiscovery().
+    static void onDeviceDiscovered(Device device);
+
     // Fired when the power state of bluetooth on the system changes.
     // |powered| : True if bluetooth is powered, false otherwise.
     static void onPowerChanged(boolean has_power);
   };
 };