public final class

BluetoothAdapter

extends Object
java.lang.Object
   ↳ android.bluetooth.BluetoothAdapter

Class Overview

Represents the local device Bluetooth adapter. The BluetoothAdapter lets you perform fundamental Bluetooth tasks, such as initiate device discovery, query a list of bonded (paired) devices, instantiate a BluetoothDevice using a known MAC address, and create a BluetoothServerSocket to listen for connection requests from other devices.

To get a BluetoothAdapter representing the local Bluetooth adapter, call the static getDefaultAdapter() method. Fundamentally, this is your starting point for all Bluetooth actions. Once you have the local adapter, you can get a set of BluetoothDevice objects representing all paired devices with getBondedDevices(); start device discovery with startDiscovery(); or create a BluetoothServerSocket to listen for incoming connection requests with listenUsingRfcommWithServiceRecord(String, UUID).

Note: Most methods require the BLUETOOTH permission and some also require the BLUETOOTH_ADMIN permission.

Summary

Constants
String ACTION_DISCOVERY_FINISHED Broadcast Action: The local Bluetooth adapter has finished the device discovery process.
String ACTION_DISCOVERY_STARTED Broadcast Action: The local Bluetooth adapter has started the remote device discovery process.
String ACTION_LOCAL_NAME_CHANGED Broadcast Action: The local Bluetooth adapter has changed its friendly Bluetooth name.
String ACTION_REQUEST_DISCOVERABLE Activity Action: Show a system activity that requests discoverable mode.
String ACTION_REQUEST_ENABLE Activity Action: Show a system activity that allows the user to turn on Bluetooth.
String ACTION_SCAN_MODE_CHANGED Broadcast Action: Indicates the Bluetooth scan mode of the local Adapter has changed.
String ACTION_STATE_CHANGED Broadcast Action: The state of the local Bluetooth adapter has been changed.
int ERROR Sentinel error value for this class.
String EXTRA_DISCOVERABLE_DURATION Used as an optional int extra field in ACTION_REQUEST_DISCOVERABLE intents to request a specific duration for discoverability in seconds.
String EXTRA_LOCAL_NAME Used as a String extra field in ACTION_LOCAL_NAME_CHANGED intents to request the local Bluetooth name.
String EXTRA_PREVIOUS_SCAN_MODE Used as an int extra field in ACTION_SCAN_MODE_CHANGED intents to request the previous scan mode.
String EXTRA_PREVIOUS_STATE Used as an int extra field in ACTION_STATE_CHANGED intents to request the previous power state.
String EXTRA_SCAN_MODE Used as an int extra field in ACTION_SCAN_MODE_CHANGED intents to request the current scan mode.
String EXTRA_STATE Used as an int extra field in ACTION_STATE_CHANGED intents to request the current power state.
int SCAN_MODE_CONNECTABLE Indicates that inquiry scan is disabled, but page scan is enabled on the local Bluetooth adapter.
int SCAN_MODE_CONNECTABLE_DISCOVERABLE Indicates that both inquiry scan and page scan are enabled on the local Bluetooth adapter.
int SCAN_MODE_NONE Indicates that both inquiry scan and page scan are disabled on the local Bluetooth adapter.
int STATE_OFF Indicates the local Bluetooth adapter is off.
int STATE_ON Indicates the local Bluetooth adapter is on, and ready for use.
int STATE_TURNING_OFF Indicates the local Bluetooth adapter is turning off.
int STATE_TURNING_ON Indicates the local Bluetooth adapter is turning on.
Public Methods
boolean cancelDiscovery()
Cancel the current device discovery process.
static boolean checkBluetoothAddress(String address)
Validate a Bluetooth address, such as "00:43:A8:23:10:F0"

Alphabetic characters must be uppercase to be valid.

