Bluetooth HFP AG Profile

group BT_HFP_AG

Provide BT HFP AG profile interfaces.

Typedefs

typedef enum t_bt_hfp_ag_call_status T_BT_HFP_AG_CALL_STATUS: Define BT HFP AG call status.

typedef enum t_bt_hfp_ag_service_indicator T_BT_HFP_AG_SERVICE_INDICATOR: Define BT HFP AG service indicator.

typedef enum t_bt_hfp_ag_call_indicator T_BT_HFP_AG_CALL_INDICATOR: Define BT HFP AG call indicator.

typedef enum t_bt_hfp_ag_call_setup_indicator T_BT_HFP_AG_CALL_SETUP_INDICATOR: Define BT HFP AG call setup indicator.

typedef enum t_bt_hfp_ag_call_held_indicator T_BT_HFP_AG_CALL_HELD_INDICATOR: Define BT HFP AG call held indicator.

typedef enum t_bt_hfp_ag_roaming_indicator T_BT_HFP_AG_ROAMING_INDICATOR: Define BT HFP AG roaming indicator.

typedef enum t_bt_hfp_ag_current_call_status T_BT_HFP_AG_CURRENT_CALL_STATUS: Define BT HFP AG current call status.

typedef enum t_bt_hfp_ag_current_call_mode T_BT_HFP_AG_CURRENT_CALL_MODE: Define BT HFP AG current call mode.

Enums

enum t_bt_hfp_ag_call_status

Define BT HFP AG call status.

Values:

enumerator BT_HFP_AG_CALL_IDLE: No call in progress.

enumerator BT_HFP_AG_CALL_INCOMING: An incoming call is ongoing.

enumerator BT_HFP_AG_CALL_OUTGOING: An outgoing call is ongoing.

enumerator BT_HFP_AG_CALL_ACTIVE: An active call is in progress.

enumerator BT_HFP_AG_CALL_HELD: A call is held.

enumerator BT_HFP_AG_CALL_ACTIVE_WITH_CALL_WAITING: One call active and another call incoming in three-way calling.

enumerator BT_HFP_AG_CALL_ACTIVE_WITH_CALL_HOLD: One call active and another call held in three-way calling.

enum t_bt_hfp_ag_service_indicator

Define BT HFP AG service indicator.

Values:

enumerator BT_HFP_AG_SERVICE_STATUS_AVAILABLE: Service status of AG is available.

enumerator BT_HFP_AG_SERVICE_STATUS_UNAVAILABLE: Service status of AG is unavailable.

enum t_bt_hfp_ag_call_indicator

Define BT HFP AG call indicator.

Values:

enumerator BT_HFP_AG_NO_CALL_IN_PROGRESS: No call in progress.

enumerator BT_HFP_AG_CALL_IN_PROGRESS: An active call in progress.

enum t_bt_hfp_ag_call_setup_indicator

Define BT HFP AG call setup indicator.

Values:

enumerator BT_HFP_AG_CALL_SETUP_STATUS_IDLE: No call in progress.

enumerator BT_HFP_AG_CALL_SETUP_STATUS_INCOMING_CALL: An incoming call is ongoing.

enumerator BT_HFP_AG_CALL_SETUP_STATUS_OUTGOING_CALL: An outgoing call is ongoing.

enumerator BT_HFP_AG_CALL_SETUP_STATUS_ALERTING: Remote party being alerted in an outgoing call.

enum t_bt_hfp_ag_call_held_indicator

Define BT HFP AG call held indicator.

Values:

enumerator BT_HFP_AG_CALL_HELD_STATUS_IDLE: No call be held.

enumerator BT_HFP_AG_CALL_HELD_STATUS_HOLD_AND_ACTIVE_CALL: One call active and another call held in three-way calling.

enumerator BT_HFP_AG_CALL_HELD_STATUS_HOLD_NO_ACTIVE_CALL: Only one call be held.

enum t_bt_hfp_ag_roaming_indicator

Define BT HFP AG roaming indicator.

Values:

enumerator BT_HFP_AG_ROAMING_STATUS_INACTIVE: Roaming status of AG is inactive.

