BluetoothConnectionManager

public class BluetoothConnectionManager
extends Object

java.lang.Object
   ↳ com.google.android.things.bluetooth.BluetoothConnectionManager


This class is responsible for handling Bluetooth pairing and connections with a remote BluetoothDevice

It allows developers to perform the following main operations.

  1. Initiate pairing with a new device
  2. Remove existing bond with a known device
  3. Control the pairing flow via user consent/input, and confirm pairing for outgoing and incoming pairing requests.
  4. Establish profile connections with a remote Bluetooth device
  5. Disconnect existing profile connections with a remote device
  6. Obtain user consent for incoming connection requests and confirm/deny them

This class should not be used for GATT profiles GATT and GATT_SERVER. For GATT, use BluetoothGatt, BluetoothGattServer and BluetoothManager

Summary

Constants

int STATE_CONNECTED

Bluetooth profile is in a connected state.

int STATE_CONNECTING

Bluetooth profile is attempting to establish a connection.

int STATE_DISCONNECTED

Bluetooth profile is in a disconnected state.

int STATE_DISCONNECTING

Bluetooth profile is disconnecting an existing connection.

Public methods

boolean cancelPairing(BluetoothDevice bluetoothDevice)

Cancel an ongoing pairing process with a remote device.

void confirmOrDenyConnection(BluetoothDevice bluetoothDevice, ConnectionParams connectionParams, boolean result)

This function should only be called in response to onConnectionRequested(BluetoothDevice, ConnectionParams) and can be used to either confirm or deny a connection request from a remote Bluetooth device.

boolean connect(BluetoothDevice bluetoothDevice, int bluetoothProfile)

Establishes a connection with the remote bluetooth device over the specified BluetoothProfile.

boolean connect(BluetoothDevice bluetoothDevice)

Establishes a connection with the provided remote bluetooth device.

boolean disconnect(BluetoothDevice bluetoothDevice, int bluetoothProfile)

Disconnects the connection for the specified BluetoothProfile with the remote device.

boolean disconnect(BluetoothDevice bluetoothDevice)

Disconnects all existing profile connections with the remote device.

boolean finishPairing(BluetoothDevice bluetoothDevice)

Invoke this function to finish the pairing process with the remote device.

boolean finishPairing(BluetoothDevice bluetoothDevice, String pairingPin)

Invoke this function to finish the pairing process with the remote device.

List<Integer> getConnectableProfiles(BluetoothDevice bluetoothDevice)

Returns all the Bluetooth Profiles which are connectable from the local device to the remote device.

int getConnectionState(BluetoothDevice bluetoothDevice, int bluetoothProfile)

Returns the connection state of the specified BluetoothProfile with the remote BluetoothDevice.

static BluetoothConnectionManager getInstance()

Returns an instance of BluetoothConnectionManager which can be used to control Bluetooth pairing/connections with a remote BluetoothDevice.

boolean initiatePairing(BluetoothDevice bluetoothDevice)

Initiate Bluetooth pairing process with a remote device.

void registerConnectionCallback(BluetoothConnectionCallback bluetoothConnectionCallback)

Register a BluetoothConnectionCallback.

void registerPairingCallback(BluetoothPairingCallback bluetoothPairingCallback)

Register a BluetoothPairingCallback.

boolean unpair(BluetoothDevice bluetoothDevice)

Destroys the existing pairing/bond with the remote device.

void unregisterConnectionCallback(BluetoothConnectionCallback bluetoothConnectionCallback)

Unregister a BluetoothConnectionCallback.

void unregisterPairingCallback(BluetoothPairingCallback bluetoothPairingCallback)

Unregister a BluetoothPairingCallback.

Inherited methods

From class java.lang.Object

Constants

STATE_CONNECTED

int STATE_CONNECTED

Bluetooth profile is in a connected state.

Constant Value: 2 (0x00000002)

STATE_CONNECTING

int STATE_CONNECTING

Bluetooth profile is attempting to establish a connection.

Constant Value: 1 (0x00000001)

STATE_DISCONNECTED

int STATE_DISCONNECTED

Bluetooth profile is in a disconnected state.

Constant Value: 0 (0x00000000)

STATE_DISCONNECTING

int STATE_DISCONNECTING

Bluetooth profile is disconnecting an existing connection.

Constant Value: 3 (0x00000003)

Public methods

