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 {
     // The address of the device, in the format "XX:XX:XX:XX:XX:XX".
@@ skipping 26 matching lines @@
     ArrayBuffer hash;
 
     // Simple Pairing Randomizer R.
     // Always 16 octets long.
     ArrayBuffer randomizer;
   };
 
   callback AddressCallback = void (DOMString result);
   callback BooleanCallback = void (boolean result);
   callback DataCallback = void (ArrayBuffer result);
+  callback DeviceCallback = void (Device device);
   callback DevicesCallback = void (Device[] result);
   callback OutOfBandPairingDataCallback = void (OutOfBandPairingData data);
   callback ResultCallback = void ();
   callback SizeCallback = void (long result);
   callback SocketCallback = void (Socket result);
 
   // Options for the getDevices function.  If neither |uuid| or |name| are
   // provided, all devices known to the system are returned.
   dictionary GetDevicesOptions {
     // Only devices providing a service with a UUID that matches |uuid| will be
@@ skipping 40 matching lines @@
   dictionary SetOutOfBandPairingDataOptions {
     // The address of the remote device that the data should be associated
     // with.  |device_address| should be in the format "XX:XX:XX:XX:XX:XX".
     DOMString address;
 
     // The Out Of Band Pairing Data.  If this 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 device_callback;
+  };
+
   // These functions all report failures via chrome.extension.lastError.
   interface Functions {
     // Checks if the system has bluetooth support.
     // |callback| : Called with the boolean result.
     static void isAvailable(BooleanCallback callback);
 
     // Checks if the system's bluetooth module has power.
     // |callback| : Called with the boolean result.
     static void isPowered(BooleanCallback callback);
 
@@ skipping 36 matching lines @@
     // |callback| : Called with the data.
     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.  Note that discovery can be resource
+    // intensive.  stopDiscovery should be called as soon as is convenient.
+    // |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 availability of bluetooth on the system changes.
     // |available| : True if bluetooth is available, false otherwise.
     static void onAvailabilityChanged(boolean available);
 
     // 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);
+
+    // Used to return discovered devices to the extension.  Users should not
+    // add listeners to this event directly.
+    static void onDeviceDiscovered_(Device device);

[asargent_no_longer_on_chrome, 2012/06/15 19:59:08]

I think that since this doesn't need to be visible to consumers of the API, you
don't need to list it in the IDL file. You can create an arbitrarily named event
to listen for in your custom_bindings.js by doing:

chromeHidden.bluetooth.onDeviceDiscovered =
  new chrome.Event("bluetooth.onDeviceDiscovered");


...

chromeHidden.bluetooth.onDeviceDiscovered.addListener(function(...) {...})

   };
 };