Added in API level 11

BluetoothHeadset

class BluetoothHeadset : BluetoothProfile
kotlin.Any
   ↳ android.bluetooth.BluetoothHeadset

Public API for controlling the Bluetooth Headset Service. This includes both Bluetooth Headset and Handsfree (v1.5) profiles.

BluetoothHeadset is a proxy object for controlling the Bluetooth Headset Service via IPC.

Use BluetoothAdapter#getProfileProxy to get the BluetoothHeadset proxy object. Use BluetoothAdapter#closeProfileProxy to close the service connection.

Android only supports one connected Bluetooth Headset at a time. Each method is protected with its appropriate permission.

Summary

Constants
static String

Intent used to broadcast the change in the Audio Connection state of the HFP profile.
static String

Intent used to broadcast the change in connection state of the Headset profile.
static String

Intent used to broadcast that the headset has posted a vendor-specific event.
static Int

AT command type ACTION used with EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE For example, AT+CHUP.
static Int

AT command type BASIC used with EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE For example, ATD.
static Int

AT command type READ used with EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE For example, AT+VGM?.
static Int

AT command type SET used with EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE For example, AT+VGM=.
static Int

AT command type TEST used with EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE For example, AT+VGM=?.
static String

A Parcelable String array extra field in ACTION_VENDOR_SPECIFIC_HEADSET_EVENT intents that contains the arguments to the vendor-specific command.
static String

A String extra field in ACTION_VENDOR_SPECIFIC_HEADSET_EVENT intents that contains the name of the vendor-specific command.
static String

An int extra field in ACTION_VENDOR_SPECIFIC_HEADSET_EVENT intents that contains the AT command type of the vendor-specific command.
static Int

Headset state when SCO audio is connected.
static Int

Headset state when SCO audio is connecting.
static Int

Headset state when SCO audio is not connected.
static String

A vendor-specific command for unsolicited result code.
static String

The intent category to be used with ACTION_VENDOR_SPECIFIC_HEADSET_EVENT for the companyId
Inherited constants
Public methods
MutableList<BluetoothDevice!>!

Get connected devices for this specific profile.
Int

Get the current connection state of the profile
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with android.app.Activity#requestPermissions(String[], int).
MutableList<BluetoothDevice!>!

Get a list of devices that match any of the given connection states.
Boolean

Check if Bluetooth SCO audio is connected.
Boolean

Checks whether the headset supports some form of noise reduction
For apps targeting Build.VERSION_CODES#R or lower, this requires the Manifest.permission#BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
Boolean

Checks whether the headset supports voice recognition
For apps targeting Build.VERSION_CODES#R or lower, this requires the Manifest.permission#BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
Boolean

Sends a vendor-specific unsolicited result code to the headset.
Boolean

Start Bluetooth voice recognition.
Boolean

Stop Bluetooth Voice Recognition mode, and shut down the Bluetooth audio path.

Constants

ACTION_AUDIO_STATE_CHANGED

Added in API level 11
static val ACTION_AUDIO_STATE_CHANGED: String

Intent used to broadcast the change in the Audio Connection state of the HFP profile.

This intent will have 3 extras:

EXTRA_STATE or EXTRA_PREVIOUS_STATE can be any of STATE_AUDIO_CONNECTED, STATE_AUDIO_DISCONNECTED,
For apps targeting Build.VERSION_CODES#R or lower, this requires the Manifest.permission#BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with android.app.Activity#requestPermissions(String[], int).
Requires android.Manifest.permission#BLUETOOTH_CONNECT

Value: "android.bluetooth.headset.profile.action.AUDIO_STATE_CHANGED"

ACTION_CONNECTION_STATE_CHANGED

Added in API level 11
static val ACTION_CONNECTION_STATE_CHANGED: String

Intent used to broadcast the change in connection state of the Headset profile.

This intent will have 3 extras:

EXTRA_STATE or EXTRA_PREVIOUS_STATE can be any of STATE_DISCONNECTED, STATE_CONNECTING, STATE_CONNECTED, STATE_DISCONNECTING.
For apps targeting Build.VERSION_CODES#R or lower, this requires the Manifest.permission#BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with android.app.Activity#requestPermissions(String[], int).
Requires android.Manifest.permission#BLUETOOTH_CONNECT

Value: "android.bluetooth.headset.profile.action.CONNECTION_STATE_CHANGED"

ACTION_VENDOR_SPECIFIC_HEADSET_EVENT

Added in API level 11
static val ACTION_VENDOR_SPECIFIC_HEADSET_EVENT: String

Intent used to broadcast that the headset has posted a vendor-specific event.

This intent will have 4 extras and 1 category.

The category is the Company ID of the vendor defining the vendor-specific command. BluetoothAssignedNumbers

For example, for Plantronics specific events Category will be VENDOR_SPECIFIC_HEADSET_EVENT_COMPANY_ID_CATEGORY.55

For example, an AT+XEVENT=foo,3 will get translated into

  • EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD = +XEVENT
  • EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE = AT_CMD_TYPE_SET
  • EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_ARGS = foo, 3

For apps targeting Build.VERSION_CODES#R or lower, this requires the Manifest.permission#BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with android.app.Activity#requestPermissions(String[], int).
Requires android.Manifest.permission#BLUETOOTH_CONNECT 
Value: "android.bluetooth.headset.action.VENDOR_SPECIFIC_HEADSET_EVENT"

AT_CMD_TYPE_ACTION

Added in API level 11
static val AT_CMD_TYPE_ACTION: Int

AT command type ACTION used with EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE For example, AT+CHUP. There are no arguments for action commands.

Value: 4

AT_CMD_TYPE_BASIC

Added in API level 11
static val AT_CMD_TYPE_BASIC: Int

AT command type BASIC used with EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE For example, ATD. Single character commands and everything following the character are arguments.

Value: 3

AT_CMD_TYPE_READ

Added in API level 11
static val AT_CMD_TYPE_READ: Int

AT command type READ used with EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE For example, AT+VGM?. There are no arguments for this command type.

Value: 0

AT_CMD_TYPE_SET

Added in API level 11
static val AT_CMD_TYPE_SET: Int

AT command type SET used with EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE For example, AT+VGM=.

Value: 2

AT_CMD_TYPE_TEST

Added in API level 11
static val AT_CMD_TYPE_TEST: Int

AT command type TEST used with EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE For example, AT+VGM=?. There are no arguments for this command type.

Value: 1

EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_ARGS

Added in API level 11
static val EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_ARGS: String

A Parcelable String array extra field in ACTION_VENDOR_SPECIFIC_HEADSET_EVENT intents that contains the arguments to the vendor-specific command.

Value: "android.bluetooth.headset.extra.VENDOR_SPECIFIC_HEADSET_EVENT_ARGS"

EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD

Added in API level 11
static val EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD: String

A String extra field in ACTION_VENDOR_SPECIFIC_HEADSET_EVENT intents that contains the name of the vendor-specific command.

Value: "android.bluetooth.headset.extra.VENDOR_SPECIFIC_HEADSET_EVENT_CMD"

EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE

Added in API level 11
static val EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE: String

An int extra field in ACTION_VENDOR_SPECIFIC_HEADSET_EVENT intents that contains the AT command type of the vendor-specific command.

Value: "android.bluetooth.headset.extra.VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE"

STATE_AUDIO_CONNECTED

Added in API level 11
static val STATE_AUDIO_CONNECTED: Int

Headset state when SCO audio is connected. This state can be one of EXTRA_STATE or EXTRA_PREVIOUS_STATE of ACTION_AUDIO_STATE_CHANGED intent.

Value: 12

STATE_AUDIO_CONNECTING

Added in API level 11
static val STATE_AUDIO_CONNECTING: Int

