diff options
Diffstat (limited to 'core/java/android/bluetooth')
| -rw-r--r-- | core/java/android/bluetooth/BluetoothAdapter.java | 270 | ||||
| -rw-r--r-- | core/java/android/bluetooth/BluetoothDevice.java | 3 | ||||
| -rw-r--r-- | core/java/android/bluetooth/BluetoothError.java | 2 | ||||
| -rw-r--r-- | core/java/android/bluetooth/BluetoothIntent.java | 28 |
4 files changed, 205 insertions, 98 deletions
diff --git a/core/java/android/bluetooth/BluetoothAdapter.java b/core/java/android/bluetooth/BluetoothAdapter.java index 5a182f0..1770bc7 100644 --- a/core/java/android/bluetooth/BluetoothAdapter.java +++ b/core/java/android/bluetooth/BluetoothAdapter.java @@ -16,6 +16,8 @@ package android.bluetooth; +import android.annotation.SdkConstant; +import android.annotation.SdkConstant.SdkConstantType; import android.os.RemoteException; import android.util.Log; @@ -40,32 +42,109 @@ import java.util.HashSet; public final class BluetoothAdapter { private static final String TAG = "BluetoothAdapter"; - /** @hide */ - public static final int BLUETOOTH_STATE_OFF = 0; - /** @hide */ - public static final int BLUETOOTH_STATE_TURNING_ON = 1; - /** @hide */ - public static final int BLUETOOTH_STATE_ON = 2; - /** @hide */ - public static final int BLUETOOTH_STATE_TURNING_OFF = 3; - - /** Inquiry scan and page scan are both off. - * Device is neither discoverable nor connectable - * @hide */ - public static final int SCAN_MODE_NONE = 0; - /** Page scan is on, inquiry scan is off. - * Device is connectable, but not discoverable - * @hide*/ - public static final int SCAN_MODE_CONNECTABLE = 1; - /** Page scan and inquiry scan are on. - * Device is connectable and discoverable - * @hide*/ - public static final int SCAN_MODE_CONNECTABLE_DISCOVERABLE = 3; + /** + * Broadcast Action: The state of the local Bluetooth adapter has been + * changed. + * <p>For example, Bluetooth has been turned on or off. + * <p>Contains the extra fields {@link #EXTRA_STATE} and {@link + * #EXTRA_PREVIOUS_STATE} containing the new and old states + * respectively. + * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive. + */ + @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) + public static final String ACTION_STATE_CHANGED = + "android.bluetooth.intent.action.STATE_CHANGED"; - /** @hide */ - public static final int RESULT_FAILURE = -1; - /** @hide */ - public static final int RESULT_SUCCESS = 0; + /** + * Used as an int extra field in {@link #ACTION_STATE_CHANGED} + * intents to request the current power state. Possible values are: + * {@link #STATE_OFF}, + * {@link #STATE_TURNING_ON}, + * {@link #STATE_ON}, + * {@link #STATE_TURNING_OFF}, + */ + public static final String EXTRA_STATE = + "android.bluetooth.intent.extra.STATE"; + /** + * Used as an int extra field in {@link #ACTION_STATE_CHANGED} + * intents to request the previous power state. Possible values are: + * {@link #STATE_OFF}, + * {@link #STATE_TURNING_ON}, + * {@link #STATE_ON}, + * {@link #STATE_TURNING_OFF}, + */ + public static final String EXTRA_PREVIOUS_STATE = + "android.bluetooth.intent.extra.PREVIOUS_STATE"; + + /** + * Indicates the local Bluetooth adapter is off. + */ + public static final int STATE_OFF = 40; + /** + * Indicates the local Bluetooth adapter is turning on. However local + * clients should wait for {@link #STATE_ON} before attempting to + * use the adapter. + */ + public static final int STATE_TURNING_ON = 41; + /** + * Indicates the local Bluetooth adapter is on, and ready for use. + */ + public static final int STATE_ON = 42; + /** + * Indicates the local Bluetooth adapter is turning off. Local clients + * should immediately attempt graceful disconnection of any remote links. + */ + public static final int STATE_TURNING_OFF = 43; + + /** + * Broadcast Action: Indicates the Bluetooth scan mode of the local Adapter + * has changed. + * <p>Contains the extra fields {@link #EXTRA_SCAN_MODE} and {@link + * #EXTRA_PREVIOUS_SCAN_MODE} containing the new and old scan modes + * respectively. + * <p>Requires {@link android.Manifest.permission#BLUETOOTH} + */ + @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) + public static final String ACTION_SCAN_MODE_CHANGED = + "android.bluetooth.intent.action.SCAN_MODE_CHANGED"; + + /** + * Used as an int extra field in {@link #ACTION_SCAN_MODE_CHANGED} + * intents to request the current scan mode. Possible values are: + * {@link #SCAN_MODE_NONE}, + * {@link #SCAN_MODE_CONNECTABLE}, + * {@link #SCAN_MODE_CONNECTABLE_DISCOVERABLE}, + */ + public static final String EXTRA_SCAN_MODE = "android.bluetooth.intent.extra.SCAN_MODE"; + /** + * Used as an int extra field in {@link #ACTION_SCAN_MODE_CHANGED} + * intents to request the previous scan mode. Possible values are: + * {@link #SCAN_MODE_NONE}, + * {@link #SCAN_MODE_CONNECTABLE}, + * {@link #SCAN_MODE_CONNECTABLE_DISCOVERABLE}, + */ + public static final String EXTRA_PREVIOUS_SCAN_MODE = + "android.bluetooth.intent.extra.PREVIOUS_SCAN_MODE"; + + /** + * Indicates that both inquiry scan and page scan are disabled on the local + * Bluetooth adapter. Therefore this device is neither discoverable + * nor connectable from remote Bluetooth devices. + */ + public static final int SCAN_MODE_NONE = 50; + /** + * Indicates that inquiry scan is disabled, but page scan is enabled on the + * local Bluetooth adapter. Therefore this device is not discoverable from + * remote Bluetooth devices, but is connectable from remote devices that + * have previously discovered this device. + */ + public static final int SCAN_MODE_CONNECTABLE = 51; + /** + * Indicates that both inquiry scan and page scan are enabled on the local + * Bluetooth adapter. Therefore this device is both discoverable and + * connectable from remote Bluetooth devices. + */ + public static final int SCAN_MODE_CONNECTABLE_DISCOVERABLE = 53; /** The user will be prompted to enter a pin * @hide */ @@ -97,6 +176,7 @@ public final class BluetoothAdapter { * such as "00:11:22:33:AA:BB". * <p>A {@link BluetoothDevice} will always be returned for a valid * hardware address, even if this adapter has never seen that device. + * * @param address valid Bluetooth MAC address * @throws IllegalArgumentException if address is invalid */ @@ -105,10 +185,12 @@ public final class BluetoothAdapter { } /** - * Is Bluetooth currently turned on. + * Return true if Bluetooth is currently enabled and ready for use. + * <p>Equivalent to: + * <code>getBluetoothState() == STATE_ON</code> + * <p>Requires {@link android.Manifest.permission#BLUETOOTH} * - * @return true if Bluetooth enabled, false otherwise. - * @hide + * @return true if the local adapter is turned on */ public boolean isEnabled() { try { @@ -118,28 +200,40 @@ public final class BluetoothAdapter { } /** - * Get the current state of Bluetooth. + * Get the current state of the local Bluetooth adapter. + * <p>Possible return values are + * {@link #STATE_OFF}, + * {@link #STATE_TURNING_ON}, + * {@link #STATE_ON}, + * {@link #STATE_TURNING_OFF}. + * <p>Requires {@link android.Manifest.permission#BLUETOOTH} * - * @return One of BLUETOOTH_STATE_ or BluetoothError.ERROR. - * @hide + * @return current state of Bluetooth adapter */ - public int getBluetoothState() { + public int getState() { try { return mService.getBluetoothState(); } catch (RemoteException e) {Log.e(TAG, "", e);} - return BluetoothError.ERROR; + return STATE_OFF; } /** - * Enable the Bluetooth device. - * Turn on the underlying hardware. - * This is an asynchronous call, - * BluetoothIntent.BLUETOOTH_STATE_CHANGED_ACTION can be used to check if - * and when the device is sucessfully enabled. - * @return false if we cannot enable the Bluetooth device. True does not - * imply the device was enabled, it only implies that so far there were no - * problems. - * @hide + * Turn on the local Bluetooth adapter. + * <p>This powers on the underlying Bluetooth hardware, and starts all + * Bluetooth system services. + * <p>This is an asynchronous call: it will return immediatley, and + * clients should listen for {@link #ACTION_STATE_CHANGED} + * to be notified of subsequent adapter state changes. If this call returns + * true, then the adapter state will immediately transition from {@link + * #STATE_OFF} to {@link #STATE_TURNING_ON}, and some time + * later transition to either {@link #STATE_OFF} or {@link + * #STATE_ON}. If this call returns false then there was an + * immediate problem that will prevent the adapter from being turned on - + * such as Airplane mode, or the adapter is already turned on. + * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN} + * + * @return true to indicate adapter startup has begun, or false on + * immediate error */ public boolean enable() { try { @@ -149,11 +243,22 @@ public final class BluetoothAdapter { } /** - * Disable the Bluetooth device. - * This turns off the underlying hardware. + * Turn off the local Bluetooth adapter. + * <p>This gracefully shuts down all Bluetooth connections, stops Bluetooth + * system services, and powers down the underlying Bluetooth hardware. + * <p>This is an asynchronous call: it will return immediatley, and + * clients should listen for {@link #ACTION_STATE_CHANGED} + * to be notified of subsequent adapter state changes. If this call returns + * true, then the adapter state will immediately transition from {@link + * #STATE_ON} to {@link #STATE_TURNING_OFF}, and some time + * later transition to either {@link #STATE_OFF} or {@link + * #STATE_ON}. If this call returns false then there was an + * immediate problem that will prevent the adapter from being turned off - + * such as the adapter already being turned off. + * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN} * - * @return true if successful, false otherwise. - * @hide + * @return true to indicate adapter shutdown has begun, or false on + * immediate error */ public boolean disable() { try { @@ -162,7 +267,13 @@ public final class BluetoothAdapter { return false; } - /** @hide */ + /** + * Returns the hardware address of the local Bluetooth adapter. + * <p>For example, "00:11:22:AA:BB:CC". + * <p>Requires {@link android.Manifest.permission#BLUETOOTH} + * + * @return Bluetooth hardware address as string + */ public String getAddress() { try { return mService.getAddress(); @@ -171,13 +282,11 @@ public final class BluetoothAdapter { } /** - * Get the friendly Bluetooth name of this device. - * - * This name is visible to remote Bluetooth devices. Currently it is only - * possible to retrieve the Bluetooth name when Bluetooth is enabled. + * Get the friendly Bluetooth name of the local Bluetooth adapter. + * <p>This name is visible to remote Bluetooth devices. + * <p>Requires {@link android.Manifest.permission#BLUETOOTH} * - * @return the Bluetooth name, or null if there was a problem. - * @hide + * @return the Bluetooth name, or null on error */ public String getName() { try { @@ -187,14 +296,15 @@ public final class BluetoothAdapter { } /** - * Set the friendly Bluetooth name of this device. - * - * This name is visible to remote Bluetooth devices. The Bluetooth Service - * is responsible for persisting this name. + * Set the friendly Bluetooth name of the local Bluetoth adapter. + * <p>This name is visible to remote Bluetooth devices. + * <p>Valid Bluetooth names are a maximum of 248 UTF-8 characters, however + * many remote devices can only display the first 40 characters, and some + * may be limited to just 20. + * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN} * - * @param name the name to set - * @return true, if the name was successfully set. False otherwise. - * @hide + * @param name a valid Bluetooth name + * @return true if the name was set, false otherwise */ public boolean setName(String name) { try { @@ -204,28 +314,46 @@ public final class BluetoothAdapter { } /** - * Get the current scan mode. - * Used to determine if the local device is connectable and/or discoverable - * @return Scan mode, one of SCAN_MODE_* or an error code - * @hide + * Get the current Bluetooth scan mode of the local Bluetooth adaper. + * <p>The Bluetooth scan mode determines if the local adapter is + * connectable and/or discoverable from remote Bluetooth devices. + * <p>Possible values are: + * {@link #SCAN_MODE_NONE}, + * {@link #SCAN_MODE_CONNECTABLE}, + * {@link #SCAN_MODE_CONNECTABLE_DISCOVERABLE}. + * <p>Requires {@link android.Manifest.permission#BLUETOOTH} + * + * @return scan mode */ public int getScanMode() { try { return mService.getScanMode(); } catch (RemoteException e) {Log.e(TAG, "", e);} - return BluetoothError.ERROR_IPC; + return SCAN_MODE_NONE; } /** - * Set the current scan mode. - * Used to make the local device connectable and/or discoverable - * @param scanMode One of SCAN_MODE_* - * @hide + * Set the Bluetooth scan mode of the local Bluetooth adapter. + * <p>The Bluetooth scan mode determines if the local adapter is + * connectable and/or discoverable from remote Bluetooth devices. + * <p>For privacy reasons, it is recommended to limit the duration of time + * that the local adapter remains in a discoverable scan mode. For example, + * 2 minutes is a generous time to allow a remote Bluetooth device to + * initiate and complete its discovery process. + * <p>Valid scan mode values are: + * {@link #SCAN_MODE_NONE}, + * {@link #SCAN_MODE_CONNECTABLE}, + * {@link #SCAN_MODE_CONNECTABLE_DISCOVERABLE}. + * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN} + * + * @param mode valid scan mode + * @return true if the scan mode was set, false otherwise */ - public void setScanMode(int scanMode) { + public boolean setScanMode(int mode) { try { - mService.setScanMode(scanMode); + return mService.setScanMode(mode); } catch (RemoteException e) {Log.e(TAG, "", e);} + return false; } /** @hide */ diff --git a/core/java/android/bluetooth/BluetoothDevice.java b/core/java/android/bluetooth/BluetoothDevice.java index 1b7011c..7086557 100644 --- a/core/java/android/bluetooth/BluetoothDevice.java +++ b/core/java/android/bluetooth/BluetoothDevice.java @@ -193,9 +193,9 @@ public final class BluetoothDevice implements Parcelable { * <p>The local adapter will automatically retrieve remote names when * performing a device scan, and will cache them. This method just returns * the name for this device from the cache. + * <p>Requires {@link android.Manifest.permission#BLUETOOTH} * * @return the Bluetooth name, or null if there was a problem. - * @hide */ public String getName() { try { @@ -358,6 +358,7 @@ public final class BluetoothDevice implements Parcelable { * connection. * <p>Valid RFCOMM channels are in range 1 to 30. * <p>Requires {@link android.Manifest.permission#BLUETOOTH} + * * @param channel RFCOMM channel to connect to * @return a RFCOMM BluetoothServerSocket ready for an outgoing connection * @throws IOException on error, for example Bluetooth not available, or diff --git a/core/java/android/bluetooth/BluetoothError.java b/core/java/android/bluetooth/BluetoothError.java index 2554bea..81c1ce9 100644 --- a/core/java/android/bluetooth/BluetoothError.java +++ b/core/java/android/bluetooth/BluetoothError.java @@ -21,6 +21,8 @@ package android.bluetooth; * * Errors are always negative. * + * TODO: Deprecate this class. + * * @hide */ public class BluetoothError { diff --git a/core/java/android/bluetooth/BluetoothIntent.java b/core/java/android/bluetooth/BluetoothIntent.java index c39bc3d..8de19f5 100644 --- a/core/java/android/bluetooth/BluetoothIntent.java +++ b/core/java/android/bluetooth/BluetoothIntent.java @@ -20,17 +20,12 @@ import android.annotation.SdkConstant; import android.annotation.SdkConstant.SdkConstantType; /** - * The Android Bluetooth API is not finalized, and *will* change. Use at your - * own risk. - * - * Manages the local Bluetooth device. Scan for devices, create bondings, - * power up and down the adapter. + * Bluetooth API constants. * + * TODO: Deprecate this class * @hide */ public interface BluetoothIntent { - public static final String SCAN_MODE = - "android.bluetooth.intent.SCAN_MODE"; public static final String DEVICE = "android.bluetooth.intent.DEVICE"; public static final String NAME = @@ -41,10 +36,6 @@ public interface BluetoothIntent { "android.bluetooth.intent.RSSI"; public static final String CLASS = "android.bluetooth.intent.CLASS"; - public static final String BLUETOOTH_STATE = - "android.bluetooth.intent.BLUETOOTH_STATE"; - public static final String BLUETOOTH_PREVIOUS_STATE = - "android.bluetooth.intent.BLUETOOTH_PREVIOUS_STATE"; public static final String HEADSET_STATE = "android.bluetooth.intent.HEADSET_STATE"; public static final String HEADSET_PREVIOUS_STATE = @@ -91,25 +82,10 @@ public interface BluetoothIntent { public static final String DEVICE_PICKER_DEVICE_PICKER = "android.bluetooth.intent.action.DEVICE_PICKER"; - /** Broadcast when the local Bluetooth device state changes, for example - * when Bluetooth is enabled. Will contain int extra's BLUETOOTH_STATE and - * BLUETOOTH_PREVIOUS_STATE. */ - @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) - public static final String BLUETOOTH_STATE_CHANGED_ACTION = - "android.bluetooth.intent.action.BLUETOOTH_STATE_CHANGED"; - @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) public static final String NAME_CHANGED_ACTION = "android.bluetooth.intent.action.NAME_CHANGED"; - /** - * Broadcast when the scan mode changes. Always contains an int extra - * named SCAN_MODE that contains the new scan mode. - */ - @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) - public static final String SCAN_MODE_CHANGED_ACTION = - "android.bluetooth.intent.action.SCAN_MODE_CHANGED"; - @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) public static final String DISCOVERY_STARTED_ACTION = "android.bluetooth.intent.action.DISCOVERY_STARTED"; |