am d4fac2c0: Doc change: updated TOC for Bluetooth CL.

* commit 'd4fac2c0263fda4b20f253edd594cf909e61eb4e':
  Doc change: updated TOC for Bluetooth CL.

docs/html/guide/guide_toc.cs

@@ -302,11 +302,13 @@
       </li> -->
   <!--<li><a style="color:gray;">Localization</a></li>  -->
       <li><a href="<?cs var:toroot ?>guide/topics/appwidgets/index.html">
-            <span class="en">App Widgets</span>
+            <span class="en">App Widgets</span></a>
-          </a></li>
+            <span class="new">updated</span>
+          </li>
       <li><a href="<?cs var:toroot?>guide/topics/wireless/bluetooth.html">
-            <span class="en">Bluetooth</span>
+            <span class="en">Bluetooth</span></a>
-          </a></li>
+            <span class="new">updated</span>
+          </li>
       <li><a href="<?cs var:toroot?>guide/topics/nfc/index.html">
             <span class="en">Near Field Communication</span>
           </a></li>
@@ -337,8 +339,8 @@
           </ul>
       </li>
       <li><a href="<?cs var:toroot?>guide/topics/admin/device-admin.html">
-            <span class="en">Device Administration</span>
+            <span class="en">Device Administration</span></a>
-         </a>
+            <span class="new">updated</span>
       </li>
       <li class="toggle-list">
            <div>

docs/html/guide/topics/wireless/bluetooth.jd

@@ -26,6 +26,10 @@ other devices</li>
         <li><a href="#ConnectingAsAClient">Connecting as a client</a></li> 
       </ol></li> 
     <li><a href="#ManagingAConnection">Managing a Connection</a></li>
+    <li><a href="#Profiles">Working with Profiles</a> 
+      <ol>
+        <li><a href="#AT-Commands">Vendor-specific AT commands</a>
+      </ol></li>
   </ol> 
  
   <h2>Key classes</h2> 
@@ -72,7 +76,7 @@ Bluetooth, finding devices that are either paired or available in the local
 area, connecting devices, and transferring data between devices.</p> 
  
 <p>All of the Bluetooth APIs are available in the {@link android.bluetooth}
-package. Here's a summary of the classes you will need to create Bluetooth
+package. Here's a summary of the classes and interfaces you will need to create Bluetooth
 connections:</p> 
  
 <dl> 
@@ -113,6 +117,27 @@ device. This is a read-only set of properties that define the device's major and
 minor device classes and its services. However, this does not reliably describe
 all Bluetooth profiles and services supported by the device, but is useful as a
 hint to the device type.</dd> 
+ 
+<dt>{@link android.bluetooth.BluetoothProfile}</dt> <dd>An interface that
+represents a Bluetooth profile. A <em>Bluetooth profile</em> is a wireless
+interface specification for Bluetooth-based communication between devices. An
+example is the Hands-Free profile.  For more discussion of profiles, see <a
+href="#Profiles">Working with Profiles</a></dd> 
+
+<dt>{@link android.bluetooth.BluetoothHeadset}</dt> <dd>Provides support for
+Bluetooth headsets to be used with mobile phones. This includes both  Bluetooth
+Headset and Hands-Free (v1.5) profiles.</dd> 
+
+<dt>{@link android.bluetooth.BluetoothA2dp}</dt> <dd> Defines how high quality
+audio can be streamed from one device to another over a Bluetooth connection.
+"A2DP" stands for Advanced Audio Distribution Profile.</dd> 
+
+<dt>{@link android.bluetooth.BluetoothProfile.ServiceListener}</dt> 
+
+<dd>An interface that notifies {@link android.bluetooth.BluetoothProfile} IPC
+clients when they have  been connected to or disconnected from the service (that
+is, the internal service that runs a particular profile). </dd> 
+ 
 </dl> 
  
  
