android.bluetooth
Class BluetoothDevice

java.lang.Object
  android.bluetooth.BluetoothDevice

public class BluetoothDevice
extends Object

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.

Field Summary

static int	MODE_CONNECTABLE
static int	MODE_DISCOVERABLE
static int	MODE_OFF
static int	MODE_UNKNOWN
static int	RESULT_FAILURE
static int	RESULT_SUCCESS

Constructor Summary

BluetoothDevice(IBluetoothDevice service)

Method Summary

boolean	cancelBondingProcess(String address)
void	cancelDiscovery()
boolean	cancelPin(String address)
static boolean	checkBluetoothAddress(String address)
boolean	clearRemoteAlias(String address)
static byte[]	convertPinToBytes(String pin) Check that a pin is valid and convert to byte array.
boolean	createBonding(String address) Create a bonding with a remote bluetooth device.
boolean	createBonding(String address, IBluetoothDeviceCallback callback) Create a bonding with a remote bluetooth device.
boolean	disable() Disable the Bluetooth device.
boolean	disconnectRemoteDeviceAcl(String address) Perform a low level (ACL) disconnection of a remote device.
boolean	enable() Enable the Bluetooth device.
boolean	enable(IBluetoothDeviceCallback callback) Enable the Bluetooth device.
String	getAddress()
String	getCompany()
int	getDiscoverableTimeout()
String	getMajorClass()
String	getManufacturer()
String	getMinorClass()
int	getMode()
String	getName() Get the friendly Bluetooth name of this device.
String	getRemoteAlias(String address)
int	getRemoteClass(String address)
String	getRemoteCompany(String address)
byte[]	getRemoteFeatures(String address)
String	getRemoteMajorClass(String address)
String	getRemoteManufacturer(String address)
String	getRemoteMinorClass(String address)
String	getRemoteName(String address)
String	getRemoteRevision(String address)
boolean	getRemoteServiceChannel(String address, short uuid16, IBluetoothDeviceCallback callback) Returns the RFCOMM channel associated with the 16-byte UUID on the remote Bluetooth address.
String[]	getRemoteServiceClasses(String address)
String	getRemoteVersion(String address)
String	getRevision()
String	getVersion()
boolean	hasBonding(String address) Check if a remote device is bonded (paired) to the local device.
boolean	isAclConnected(String address) Check if a specified remote device has a low level (ACL) connection.
boolean	isDiscovering()
boolean	isEnabled() Get the current status of Bluetooth hardware.
boolean	isPeriodicDiscovery()
String	lastSeen(String address)
String	lastUsed(String address)
String[]	listAclConnections() List remote devices that have a low level (ACL) connection.
String[]	listBondings() List remote devices that are bonded (paired) to the local device.
String[]	listRemoteDevices()
boolean	removeBonding(String address)
void	setDiscoverableTimeout(int timeout)
void	setMode(int mode)
boolean	setName(String name) Set the friendly Bluetooth name of this device.
boolean	setPin(String address, byte[] pin)
boolean	setRemoteAlias(String address, String alias)
boolean	startDiscovery()
boolean	startDiscovery(boolean resolveNames)
boolean	startPeriodicDiscovery()
boolean	stopPeriodicDiscovery()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MODE_UNKNOWN

public static final int MODE_UNKNOWN

See Also:

Constant Field Values

MODE_OFF

public static final int MODE_OFF

See Also:

Constant Field Values

MODE_CONNECTABLE

public static final int MODE_CONNECTABLE

See Also:

Constant Field Values

MODE_DISCOVERABLE

public static final int MODE_DISCOVERABLE

See Also:

Constant Field Values

RESULT_FAILURE

public static final int RESULT_FAILURE

See Also:

Constant Field Values

RESULT_SUCCESS

public static final int RESULT_SUCCESS

See Also:

Constant Field Values

Constructor Detail

BluetoothDevice

public BluetoothDevice(IBluetoothDevice service)

Method Detail

isEnabled

