FileDocCategorySizeDatePackage
BluetoothDevice.javaAPI DocAndroid 1.5 API19487Wed May 06 22:41:54 BST 2009android.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.
hide

Fields Summary
public static final int
BLUETOOTH_STATE_OFF
public static final int
BLUETOOTH_STATE_TURNING_ON
public static final int
BLUETOOTH_STATE_ON
public static final int
BLUETOOTH_STATE_TURNING_OFF
public static final int
SCAN_MODE_NONE
Inquiry scan and page scan are both off. Device is neither discoverable nor connectable
public static final int
SCAN_MODE_CONNECTABLE
Page scan is on, inquiry scan is off. Device is connectable, but not discoverable
public static final int
SCAN_MODE_CONNECTABLE_DISCOVERABLE
Page scan and inquiry scan are on. Device is connectable and discoverable
public static final int
RESULT_FAILURE
public static final int
RESULT_SUCCESS
public static final int
BOND_NOT_BONDED
We do not have a link key for the remote device, and are therefore not bonded
public static final int
BOND_BONDED
We have a link key for the remote device, and are probably bonded.
public static final int
BOND_BONDING
We are currently attempting bonding
public static final int
UNBOND_REASON_AUTH_FAILED
A bond attempt failed because pins did not match, or remote device did not respond to pin request in time
public static final int
UNBOND_REASON_AUTH_REJECTED
A bond attempt failed because the other side explicilty rejected bonding
public static final int
UNBOND_REASON_AUTH_CANCELED
A bond attempt failed because we canceled the bonding process
public static final int
UNBOND_REASON_REMOTE_DEVICE_DOWN
A bond attempt failed because we could not contact the remote device
public static final int
UNBOND_REASON_DISCOVERY_IN_PROGRESS
A bond attempt failed because a discovery is in progress
public static final int
UNBOND_REASON_REMOVED
An existing bond was explicitly revoked
private static final String
TAG
private final IBluetoothDevice
mService
private static final int
ADDRESS_LENGTH
Constructors Summary
public BluetoothDevice(IBluetoothDevice service)

hide
- hide this because it takes a parameter of type IBluetoothDevice, which is a System private class. Also note that Context.getSystemService is a factory that returns a BlueToothDevice. That is the right way to get a BluetoothDevice.

                                               
       
        mService = service;
