API_CHANGE

Deprecate BluetoothError.java.

I spent a lot of time experimenting with a class BluetoothError to enumerate
the many error codes returned by the Bluetooth API. But at the end of the day
they were never used. The vast majority of method calls only really need a
true/false error value, and often not even that.

Methods which do need more detailed error enumeration (for example, bonding
failures) can have there own enumerated error codes. But there is no need
for a common set of error codes.

Also change the IPC failed warnings in BluetoothA2dp to Log.e. These indicate
a very serious error.

Introduce BluetoothAdapter.ERROR and BluetoothDevice.ERROR as helper sentinel
values.

5 files changed, 46 insertions, 73 deletions

diff --git a/core/java/android/bluetooth/BluetoothA2dp.java b/core/java/android/bluetooth/BluetoothA2dp.java
index b531a50..060f20e 100644
--- a/core/java/android/bluetooth/BluetoothA2dp.java
+++ b/core/java/android/bluetooth/BluetoothA2dp.java
@@ -42,9 +42,6 @@ import java.util.HashSet;
  *
  * Currently the BluetoothA2dp service runs in the system server and this
  * proxy object will be immediately bound to the service on construction.
- * However this may change in future releases, and error codes such as
- * BluetoothError.ERROR_IPC_NOT_READY will be returned from this API when the
- * proxy object is not yet attached.
  * 
  * Currently this class provides methods to connect to A2DP audio sinks.
  *
