bt_hfp_ag_cb Struct Reference

HFP profile AG application callback. More...

#include <zephyr/bluetooth/classic/hfp_ag.h>

Data Fields
void(*	connected )(struct bt_conn *conn, struct bt_hfp_ag *ag)
	HF AG connected callback to application.
void(*	disconnected )(struct bt_hfp_ag *ag)
	HF disconnected callback to application.
void(*	sco_connected )(struct bt_hfp_ag *ag, struct bt_conn *sco_conn)
	HF SCO/eSCO connected Callback.
void(*	sco_disconnected )(struct bt_conn *sco_conn, uint8_t reason)
	HF SCO/eSCO disconnected Callback.
int(*	get_indicator_value )(struct bt_hfp_ag *ag, uint8_t *service, uint8_t *strength, uint8_t *roam, uint8_t *battery)
	Get indicator values callback.
int(*	get_ongoing_call )(struct bt_hfp_ag *ag)
	Get ongoing call information Callback.
int(*	memory_dial )(struct bt_hfp_ag *ag, const char *location, char **number)
	HF memory dialing request Callback.
int(*	number_call )(struct bt_hfp_ag *ag, const char *number)
	HF phone number calling request Callback.
int(*	redial )(struct bt_hfp_ag *ag, char number[CONFIG_BT_HFP_AG_PHONE_NUMBER_MAX_LEN+1])
	HF last number redial request Callback.
void(*	outgoing )(struct bt_hfp_ag *ag, struct bt_hfp_ag_call *call, const char *number)
	HF outgoing Callback.
void(*	incoming )(struct bt_hfp_ag *ag, struct bt_hfp_ag_call *call, const char *number)
	HF incoming Callback.
void(*	incoming_held )(struct bt_hfp_ag_call *call)
	HF incoming call is held Callback.
void(*	ringing )(struct bt_hfp_ag_call *call, bool in_band)
	HF ringing Callback.
void(*	accept )(struct bt_hfp_ag_call *call)
	HF call accept Callback.
void(*	held )(struct bt_hfp_ag_call *call)
	HF call held Callback.
void(*	retrieve )(struct bt_hfp_ag_call *call)
	HF call retrieve Callback.
void(*	reject )(struct bt_hfp_ag_call *call)
	HF call reject Callback.
void(*	terminate )(struct bt_hfp_ag_call *call)
	HF call terminate Callback.
void(*	codec )(struct bt_hfp_ag *ag, uint32_t ids)
	Supported codec Ids callback.
void(*	codec_negotiate )(struct bt_hfp_ag *ag, int err)
	Codec negotiate callback.
void(*	audio_connect_req )(struct bt_hfp_ag *ag)
	Audio connection request callback.
void(*	vgm )(struct bt_hfp_ag *ag, uint8_t gain)
	HF VGM setting callback.
void(*	vgs )(struct bt_hfp_ag *ag, uint8_t gain)
	HF VGS setting callback.
void(*	ecnr_turn_off )(struct bt_hfp_ag *ag)
	HF ECNR turns off callback.
void(*	explicit_call_transfer )(struct bt_hfp_ag *ag)
	HF explicit call transfer callback.
void(*	voice_recognition )(struct bt_hfp_ag *ag, bool activate)
	Voice recognition activation/deactivation callback.
void(*	ready_to_accept_audio )(struct bt_hfp_ag *ag)
	Ready to accept audio callback.
int(*	request_phone_number )(struct bt_hfp_ag *ag, char **number)
	Request phone number callback.
void(*	transmit_dtmf_code )(struct bt_hfp_ag *ag, char code)
	Transmit a DTMF Code callback.
int(*	subscriber_number )(struct bt_hfp_ag *ag, bt_hfp_ag_query_subscriber_func_t func)
	Get subscriber number callback.
void(*	hf_indicator_value )(struct bt_hfp_ag *ag, enum hfp_ag_hf_indicators indicator, uint32_t value)
	HF indicator value callback.

Detailed Description

HFP profile AG application callback.

Field Documentation

accept

void(* bt_hfp_ag_cb::accept) (struct bt_hfp_ag_call *call)

HF call accept Callback.

If this callback is provided it will be called whenever the call is accepted.

Parameters

call	HFP AG call object.

audio_connect_req

void(* bt_hfp_ag_cb::audio_connect_req) (struct bt_hfp_ag *ag)

Audio connection request callback.

