Bluetooth: add Device events, and cleanup JS API

chrome/common/extensions/docs/templates/articles/app_bluetooth.html

Index: chrome/common/extensions/docs/templates/articles/app_bluetooth.html
diff --git a/chrome/common/extensions/docs/templates/articles/app_bluetooth.html b/chrome/common/extensions/docs/templates/articles/app_bluetooth.html
new file mode 100644
index 0000000000000000000000000000000000000000..14d766dbc222a2f5bf79634b7711dc03939039f7
--- /dev/null
+++ b/chrome/common/extensions/docs/templates/articles/app_bluetooth.html
@@ -0,0 +1,126 @@
+<h1>Bluetooth Devices</h1>
+
+<p>
+  This document describes how to use the <a href="bluetooth.html">Bluetooth
+  API</a> to communicate with Bluetooth and Bluetooth Low Energy devices.
+</p>
+
+<p>
+  For background information about Bluetooth, see the official
+  <a href="http://www.bluetooth.org">Bluetooth specifications</a>.
+</p>
+
+<h2 id="listing_devices">Listing known devices</h2>
+
+<p>
+  To get a list of the devices known to the Bluetooth adapter, use the
+  <code>chrome.bluetooth.getDevices</code> method:
+</p>
+
+<pre>
+chrome.bluetooth.getDevices(function(devices) {
+  for (var i = 0; i < devices.length; i++) {
+    console.log(devices[i].address);
+  }
+});
+</pre>
+
+<p>
+  All devices are returned, including paired devices and devices recently
+  discovered. It will not begin discovery of new devices.
+</p>
+
+<h2 id="device_notifications">Receiving device notifications</h2>
+
+<p>
+  Instead of repeatedly calling <code>chrome.bluetooth.getDevices</code>, you
+  can use the <code>chrome.bluetooth.onDeviceAdded</code>,
+  <code>chrome.bluetooth.onDeviceChanged</code> and
+  <code>chrome.bluetooth.onDeviceRemoved</code> events to receive notifications.
+</p>
+
+<p>
+  The <code>chrome.bluetooth.onDeviceAdded</code> event is sent whenever a
+  device is discovered by the adapter or makes a connection to the adapter:
+</p>
+
+<pre>
+chrome.bluetooth.onDeviceAdded.addListener(function(device) {
+  console.log(device.address);
+});
+</pre>
+
+<p>
+  Adding a listener for this event does not begin discovery of devices.  
+</p>
+
+<p>
+  Changes to devices, including previously discovered devices becoming paired,
+  are notified by the <code>chrome.bluetooth.onDeviceChanged</code> event:
+</p>
+
+<pre>
+chrome.bluetooth.onDeviceChanged.addListener(function(device) {
+  console.log(device.address);
+});
+</pre>
+
+<p>
+  Finally the <code>chrome.bluetooth.onDeviceRemoved</code>code> event is sent whenever a paired device is removed from the system, or a discovered device

[armansito, 2014/03/05 21:44:15]

Remove the stray tag there (i.e. "</code>code>" -> "</code>")

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

Done.

+  has not been seen recently:
+</p>
+
+<pre>
+chrome.bluetooth.onDeviceRemoved.addListener(function(device) {
+  console.log(device.address);
+});
+</pre>
+
+<h2 id="discovery">Discovering nearby devices</h2>
+
+<p>
+  To begin discovery of nearby devices use the
+  <code>chrome.bluetooth.startDiscovery</code>code> method, discovery can be resource intensive so you should call

[armansito, 2014/03/05 21:44:15]

"</code>code>" -> "</code>"

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

Done.

+  <code>chrome.bluetooth.stopDiscovery</code> when done.
+</p>
+
+<p>
+  Information about each newly discovered device is received using the
+  <code>chrome.bluetooth.onDeviceAdded</code> event. For devices that have
+  already been discovered recently, or have been previously paired with or
+  connected to, the event will not be sent, instead you should call
+  <code>chrome.bluetooth.getDevices</code> to obtain the current information,
+  and use the <code>chrome.bluetooth.onDeviceChanged</code> event to be notified of changes to that information as a result of discovery.
+</p>
+
+<p>
+  Example:
+</p>
+
+<pre>
+var device_names = {};
+var updateDeviceName = function(device) {
+  device_names[device.address] = device.name;
+};
+var removeDeviceName = function(device) {
+  delete device_names[device.address];
+}
+
+chrome.bluetooth.onDeviceAdded.addListener(updateDeviceName);
+chrome.bluetooth.onDeviceChanged.addListener(updateDeviceName);
+chrome.bluetooth.onDeviceRemoved.addListener(removeDeviceName);
+
+chrome.bluetooth.getDevices(function(devices) {
+  for (var i = 0; i < devices.length; i++) {
+    updateDeviceName(devices[i]);
+  }
+});
+
+chrome.bluetooth.startDiscovery(function() {
+  // Stop discovery after 30 seconds.
+  setTimeout(function() {
+    chrome.bluetooth.stopDiscovery(function() {});
+  }, 30000);
+});
+</pre>
+