BluetoothHeadset | API reference

BluetoothHeadset | API reference | Android Developers

public final class BluetoothHeadset
extends Object implements BluetoothProfile

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
`String`	`ACTION_AUDIO_STATE_CHANGED` Intent used to broadcast the change in the Audio Connection state of the HFP profile.
`String`	`ACTION_CONNECTION_STATE_CHANGED` Intent used to broadcast the change in connection state of the Headset profile.
`String`	`ACTION_VENDOR_SPECIFIC_HEADSET_EVENT` Intent used to broadcast that the headset has posted a vendor-specific event.
`int`	`AT_CMD_TYPE_ACTION` AT command type ACTION used with `EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE` For example, AT+CHUP.
`int`	`AT_CMD_TYPE_BASIC` AT command type BASIC used with `EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE` For example, ATD.
`int`	`AT_CMD_TYPE_READ` AT command type READ used with `EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE` For example, AT+VGM?.
`int`	`AT_CMD_TYPE_SET` AT command type SET used with `EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE` For example, AT+VGM=.
`int`	`AT_CMD_TYPE_TEST` AT command type TEST used with `EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE` For example, AT+VGM=?.
`String`	`EXTRA_DISCONNECTED_REASON` Used as an int extra field in `ACTION_CONNECTION_STATE_CHANGED` intents for connection failure reasons.
`String`	`EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_ARGS` A Parcelable String array extra field in `ACTION_VENDOR_SPECIFIC_HEADSET_EVENT` intents that contains the arguments to the vendor-specific command.
`String`	`EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD` A String extra field in `ACTION_VENDOR_SPECIFIC_HEADSET_EVENT` intents that contains the name of the vendor-specific command.
`String`	`EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE` An int extra field in `ACTION_VENDOR_SPECIFIC_HEADSET_EVENT` intents that contains the AT command type of the vendor-specific command.
`int`	`STATE_AUDIO_CONNECTED` Headset state when SCO audio is connected.
`int`	`STATE_AUDIO_CONNECTING` Headset state when SCO audio is connecting.
`int`	`STATE_AUDIO_DISCONNECTED` Headset state when SCO audio is not connected.
`String`	`VENDOR_RESULT_CODE_COMMAND_ANDROID` A vendor-specific command for unsolicited result code.
`String`	`VENDOR_SPECIFIC_HEADSET_EVENT_COMPANY_ID_CATEGORY` The intent category to be used with `ACTION_VENDOR_SPECIFIC_HEADSET_EVENT` for the companyId

Inherited constants

From interface android.bluetooth.BluetoothProfile

`int`	`A2DP` Advanced Audio Distribution Profile (A2DP)
`int`	`CSIP_SET_COORDINATOR` Coordinated Set Identification Profile (CSIP) set coordinator
`String`	`EXTRA_PREVIOUS_STATE` Extra for the connection state intents of the individual profiles.
`String`	`EXTRA_PROFILE` Extra for the `BluetoothProfile` that the intent applies to.
`String`	`EXTRA_STATE` Extra for the connection state intents of the individual profiles.
`int`	`GATT` Generic Attribute Profile (GATT)
`int`	`GATT_SERVER` Generic Attribute Profile (GATT) Server
`int`	`HAP_CLIENT`
`int`	`HEADSET` Headset and Handsfree profile
`int`	`HEALTH` This constant was deprecated in API level 29. Health Device Profile (HDP) and MCAP protocol are no longer used. New apps should use Bluetooth Low Energy based solutions such as `BluetoothGatt`, `BluetoothAdapter.listenUsingL2capChannel()`, or `BluetoothDevice.createL2capChannel(int)`
`int`	`HEARING_AID` Hearing Aid Device
`int`	`HID_DEVICE` Human Interface Device (HID) Device
`int`	`LE_AUDIO` LE Audio Device
`int`	`SAP` SIM Access Profile (SAP)
`int`	`STATE_CONNECTED` The profile is in connected state
`int`	`STATE_CONNECTING` The profile is in connecting state
`int`	`STATE_DISCONNECTED` The profile is in disconnected state
`int`	`STATE_DISCONNECTING` The profile is in disconnecting state