If this callback is provided it will be called whenever the audio conenction request is triggered by HF. When AT+BCC AT command received, it means the procedure of establishment of audio connection is triggered by HF. If the callback is provided by application, AG needs to start the codec connection procedure by calling function bt_hfp_ag_audio_connect in application layer. Or, the codec conenction procedure will be started with default codec id BT_HFP_AG_CODEC_CVSD.

Parameters

ag	HFP AG object.
err	Result of codec negotiation.

codec

void(* bt_hfp_ag_cb::codec) (struct bt_hfp_ag *ag, uint32_t ids)

Supported codec Ids callback.

If this callback is provided it will be called whenever the supported codec ids are updated.

Parameters

ag	HFP AG object.

codec_negotiate

void(* bt_hfp_ag_cb::codec_negotiate) (struct bt_hfp_ag *ag, int err)

Codec negotiate callback.

If this callback is provided it will be called whenever the codec negotiation succeeded or failed.

Parameters

ag	HFP AG object.
err	Result of codec negotiation.

connected

void(* bt_hfp_ag_cb::connected) (struct bt_conn *conn, struct bt_hfp_ag *ag)

HF AG connected callback to application.

If this callback is provided it will be called whenever the AG connection completes.

Parameters

conn	Connection object.
ag	HFP AG object.

disconnected

void(* bt_hfp_ag_cb::disconnected) (struct bt_hfp_ag *ag)

HF disconnected callback to application.

If this callback is provided it will be called whenever the connection gets disconnected, including when a connection gets rejected or cancelled or any error in SLC establishment.

Parameters

ag	HFP AG object.

ecnr_turn_off

void(* bt_hfp_ag_cb::ecnr_turn_off) (struct bt_hfp_ag *ag)

HF ECNR turns off callback.

If this callback is provided it will be called whenever the ECNR turning off request is received from HF. If the callback is NULL or CONFIG_BT_HFP_AG_ECNR is not enabled, the response result code of AT command will be an AT ERROR.

Parameters

ag	HFP AG object.

explicit_call_transfer

void(* bt_hfp_ag_cb::explicit_call_transfer) (struct bt_hfp_ag *ag)

HF explicit call transfer callback.

If this callback is provided it will be called whenever the AT+CHLD=4 is sent from HF. When the callback is notified, the application should connect the two calls and disconnects the subscriber from both calls (Explicit Call Transfer). After the callback returned, the call objects will be invalid. If the callback is NULL, the response result code of AT command will be an AT ERROR. If CONFIG_BT_HFP_AG_3WAY_CALL is not enabled, the callback will not be notified.

Parameters

ag	HFP AG object.

get_indicator_value

int(* bt_hfp_ag_cb::get_indicator_value) (struct bt_hfp_ag *ag, uint8_t *service, uint8_t *strength, uint8_t *roam, uint8_t *battery)

Get indicator values callback.

If this callback is provided it will be called whenever the AG needs to provide current indicator values to the HF. This typically occurs when the HF sends AT+CIND? command to query the current status of AG indicators.

The application should populate the indicator values through the provided pointers. All indicator values should be set according to the current status of the AG.

Parameters

ag	HFP AG object.
service	Pointer to store service availability indicator value. 0 = service is not available, 1 = service is available.
strength	Pointer to store signal strength indicator value. Range: 0-5 (0 = no signal, 5 = maximum signal).
roam	Pointer to store roaming status indicator value. 0 = not roaming, 1 = roaming.
battery	Pointer to store battery level indicator value. Range: 0-5 (0 = battery exhausted, 5 = battery full).

Note

The AG is in SLC establishment phase. The AG callback connected() is not notified at this time.

If the callback is not provided by the application or the returned error is no zero, the value of these all indicators will be set to 0 by default. And the specific can be set and notified by calling the dedicated function. Such as service availability indicator value can be set by calling the function bt_hfp_ag_service_availability(). The signal strength value can be set by calling bt_hfp_ag_signal_strength(), and so on.

Returns

0 in case of success or negative value in case of error.

get_ongoing_call

int(* bt_hfp_ag_cb::get_ongoing_call) (struct bt_hfp_ag *ag)

Get ongoing call information Callback.

If this callback is provided it will be called whenever the AT command AT+CIND? is received from HF has been sent. After the callback notified, the ongoing calls should be set via function bt_hfp_ag_ongoing_calls() within the timeout CONFIG_BT_HFP_AG_GET_ONGOING_CALL_TIMEOUT.

Parameters

ag	HFP AG object.

Note

The AG is in SLC establishment phase. The AG callback connected() is not notified at this time.