@@ -365,14 +390,17 @@ not perform discovery while connected.</p>
  
 <p>If you would like to make the local device discoverable to other devices,
 call {@link android.app.Activity#startActivityForResult(Intent,int)} with the
-{@link android.bluetooth.BluetoothAdapter#ACTION_REQUEST_DISCOVERABLE} action Intent.
+{@link android.bluetooth.BluetoothAdapter#ACTION_REQUEST_DISCOVERABLE} action
-This will issue a request to enable discoverable mode through the system settings (without
+Intent. This will issue a request to enable discoverable mode through the system
-stopping your application). By default, the device will become discoverable for
+settings (without stopping your application). By default, the device will become
-120 seconds. You can define a different duration by adding the
+discoverable for 120 seconds. You can define a different duration by adding the
-{@link android.bluetooth.BluetoothAdapter#EXTRA_DISCOVERABLE_DURATION} Intent extra
+{@link android.bluetooth.BluetoothAdapter#EXTRA_DISCOVERABLE_DURATION} Intent
-(maximum duration is 300 seconds). For example:</p>
+extra. The maximum duration an app can set is 3600 seconds, and a value of 0
-<pre>
+means the device is always discoverable. Any value below 0 or above 3600 is
-Intent discoverableIntent = new
+automatically set to 120 secs). For example, this snippet sets the duration to
+300:</p> 
+
+<pre>Intent discoverableIntent = new
 Intent(BluetoothAdapter.ACTION_REQUEST_DISCOVERABLE);
 discoverableIntent.putExtra(BluetoothAdapter.EXTRA_DISCOVERABLE_DURATION, 300);
 startActivity(discoverableIntent);
@@ -836,6 +864,103 @@ This should always be called when you're done using the Bluetooth
 connection.</p> 
  
 <div class="special"> 
-<p>For a complete demonstration using the Bluetooth APIs, see the <a
+<p>For a  demonstration of using the Bluetooth APIs, see the <a
 href="{@docRoot}resources/samples/BluetoothChat/index.html">Bluetooth Chat sample app</a>.</p> 
 </div> 
+
+<h2 id="Profiles">Working with Profiles</h2> 
+
+<p>Starting in Android 3.0, the Bluetooth API includes support for working with
+Bluetooth profiles. A <em>Bluetooth profile</em> is a wireless interface
+specification for Bluetooth-based communication between devices. An example
+is the Hands-Free profile. For a mobile phone to connect to a wireless headset,
+both devices must support the Hands-Free profile. </p> 
+
+<p>You can implement the interface {@link android.bluetooth.BluetoothProfile} to write
+your own classes to support a particular Bluetooth profile. The Android
+Bluetooth API provides implementations for the following Bluetooth
+profiles:</p> 
+<ul> 
+
+  <li><strong>Headset</strong>. The Headset profile provides support for
+Bluetooth headsets to be used with mobile phones. Android provides the {@link
+android.bluetooth.BluetoothHeadset} class, which is a proxy for controlling the
+Bluetooth Headset Service via interprocess communication (<a
+href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#IPC">IPC</a
+>). This includes both  Bluetooth Headset and Hands-Free (v1.5) profiles. The
+{@link android.bluetooth.BluetoothHeadset} class includes support for AT commands.
+For more discussion of this topic, see <a href="#AT-Commands">Vendor-specific AT commands</a></li> 
+
+  <li><strong>A2DP</strong>. The Advanced Audio Distribution Profile (A2DP)
+profile defines how high quality audio can be streamed from one device to
+another over a Bluetooth connection. Android provides the {@link
+android.bluetooth.BluetoothA2dp} class, which is a proxy for controlling
+the Bluetooth A2DP  Service via IPC.</li> 
+
+</ul> 
+
+<p>Here are the basic steps for working with a profile:</p> 
+<ol> 
+
+  <li>Get the default adapter, as described in <a href="{@docRoot}guide/topics/wireless/bluetooth.
+html#SettingUp">Setting Up Bluetooth</a>.</li> 
+
+  <li>Use {@link
+android.bluetooth.BluetoothAdapter#getProfileProxy(android.content.Context,
+android.bluetooth.BluetoothProfile.ServiceListener, int) getProfileProxy()} to
+establish a connection to the profile proxy object associated with the profile.
+In the example below, the profile proxy object is an instance of {@link
+android.bluetooth.BluetoothHeadset}. </li> 
+
+  <li>Set up a  {@link android.bluetooth.BluetoothProfile.ServiceListener}. This
+listener notifies {@link android.bluetooth.BluetoothProfile} IPC clients when
+they have been connected to or disconnected from the service.</li> 
+
+  <li>In {@link
+android.bluetooth.BluetoothProfile.ServiceListener#onServiceConnected(int,
+android.bluetooth.BluetoothProfile) onServiceConnected()}, get a handle
+to the profile proxy object.</li> 
+
+  <li>Once you have the profile proxy object, you can use it to monitor the
+state of the connection and perform other operations that are relevant to that
+profile.</li> 
+</ol> 
+<p> For example, this code snippet shows how to connect to a {@link android.bluetooth.BluetoothHeadset} proxy object so that you can control the
+Headset profile:</p> 
+
+<pre>BluetoothHeadset mBluetoothHeadset;
+ 
+// Get the default adapter
+BluetoothAdapter mBluetoothAdapter = BluetoothAdapter.getDefaultAdapter();
+ 
+// Establish connection to the proxy.
+mBluetoothAdapter.getProfileProxy(context, mProfileListener, BluetoothProfile.HEADSET);
+ 
+private BluetoothProfile.ServiceListener mProfileListener = new BluetoothProfile.ServiceListener() {
+    public void onServiceConnected(int profile, BluetoothProfile proxy) {
+        if (profile == BluetoothProfile.HEADSET) {
+            mBluetoothHeadset = (BluetoothHeadset) proxy;
+        }
+    }
+    public void onServiceDisconnected(int profile) {
+        if (profile == BluetoothProfile.HEADSET) {
+            mBluetoothHeadset = null;
+        }
+    }
+};
+ 
+// ... call functions on mBluetoothHeadset
+ 
+// Close proxy connection after use.
+mBluetoothAdapter.closeProfileProxy(mBluetoothHeadset);
+</pre> 
+
+<h3 id="AT-Commands">Vendor-specific AT commands</h3> 
+
+<p>Starting in Android 3.0, applications can register to receive system
+broadcasts of pre-defined vendor-specific AT commands sent by headsets (such as
+a Plantronics +XEVENT command). For example, an application could receive
+broadcasts that indicate a connected device's battery level and could notify the
+user or take other action as needed. Create a broadcast receiver for the {@link
+android.bluetooth.BluetoothHeadset#ACTION_VENDOR_SPECIFIC_HEADSET_EVENT} intent
+to handle vendor-specific AT commands for the headset.</p>