enumerator BT_HFP_AG_ROAMING_STATUS_ACTIVE: Roaming status of AG is active.

enum t_bt_hfp_ag_current_call_status

Define BT HFP AG current call status.

Values:

enumerator BT_HFP_AG_CURRENT_CALL_STATUS_ACTIVE: Call is in active.

enumerator BT_HFP_AG_CURRENT_CALL_STATUS_HELD: Call is be held.

enumerator BT_HFP_AG_CURRENT_CALL_STATUS_DIALING: An outgoing call is ongoing, outgoing calls only.

enumerator BT_HFP_AG_CURRENT_CALL_STATUS_ALERTING: Remote party being alerted in an outgoing call, outgoing calls only.

enumerator BT_HFP_AG_CURRENT_CALL_STATUS_INCOMING: An incoming call is ongoing, incoming calls only.

enumerator BT_HFP_AG_CURRENT_CALL_STATUS_WAITING: An incoming call is waiting, incoming calls only.

enumerator BT_HFP_AG_CURRENT_CALL_STATUS_CALL_HELD_BY_RSP_AND_HOLD: Call is be held by respond and hold.

enum t_bt_hfp_ag_current_call_mode

Define BT HFP AG current call mode.

Values:

enumerator BT_HFP_AG_CURRENT_CALL_MODE_VOICE: Current call mode is voice.

enumerator BT_HFP_AG_CURRENT_CALL_MODE_DATA: Current call mode is data.

enumerator BT_HFP_AG_CURRENT_CALL_MODE_FAX: Current call mode is facsimile.

Functions

bool bt_hfp_ag_init(uint8_t rfc_hfp_chann_num, uint8_t rfc_hsp_chann_num, uint16_t supported_features, uint8_t supported_codecs)

Initialize HFP AG profile.

Parameters:

link_num -- [in] HFP HF/HSP AG maximum connected link number.
rfc_hfp_chann_num -- [in] RFCOMM channel number used for HFP AG.
rfc_hsp_chann_num -- [in] RFCOMM channel number used for HSP AG.
supported_features -- [in] AG supported features BT_HFP_AG_LOCAL_SUPPORTED_FEATURE.
supported_codecs -- [in] AG supported codecs BT HFP AG Supported Codec Type.

Return values:

true -- HFP AG profile was initialized successfully.
false -- HFP AG profile was failed to initialize.

Returns:

The status of initializing HFP AG profile.

void bt_hfp_ag_deinit(void)

De-initialize HFP AG profile.

Experimental Added Since 2.14.0.0:

bool bt_hfp_ag_connect_req(uint8_t bd_addr[6], uint8_t server_chann, bool is_hfp)

Send an HFP AG connection request.

Parameters:

bd_addr -- [in] Remote BT address.
server_chann -- [in] Server channel which can be found from the SDP info.
is_hfp -- [in] Choose to create an HFP or HSP connection.
- true Create an HFP connection.
- false Create an HSP connection.

Return values:

true -- HFP or HSP connection request was sent successfully.
false -- HFP or HSP connection request was failed to send.

Returns:

The status of sending the HFP or HSP connection request.

bool bt_hfp_ag_connect_cfm(uint8_t bd_addr[6], bool accept)

Send an HFP AG connection confirmation.

Parameters:

bd_addr -- [in] Remote BT address.
accept -- [in] Accept or reject the connection indication.
- true Accept the connection indication.
- false Reject the connection indication.

Return values:

true -- HFP connection confirmation was sent successfully.
false -- HFP connection confirmation was failed to send.

Returns:

The status of sending the HFP connection confirmation.

bool bt_hfp_ag_disconnect_req(uint8_t bd_addr[6])

Send an HFP AG disconnection request.

Parameters:

bd_addr -- [in] Remote BT address.

Return values:

true -- HFP disconnection request was sent successfully.
false -- HFP disconnection request was failed to send.

Returns:

The status of sending the HFP disconnection request.

bool bt_hfp_ag_audio_connect_req(uint8_t bd_addr[6])

Send a request to creat audio connection.

Note