boolean disable()
Turn off the local Bluetooth adapter—do not use without explicit user action to turn off Bluetooth.
boolean enable()
Turn on the local Bluetooth adapter—do not use without explicit user action to turn on Bluetooth.
String getAddress()
Returns the hardware address of the local Bluetooth adapter.
Set<BluetoothDevice> getBondedDevices()
Return the set of BluetoothDevice objects that are bonded (paired) to the local adapter.
synchronized static BluetoothAdapter getDefaultAdapter()
Get a handle to the default local Bluetooth adapter.
String getName()
Get the friendly Bluetooth name of the local Bluetooth adapter.
BluetoothDevice getRemoteDevice(String address)
Get a BluetoothDevice object for the given Bluetooth hardware address.
int getScanMode()
Get the current Bluetooth scan mode of the local Bluetooth adapter.
int getState()
Get the current state of the local Bluetooth adapter.
boolean isDiscovering()
Return true if the local Bluetooth adapter is currently in the device discovery process.
boolean isEnabled()
Return true if Bluetooth is currently enabled and ready for use.
BluetoothServerSocket listenUsingInsecureRfcommWithServiceRecord(String name, UUID uuid)
Create a listening, insecure RFCOMM Bluetooth socket with Service Record.
BluetoothServerSocket listenUsingRfcommWithServiceRecord(String name, UUID uuid)
Create a listening, secure RFCOMM Bluetooth socket with Service Record.
boolean setName(String name)
Set the friendly Bluetooth name of the local Bluetooth adapter.
boolean startDiscovery()
Start the remote device discovery process.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String ACTION_DISCOVERY_FINISHED

Since: API Level 5

Broadcast Action: The local Bluetooth adapter has finished the device discovery process.

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.adapter.action.DISCOVERY_FINISHED"

public static final String ACTION_DISCOVERY_STARTED

Since: API Level 5

Broadcast Action: The local Bluetooth adapter has started the remote device discovery process.

This usually involves an inquiry scan of about 12 seconds, followed by a page scan of each new device to retrieve its Bluetooth name.

Register for ACTION_FOUND to be notified as remote Bluetooth devices are found.

Device discovery is a heavyweight procedure. New connections to remote Bluetooth devices should not be attempted while discovery is in progress, and existing connections will experience limited bandwidth and high latency. Use cancelDiscovery() to cancel an ongoing discovery.

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.adapter.action.DISCOVERY_STARTED"

public static final String ACTION_LOCAL_NAME_CHANGED

Since: API Level 5

Broadcast Action: The local Bluetooth adapter has changed its friendly Bluetooth name.

This name is visible to remote Bluetooth devices.

Always contains the extra field EXTRA_LOCAL_NAME containing the name.

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.adapter.action.LOCAL_NAME_CHANGED"

public static final String ACTION_REQUEST_DISCOVERABLE

Since: API Level 5

Activity Action: Show a system activity that requests discoverable mode. This activity will also request the user to turn on Bluetooth if it is not currently enabled.

Discoverable mode is equivalent to SCAN_MODE_CONNECTABLE_DISCOVERABLE. It allows remote devices to see this Bluetooth adapter when they perform a discovery.

For privacy, Android is not discoverable by default.

The sender of this Intent can optionally use extra field EXTRA_DISCOVERABLE_DURATION to request the duration of discoverability. Currently the default duration is 120 seconds, and maximum duration is capped at 300 seconds for each request.

Notification of the result of this activity is posted using the onActivityResult(int, int, Intent) callback. The resultCode will be the duration (in seconds) of discoverability or RESULT_CANCELED if the user rejected discoverability or an error has occurred.

Applications can also listen for ACTION_SCAN_MODE_CHANGED for global notification whenever the scan mode changes. For example, an application can be notified when the device has ended discoverability.

Requires BLUETOOTH

Constant Value: "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE"

public static final String ACTION_REQUEST_ENABLE

Since: API Level 5

Activity Action: Show a system activity that allows the user to turn on Bluetooth.

This system activity will return once Bluetooth has completed turning on, or the user has decided not to turn Bluetooth on.