Returns

0 in case of success. The response +CIND will be sent after the function bt_hfp_ag_ongoing_calls() called or after the time exceeds CONFIG_BT_HFP_AG_GET_ONGOING_CALL_TIMEOUT. Or negative value in case of error. The response +CIND will be replied immediately.

held

void(* bt_hfp_ag_cb::held) (struct bt_hfp_ag_call *call)

HF call held Callback.

If this callback is provided it will be called whenever the call is held.

Parameters

call	HFP AG call object.

hf_indicator_value

void(* bt_hfp_ag_cb::hf_indicator_value) (struct bt_hfp_ag *ag, enum hfp_ag_hf_indicators indicator, uint32_t value)

HF indicator value callback.

If this callback is provided it will be called whenever the AT command AT+BIEV is received. If CONFIG_BT_HFP_AG_HF_INDICATORS is not enabled, the callback will not be notified.

Parameters

ag	HFP AG object.
indicator	HF indicator
value	The value of specific indicator

incoming

void(* bt_hfp_ag_cb::incoming) (struct bt_hfp_ag *ag, struct bt_hfp_ag_call *call, const char *number)

HF incoming Callback.

If this callback is provided it will be called whenever a new call is incoming.

Parameters

ag	HFP AG object.
call	HFP AG call object.
number	Incoming number

incoming_held

void(* bt_hfp_ag_cb::incoming_held) (struct bt_hfp_ag_call *call)

HF incoming call is held Callback.

If this callback is provided it will be called whenever the incoming call is held but not accepted.

Parameters

call	HFP AG call object.

memory_dial

int(* bt_hfp_ag_cb::memory_dial) (struct bt_hfp_ag *ag, const char *location, char **number)

HF memory dialing request Callback.

If this callback is provided it will be called whenever a new call is requested with memory dialing from HF. Get the phone number according to the given AG memory location.

Parameters

ag	HFP AG object.
location	AG memory location
number	Dialing number

Returns

0 in case of success or negative value in case of error.

number_call

int(* bt_hfp_ag_cb::number_call) (struct bt_hfp_ag *ag, const char *number)

HF phone number calling request Callback.

If this callback is provided it will be called whenever a new call is requested with specific phone number from HF. When the callback is triggered, the application needs to start dialing the number with the passed phone number. If the callback is invalid, the phone number dialing from HF cannot be supported.

Parameters

ag	HFP AG object.
number	Dialing number

Returns

0 in case of success or negative value in case of error.

outgoing

void(* bt_hfp_ag_cb::outgoing) (struct bt_hfp_ag *ag, struct bt_hfp_ag_call *call, const char *number)

HF outgoing Callback.

If this callback is provided it will be called whenever a new call is outgoing.

Parameters

ag	HFP AG object.
call	HFP AG call object.
number	Dialing number

ready_to_accept_audio

void(* bt_hfp_ag_cb::ready_to_accept_audio) (struct bt_hfp_ag *ag)

Ready to accept audio callback.

If this callback is provided it will be called whenever the HF is ready to accept audio. If the feature Enhanced Voice Recognition Status is supported by HF, the callback will be notified if the AT command AT+BVRA=2 is received. The HF may send this value during an ongoing VR (Voice Recognition) session to terminate audio output from the AG (if there is any) and prepare the AG for new audio input. Or, the callback will be notified after the voice recognition is activated. If CONFIG_BT_HFP_AG_ENH_VOICE_RECG is not enabled, the callback will not be notified.

Parameters

ag	HFP AG object.

redial

int(* bt_hfp_ag_cb::redial) (struct bt_hfp_ag *ag, char number[CONFIG_BT_HFP_AG_PHONE_NUMBER_MAX_LEN+1])

HF last number redial request Callback.

If this callback is provided it will be called whenever a last number redial request is received from HF via AT+BLDN command. When the callback is triggered, the application needs to provide the last dialed phone number. If the callback is invalid, the last number redial from HF cannot be supported.

The application should:

1. Retrieve the last dialed phone number from its call history
2. Copy the phone number to the provided buffer

Parameters

ag	HFP AG object.
number	Buffer to store the last dialed phone number. The buffer size is BT_HFP_AG_PHONE_NUMBER_MAX_LEN + 1, and should be null-terminated.

Returns

0 in case of success or negative value in case of error. If successful, the AG will proceed with the call setup procedure. If error, an ERROR response will be sent to HF.

reject

void(* bt_hfp_ag_cb::reject) (struct bt_hfp_ag_call *call)