Public methods
`List<BluetoothDevice>`	`getConnectedDevices()` Get connected devices for this specific 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)`.
`int`	`getConnectionState(BluetoothDevice device)` 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)`.
`List<BluetoothDevice>`	`getDevicesMatchingConnectionStates(int[] states)` Get a list of devices that match any of the given connection states. 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)`.
`boolean`	`isAudioConnected(BluetoothDevice device)` Check if Bluetooth SCO audio is connected.
`boolean`	`isNoiseReductionSupported(BluetoothDevice device)` Checks whether the headset supports some form of noise reduction.
`boolean`	`isVoiceRecognitionSupported(BluetoothDevice device)` Checks whether the headset supports voice recognition.
`boolean`	`sendVendorSpecificResultCode(BluetoothDevice device, String command, String arg)` Sends a vendor-specific unsolicited result code to the headset.
`boolean`	`startVoiceRecognition(BluetoothDevice device)` Start Bluetooth voice recognition.
`boolean`	`stopVoiceRecognition(BluetoothDevice device)` Stop Bluetooth Voice Recognition mode, and shut down the Bluetooth audio path.

Protected methods
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

Inherited methods

From class java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeoutMillis, int nanos)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait()` Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

From interface android.bluetooth.BluetoothProfile

`abstract List<BluetoothDevice>`	`getConnectedDevices()` Get connected devices for this specific profile.
`abstract int`	`getConnectionState(BluetoothDevice device)` Get the current connection state of the profile
`abstract List<BluetoothDevice>`	`getDevicesMatchingConnectionStates(int[] states)` Get a list of devices that match any of the given connection states.

Constants

ACTION_VENDOR_SPECIFIC_HEADSET_EVENT

public static final String ACTION_VENDOR_SPECIFIC_HEADSET_EVENT

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

This intent will have 4 extras and 1 category.

BluetoothDevice.EXTRA_DEVICE - The remote Bluetooth Device
EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD - The vendor specific command
EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE - The AT command type which can be one of AT_CMD_TYPE_READ, AT_CMD_TYPE_TEST, or AT_CMD_TYPE_SET, AT_CMD_TYPE_BASIC,AT_CMD_TYPE_ACTION.
EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_ARGS - Command arguments.

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 Manifest.permission.BLUETOOTH_CONNECT

Constant Value: "android.bluetooth.headset.action.VENDOR_SPECIFIC_HEADSET_EVENT"

AT_CMD_TYPE_ACTION

public static final int AT_CMD_TYPE_ACTION

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

Constant Value: 4 (0x00000004)

AT_CMD_TYPE_BASIC

public static final int AT_CMD_TYPE_BASIC

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.

Constant Value: 3 (0x00000003)

AT_CMD_TYPE_READ

public static final int AT_CMD_TYPE_READ

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.

Constant Value: 0 (0x00000000)

AT_CMD_TYPE_TEST

public static final int AT_CMD_TYPE_TEST

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.

Constant Value: 1 (0x00000001)

public static final String EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_ARGS

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

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

public static final String EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD

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

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

public static final String EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE

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

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

VENDOR_RESULT_CODE_COMMAND_ANDROID

public static final String VENDOR_RESULT_CODE_COMMAND_ANDROID

A vendor-specific command for unsolicited result code.

Constant Value: "+ANDROID"

VENDOR_SPECIFIC_HEADSET_EVENT_COMPANY_ID_CATEGORY

public static final String VENDOR_SPECIFIC_HEADSET_EVENT_COMPANY_ID_CATEGORY

The intent category to be used with ACTION_VENDOR_SPECIFIC_HEADSET_EVENT for the companyId

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

Public methods

Protected methods

finalize

protected void finalize ()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

Throws
`Throwable`