Notification of the result of this activity is posted using the onActivityResult(int, int, Intent) callback. The resultCode will be RESULT_OK if Bluetooth has been turned on or RESULT_CANCELED if the user has rejected the request or an error has occurred.

Applications can also listen for ACTION_STATE_CHANGED for global notification whenever Bluetooth is turned on or off.

Requires BLUETOOTH

Constant Value: "android.bluetooth.adapter.action.REQUEST_ENABLE"

public static final String ACTION_SCAN_MODE_CHANGED

Since: API Level 5

Broadcast Action: Indicates the Bluetooth scan mode of the local Adapter has changed.

Always contains the extra fields EXTRA_SCAN_MODE and EXTRA_PREVIOUS_SCAN_MODE containing the new and old scan modes respectively.

Requires BLUETOOTH

Constant Value: "android.bluetooth.adapter.action.SCAN_MODE_CHANGED"

public static final String ACTION_STATE_CHANGED

Since: API Level 5

Broadcast Action: The state of the local Bluetooth adapter has been changed.

For example, Bluetooth has been turned on or off.

Always contains the extra fields EXTRA_STATE and EXTRA_PREVIOUS_STATE containing the new and old states respectively.

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.adapter.action.STATE_CHANGED"

public static final int ERROR

Since: API Level 5

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:

Intent.getIntExtra(BluetoothAdapter.EXTRA_STATE, BluetoothAdapter.ERROR)

Constant Value: -2147483648 (0x80000000)

public static final String EXTRA_DISCOVERABLE_DURATION

Since: API Level 5

Used as an optional int extra field in ACTION_REQUEST_DISCOVERABLE intents to request a specific duration for discoverability in seconds. The current default is 120 seconds, and requests over 300 seconds will be capped. These values could change.

Constant Value: "android.bluetooth.adapter.extra.DISCOVERABLE_DURATION"

public static final String EXTRA_LOCAL_NAME

Since: API Level 5

Used as a String extra field in ACTION_LOCAL_NAME_CHANGED intents to request the local Bluetooth name.

Constant Value: "android.bluetooth.adapter.extra.LOCAL_NAME"

public static final String EXTRA_PREVIOUS_SCAN_MODE

Since: API Level 5

Used as an int extra field in ACTION_SCAN_MODE_CHANGED intents to request the previous scan mode. Possible values are: SCAN_MODE_NONE, SCAN_MODE_CONNECTABLE, SCAN_MODE_CONNECTABLE_DISCOVERABLE,

Constant Value: "android.bluetooth.adapter.extra.PREVIOUS_SCAN_MODE"

public static final String EXTRA_PREVIOUS_STATE

Since: API Level 5

Used as an int extra field in ACTION_STATE_CHANGED intents to request the previous power state. Possible values are: STATE_OFF, STATE_TURNING_ON, STATE_ON, STATE_TURNING_OFF,

Constant Value: "android.bluetooth.adapter.extra.PREVIOUS_STATE"

public static final String EXTRA_SCAN_MODE

Since: API Level 5

Used as an int extra field in ACTION_SCAN_MODE_CHANGED intents to request the current scan mode. Possible values are: SCAN_MODE_NONE, SCAN_MODE_CONNECTABLE, SCAN_MODE_CONNECTABLE_DISCOVERABLE,

Constant Value: "android.bluetooth.adapter.extra.SCAN_MODE"

public static final String EXTRA_STATE

Since: API Level 5

Used as an int extra field in ACTION_STATE_CHANGED intents to request the current power state. Possible values are: STATE_OFF, STATE_TURNING_ON, STATE_ON, STATE_TURNING_OFF,

Constant Value: "android.bluetooth.adapter.extra.STATE"

public static final int SCAN_MODE_CONNECTABLE

Since: API Level 5

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.

Constant Value: 21 (0x00000015)

public static final int SCAN_MODE_CONNECTABLE_DISCOVERABLE

Since: API Level 5

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.

Constant Value: 23 (0x00000017)

public static final int SCAN_MODE_NONE