Although the audio connection may be triggered by either AG or HF, the codec connection and the synchronous connection shall always be established by the AG (unless one of the devices is a legacy device). AG implementations that comply with the Hands-Free Profile specification Rev. 0.96, 1.0 or 1.5, shall not indicate support for the codec negotiation feature and shall neither send the +BCS unsolicited response to the HF. In order to guarantee backward compatibility, HFP Rev. x.y implementations shall be able to handle establishment of synchronous connections according to Hands-Free profile specification Rev. 1.0 or 1.5.

Parameters:

bd_addr -- [in] Remote BT address.

Return values:

true -- Command request was sent successfully.
false -- Command request was failed to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_audio_connect_cfm(uint8_t bd_addr[6], bool accept)

Send an audio connection confirmation.

Experimental Added Since 2.14.0.0:

Parameters:

bd_addr -- [in] Remote BT address.
accept -- [in] Accept or reject the audio connection indication.
- true Accept the audio connection indication.
- false Reject the audio connection indication.

Return values:

true -- Audio connection confirmation was sent successfully.
false -- Audio connection confirmation was failed to send.

Returns:

The status of sending audio connection confirmation.

bool bt_hfp_ag_audio_disconnect_req(uint8_t bd_addr[6])

Send a request to disconnect audio connection.

Parameters:

bd_addr -- [in] Remote BT address.

Return values:

true -- Command request was sent successfully.
false -- Command request was failed to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_send_vnd_at_cmd_req(uint8_t bd_addr[6], const char *at_cmd)

Send an vendor AT command request.

Parameters:

bd_addr -- [in] Remote BT address.
at_cmd -- [in] The start address of buffer that stores AT command. AT command string must end with "\r\n".

Return values:

true -- AT command request was sent successfully.
false -- AT command request was failed to send.

Returns:

The status of sending the AT command request.

bool bt_hfp_ag_ok_send(uint8_t bd_addr[6])

Send an OK result code.

Parameters:

bd_addr -- [in] Remote BT address.

Return values:

true -- OK result code was sent successfully.
false -- OK result code was failed to send.

Returns:

The status of sending the OK result code.

bool bt_hfp_ag_error_send(uint8_t bd_addr[6], uint8_t error_code)

Send an Error result code.

Parameters:

bd_addr -- [in] Remote BT address.
error_code -- [in] HFP AG extended audio gateway error result code BT HFP AG Extended Audio Gateway Error Result Code.

Return values:

true -- Error result code was sent successfully.
false -- Error result code was failed to send.

Returns:

The status of sending the error result code.

bool bt_hfp_ag_indicators_send(uint8_t bd_addr[6], T_BT_HFP_AG_SERVICE_INDICATOR service_indicator, T_BT_HFP_AG_CALL_INDICATOR call_indicator, T_BT_HFP_AG_CALL_SETUP_INDICATOR call_setup_indicator, T_BT_HFP_AG_CALL_HELD_INDICATOR call_held_indicator, uint8_t signal_indicator, T_BT_HFP_AG_ROAMING_INDICATOR roaming_indicator, uint8_t batt_chg_indicator)

Send HFP AG indicators during HFP service level connection establishment.

Parameters:

bd_addr -- [in] Remote BT address.
service_indicator -- [in] HFP AG service availability indicator.
call_indicator -- [in] HFP AG standard call status indicator.
call_setup_indicator -- [in] HFP AG call set up status indicator.
call_held_indicator -- [in] HFP AG call hold status indicator.
signal_indicator -- [in] HFP AG signal strength indicator.
roaming_indicator -- [in] HFP AG roaming status indicator.
batt_chg_indicator -- [in] HFP AG battery charge indicator.

Return values:

true -- Request has been sent successfully.
false -- Request was fail to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_call_incoming(uint8_t bd_addr[6], const char *call_num, uint8_t call_num_len, uint8_t call_num_type)

Notify the incoming call.

Parameters:

bd_addr -- [in] Remote BT address.
call_num -- [in] HFP AG incoming call number.
call_num_len -- [in] HFP AG incoming call number length with the maximum of 20 including '\0'.
call_num_type -- [in] HFP AG incoming call number type.

Return values:

true -- Command has been sent successfully.
false -- Command was fail to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_call_answer(uint8_t bd_addr[6])