cancelPairing

boolean cancelPairing (BluetoothDevice bluetoothDevice)

Cancel an ongoing pairing process with a remote device.

Parameters
bluetoothDevice BluetoothDevice: remote Bluetooth device.

Returns
boolean

Throws
IllegalArgumentException when the Bluetooth device is null.
IllegalStateException when the connection to the service has died.

confirmOrDenyConnection

void confirmOrDenyConnection (BluetoothDevice bluetoothDevice, 
                ConnectionParams connectionParams, 
                boolean result)

This function should only be called in response to onConnectionRequested(BluetoothDevice, ConnectionParams) and can be used to either confirm or deny a connection request from a remote Bluetooth device.

Parameters
bluetoothDevice BluetoothDevice: remote Bluetooth device.

connectionParams ConnectionParams: Parameters for current connection request.

result boolean: whether the connection request was accepted/rejected.

connect

boolean connect (BluetoothDevice bluetoothDevice, 
                int bluetoothProfile)

Establishes a connection with the remote bluetooth device over the specified BluetoothProfile.

This method attempts to connect with a remote device over the specified profile regardless of whether the remote device is known to support it or not, as reported by getConnectableProfiles(BluetoothDevice). This allows the user of the API to force a connection in cases where a device may support a particular profile but does not advertise it through getUuids().

Only the following profiles are currently supported by this method. Supported Profiles: HEADSET, A2DP, A2DP_SINK.

Parameters
bluetoothDevice BluetoothDevice: remote Bluetooth device.

bluetoothProfile int: The BluetoothProfile to connect.

Returns
boolean False if connection infeasible or connection attempt fails. True otherwise.

Throws
IllegalArgumentException when the Bluetooth device is null.
IllegalStateException when the connection to the server has died.

connect

boolean connect (BluetoothDevice bluetoothDevice)

Establishes a connection with the provided remote bluetooth device. This method attempts to establish a connection over all connectable Bluetooth Profiles, as reported by getConnectableProfiles(BluetoothDevice).

Only the following profiles are currently supported by this method. Supported Profiles: HEADSET, A2DP, A2DP_SINK.

Parameters
bluetoothDevice BluetoothDevice: remote Bluetooth device.

Returns
boolean False if no supported connectable profiles exist and if any of the connection attempts fail. True otherwise.

Throws
IllegalArgumentException when the Bluetooth device is null.
IllegalStateException when the connection to the server has died.

disconnect

boolean disconnect (BluetoothDevice bluetoothDevice, 
                int bluetoothProfile)

Disconnects the connection for the specified BluetoothProfile with the remote device.

Only the following profiles are currently supported by this method. Supported Profiles: HEADSET, A2DP, A2DP_SINK, SAP.

Parameters
bluetoothDevice BluetoothDevice: remote Bluetooth device.

bluetoothProfile int

Returns
boolean False if no connection exists or the disconnect attempt fails. True otherwise.

Throws
IllegalArgumentException when the Bluetooth device is null.
IllegalStateException when the connection to the server has died.

disconnect

boolean disconnect (BluetoothDevice bluetoothDevice)

Disconnects all existing profile connections with the remote device.

Only the following profiles are currently supported by this method. Supported Profiles: HEADSET, A2DP, A2DP_SINK, SAP.

Parameters
bluetoothDevice BluetoothDevice: remote Bluetooth device.

Returns
boolean False if no connection exists with the remote device or if any of the disconnect attempts fail. True otherwise.

Throws
IllegalArgumentException when the Bluetooth device is null.
IllegalStateException when the connection to the server has died.

finishPairing

boolean finishPairing (BluetoothDevice bluetoothDevice)

Invoke this function to finish the pairing process with the remote device. Should be called only after receiving a callback from onPairingInitiated(BluetoothDevice, PairingParams).

This function should be used for pairing variants PAIRING_VARIANT_CONSENT, PAIRING_VARIANT_PASSKEY_CONFIRMATION.

Parameters
bluetoothDevice BluetoothDevice: remote Bluetooth device.

Returns
boolean

Throws
IllegalArgumentException when the Bluetooth device is null.
IllegalStateException when the connection to the service has died.

finishPairing

boolean finishPairing (BluetoothDevice bluetoothDevice, 
                String pairingPin)

Invoke this function to finish the pairing process with the remote device. Should be called only after receiving a callback from onPairingInitiated(BluetoothDevice, PairingParams).