Since: API Level 5

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.

Constant Value: 20 (0x00000014)

public static final int STATE_OFF

Since: API Level 5

Indicates the local Bluetooth adapter is off.

Constant Value: 10 (0x0000000a)

public static final int STATE_ON

Since: API Level 5

Indicates the local Bluetooth adapter is on, and ready for use.

Constant Value: 12 (0x0000000c)

public static final int STATE_TURNING_OFF

Since: API Level 5

Indicates the local Bluetooth adapter is turning off. Local clients should immediately attempt graceful disconnection of any remote links.

Constant Value: 13 (0x0000000d)

public static final int STATE_TURNING_ON

Since: API Level 5

Indicates the local Bluetooth adapter is turning on. However local clients should wait for STATE_ON before attempting to use the adapter.

Constant Value: 11 (0x0000000b)

Public Methods

public boolean cancelDiscovery ()

Since: API Level 5

Cancel the current device discovery process.

Requires BLUETOOTH_ADMIN.

Because discovery is a heavyweight procedure for the Bluetooth adapter, this method should always be called before attempting to connect to a remote device with connect(). Discovery is not managed by the Activity, but is run as a system service, so an application should always call cancel discovery even if it did not directly request a discovery, just to be sure.

If Bluetooth state is not STATE_ON, this API will return false. After turning on Bluetooth, wait for ACTION_STATE_CHANGED with STATE_ON to get the updated value.

Returns
  • true on success, false on error

public static boolean checkBluetoothAddress (String address)

Since: API Level 5

Validate a Bluetooth address, such as "00:43:A8:23:10:F0"

Alphabetic characters must be uppercase to be valid.

Parameters
address Bluetooth address as string
Returns
  • true if the address is valid, false otherwise

public boolean disable ()

Since: API Level 5

Turn off the local Bluetooth adapter—do not use without explicit user action to turn off Bluetooth.

This gracefully shuts down all Bluetooth connections, stops Bluetooth system services, and powers down the underlying Bluetooth hardware.

Bluetooth should never be disabled without direct user consent. The disable() method is provided only for applications that include a user interface for changing system settings, such as a "power manager" app.

This is an asynchronous call: it will return immediately, and clients should listen for ACTION_STATE_CHANGED to be notified of subsequent adapter state changes. If this call returns true, then the adapter state will immediately transition from STATE_ON to STATE_TURNING_OFF, and some time later transition to either STATE_OFF or 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.

Requires the BLUETOOTH_ADMIN permission

Returns
  • true to indicate adapter shutdown has begun, or false on immediate error

public boolean enable ()

Since: API Level 5

Turn on the local Bluetooth adapter—do not use without explicit user action to turn on Bluetooth.

This powers on the underlying Bluetooth hardware, and starts all Bluetooth system services.

Bluetooth should never be enabled without direct user consent. If you want to turn on Bluetooth in order to create a wireless connection, you should use the ACTION_REQUEST_ENABLE Intent, which will raise a dialog that requests user permission to turn on Bluetooth. The enable() method is provided only for applications that include a user interface for changing system settings, such as a "power manager" app.

This is an asynchronous call: it will return immediately, and clients should listen for ACTION_STATE_CHANGED to be notified of subsequent adapter state changes. If this call returns true, then the adapter state will immediately transition from STATE_OFF to STATE_TURNING_ON, and some time later transition to either STATE_OFF or 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.

Requires the BLUETOOTH_ADMIN permission

Returns
  • true to indicate adapter startup has begun, or false on immediate error

public String getAddress ()

Since: API Level 5

Returns the hardware address of the local Bluetooth adapter.

For example, "00:11:22:AA:BB:CC".

Requires BLUETOOTH

Returns
  • Bluetooth hardware address as string

public Set<BluetoothDevice> getBondedDevices ()

Since: API Level 5

Return the set of BluetoothDevice objects that are bonded (paired) to the local adapter.