Methods Summary
public booleancancelBondProcess(java.lang.String address)
Cancel an in-progress bonding request started with createBond.

        try {
            return mService.cancelBondProcess(address);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;
public voidcancelDiscovery()

        try {
            mService.cancelDiscovery();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
public booleancancelPin(java.lang.String address)

        try {
            return mService.cancelPin(address);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;
public static booleancheckBluetoothAddress(java.lang.String address)
Sanity check a bluetooth address, such as "00:43:A8:23:10:F0"

             
         
        if (address == null || address.length() != ADDRESS_LENGTH) {
            return false;
        }
        for (int i = 0; i < ADDRESS_LENGTH; i++) {
            char c = address.charAt(i);
            switch (i % 3) {
            case 0:
            case 1:
                if (Character.digit(c, 16) != -1) {
                    break;  // hex character, OK
                }
                return false;
            case 2:
                if (c == ':") {
                    break;  // OK
                }
                return false;
            }
        }
        return true;
public static byte[]convertPinToBytes(java.lang.String pin)
Check that a pin is valid and convert to byte array. Bluetooth pin's are 1 to 16 bytes of UTF8 characters.

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

        if (pin == null) {
            return null;
        }
        byte[] pinBytes;
        try {
            pinBytes = pin.getBytes("UTF8");
        } catch (UnsupportedEncodingException uee) {
            Log.e(TAG, "UTF8 not supported?!?");  // this should not happen
            return null;
        }
        if (pinBytes.length <= 0 || pinBytes.length > 16) {
            return null;
        }
        return pinBytes;
public booleancreateBond(java.lang.String address)
Create a bonding with a remote bluetooth device. This is an asynchronous call. The result of this bonding attempt can be observed through BluetoothIntent.BOND_STATE_CHANGED_ACTION intents.

param
address the remote device Bluetooth address.
return
false If there was an immediate problem creating the bonding, true otherwise.

        try {
            return mService.createBond(address);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;
public booleandisable()
Disable the Bluetooth device. This turns off the underlying hardware.

return
true if successful, false otherwise.

        try {
            return mService.disable(true);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;
public booleandisconnectRemoteDeviceAcl(java.lang.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.

param
address the Bluetooth hardware address you want to disconnect.
return
true if the device was disconnected, false otherwise and on error.

        try {
            return mService.disconnectRemoteDeviceAcl(address);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;
public booleanenable()
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.

        try {
            return mService.enable();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;
public java.lang.StringgetAddress()

        try {
            return mService.getAddress();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public intgetBluetoothState()
Get the current state of Bluetooth.

return
One of BLUETOOTH_STATE_ or BluetoothError.ERROR.

        try {
            return mService.getBluetoothState();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return BluetoothError.ERROR;
public intgetBondState(java.lang.String address)
Get the bonding state of a remote device. Result is one of: BluetoothError.* BOND_*

param
address Bluetooth hardware address of the remote device to check.
return
Result code

        try {
            return mService.getBondState(address);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return BluetoothError.ERROR_IPC;
public java.lang.StringgetCompany()

        try {
            return mService.getCompany();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public intgetDiscoverableTimeout()

        try {
            return mService.getDiscoverableTimeout();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return -1;
public java.lang.StringgetManufacturer()

        try {
            return mService.getManufacturer();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public java.lang.StringgetName()
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.

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

        try {
            return mService.getName();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public intgetRemoteClass(java.lang.String address)
Get the major, minor and servics classes of a remote device. These classes are encoded as a 32-bit integer. See BluetoothClass.

param
address remote device
return
32-bit class suitable for use with BluetoothClass, or BluetoothClass.ERROR on error

        try {
            return mService.getRemoteClass(address);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return BluetoothClass.ERROR;
public java.lang.StringgetRemoteCompany(java.lang.String address)

        try {
            return mService.getRemoteCompany(address);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public byte[]getRemoteFeatures(java.lang.String address)

        try {
            return mService.getRemoteFeatures(address);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public java.lang.StringgetRemoteManufacturer(java.lang.String address)

        try {
            return mService.getRemoteManufacturer(address);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public java.lang.StringgetRemoteName(java.lang.String address)

        try {
            return mService.getRemoteName(address);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public java.lang.StringgetRemoteRevision(java.lang.String address)

        try {
            return mService.getRemoteRevision(address);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public booleangetRemoteServiceChannel(java.lang.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.

        try {
            return mService.getRemoteServiceChannel(address, uuid16, callback);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;
public java.lang.StringgetRemoteVersion(java.lang.String address)

        try {
            return mService.getRemoteVersion(address);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public java.lang.StringgetRevision()

        try {
            return mService.getRevision();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public intgetScanMode()
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

        try {
            return mService.getScanMode();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return BluetoothError.ERROR_IPC;
public java.lang.StringgetVersion()

        try {
            return mService.getVersion();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public booleanisAclConnected(java.lang.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.

param
address the Bluetooth hardware address you want to check.
return
true if there is an ACL connection, false otherwise and on error.

        try {
            return mService.isAclConnected(address);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;
public booleanisDiscovering()

        try {
            return mService.isDiscovering();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;
public booleanisEnabled()
Is Bluetooth currently turned on.

return
true if Bluetooth enabled, false otherwise.

        try {
            return mService.isEnabled();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;
public booleanisPeriodicDiscovery()

        try {
            return mService.isPeriodicDiscovery();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;
public java.lang.StringlastSeen(java.lang.String address)

        try {
            return mService.lastSeen(address);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public java.lang.StringlastUsed(java.lang.String address)

        try {
            return mService.lastUsed(address);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public java.lang.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.

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

        try {
            return mService.listAclConnections();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public java.lang.String[]listBonds()
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. Remote devices that have an in-progress bonding attempt are not returned.

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

        try {
            return mService.listBonds();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public java.lang.String[]listRemoteDevices()

        try {
            return mService.listRemoteDevices();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return null;
public booleanremoveBond(java.lang.String address)
Remove an already exisiting bonding (delete the link key).

        try {
            return mService.removeBond(address);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;
public voidsetDiscoverableTimeout(int timeout)

        try {
            mService.setDiscoverableTimeout(timeout);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
public booleansetName(java.lang.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.

param
name the name to set
return
true, if the name was successfully set. False otherwise.

        try {
            return mService.setName(name);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;
public booleansetPin(java.lang.String address, byte[] pin)

        try {
            return mService.setPin(address, pin);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;
public voidsetScanMode(int scanMode)
Set the current scan mode. Used to make the local device connectable and/or discoverable

param
scanMode One of SCAN_MODE_*

        try {
            mService.setScanMode(scanMode);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
public booleanstartDiscovery()

        return startDiscovery(true);
public booleanstartDiscovery(boolean resolveNames)

        try {
            return mService.startDiscovery(resolveNames);
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;
public booleanstartPeriodicDiscovery()

        try {
            return mService.startPeriodicDiscovery();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;
public booleanstopPeriodicDiscovery()

        try {
            return mService.stopPeriodicDiscovery();
        } catch (RemoteException e) {Log.e(TAG, "", e);}
        return false;