Headset state when SCO audio is connecting. This state can be one of EXTRA_STATE or EXTRA_PREVIOUS_STATE of ACTION_AUDIO_STATE_CHANGED intent.

Value: 11

STATE_AUDIO_DISCONNECTED

Added in API level 11
static val STATE_AUDIO_DISCONNECTED: Int

Headset state when SCO audio is not connected. This state can be one of EXTRA_STATE or EXTRA_PREVIOUS_STATE of ACTION_AUDIO_STATE_CHANGED intent.

Value: 10

VENDOR_RESULT_CODE_COMMAND_ANDROID

Added in API level 19
static val VENDOR_RESULT_CODE_COMMAND_ANDROID: String

A vendor-specific command for unsolicited result code.

Value: "+ANDROID"

VENDOR_SPECIFIC_HEADSET_EVENT_COMPANY_ID_CATEGORY

Added in API level 11
static val VENDOR_SPECIFIC_HEADSET_EVENT_COMPANY_ID_CATEGORY: String

The intent category to be used with ACTION_VENDOR_SPECIFIC_HEADSET_EVENT for the companyId

Value: "android.bluetooth.headset.intent.category.companyid"

Public methods

getConnectedDevices

Added in API level 11
fun getConnectedDevices(): MutableList<BluetoothDevice!>!

Get connected devices for this specific profile.

Return the set of devices which are in state STATE_CONNECTED
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with android.app.Activity#requestPermissions(String[], int).
Requires android.Manifest.permission#BLUETOOTH_CONNECT

Return
MutableList<BluetoothDevice!>! List of devices. The list will be empty on error.

getConnectionState

Added in API level 11
fun getConnectionState(device: BluetoothDevice!): Int

Get the current connection state of the profile
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with android.app.Activity#requestPermissions(String[], int).
Requires android.Manifest.permission#BLUETOOTH_CONNECT

Parameters
device BluetoothDevice!: Remote bluetooth device.
Return
Int State of the profile connection. One of STATE_CONNECTED, STATE_CONNECTING, STATE_DISCONNECTED, STATE_DISCONNECTING Value is android.bluetooth.BluetoothProfile#STATE_DISCONNECTED, android.bluetooth.BluetoothProfile#STATE_CONNECTING, android.bluetooth.BluetoothProfile#STATE_CONNECTED, or android.bluetooth.BluetoothProfile#STATE_DISCONNECTING

getDevicesMatchingConnectionStates

Added in API level 11
fun getDevicesMatchingConnectionStates(states: IntArray!): MutableList<BluetoothDevice!>!

Get a list of devices that match any of the given connection states.

If none of the devices match any of the given states, an empty list will be returned.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with android.app.Activity#requestPermissions(String[], int).
Requires android.Manifest.permission#BLUETOOTH_CONNECT

Parameters
states IntArray!: Array of states. States can be one of STATE_CONNECTED, STATE_CONNECTING, STATE_DISCONNECTED, STATE_DISCONNECTING,
Return
MutableList<BluetoothDevice!>! List of devices. The list will be empty on error.

isAudioConnected

Added in API level 11
fun isAudioConnected(device: BluetoothDevice!): Boolean

Check if Bluetooth SCO audio is connected.
For apps targeting Build.VERSION_CODES#R or lower, this requires the Manifest.permission#BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with android.app.Activity#requestPermissions(String[], int).
Requires android.Manifest.permission#BLUETOOTH_CONNECT

Parameters
device BluetoothDevice!: Bluetooth headset
Return
Boolean true if SCO is connected, false otherwise or on error

isNoiseReductionSupported

Added in API level 31
fun isNoiseReductionSupported(device: BluetoothDevice): Boolean

Checks whether the headset supports some form of noise reduction
For apps targeting Build.VERSION_CODES#R or lower, this requires the Manifest.permission#BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with android.app.Activity#requestPermissions(String[], int).
Requires android.Manifest.permission#BLUETOOTH_CONNECT