@@ -105,16 +102,16 @@ public final class BluetoothA2dp {
      *  Listen for SINK_STATE_CHANGED_ACTION to find out when the
      *  connection is completed.
      *  @param device Remote BT device.
-     *  @return Result code, negative indicates an immediate error.
+     *  @return false on immediate error, true otherwise
      *  @hide
      */
-    public int connectSink(BluetoothDevice device) {
+    public boolean connectSink(BluetoothDevice device) {
         if (DBG) log("connectSink(" + device + ")");
         try {
             return mService.connectSink(device);
         } catch (RemoteException e) {
-            Log.w(TAG, "", e);
-            return BluetoothError.ERROR_IPC;
+            Log.e(TAG, "", e);
+            return false;
         }
     }
 
@@ -122,16 +119,16 @@ public final class BluetoothA2dp {
      *  Listen for SINK_STATE_CHANGED_ACTION to find out when
      *  disconnect is completed.
      *  @param device Remote BT device.
-     *  @return Result code, negative indicates an immediate error.
+     *  @return false on immediate error, true otherwise
      *  @hide
      */
-    public int disconnectSink(BluetoothDevice device) {
+    public boolean disconnectSink(BluetoothDevice device) {
         if (DBG) log("disconnectSink(" + device + ")");
         try {
             return mService.disconnectSink(device);
         } catch (RemoteException e) {
-            Log.w(TAG, "", e);
-            return BluetoothError.ERROR_IPC;
+            Log.e(TAG, "", e);
+            return false;
         }
     }
 
@@ -156,14 +153,14 @@ public final class BluetoothA2dp {
             return Collections.unmodifiableSet(
                     new HashSet<BluetoothDevice>(Arrays.asList(mService.getConnectedSinks())));
         } catch (RemoteException e) {
-            Log.w(TAG, "", e);
+            Log.e(TAG, "", e);
             return null;
         }
     }
 
     /** Get the state of an A2DP sink
      *  @param device Remote BT device.
-     *  @return State code, or negative on error
+     *  @return State code, one of STATE_
      *  @hide
      */
     public int getSinkState(BluetoothDevice device) {
@@ -171,8 +168,8 @@ public final class BluetoothA2dp {
         try {
             return mService.getSinkState(device);
         } catch (RemoteException e) {
-            Log.w(TAG, "", e);
-            return BluetoothError.ERROR_IPC;
+            Log.e(TAG, "", e);
+            return BluetoothA2dp.STATE_DISCONNECTED;
         }
     }
 
@@ -186,15 +183,15 @@ public final class BluetoothA2dp {
      * @param device Paired sink
      * @param priority Integer priority, for example PRIORITY_AUTO or
      *                 PRIORITY_NONE
-     * @return Result code, negative indicates an error
+     * @return true if priority is set, false on error
      */
-    public int setSinkPriority(BluetoothDevice device, int priority) {
+    public boolean setSinkPriority(BluetoothDevice device, int priority) {
         if (DBG) log("setSinkPriority(" + device + ", " + priority + ")");
         try {
             return mService.setSinkPriority(device, priority);
         } catch (RemoteException e) {
-            Log.w(TAG, "", e);
-            return BluetoothError.ERROR_IPC;
+            Log.e(TAG, "", e);
+            return false;
         }
     }
 
@@ -208,8 +205,8 @@ public final class BluetoothA2dp {
         try {
             return mService.getSinkPriority(device);
         } catch (RemoteException e) {
-            Log.w(TAG, "", e);
-            return BluetoothError.ERROR_IPC;
+            Log.e(TAG, "", e);
+            return PRIORITY_OFF;
         }
     }
 
diff --git a/core/java/android/bluetooth/BluetoothAdapter.java b/core/java/android/bluetooth/BluetoothAdapter.java
index 1770bc7..18f6995 100644
--- a/core/java/android/bluetooth/BluetoothAdapter.java
+++ b/core/java/android/bluetooth/BluetoothAdapter.java
@@ -43,6 +43,15 @@ public final class BluetoothAdapter {
     private static final String TAG = "BluetoothAdapter";
 
     /**
+     * Sentinel error value for this class. Guaranteed to not equal any other
+     * integer constant in this class. Provided as a convenience for functions
+     * that require a sentinel error value, for example:
+     * <p><code>Intent.getIntExtra(BluetoothAdapter.EXTRA_STATE,
+     * BluetoothAdapter.ERROR)</code>
+     */
+    public static final int ERROR = -1;
+
+    /**
      * Broadcast Action: The state of the local Bluetooth adapter has been
      * changed.
      * <p>For example, Bluetooth has been turned on or off.
diff --git a/core/java/android/bluetooth/BluetoothDevice.java b/core/java/android/bluetooth/BluetoothDevice.java
index 7086557..1ab4389 100644
--- a/core/java/android/bluetooth/BluetoothDevice.java
+++ b/core/java/android/bluetooth/BluetoothDevice.java
@@ -44,6 +44,15 @@ import java.io.UnsupportedEncodingException;
 public final class BluetoothDevice implements Parcelable {
     private static final String TAG = "BluetoothDevice";
 
+    /**
+     * Sentinel error value for this class. Guaranteed to not equal any other
+     * integer constant in this class. Provided as a convenience for functions
+     * that require a sentinel error value, for example:
+     * <p><code>Intent.getIntExtra(BluetoothAdapter.EXTRA_STATE,
+     * BluetoothAdapter.ERROR)</code>
+     */
+    public static final int ERROR = -1;
+
     /** We do not have a link key for the remote device, and are therefore not
      * bonded
      * @hide*/
@@ -65,7 +74,9 @@ public final class BluetoothDevice implements Parcelable {
      *  @hide */
     public static final int DEVICE_PICKER_FILTER_TYPE_TRANSFER = 2;
 
-    //TODO: Unify these result codes in BluetoothResult or BluetoothError
+    /** A bond attempt succeeded
+     * @hide */
+    public static final int BOND_SUCCESS = 0;
     /** A bond attempt failed because pins did not match, or remote device did
      * not respond to pin request in time 
      * @hide */
@@ -252,8 +263,8 @@ public final class BluetoothDevice implements Parcelable {
      * Get the bonding state of a remote device.
      *
      * Result is one of:
-     * BluetoothError.*
      * BOND_*
+     * ERROR
      *
      * @param address Bluetooth hardware address of the remote device to check.
      * @return Result code
@@ -263,7 +274,7 @@ public final class BluetoothDevice implements Parcelable {
         try {
             return sService.getBondState(mAddress);
         } catch (RemoteException e) {Log.e(TAG, "", e);}
-        return BluetoothError.ERROR_IPC;
+        return BluetoothDevice.ERROR;
     }
 
     /**
@@ -298,7 +309,7 @@ public final class BluetoothDevice implements Parcelable {
         try {
             return sService.getRemoteClass(mAddress);
         } catch (RemoteException e) {Log.e(TAG, "", e);}
-        return BluetoothError.ERROR_IPC;
+        return BluetoothDevice.ERROR;
     }
 
     /** @hide */
@@ -314,7 +325,7 @@ public final class BluetoothDevice implements Parcelable {
          try {
              return sService.getRemoteServiceChannel(mAddress, uuid);
          } catch (RemoteException e) {Log.e(TAG, "", e);}
-         return BluetoothError.ERROR_IPC;
+         return BluetoothDevice.ERROR;
     }
 
     /** @hide */
diff --git a/core/java/android/bluetooth/BluetoothError.java b/core/java/android/bluetooth/BluetoothError.java
deleted file mode 100644
index 81c1ce9..0000000
--- a/core/java/android/bluetooth/BluetoothError.java
+++ /dev/null
@@ -1,44 +0,0 @@
-/*
- * Copyright (C) 2008 The Android Open Source Project
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package android.bluetooth;
-
-/**
- * Bluetooth API error codes.
- *
- * Errors are always negative.
- *
- * TODO: Deprecate this class.
- *
- * @hide
- */
-public class BluetoothError {
-    /** No error */
-    public static final int SUCCESS = 0;
-
-    /** Generic error */
-    public static final int ERROR = -1000;
-
-    /** Bluetooth currently disabled */
-    public static final int ERROR_DISABLED = -1001;
-
-    /** IPC is not ready, for example service is not yet bound */
-    public static final int ERROR_IPC_NOT_READY = -1011;
-
-    /** Some other IPC error, for example a RemoteException */
-    public static final int ERROR_IPC = -1012;
-
-}
diff --git a/core/java/android/bluetooth/IBluetoothA2dp.aidl b/core/java/android/bluetooth/IBluetoothA2dp.aidl
index e6c6be2..2df7f23 100644
--- a/core/java/android/bluetooth/IBluetoothA2dp.aidl
+++ b/core/java/android/bluetooth/IBluetoothA2dp.aidl
@@ -24,10 +24,10 @@ import android.bluetooth.BluetoothDevice;
  * {@hide}
  */
 interface IBluetoothA2dp {
-    int connectSink(in BluetoothDevice device);
-    int disconnectSink(in BluetoothDevice device);
+    boolean connectSink(in BluetoothDevice device);
+    boolean disconnectSink(in BluetoothDevice device);
     BluetoothDevice[] getConnectedSinks();  // change to Set<> once AIDL supports
     int getSinkState(in BluetoothDevice device);
-    int setSinkPriority(in BluetoothDevice device, int priority);
+    boolean setSinkPriority(in BluetoothDevice device, int priority);
     int getSinkPriority(in BluetoothDevice device);
 }