If Bluetooth state is not STATE_ON, this API will return an empty set. After turning on Bluetooth, wait for ACTION_STATE_CHANGED with STATE_ON to get the updated value.

Requires BLUETOOTH.

Returns

public static synchronized BluetoothAdapter getDefaultAdapter ()

Since: API Level 5

Get a handle to the default local Bluetooth adapter.

Currently Android only supports one Bluetooth adapter, but the API could be extended to support more. This will always return the default adapter.

Returns
  • the default local adapter, or null if Bluetooth is not supported on this hardware platform

public String getName ()

Since: API Level 5

Get the friendly Bluetooth name of the local Bluetooth adapter.

This name is visible to remote Bluetooth devices.

Requires BLUETOOTH

Returns
  • the Bluetooth name, or null on error

public BluetoothDevice getRemoteDevice (String address)

Since: API Level 5

Get a BluetoothDevice object for the given Bluetooth hardware address.

Valid Bluetooth hardware addresses must be upper case, in a format such as "00:11:22:33:AA:BB". The helper checkBluetoothAddress(String) is available to validate a Bluetooth address.

A BluetoothDevice will always be returned for a valid hardware address, even if this adapter has never seen that device.

Parameters
address valid Bluetooth MAC address
Throws
IllegalArgumentException if address is invalid

public int getScanMode ()

Since: API Level 5

Get the current Bluetooth scan mode of the local Bluetooth adapter.

The Bluetooth scan mode determines if the local adapter is connectable and/or discoverable from remote Bluetooth devices.

Possible values are: SCAN_MODE_NONE, SCAN_MODE_CONNECTABLE, SCAN_MODE_CONNECTABLE_DISCOVERABLE.

If Bluetooth state is not STATE_ON, this API will return SCAN_MODE_NONE. After turning on Bluetooth, wait for ACTION_STATE_CHANGED with STATE_ON to get the updated value.

Requires BLUETOOTH

Returns
  • scan mode

public int getState ()

Since: API Level 5

Get the current state of the local Bluetooth adapter.

Possible return values are STATE_OFF, STATE_TURNING_ON, STATE_ON, STATE_TURNING_OFF.

Requires BLUETOOTH

Returns
  • current state of Bluetooth adapter

public boolean isDiscovering ()

Since: API Level 5

Return true if the local Bluetooth adapter is currently in the device discovery process.

Device discovery is a heavyweight procedure. New connections to remote Bluetooth devices should not be attempted while discovery is in progress, and existing connections will experience limited bandwidth and high latency. Use cancelDiscovery() to cancel an ongoing discovery.

Applications can also register for ACTION_DISCOVERY_STARTED or ACTION_DISCOVERY_FINISHED to be notified when discovery starts or completes.

If Bluetooth state is not STATE_ON, this API will return false. After turning on Bluetooth, wait for ACTION_STATE_CHANGED with STATE_ON to get the updated value.

Requires BLUETOOTH.

Returns
  • true if discovering

public boolean isEnabled ()

Since: API Level 5

Return true if Bluetooth is currently enabled and ready for use.

Equivalent to: getBluetoothState() == STATE_ON

Requires BLUETOOTH

Returns
  • true if the local adapter is turned on

public BluetoothServerSocket listenUsingInsecureRfcommWithServiceRecord (String name, UUID uuid)

Since: API Level 10

Create a listening, insecure RFCOMM Bluetooth socket with Service Record.

The link key will be unauthenticated i.e the communication is vulnerable to Man In the Middle attacks. For Bluetooth 2.1 devices, the link key will be encrypted, as encryption is mandartory. For legacy devices (pre Bluetooth 2.1 devices) the link key will not be encrypted. Use listenUsingRfcommWithServiceRecord(String, UUID), if an encrypted and authenticated communication channel is desired.

Use accept() to retrieve incoming connections from a listening BluetoothServerSocket.

The system will assign an unused RFCOMM channel to listen on.

