Tizen(Headed) Native API  6.5
Bluetooth Audio

Bluetooth Audio API provides functions for connecting to Bluetooth audio devices such as headset, hand-free and headphone.

Required Header

#include <bluetooth.h>

Overview

This API supports the HFP(Hands-Free Profile), HSP(Headset Profile) and A2DP(Advanced Audio Distribution Profile).

Related Features

This API is related with the following features:

  • http://tizen.org/feature/network.bluetooth.audio.call
  • http://tizen.org/feature/network.bluetooth.audio.media

It is recommended to design feature related codes in your application for reliability.

You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from Feature Element.

Functions

int bt_audio_initialize (void)
 Initializes the Bluetooth profiles related with audio.
int bt_audio_deinitialize (void)
 Deinitializes the Bluetooth profiles related with audio.
int bt_audio_connect (const char *remote_address, bt_audio_profile_type_e type)
 Connects the remote device with the given audio profile, asynchronously.
int bt_audio_disconnect (const char *remote_address, bt_audio_profile_type_e type)
 Disconnects the remote device with the given audio profile, asynchronously.
int bt_audio_set_connection_state_changed_cb (bt_audio_connection_state_changed_cb callback, void *user_data)
 Registers a callback function that will be invoked when the connection state is changed.
int bt_audio_unset_connection_state_changed_cb (void)
 Unregisters a callback function that will be invoked when the connection state is changed.

Typedefs

typedef void(* bt_audio_connection_state_changed_cb )(int result, bool connected, const char *remote_address, bt_audio_profile_type_e type, void *user_data)
 Called when the connection state is changed.

Typedef Documentation

typedef void(* bt_audio_connection_state_changed_cb)(int result, bool connected, const char *remote_address, bt_audio_profile_type_e type, void *user_data)

Called when the connection state is changed.

This callback is called when the connection state is changed.

Since :
2.3 When you call bt_audio_connect() or bt_audio_disconnect(), this callback is also called with error result even though these functions fail.
Parameters:
[in]resultThe result of changing the connection state
[in]connectedThe state to be changed. true means connected state, Otherwise, false.
[in]remote_addressThe remote address
[in]typeThe type of audio profile except BT_AUDIO_PROFILE_TYPE_ALL
[in]user_dataThe user data passed from the callback registration function
See also:
bt_audio_set_connection_state_changed_cb()
bt_audio_unset_connection_state_changed_cb()

Enumeration Type Documentation

Enumerations for the types of profiles related with audio.

Since :
2.3
Enumerator:
BT_AUDIO_PROFILE_TYPE_ALL 

All supported profiles related with audio (Both Host and Device role)

BT_AUDIO_PROFILE_TYPE_HSP_HFP 

local device AG and remote device HF Client (Host role, ex: mobile)

BT_AUDIO_PROFILE_TYPE_A2DP 

A2DP Source Connection, remote device is A2DP Sink (Host role, ex: mobile)

BT_AUDIO_PROFILE_TYPE_AG 

local device HF Client and remote device AG (Device role, ex: headset)

BT_AUDIO_PROFILE_TYPE_A2DP_SINK 

A2DP Sink Connection, remote device is A2DP Source (Device role, ex: headset)


Function Documentation

int bt_audio_connect ( const char *  remote_address,
bt_audio_profile_type_e  type 
)

Connects the remote device with the given audio profile, asynchronously.

If you input type as BT_AUDIO_PROFILE_TYPE_ALL and connection request succeeds, then bt_audio_connection_state_changed_cb() will be called twice
when BT_AUDIO_PROFILE_TYPE_HSP_HFP is connected and BT_AUDIO_PROFILE_TYPE_A2DP is connected.

Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]remote_addressThe remote address
[in]typeThe type of audio profile
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The Bluetooth audio service must be initialized with bt_audio_initialize().
The local device must be bonded with the remote device by bt_device_create_bond().
Postcondition:
bt_audio_connection_state_changed_cb() will be invoked.
See also:
bt_audio_disconnect()
bt_audio_connection_state_changed_cb()
int bt_audio_deinitialize ( void  )

Deinitializes the Bluetooth profiles related with audio.

Since :
2.3
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The Bluetooth audio service must be initialized with bt_audio_initialize().
See also:
bt_audio_initialize()
int bt_audio_disconnect ( const char *  remote_address,
bt_audio_profile_type_e  type 
)

Disconnects the remote device with the given audio profile, asynchronously.

If you input type as BT_AUDIO_PROFILE_TYPE_ALL and disconnection request succeeds, then bt_audio_connection_state_changed_cb() will be called twice
when BT_AUDIO_PROFILE_TYPE_HSP_HFP is disconnected and BT_AUDIO_PROFILE_TYPE_A2DP is disconnected.

Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/bluetooth
Parameters:
[in]remote_addressThe remote address
[in]typeThe type of audio profile
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_ENABLEDNot enabled
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_PERMISSION_DENIEDPermission denied
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The remote device must be connected by bt_audio_connect().
Postcondition:
bt_audio_connection_state_changed_cb() will be invoked.
See also:
bt_audio_connect()
bt_audio_connection_state_changed_cb()
int bt_audio_initialize ( void  )

Initializes the Bluetooth profiles related with audio.

Since :
2.3
Remarks:
This function must be called before Bluetooth profiles related with audio starts.
You must free all resources of the this service by calling bt_audio_deinitialize()
if Bluetooth profiles related with audio service is no longer needed.
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_OPERATION_FAILEDOperation failed
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The Bluetooth service must be initialized with bt_initialize().
See also:
bt_initialize()
bt_audio_deinitialize()

Registers a callback function that will be invoked when the connection state is changed.

Since :
2.3
Parameters:
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_INVALID_PARAMETERInvalid parameter
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The Bluetooth audio service must be initialized with bt_audio_initialize().
See also:
bt_audio_initialize()
bt_audio_connection_state_changed_cb()

Unregisters a callback function that will be invoked when the connection state is changed.

Since :
2.3
Returns:
0 on success, otherwise a negative error value.
Return values:
BT_ERROR_NONESuccessful
BT_ERROR_NOT_INITIALIZEDNot initialized
BT_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The Bluetooth audio service must be initialized with bt_audio_initialize().
See also:
bt_audio_initialize()
bt_audio_connection_state_changed_cb()
bt_audio_set_connection_state_changed_cb()