# Print output for @column tags ?>
public
final
class
BluetoothHeadset
extends Object
implements
BluetoothProfile
java.lang.Object | |
↳ | 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.
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
|
int |
AT_CMD_TYPE_BASIC
AT command type BASIC used with
|
int |
AT_CMD_TYPE_READ
AT command type READ used with
|
int |
AT_CMD_TYPE_SET
AT command type SET used with
|
int |
AT_CMD_TYPE_TEST
AT command type TEST used with
|
String |
EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_ARGS
A Parcelable String array extra field in
|
String |
EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD
A String extra field in |
String |
EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE
An int extra field in |
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 |
Inherited constants |
---|
Public methods | |
---|---|
List<BluetoothDevice>
|
getConnectedDevices()
Get connected devices for this specific profile.
|
int
|
getConnectionState(BluetoothDevice device)
Get the current connection state of the profile
|
List<BluetoothDevice>
|
getDevicesMatchingConnectionStates(int[] states)
Get a list of devices that match any of the given connection
states.
|
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. |
Inherited methods | |
---|---|
public static final String ACTION_AUDIO_STATE_CHANGED
Intent used to broadcast the change in the Audio Connection state of the HFP profile.
This intent will have 3 extras:
BluetoothProfile.EXTRA_STATE
- The current state of the profile. BluetoothProfile.EXTRA_PREVIOUS_STATE
- The previous state of the profile. BluetoothDevice#EXTRA_DEVICE
- The remote device. BluetoothProfile.EXTRA_STATE
or BluetoothProfile.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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Constant Value: "android.bluetooth.headset.profile.action.AUDIO_STATE_CHANGED"
public static final String ACTION_CONNECTION_STATE_CHANGED
Intent used to broadcast the change in connection state of the Headset profile.
This intent will have 3 extras:
BluetoothProfile.EXTRA_STATE
- The current state of the profile. BluetoothProfile.EXTRA_PREVIOUS_STATE
- The previous state of the profile. BluetoothDevice#EXTRA_DEVICE
- The remote device. BluetoothProfile.EXTRA_STATE
or BluetoothProfile.EXTRA_PREVIOUS_STATE
can be any of
BluetoothProfile.STATE_DISCONNECTED
, BluetoothProfile.STATE_CONNECTING
,
BluetoothProfile.STATE_CONNECTED
, BluetoothProfile.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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Constant Value: "android.bluetooth.headset.profile.action.CONNECTION_STATE_CHANGED"
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
Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Manifest.permission.BLUETOOTH_CONNECT
Constant Value: "android.bluetooth.headset.action.VENDOR_SPECIFIC_HEADSET_EVENT"
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)
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)
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)
public static final int AT_CMD_TYPE_SET
AT command type SET used with
EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE
For example, AT+VGM=
Constant Value: 2 (0x00000002)
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"
public static final int STATE_AUDIO_CONNECTED
Headset state when SCO audio is connected.
This state can be one of
BluetoothProfile.EXTRA_STATE
or BluetoothProfile.EXTRA_PREVIOUS_STATE
of
ACTION_AUDIO_STATE_CHANGED
intent.
Constant Value: 12 (0x0000000c)
public static final int STATE_AUDIO_CONNECTING
Headset state when SCO audio is connecting.
This state can be one of
BluetoothProfile.EXTRA_STATE
or BluetoothProfile.EXTRA_PREVIOUS_STATE
of
ACTION_AUDIO_STATE_CHANGED
intent.
Constant Value: 11 (0x0000000b)
public static final int STATE_AUDIO_DISCONNECTED
Headset state when SCO audio is not connected.
This state can be one of
BluetoothProfile.EXTRA_STATE
or BluetoothProfile.EXTRA_PREVIOUS_STATE
of
ACTION_AUDIO_STATE_CHANGED
intent.
Constant Value: 10 (0x0000000a)
public static final String VENDOR_RESULT_CODE_COMMAND_ANDROID
A vendor-specific command for unsolicited result code.
Constant Value: "+ANDROID"
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 List<BluetoothDevice> getConnectedDevices ()
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Returns | |
---|---|
List<BluetoothDevice> |
List of devices. The list will be empty on error. |
public 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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
device |
BluetoothDevice : Remote bluetooth device. |
Returns | |
---|---|
int |
State of the profile connection. One of STATE_CONNECTED , STATE_CONNECTING , STATE_DISCONNECTED , STATE_DISCONNECTING
Value is STATE_DISCONNECTED , STATE_CONNECTING , STATE_CONNECTED , or STATE_DISCONNECTING |
public List<BluetoothDevice> getDevicesMatchingConnectionStates (int[] states)
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
states |
int : Array of states. States can be one of BluetoothProfile.STATE_CONNECTED , BluetoothProfile.STATE_CONNECTING , BluetoothProfile.STATE_DISCONNECTED , BluetoothProfile.STATE_DISCONNECTING , |
Returns | |
---|---|
List<BluetoothDevice> |
List of devices. The list will be empty on error. |
public boolean isAudioConnected (BluetoothDevice device)
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
device |
BluetoothDevice : Bluetooth headset |
Returns | |
---|---|
boolean |
true if SCO is connected, false otherwise or on error |
public boolean isNoiseReductionSupported (BluetoothDevice device)
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
device |
BluetoothDevice : Bluetooth device
This value cannot be null . |
Returns | |
---|---|
boolean |
true if echo cancellation and/or noise reduction is supported, false otherwise |
public boolean isVoiceRecognitionSupported (BluetoothDevice device)
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
device |
BluetoothDevice : Bluetooth device
This value cannot be null . |
Returns | |
---|---|
boolean |
true if voice recognition is supported, false otherwise |
public boolean sendVendorSpecificResultCode (BluetoothDevice device, String command, String arg)
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
Activity.requestPermissions(String[], int)
.
Requires 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. |
Returns | |
---|---|
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. |
Throws | |
---|---|
IllegalArgumentException |
if command is null . |
public boolean startVoiceRecognition (BluetoothDevice device)
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
BluetoothProfile.EXTRA_STATE
set to STATE_AUDIO_CONNECTING
.
BluetoothProfile.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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
and Manifest.permission.MODIFY_PHONE_STATE
Parameters | |
---|---|
device |
BluetoothDevice : Bluetooth headset |
Returns | |
---|---|
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 |
public boolean stopVoiceRecognition (BluetoothDevice device)
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
BluetoothProfile.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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
device |
BluetoothDevice : Bluetooth headset |
Returns | |
---|---|
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 |