This function should be used for pairing variants PAIRING_VARIANT_PIN, PAIRING_VARIANT_PIN_16_DIGITS.

Parameters
bluetoothDevice BluetoothDevice: remote Bluetooth device.

pairingPin String: Pairing pin

Returns
boolean

Throws
IllegalArgumentException when the Bluetooth device is null.
IllegalStateException when the connection to the service has died.

getConnectableProfiles

List<Integer> getConnectableProfiles (BluetoothDevice bluetoothDevice)

Returns all the Bluetooth Profiles which are connectable from the local device to the remote device. This is determined by the Bluetooth service UUIDs advertised by the remote device and the capabilities of the local Bluetooth device.

For example, if the local device is an A2DP source A2DP and the remote device an A2DP sink A2DP_SINK then A2DP would be one of the connectable profiles.

Parameters
bluetoothDevice BluetoothDevice: remote Bluetooth device.

Returns
List<Integer> List<BluetoothProfile> of all connectable BluetoothProfiles.

Throws
IllegalArgumentException when the Bluetooth device is null.
IllegalStateException when the connection to the service has died.

getConnectionState

int getConnectionState (BluetoothDevice bluetoothDevice, 
                int bluetoothProfile)

Returns the connection state of the specified BluetoothProfile with the remote BluetoothDevice.

Parameters
bluetoothDevice BluetoothDevice: remote Bluetooth device.

bluetoothProfile int: The BluetoothProfile to connect.

Returns
int the connection state of bluetoothProfile with the Bluetooth device.

Throws
IllegalArgumentException when the Bluetooth device is null.
IllegalStateException when the connection to the server has died.

getInstance

BluetoothConnectionManager getInstance ()

Returns an instance of BluetoothConnectionManager which can be used to control Bluetooth pairing/connections with a remote BluetoothDevice.

Returns
BluetoothConnectionManager

Throws
IllegalStateException if a connection cannot be established to the back-end service.

initiatePairing

boolean initiatePairing (BluetoothDevice bluetoothDevice)

Initiate Bluetooth pairing process with a remote device.

Parameters
bluetoothDevice BluetoothDevice: remote Bluetooth device.

Returns
boolean

Throws
IllegalArgumentException when the Bluetooth device is null.
IllegalStateException when the connection to the service has died.

registerConnectionCallback

void registerConnectionCallback (BluetoothConnectionCallback bluetoothConnectionCallback)

Register a BluetoothConnectionCallback. This allows you to listen for Bluetooth connection events such as incoming connection requests, connection/disconnection of profiles etc.

Parameters
bluetoothConnectionCallback BluetoothConnectionCallback: Bluetooth Connection callback.

registerPairingCallback

void registerPairingCallback (BluetoothPairingCallback bluetoothPairingCallback)

Register a BluetoothPairingCallback. This allows you to listen for Bluetooth pairing events such as incoming pairing request, devices paired/unpaired etc.

Parameters
bluetoothPairingCallback BluetoothPairingCallback: Bluetooth Pairing callback.

unpair

boolean unpair (BluetoothDevice bluetoothDevice)

Destroys the existing pairing/bond with the remote device. This also severs any existing Bluetooth profile connections with the remote remote device.

Any future connection attempts will have to undergo the pairing process again, and the local Bluetooth adapter will have no memory/record of the remote device.

Parameters
bluetoothDevice BluetoothDevice: remote Bluetooth device.

Returns
boolean

Throws
IllegalArgumentException when the Bluetooth device is null.
IllegalStateException when the connection to the service has died.

unregisterConnectionCallback

void unregisterConnectionCallback (BluetoothConnectionCallback bluetoothConnectionCallback)

Unregister a BluetoothConnectionCallback. This function needs to be invoked to ensure proper clearing up of resources, and should be called once you don't need to listen to connection events.

Parameters
bluetoothConnectionCallback BluetoothConnectionCallback: Bluetooth Connection callback.

unregisterPairingCallback

void unregisterPairingCallback (BluetoothPairingCallback bluetoothPairingCallback)

Unregister a BluetoothPairingCallback. This function needs to be invoked to ensure proper clearing up of resources, and should be called once you don't need to listen to pairing events.

Parameters
bluetoothPairingCallback BluetoothPairingCallback: Bluetooth Pairing callback.