Answer the incoming or outgoing alerting call.

Parameters:

bd_addr -- [in] Remote BT address.

Return values:

true -- Command has been sent successfully.
false -- Command was fail to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_call_hold(uint8_t bd_addr[6])

Hold the active call.

Experimental Added Since 2.14.0.0:

Parameters:

bd_addr -- [in] Remote BT address.

Return values:

true -- Command has been sent successfully.
false -- Command was fail to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_held_call_accept(uint8_t bd_addr[6])

Accept the held call. The call will be active.

Experimental Added Since 2.14.0.0:

Parameters:

bd_addr -- [in] Remote BT address.

Return values:

true -- Command has been sent successfully.
false -- Command was fail to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_held_call_release(uint8_t bd_addr[6])

Release the held call.

Experimental Added Since 2.14.0.0:

Parameters:

bd_addr -- [in] Remote BT address.

Return values:

true -- Command has been sent successfully.
false -- Command was fail to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_call_terminate(uint8_t bd_addr[6])

Reject the incoming call, terminate the outgoing call, or ongoing call.

Parameters:

bd_addr -- [in] Remote BT address.

Return values:

true -- Command has been sent successfully.
false -- Command was fail to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_call_dial(uint8_t bd_addr[6])

Dial the outgoing call.

Parameters:

bd_addr -- [in] Remote BT address.

Return values:

true -- Command has been sent successfully.
false -- Command was fail to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_call_alert(uint8_t bd_addr[6])

Notify the outgoing call alerted.

Parameters:

bd_addr -- [in] Remote BT address.

Return values:

true -- Command has been sent successfully.
false -- Command was fail to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_call_waiting_send(uint8_t bd_addr[6], const char *call_num, uint8_t call_num_len, uint8_t call_num_type)

Send the call waiting notification.

Parameters:

bd_addr -- [in] Remote BT address.
call_num -- [in] HFP AG call waiting number.
call_num_len -- [in] HFP AG call waiting number length with the maximum of 20 including '\0'.
call_num_type -- [in] HFP AG call waiting number type.

Return values:

true -- Command request was sent successfully.
false -- Command request was failed to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_microphone_gain_set(uint8_t bd_addr[6], uint8_t level)

Set HF microphone volume level.

Parameters:

bd_addr -- [in] Remote BT address.
level -- [in] HF microphone gain level to set that ranges from 0 to 15.

Return values:

true -- Command request was sent successfully.
false -- Command request was failed to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_speaker_gain_set(uint8_t bd_addr[6], uint8_t level)

Set HF speaker volume level.

Parameters:

bd_addr -- [in] Remote BT address.
level -- [in] HF speaker gain level to set that ranges from 0 to 15.

Return values:

true -- Command request was sent successfully.
false -- Command request was failed to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_service_indicator_send(uint8_t bd_addr[6], T_BT_HFP_AG_SERVICE_INDICATOR status)

Send service availability indicator.

Parameters:

bd_addr -- [in] Remote BT address.
status -- [in] HFP AG service availability indicator.

Return values:

true -- Command request was sent successfully.
false -- Command request was failed to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_call_indicator_send(uint8_t bd_addr[6], T_BT_HFP_AG_CALL_INDICATOR status)

Send call indicator.

Parameters:

bd_addr -- [in] Remote BT address.
status -- [in] HFP AG call indicator.

Return values:

true -- Command request was sent successfully.
false -- Command request was failed to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_call_setup_indicator_send(uint8_t bd_addr[6], T_BT_HFP_AG_CALL_SETUP_INDICATOR status)

Send call setup indicator.

Parameters:

bd_addr -- [in] Remote BT address.
status -- [in] HFP AG call setup indicator.

Return values:

true -- Command request was sent successfully.
false -- Command request was failed to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_call_held_indicator_send(uint8_t bd_addr[6], T_BT_HFP_AG_CALL_HELD_INDICATOR status)

Send call hold indicator.

Parameters:

bd_addr -- [in] Remote BT address.
status -- [in] HFP AG call hold indicator.

Return values:

true -- Command request was sent successfully.
false -- Command request was failed to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_signal_strength_send(uint8_t bd_addr[6], uint8_t value)