Parameters
device BluetoothDevice: Bluetooth device This value cannot be null.
Return
Boolean true if echo cancellation and/or noise reduction is supported, false otherwise

isVoiceRecognitionSupported

Added in API level 31
fun isVoiceRecognitionSupported(device: BluetoothDevice): Boolean

Checks whether the headset supports voice recognition
For apps targeting Build.VERSION_CODES#R or lower, this requires the Manifest.permission#BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with android.app.Activity#requestPermissions(String[], int).
Requires android.Manifest.permission#BLUETOOTH_CONNECT

Parameters
device BluetoothDevice: Bluetooth device This value cannot be null.
Return
Boolean true if voice recognition is supported, false otherwise

sendVendorSpecificResultCode

Added in API level 19
fun sendVendorSpecificResultCode(
    device: BluetoothDevice!, 
    command: String!, 
    arg: String!
): Boolean

Sends a vendor-specific unsolicited result code to the headset.

The actual string to be sent is command + ": " + arg. For example, if command is VENDOR_RESULT_CODE_COMMAND_ANDROID and arg is "0", the string "+ANDROID: 0" will be sent.

Currently only VENDOR_RESULT_CODE_COMMAND_ANDROID is allowed as command.
For apps targeting Build.VERSION_CODES#R or lower, this requires the Manifest.permission#BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with android.app.Activity#requestPermissions(String[], int).
Requires android.Manifest.permission#BLUETOOTH_CONNECT

Parameters
device BluetoothDevice!: Bluetooth headset.
command String!: A vendor-specific command.
arg String!: The argument that will be attached to the command.
Return
Boolean false if there is no headset connected, or if the command is not an allowed vendor-specific unsolicited result code, or on error. true otherwise.
Exceptions
java.lang.IllegalArgumentException if command is null.

startVoiceRecognition

Added in API level 11
fun startVoiceRecognition(device: BluetoothDevice!): Boolean

Start Bluetooth voice recognition. This methods sends the voice recognition AT command to the headset and establishes the audio connection.

Users can listen to ACTION_AUDIO_STATE_CHANGED. If this function returns true, this intent will be broadcasted with EXTRA_STATE set to STATE_AUDIO_CONNECTING.

EXTRA_STATE will transition from STATE_AUDIO_CONNECTING to STATE_AUDIO_CONNECTED when audio connection is established and to STATE_AUDIO_DISCONNECTED in case of failure to establish the audio connection.
For apps targeting Build.VERSION_CODES#R or lower, this requires the Manifest.permission#BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with android.app.Activity#requestPermissions(String[], int).
Requires android.Manifest.permission#BLUETOOTH_CONNECT and android.Manifest.permission#MODIFY_PHONE_STATE

Parameters
device BluetoothDevice!: Bluetooth headset
Return
Boolean false if there is no headset connected, or the connected headset doesn't support voice recognition, or voice recognition is already started, or audio channel is occupied, or on error, true otherwise

stopVoiceRecognition

Added in API level 11
fun stopVoiceRecognition(device: BluetoothDevice!): Boolean

Stop Bluetooth Voice Recognition mode, and shut down the Bluetooth audio path.

Users can listen to ACTION_AUDIO_STATE_CHANGED. If this function returns true, this intent will be broadcasted with EXTRA_STATE set to STATE_AUDIO_DISCONNECTED.
For apps targeting Build.VERSION_CODES#R or lower, this requires the Manifest.permission#BLUETOOTH permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES#S or or higher, this requires the Manifest.permission#BLUETOOTH_CONNECT permission which can be gained with android.app.Activity#requestPermissions(String[], int).
Requires android.Manifest.permission#BLUETOOTH_CONNECT

Parameters
device BluetoothDevice!: Bluetooth headset
Return
Boolean false if there is no headset connected, or voice recognition has not started, or voice recognition has ended on this headset, or on error, true otherwise