public boolean isEnabled()

Get the current status of Bluetooth hardware.

Returns:

true if Bluetooth enabled, false otherwise.

enable

public boolean enable()

Enable the Bluetooth device. Turn on the underlying hardware. This is an asynchronous call, BluetoothIntent.ENABLED_ACTION will be sent if and when the device is successfully enabled.

Returns:

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.

enable

public boolean enable(IBluetoothDeviceCallback callback)

Enable the Bluetooth device. Turns on the underlying hardware. This is an asynchronous call. onEnableResult() of your callback will be called when the call is complete, with either RESULT_SUCCESS or RESULT_FAILURE. Your callback will be called from a binder thread, not the main thread. In addition to the callback, BluetoothIntent.ENABLED_ACTION will be broadcast if the device is successfully enabled.

Parameters:

callback - Your callback, null is ok.

Returns:

true if your callback was successfully registered, or false if there was an error, implying your callback will never be called.

disable

public boolean disable()

Disable the Bluetooth device. This turns off the underlying hardware.

Returns:

true if successful, false otherwise.

getAddress

public String getAddress()

getName

public String getName()

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.

Returns:

the Bluetooth name, or null if there was a problem.

setName

public boolean setName(String name)

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.

Parameters:

name - the name to set

Returns:

true, if the name was successfully set. False otherwise.

getMajorClass

public String getMajorClass()

getMinorClass

public String getMinorClass()

getVersion

public String getVersion()

getRevision

public String getRevision()

getManufacturer

public String getManufacturer()

getCompany

public String getCompany()

getMode

public int getMode()

setMode

public void setMode(int mode)

getDiscoverableTimeout

public int getDiscoverableTimeout()

setDiscoverableTimeout

public void setDiscoverableTimeout(int timeout)

startDiscovery

public boolean startDiscovery()

startDiscovery

public boolean startDiscovery(boolean resolveNames)

cancelDiscovery

public void cancelDiscovery()

isDiscovering

public boolean isDiscovering()

startPeriodicDiscovery

public boolean startPeriodicDiscovery()

stopPeriodicDiscovery

public boolean stopPeriodicDiscovery()

isPeriodicDiscovery

public boolean isPeriodicDiscovery()

listRemoteDevices

public String[] listRemoteDevices()

listAclConnections

public String[] listAclConnections()

List remote devices that have a low level (ACL) connection. RFCOMM, SDP and L2CAP are all built on ACL connections. Devices can have an ACL connection even when not paired - this is common for SDP queries or for in-progress pairing requests. In most cases you probably want to test if a higher level protocol is connected, rather than testing ACL connections.

Returns:

bluetooth hardware addresses of remote devices with a current ACL connection. Array size is 0 if no devices have a connection. Null on error.

isAclConnected

public boolean isAclConnected(String address)

Check if a specified remote device has a low level (ACL) connection. RFCOMM, SDP and L2CAP are all built on ACL connections. Devices can have an ACL connection even when not paired - this is common for SDP queries or for in-progress pairing requests. In most cases you probably want to test if a higher level protocol is connected, rather than testing ACL connections.

Parameters:

address - the Bluetooth hardware address you want to check.

Returns:

true if there is an ACL connection, false otherwise and on error.

disconnectRemoteDeviceAcl

public boolean disconnectRemoteDeviceAcl(String address)

Perform a low level (ACL) disconnection of a remote device. This forcably disconnects the ACL layer connection to a remote device, which will cause all RFCOMM, SDP and L2CAP connections to this remote device to close.

Parameters:

address - the Bluetooth hardware address you want to disconnect.

Returns:

true if the device was disconnected, false otherwise and on error.

createBonding

public boolean createBonding(String address)

Create a bonding with a remote bluetooth device. This is an asynchronous call. BluetoothIntent.BONDING_CREATED_ACTION will be broadcast if and when the remote device is successfully bonded.

Parameters:

address - the remote device Bluetooth address.

Returns:

false if we cannot create a bonding to that device, true if there were no problems beginning the bonding process.

createBonding

public boolean createBonding(String address,
                             IBluetoothDeviceCallback callback)

Create a bonding with a remote bluetooth device. This is an asynchronous call. onCreateBondingResult() of your callback will be called when the call is complete, with either RESULT_SUCCESS or RESULT_FAILURE. In addition to the callback, BluetoothIntent.BONDING_CREATED_ACTION will be broadcast if the remote device is successfully bonded.

Parameters:

address - The remote device Bluetooth address.

callback - Your callback, null is ok.

Returns:

true if your callback was successfully registered, or false if there was an error, implying your callback will never be called.

cancelBondingProcess

public boolean cancelBondingProcess(String address)

listBondings

public String[] listBondings()

List remote devices that are bonded (paired) to the local device. Bonding (pairing) is the process by which the user enters a pin code for the device, which generates a shared link key, allowing for authentication and encryption of future connections. In Android we require bonding before RFCOMM or SCO connections can be made to a remote device. This function lists which remote devices we have a link key for. It does not cause any RF transmission, and does not check if the remote device still has it's link key with us. If the other side no longer has its link key then the RFCOMM or SCO connection attempt will result in an error. This function does not check if the remote device is in range.

Returns:

bluetooth hardware addresses of remote devices that are bonded. Array size is 0 if no devices are bonded. Null on error.

hasBonding

public boolean hasBonding(String address)

Check if a remote device is bonded (paired) to the local device. Bonding (pairing) is the process by which the user enters a pin code for the device, which generates a shared link key, allowing for authentication and encryption of future connections. In Android we require bonding before RFCOMM or SCO connections can be made to a remote device. This function checks if we have a link key with the remote device. It does not cause any RF transmission, and does not check if the remote device still has it's link key with us. If the other side no longer has a link key then the RFCOMM or SCO connection attempt will result in an error. This function does not check if the remote device is in range.

Parameters:

address - Bluetooth hardware address of the remote device to check.

Returns:

true if bonded, false otherwise and on error.

removeBonding

public boolean removeBonding(String address)

getRemoteName

public String getRemoteName(String address)

getRemoteAlias

public String getRemoteAlias(String address)

setRemoteAlias

public boolean setRemoteAlias(String address,
                              String alias)

clearRemoteAlias

public boolean clearRemoteAlias(String address)

getRemoteVersion

public String getRemoteVersion(String address)

getRemoteRevision

public String getRemoteRevision(String address)

getRemoteManufacturer

public String getRemoteManufacturer(String address)

getRemoteCompany

public String getRemoteCompany(String address)

getRemoteMajorClass

public String getRemoteMajorClass(String address)

getRemoteMinorClass

public String getRemoteMinorClass(String address)

getRemoteServiceClasses

public String[] getRemoteServiceClasses(String address)

getRemoteServiceChannel

public boolean getRemoteServiceChannel(String address,
                                       short uuid16,
                                       IBluetoothDeviceCallback callback)

Returns the RFCOMM channel associated with the 16-byte UUID on the remote Bluetooth address. Performs a SDP ServiceSearchAttributeRequest transaction. The provided uuid is verified in the returned record. If there was a problem, or the specified uuid does not exist, -1 is returned.

getRemoteClass

public int getRemoteClass(String address)

getRemoteFeatures

public byte[] getRemoteFeatures(String address)

lastSeen

public String lastSeen(String address)

lastUsed

public String lastUsed(String address)

setPin

public boolean setPin(String address,
                      byte[] pin)

cancelPin

public boolean cancelPin(String address)

convertPinToBytes

public static byte[] convertPinToBytes(String pin)

Check that a pin is valid and convert to byte array. Bluetooth pin's are 1 to 16 bytes of UTF8 characters.

Parameters:

pin - pin as java String

Returns:

the pin code as a UTF8 byte array, or null if it is an invalid Bluetooth pin.

checkBluetoothAddress

public static boolean checkBluetoothAddress(String address)