The system will also register a Service Discovery Protocol (SDP) record with the local SDP server containing the specified UUID, service name, and auto-assigned channel. Remote Bluetooth devices can use the same UUID to query our SDP server and discover which channel to connect to. This SDP record will be removed when this socket is closed, or if this application closes unexpectedly.

Use createRfcommSocketToServiceRecord(UUID) to connect to this socket from another device using the same UUID.

Requires BLUETOOTH

Parameters
name service name for SDP record
uuid uuid for SDP record
Returns
  • a listening RFCOMM BluetoothServerSocket
Throws
IOException on error, for example Bluetooth not available, or insufficient permissions, or channel in use.

public BluetoothServerSocket listenUsingRfcommWithServiceRecord (String name, UUID uuid)

Since: API Level 5

Create a listening, secure RFCOMM Bluetooth socket with Service Record.

A remote device connecting to this socket will be authenticated and communication on this socket will be encrypted.

Use this socket only if an authenticated socket link is possible. Authentication refers to the authentication of the link key to prevent man-in-the-middle type of attacks. For example, for Bluetooth 2.1 devices, if any of the devices does not have an input and output capability or just has the ability to display a numeric key, a secure socket connection is not possible. In such a case, use {#link listenUsingInsecureRfcommWithServiceRecord}. For more details, refer to the Security Model section 5.2 (vol 3) of Bluetooth Core Specification version 2.1 + EDR.

Use accept() to retrieve incoming connections from a listening BluetoothServerSocket.

The system will assign an unused RFCOMM channel to listen on.

The system will also register a Service Discovery Protocol (SDP) record with the local SDP server containing the specified UUID, service name, and auto-assigned channel. Remote Bluetooth devices can use the same UUID to query our SDP server and discover which channel to connect to. This SDP record will be removed when this socket is closed, or if this application closes unexpectedly.

Use createRfcommSocketToServiceRecord(UUID) to connect to this socket from another device using the same UUID.

Requires BLUETOOTH

Parameters
name service name for SDP record
uuid uuid for SDP record
Returns
  • a listening RFCOMM BluetoothServerSocket
Throws
IOException on error, for example Bluetooth not available, or insufficient permissions, or channel in use.

public boolean setName (String name)

Since: API Level 5

Set the friendly Bluetooth name of the local Bluetooth adapter.

This name is visible to remote Bluetooth devices.

Valid Bluetooth names are a maximum of 248 bytes using UTF-8 encoding, although many remote devices can only display the first 40 characters, and some may be limited to just 20.

If Bluetooth state is not STATE_ON, this API will return false. After turning on Bluetooth, wait for ACTION_STATE_CHANGED with STATE_ON to get the updated value.

Requires BLUETOOTH_ADMIN

Parameters
name a valid Bluetooth name
Returns
  • true if the name was set, false otherwise

public boolean startDiscovery ()

Since: API Level 5

Start the remote device discovery process.

The discovery process usually involves an inquiry scan of about 12 seconds, followed by a page scan of each new device to retrieve its Bluetooth name.

This is an asynchronous call, it will return immediately. Register for ACTION_DISCOVERY_STARTED and ACTION_DISCOVERY_FINISHED intents to determine exactly when the discovery starts and completes. Register for ACTION_FOUND to be notified as remote Bluetooth devices are found.

Device discovery is a heavyweight procedure. New connections to remote Bluetooth devices should not be attempted while discovery is in progress, and existing connections will experience limited bandwidth and high latency. Use cancelDiscovery() to cancel an ongoing discovery. Discovery is not managed by the Activity, but is run as a system service, so an application should always call cancelDiscovery() even if it did not directly request a discovery, just to be sure.

Device discovery will only find remote devices that are currently discoverable (inquiry scan enabled). Many Bluetooth devices are not discoverable by default, and need to be entered into a special mode.

If Bluetooth state is not STATE_ON, this API will return false. After turning on Bluetooth, wait for ACTION_STATE_CHANGED with STATE_ON to get the updated value.

Requires BLUETOOTH_ADMIN.

Returns
  • true on success, false on error