Send signal strength indicator.

Parameters:

bd_addr -- [in] Remote BT address.
value -- [in] HFP AG signal strength, ranges from 0 to 5.

Return values:

true -- Command request was sent successfully.
false -- Command request was failed to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_roaming_indicator_send(uint8_t bd_addr[6], T_BT_HFP_AG_ROAMING_INDICATOR status)

Send roaming indicator.

Parameters:

bd_addr -- [in] Remote BT address.
status -- [in] HFP AG roaming indicator.

Return values:

true -- Command request was sent successfully.
false -- Command request was failed to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_battery_charge_send(uint8_t bd_addr[6], uint8_t value)

Send battery charge indicator.

Parameters:

bd_addr -- [in] Remote BT address.
value -- [in] HFP AG battery level, ranges from 0 to 5.

Return values:

true -- Command request was sent successfully.
false -- Command request was failed to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_ring_interval_set(uint8_t bd_addr[6], uint16_t interval)

Set AG ring interval.

Parameters:

bd_addr -- [in] Remote BT address.
interval -- [in] AG ring interval in milliseconds with default value as 5000ms.

Return values:

true -- Command request was sent successfully.
false -- Command request was failed to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_inband_ringing_set(uint8_t bd_addr[6], bool enable)

Change HFP or HSP AG in-band ring tone setting dynamically after service level connection establishment.

Parameters:

bd_addr -- [in] Remote BT address.
enable -- [in] Enable HFP or HSP AG in-band ring tone or not dynamically.

Return values:

true -- Success to change HFP or HSP AG in-band ring tone setting dynamically.
false -- Failed to change HFP or HSP AG in-band ring tone setting dynamically.

Returns:

The status of changing HFP or HSP AG in-band ring tone setting dynamically.

bool bt_hfp_ag_current_calls_list_send(uint8_t bd_addr[6], uint8_t call_idx, uint8_t call_dir, T_BT_HFP_AG_CURRENT_CALL_STATUS call_status, T_BT_HFP_AG_CURRENT_CALL_MODE call_mode, uint8_t mpty, const char *call_num, uint8_t call_num_type)

Send HFP AG current calls list.

Parameters:

bd_addr -- [in] Remote BT address.
call_idx -- [in] HFP AG current call index.
call_dir -- [in] HFP AG current call direction.
- 0 outgoing.
- 1 incoming.
call_status -- [in] HFP AG current call status.
call_mode -- [in] HFP AG current call mode.
mpty -- [in] HFP AG current multi-party call or not.
- 0 this call is not a member of a multi-party (conference) call.
- 1 this call IS a member of a multi-party (conference) call.
call_num -- [in] HFP AG current call number.
call_num_type -- [in] HFP AG current call number type.

Return values:

true -- Command request was sent successfully.
false -- Command request was failed to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_network_operator_name_send(uint8_t bd_addr[6], const char *operator, uint8_t operator_len)

Indicate the currently selected operator.

Parameters:

bd_addr -- [in] Remote BT address.
operator -- [in] HFP AG the currently selected operator.
operator_len -- [in] HFP AG the currently selected operator length with the maximum of 17 including '\0'.

Return values:

true -- Command has been sent successfully.
false -- Command was fail to send.

Returns:

The status of sending the command request.

bool bt_hfp_ag_subscriber_number_send(uint8_t bd_addr[6], const char *call_num, uint8_t call_num_len, uint8_t call_num_type, uint8_t service)

Send subscriber number information.

Parameters:

bd_addr -- [in] Remote BT address.
call_num -- [in] HFP AG subscriber number.
call_num_len -- [in] HFP AG subscriber number length with the maximum of 20 including '\0'.
call_num_type -- [in] HFP AG subscriber number type.
service -- [in] HFP AG service the subscriber number relates to, Shall be either 4 (voice) or 5 (fax).

Return values:

true -- Command has been sent successfully.
false -- Command was fail to send.

Returns:

The status of sending the command request.

BT HFP HF Supported Codec Type

BT HFP AG Remote Supported Features

BT HFP AG Extended Audio Gateway Error Result Code

BT HFP AG Supported Codec Type