HF call reject Callback.

If this callback is provided it will be called whenever the call is rejected.

Parameters

call	HFP AG call object.

request_phone_number

int(* bt_hfp_ag_cb::request_phone_number) (struct bt_hfp_ag *ag, char **number)

Request phone number callback.

If this callback is provided it will be called whenever the AT command AT+BINP=1 is received. If the upper layer accepts the request, it shall obtain a phone number. If the upper layer rejects the request, it shall return a an error. If CONFIG_BT_HFP_AG_VOICE_TAG is not enabled, the callback will not be notified.

Parameters

ag	HFP AG object.
number	Phone number of voice tag.

Returns

0 in case of success or negative value in case of error.

retrieve

void(* bt_hfp_ag_cb::retrieve) (struct bt_hfp_ag_call *call)

HF call retrieve Callback.

If this callback is provided it will be called whenever the call is retrieved.

Parameters

call	HFP AG call object.

ringing

void(* bt_hfp_ag_cb::ringing) (struct bt_hfp_ag_call *call, bool in_band)

HF ringing Callback.

If this callback is provided it will be called whenever the call is in the ringing

Parameters

call	HFP AG call object.
in_bond	true - in-bond ringing, false - No in-bond ringing

sco_connected

void(* bt_hfp_ag_cb::sco_connected) (struct bt_hfp_ag *ag, struct bt_conn *sco_conn)

HF SCO/eSCO connected Callback.

If this callback is provided it will be called whenever the SCO/eSCO connection completes.

Parameters

ag	HFP AG object.
sco_conn	SCO/eSCO Connection object.

sco_disconnected

void(* bt_hfp_ag_cb::sco_disconnected) (struct bt_conn *sco_conn, uint8_t reason)

HF SCO/eSCO disconnected Callback.

If this callback is provided it will be called whenever the SCO/eSCO connection gets disconnected.

Parameters

conn	SCO/eSCO Connection object.
reason	BT_HCI_ERR_* reason for the disconnection.

subscriber_number

int(* bt_hfp_ag_cb::subscriber_number) (struct bt_hfp_ag *ag, bt_hfp_ag_query_subscriber_func_t func)

Get subscriber number callback.

If this callback is provided it will be called whenever the AT command AT+CNUM is received.

Parameters

ag	HFP AG object.
func	Query subscriber number callback.

Returns

0 in case of success or negative value in case of error.

terminate

void(* bt_hfp_ag_cb::terminate) (struct bt_hfp_ag_call *call)

HF call terminate Callback.

If this callback is provided it will be called whenever the call is terminated.

Parameters

call	HFP AG call object.

transmit_dtmf_code

void(* bt_hfp_ag_cb::transmit_dtmf_code) (struct bt_hfp_ag *ag, char code)

Transmit a DTMF Code callback.

If this callback is provided it will be called whenever the AT command AT+VTS=<code> is received. During an ongoing call, the HF transmits the AT+VTS command to instruct the AG to transmit a specific DTMF code to its network connection.

Parameters

ag	HFP AG object.
code	A specific DTMF code.

vgm

void(* bt_hfp_ag_cb::vgm) (struct bt_hfp_ag *ag, uint8_t gain)

HF VGM setting callback.

If this callback is provided it will be called whenever the VGM gain setting is informed from HF.

Parameters

ag	HFP AG object.
gain	HF microphone gain value.

vgs

void(* bt_hfp_ag_cb::vgs) (struct bt_hfp_ag *ag, uint8_t gain)

HF VGS setting callback.

If this callback is provided it will be called whenever the VGS gain setting is informed from HF.

Parameters

ag	HFP AG object.
gain	HF speaker gain value.

voice_recognition

void(* bt_hfp_ag_cb::voice_recognition) (struct bt_hfp_ag *ag, bool activate)

Voice recognition activation/deactivation callback.

If this callback is provided it will be called whenever the voice recognition activation is changed. If voice recognition is activated, the upper layer should call bt_hfp_ag_audio_connect with appropriate codec ID to setup audio connection. If the callback is not provided by upper layer, the function bt_hfp_ag_audio_connect will be called with default codec ID BT_HFP_AG_CODEC_CVSD. If CONFIG_BT_HFP_AG_VOICE_RECG is not enabled, the callback will not be notified.

Parameters

ag	HFP AG object.
activate	Voice recognition activation/deactivation.

---

The documentation for this struct was generated from the following file:

• zephyr/bluetooth/classic/hfp_ag.h