1 /* 2 * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef __ESP_HF_AG_API_H__ 8 #define __ESP_HF_AG_API_H__ 9 10 #include "esp_err.h" 11 #include "esp_bt_defs.h" 12 #include "esp_hf_defs.h" 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 /* features masks of HF AG */ 19 #define ESP_HF_PEER_FEAT_3WAY 0x01 /* Three-way calling */ 20 #define ESP_HF_PEER_FEAT_ECNR 0x02 /* Echo cancellation and/or noise reduction */ 21 #define ESP_HF_PEER_FEAT_VREC 0x04 /* Voice recognition */ 22 #define ESP_HF_PEER_FEAT_INBAND 0x08 /* In-band ring tone */ 23 #define ESP_HF_PEER_FEAT_VTAG 0x10 /* Attach a phone number to a voice tag */ 24 #define ESP_HF_PEER_FEAT_REJECT 0x20 /* Ability to reject incoming call */ 25 #define ESP_HF_PEER_FEAT_ECS 0x40 /* Enhanced Call Status */ 26 #define ESP_HF_PEER_FEAT_ECC 0x80 /* Enhanced Call Control */ 27 #define ESP_HF_PEER_FEAT_EXTERR 0x100 /* Extended error codes */ 28 #define ESP_HF_PEER_FEAT_CODEC 0x200 /* Codec Negotiation */ 29 /* HFP 1.7+ */ 30 #define ESP_HF_PEER_FEAT_HF_IND 0x400 /* HF Indicators */ 31 #define ESP_HF_PEER_FEAT_ESCO_S4 0x800 /* eSCO S4 Setting Supported */ 32 33 34 /* CHLD feature masks of HF AG */ 35 #define ESP_HF_CHLD_FEAT_REL 0x01 /* 0 Release waiting call or held calls */ 36 #define ESP_HF_CHLD_FEAT_REL_ACC 0x02 /* 1 Release active calls and accept other waiting or held call */ 37 #define ESP_HF_CHLD_FEAT_REL_X 0x04 /* 1x Release specified active call only */ 38 #define ESP_HF_CHLD_FEAT_HOLD_ACC 0x08 /* 2 Active calls on hold and accept other waiting or held call */ 39 #define ESP_HF_CHLD_FEAT_PRIV_X 0x10 /* 2x Request private mode with specified call(put the rest on hold) */ 40 #define ESP_HF_CHLD_FEAT_MERGE 0x20 /* 3 Add held call to multiparty */ 41 #define ESP_HF_CHLD_FEAT_MERGE_DETACH 0x40 /* 4 Connect two calls and leave(disconnect from multiparty) */ 42 43 /// HF callback events 44 typedef enum 45 { 46 ESP_HF_CONNECTION_STATE_EVT = 0, /*!< Connection state changed event */ 47 ESP_HF_AUDIO_STATE_EVT, /*!< Audio connection state change event */ 48 ESP_HF_BVRA_RESPONSE_EVT, /*!< Voice recognition state change event */ 49 ESP_HF_VOLUME_CONTROL_EVT, /*!< Audio volume control command from HF Client, provided by +VGM or +VGS message */ 50 51 ESP_HF_UNAT_RESPONSE_EVT, /*!< Unknown AT cmd Response*/ 52 ESP_HF_IND_UPDATE_EVT, /*!< Indicator Update Event*/ 53 ESP_HF_CIND_RESPONSE_EVT, /*!< Call And Device Indicator Response*/ 54 ESP_HF_COPS_RESPONSE_EVT, /*!< Current operator information */ 55 ESP_HF_CLCC_RESPONSE_EVT, /*!< List of current calls notification */ 56 ESP_HF_CNUM_RESPONSE_EVT, /*!< Subscriber information response from HF Client */ 57 ESP_HF_VTS_RESPONSE_EVT, /*!< Enable or not DTMF */ 58 ESP_HF_NREC_RESPONSE_EVT, /*!< Enable or not NREC */ 59 60 ESP_HF_ATA_RESPONSE_EVT, /*!< Answer an Incoming Call */ 61 ESP_HF_CHUP_RESPONSE_EVT, /*!< Reject an Incoming Call */ 62 ESP_HF_DIAL_EVT, /*!< Origin an outgoing call with specific number or the dial the last number */ 63 ESP_HF_WBS_RESPONSE_EVT, /*!< Codec Status */ 64 ESP_HF_BCS_RESPONSE_EVT, /*!< Final Codec Choice */ 65 ESP_HF_PKT_STAT_NUMS_GET_EVT, /*!< Request number of packet different status */ 66 ESP_HF_PROF_STATE_EVT, /*!< Indicate HF init or deinit complete */ 67 } esp_hf_cb_event_t; 68 69 /// Dial type of ESP_HF_DIAL_EVT 70 typedef enum 71 { 72 ESP_HF_DIAL_NUM = 0, /*!< Dial with a phone number */ 73 ESP_HF_DIAL_VOIP, /*!< Dial with VoIP */ 74 ESP_HF_DIAL_MEM, /*!< Dial with a memory position */ 75 } esp_hf_dial_type_t; 76 77 /// HFP AG callback parameters 78 typedef union 79 { 80 /** 81 * @brief ESP_HF_CONNECTION_STATE_EVT 82 */ 83 struct hf_conn_stat_param { 84 esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ 85 esp_hf_connection_state_t state; /*!< Connection state */ 86 uint32_t peer_feat; /*!< HF supported features */ 87 uint32_t chld_feat; /*!< AG supported features on call hold and multiparty services */ 88 } conn_stat; /*!< AG callback param of ESP_HF_CONNECTION_STATE_EVT */ 89 90 /** 91 * @brief ESP_HF_AUDIO_STATE_EVT 92 */ 93 struct hf_audio_stat_param { 94 esp_bd_addr_t remote_addr; /*!< Remote bluetooth device address */ 95 esp_hf_audio_state_t state; /*!< Audio connection state */ 96 uint16_t sync_conn_handle; /*!< (e)SCO connection handle */ 97 } audio_stat; /*!< AG callback param of ESP_HF_AUDIO_STATE_EVT */ 98 99 /** 100 * @brief ESP_HF_BVRA_RESPONSE_EVT 101 */ 102 struct hf_vra_rep_param { 103 esp_bd_addr_t remote_addr; /*!< Remote bluetooth device address */ 104 esp_hf_vr_state_t value; /*!< Voice recognition state */ 105 } vra_rep; /*!< AG callback param of ESP_HF_BVRA_RESPONSE_EVT */ 106 107 /** 108 * @brief ESP_HF_VOLUME_CONTROL_EVT 109 */ 110 struct hf_volume_control_param { 111 esp_bd_addr_t remote_addr; /*!< Remote bluetooth device address */ 112 esp_hf_volume_type_t type; /*!< Volume control target, speaker or microphone */ 113 int volume; /*!< Gain, ranges from 0 to 15 */ 114 } volume_control; /*!< AG callback param of ESP_HF_VOLUME_CONTROL_EVT */ 115 116 /** 117 * @brief ESP_HF_UNAT_RESPONSE_EVT 118 */ 119 struct hf_unat_rep_param { 120 esp_bd_addr_t remote_addr; /*!< Remote bluetooth device address */ 121 char *unat; /*!< Unknown AT command string */ 122 } unat_rep; /*!< AG callback param of ESP_HF_UNAT_RESPONSE_EVT */ 123 124 /** 125 * @brief ESP_HF_DIAL_EVT 126 */ 127 struct hf_out_call_param { 128 esp_bd_addr_t remote_addr; /*!< remote bluetooth device address */ 129 esp_hf_dial_type_t type; /*!< dial type */ 130 char *num_or_loc; /*!< location in phone memory */ 131 } out_call; /*!< AG callback param of ESP_HF_DIAL_EVT */ 132 133 /** 134 * @brief ESP_HF_IND_UPDATE_EVT 135 */ 136 struct hf_ind_upd_param { 137 esp_bd_addr_t remote_addr; /*!< remote bluetooth device address */ 138 } ind_upd; /*!< AG callback param of ESP_HF_IND_UPDATE_EVT */ 139 140 /** 141 * @brief ESP_HF_CIND_RESPONSE_EVT 142 */ 143 struct hf_cind_rep_param { 144 esp_bd_addr_t remote_addr; /*!< remote bluetooth device address */ 145 } cind_rep; /*!< AG callback param of ESP_HF_CIND_RESPONSE_EVT */ 146 147 /** 148 * @brief ESP_HF_COPS_RESPONSE_EVT 149 */ 150 struct hf_cops_rep_param { 151 esp_bd_addr_t remote_addr; /*!< remote bluetooth device address */ 152 } cops_rep; /*!< AG callback param of ESP_HF_COPS_RESPONSE_EVT */ 153 154 /** 155 * @brief ESP_HF_CLCC_RESPONSE_EVT 156 */ 157 struct hf_clcc_rep_param { 158 esp_bd_addr_t remote_addr; /*!< remote bluetooth device address */ 159 } clcc_rep; /*!< AG callback param of ESP_HF_CLCC_RESPONSE_EVT */ 160 161 /** 162 * @brief ESP_HF_CNUM_RESPONSE_EVT 163 */ 164 struct hf_cnum_rep_param { 165 esp_bd_addr_t remote_addr; /*!< remote bluetooth device address */ 166 } cnum_rep; /*!< AG callback param of ESP_HF_CNUM_RESPONSE_EVT */ 167 168 /** 169 * @brief ESP_HF_VTS_RESPONSE_EVT 170 */ 171 struct hf_vts_rep_param { 172 esp_bd_addr_t remote_addr; /*!< Remote bluetooth device address */ 173 char *code; /*!< MTF code from HF Client */ 174 } vts_rep; /*!< AG callback param of ESP_HF_VTS_RESPONSE_EVT */ 175 176 /** 177 * @brief ESP_HF_NREC_RESPONSE_EVT 178 */ 179 struct hf_nrec_param { 180 esp_bd_addr_t remote_addr; /*!< Remote bluetooth device address */ 181 esp_hf_nrec_t state; /*!< NREC enabled or disabled */ 182 } nrec; /*!< AG callback param of ESP_HF_NREC_RESPONSE_EVT */ 183 184 /** 185 * @brief ESP_HF_ATA_RESPONSE_EVT 186 */ 187 struct hf_ata_rep_param { 188 esp_bd_addr_t remote_addr; /*!< remote bluetooth device address */ 189 } ata_rep; /*!< AG callback param of ESP_HF_ATA_RESPONSE_EVT */ 190 191 /** 192 * @brief ESP_HF_CHUP_RESPONSE_EVT 193 */ 194 struct hf_chup_rep_param { 195 esp_bd_addr_t remote_addr; /*!< remote bluetooth device address */ 196 } chup_rep; /*!< AG callback param of ESP_HF_CHUP_RESPONSE_EVT */ 197 198 /** 199 * @brief ESP_HF_WBS_RESPONSE_EVT 200 */ 201 struct hf_wbs_rep_param { 202 esp_bd_addr_t remote_addr; /*!< Remote bluetooth device address */ 203 esp_hf_wbs_config_t codec; /*!< codec mode CVSD or mSBC */ 204 } wbs_rep; /*!< AG callback param of ESP_HF_WBS_RESPONSE_EVT */ 205 206 /** 207 * @brief ESP_HF_BCS_RESPONSE_EVT 208 */ 209 struct hf_bcs_rep_param { 210 esp_bd_addr_t remote_addr; /*!< Remote bluetooth device address */ 211 esp_hf_wbs_config_t mode; /*!< codec mode CVSD or mSBC */ 212 } bcs_rep; /*!< AG callback param of ESP_HF_BCS_RESPONSE_EVT */ 213 214 /** 215 * @brief ESP_HF_PKT_STAT_NUMS_GET_EVT 216 */ 217 struct ag_pkt_status_nums { 218 uint32_t rx_total; /*!< the total number of packets received */ 219 uint32_t rx_correct; /*!< the total number of packets data correctly received */ 220 uint32_t rx_err; /*!< the total number of packets data with possible invalid */ 221 uint32_t rx_none; /*!< the total number of packets data no received */ 222 uint32_t rx_lost; /*!< the total number of packets data partially lost */ 223 uint32_t tx_total; /*!< the total number of packets send */ 224 uint32_t tx_discarded; /*!< the total number of packets send lost */ 225 } pkt_nums; /*!< AG callback param of ESP_HF_PKT_STAT_NUMS_GET_EVT */ 226 227 /** 228 * @brief ESP_HF_PROF_STATE_EVT 229 */ 230 struct ag_prof_stat_param { 231 esp_hf_prof_state_t state; /*!< hf profile state param */ 232 } prof_stat; /*!< status to indicate hf prof init or deinit */ 233 234 } esp_hf_cb_param_t; /*!< HFP AG callback param compound*/ 235 236 /** 237 * @brief AG incoming data callback function, the callback is useful in case of 238 * Voice Over HCI. 239 * 240 * @param[in] buf : pointer to incoming data(payload of HCI synchronous data packet), the 241 * buffer is allocated inside bluetooth protocol stack and will be released after 242 * invoke of the callback is finished. 243 * 244 * @param[in] len : size(in bytes) in buf 245 */ 246 typedef void (* esp_hf_incoming_data_cb_t)(const uint8_t *buf, uint32_t len); 247 248 /** 249 * @brief AG outgoing data callback function, the callback is useful in case of 250 * Voice Over HCI. Once audio connection is set up and the application layer has 251 * prepared data to send, the lower layer will call this function to read data 252 * and then send. This callback is supposed to be implemented as non-blocking, 253 * and if data is not enough, return value 0 is supposed. 254 * 255 * @param[in] buf : pointer to incoming data(payload of HCI synchronous data packet), the 256 * buffer is allocated inside bluetooth protocol stack and will be released after 257 * invoke of the callback is finished. 258 * 259 * @param[in] len : size(in bytes) in buf 260 * 261 * @return length of data successfully read 262 */ 263 typedef uint32_t (* esp_hf_outgoing_data_cb_t) (uint8_t *buf, uint32_t len); 264 265 /** 266 * @brief HF AG callback function type 267 * 268 * @param event : Event type 269 * 270 * @param param : Pointer to callback parameter 271 */ 272 typedef void (* esp_hf_cb_t) (esp_hf_cb_event_t event, esp_hf_cb_param_t *param); 273 274 /************************************************************************************ 275 ** ESP HF API 276 ************************************************************************************/ 277 /** 278 * @brief Register application callback function to HFP AG module. 279 * This function should be called only after esp_bluedroid_enable() completes successfully. 280 * 281 * @param[in] callback: HFP AG event callback function 282 * 283 * @return 284 * - ESP_OK: success 285 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 286 * - ESP_FAIL: if callback is a NULL function pointer 287 * 288 */ 289 esp_err_t esp_hf_ag_register_callback(esp_hf_cb_t callback); 290 291 /** 292 * 293 * @brief Initialize the bluetooth HF AG module. 294 * This function should be called after esp_bluedroid_enable() completes successfully. 295 * ESP_HF_PROF_STATE_EVT with ESP_HF_INIT_SUCCESS will reported to the APP layer. 296 * 297 * @return 298 * - ESP_OK: if the initialization request is sent successfully 299 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 300 * - ESP_FAIL: others 301 * 302 */ 303 esp_err_t esp_hf_ag_init(void); 304 305 /** 306 * 307 * @brief De-initialize for HF AG module. 308 * This function should be called only after esp_bluedroid_enable() completes successfully. 309 * ESP_HF_PROF_STATE_EVT with ESP_HF_DEINIT_SUCCESS will reported to the APP layer. 310 * 311 * @return 312 * - ESP_OK: success 313 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 314 * - ESP_FAIL: others 315 * 316 */ 317 esp_err_t esp_hf_ag_deinit(void); 318 319 /** 320 * 321 * @brief To establish a Service Level Connection to remote bluetooth HFP client device. 322 * This function must be called after esp_hf_ag_init() and before esp_hf_ag_deinit(). 323 * 324 * @param[in] remote_bda: remote bluetooth HFP client device address 325 * 326 * @return 327 * - ESP_OK: connect request is sent to lower layer 328 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 329 * - ESP_FAIL: others 330 * 331 */ 332 esp_err_t esp_hf_ag_slc_connect(esp_bd_addr_t remote_bda); 333 334 /** 335 * 336 * @brief Disconnect from the remote HFP client. This function must be called 337 * after esp_hf_ag_init() and before esp_hf_ag_deinit(). 338 * 339 * @param[in] remote_bda: remote bluetooth device address 340 * 341 * @return 342 * - ESP_OK: disconnect request is sent to lower layer 343 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 344 * - ESP_FAIL: others 345 * 346 */ 347 esp_err_t esp_hf_ag_slc_disconnect(esp_bd_addr_t remote_bda); 348 349 /** 350 * 351 * @brief Create audio connection with remote HFP client. 352 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 353 * 354 * @param[in] remote_bda: remote bluetooth device address 355 * 356 * @return 357 * - ESP_OK: audio connect request is sent to lower layer 358 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 359 * - ESP_FAIL: others 360 * 361 */ 362 esp_err_t esp_hf_ag_audio_connect(esp_bd_addr_t remote_bda); 363 364 /** 365 * 366 * @brief Release the established audio connection with remote HFP client. 367 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 368 * 369 * @param[in] remote_bda: remote bluetooth device address 370 * 371 * @return 372 * - ESP_OK: audio disconnect request is sent to lower layer 373 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 374 * - ESP_FAIL: others 375 * 376 */ 377 esp_err_t esp_hf_ag_audio_disconnect(esp_bd_addr_t remote_bda); 378 379 /** 380 * 381 * @brief Response of Volume Recognition Command(AT+VRA) from HFP client. 382 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 383 * 384 * @param[in] remote_bda: the device address of voice recognition initiator 385 * 386 * @param[in] value: 0 - voice recognition disabled, 1- voice recognition enabled 387 * 388 * @return 389 * - ESP_OK: response of volume recognition is sent to lower layer 390 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 391 * - ESP_FAIL: others 392 * 393 */ 394 esp_err_t esp_hf_ag_vra_control(esp_bd_addr_t remote_bda, esp_hf_vr_state_t value); 395 396 /** 397 * 398 * @brief Volume synchronization with HFP client. 399 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 400 * 401 * @param[in] remote_bda: remote bluetooth device address 402 * 403 * @param[in] type: volume control target, speaker or microphone 404 * 405 * @param[in] volume: gain of the speaker of microphone, ranges 0 to 15 406 * 407 * @return 408 * - ESP_OK: volume synchronization control is sent to lower layer 409 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 410 * - ESP_ERR_INVALID_ARG: if arguments are invalid 411 * - ESP_FAIL: others 412 * 413 */ 414 esp_err_t esp_hf_ag_volume_control(esp_bd_addr_t remote_bda, esp_hf_volume_control_target_t type, int volume); 415 416 /** 417 * 418 * @brief Handle Unknown AT command from HFP Client. 419 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 420 * 421 * @param[in] remote_addr: remote bluetooth device address 422 * 423 * @param[in] unat: User AT command response to HF Client. 424 * It will response "ERROR" by default if unat is NULL. 425 * @return 426 * - ESP_OK: response of unknown AT command is sent to lower layer 427 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 428 * - ESP_FAIL: others 429 * 430 */ 431 esp_err_t esp_hf_ag_unknown_at_send(esp_bd_addr_t remote_addr, char *unat); 432 433 /** 434 * 435 * @brief Unsolicited send extend AT error code to HFP Client. 436 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 437 * 438 * @param[in] remote_bda: remote bluetooth device address 439 * @param[in] response_code: AT command response code 440 * @param[in] error_code: CME error code 441 * @return 442 * - ESP_OK: extend error code is sent to lower layer 443 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 444 * - ESP_FAIL: others 445 * 446 */ 447 esp_err_t esp_hf_ag_cmee_send(esp_bd_addr_t remote_bda, esp_hf_at_response_code_t response_code, esp_hf_cme_err_t error_code); 448 449 /** 450 * 451 * @brief Unsolicited send device status notification to HFP Client. 452 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 453 * 454 * @param[in] remote_addr: remote bluetooth device address 455 * @param[in] call_state: call state 456 * @param[in] call_setup_state: call setup state 457 * @param[in] ntk_state: network service state 458 * @param[in] signal: signal strength from 0 to 5 459 * @return 460 * - ESP_OK: device status notification is sent to lower layer 461 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 462 * - ESP_ERR_INVALID_ARG: if arguments are invalid 463 * - ESP_FAIL: others 464 * 465 */ 466 esp_err_t esp_hf_ag_devices_status_indchange(esp_bd_addr_t remote_addr, esp_hf_call_status_t call_state, 467 esp_hf_call_setup_status_t call_setup_state, 468 esp_hf_network_state_t ntk_state, int signal) __attribute__(( 469 deprecated("Please use esp_hf_ag_ciev_report") 470 )); 471 472 /** 473 * 474 * @brief Send indicator report "+CIEV: <ind> <value>" to HFP Client. "CIEV" means “indicator events reporting", 475 * and all indicator types can be sent one type at a time. 476 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 477 * 478 * @param[in] remote_addr: remote bluetooth device address 479 * @param[in] ind_type: indicator type 480 * @param[in] value: indicator value 481 * @return 482 * - ESP_OK: indicator report is sent to lower layer 483 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 484 * - ESP_FAIL: others 485 * 486 */ 487 esp_err_t esp_hf_ag_ciev_report(esp_bd_addr_t remote_addr, esp_hf_ciev_report_type_t ind_type, int value); 488 489 /** 490 * 491 * @brief Response to device individual indicators to HFP Client. 492 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 493 * 494 * @param[in] remote_addr: remote bluetooth device address 495 * @param[in] call_state: call state 496 * @param[in] call_setup_state: call setup state 497 * @param[in] ntk_state: network service state 498 * @param[in] signal: signal strength from 0 to 5 499 * @param[in] roam: roam state 500 * @param[in] batt_lev: battery level from 0 to 5 501 * @param[in] call_held_status: call held status 502 * @return 503 * - ESP_OK: response to device individual indicators is sent to lower layer 504 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 505 * - ESP_ERR_INVALID_ARG: if the arguments are invalid 506 * - ESP_FAIL: others 507 * 508 */ 509 esp_err_t esp_hf_ag_cind_response(esp_bd_addr_t remote_addr, 510 esp_hf_call_status_t call_state, 511 esp_hf_call_setup_status_t call_setup_state, 512 esp_hf_network_state_t ntk_state, int signal, esp_hf_roaming_status_t roam, int batt_lev, 513 esp_hf_call_held_status_t call_held_status); 514 515 /** 516 * 517 * @brief Response for AT+COPS command from HF Client. 518 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 519 * 520 * @param[in] remote_addr: remote bluetooth device address 521 * @param[in] name: current operator name 522 * @return 523 * - ESP_OK: response for AT+COPS command is sent to lower layer 524 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 525 * - ESP_FAIL: others 526 * 527 */ 528 esp_err_t esp_hf_ag_cops_response(esp_bd_addr_t remote_addr, char *name); 529 530 /** 531 * 532 * @brief Response to AT+CLCC command from HFP Client. 533 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 534 * 535 * @param[in] remote_addr: remote bluetooth device address 536 * @param[in] index: the index of current call, starting with 1, finishing response with 0 (send OK) 537 * @param[in] dir: call direction (incoming/outgoing) 538 * @param[in] current_call_state: current call state 539 * @param[in] mode: current call mode (voice/data/fax) 540 * @param[in] mpty: single or multi type 541 * @param[in] number: current call number 542 * @param[in] type: international type or unknown 543 * @return 544 * - ESP_OK: response to AT+CLCC command is sent to lower layer 545 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 546 * - ESP_FAIL: others 547 * 548 */ 549 esp_err_t esp_hf_ag_clcc_response(esp_bd_addr_t remote_addr, int index, esp_hf_current_call_direction_t dir, 550 esp_hf_current_call_status_t current_call_state, esp_hf_current_call_mode_t mode, 551 esp_hf_current_call_mpty_type_t mpty, char *number, esp_hf_call_addr_type_t type); 552 553 /** 554 * 555 * @brief Response for AT+CNUM command from HF Client. 556 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 557 * 558 * @param[in] remote_addr: remote bluetooth device address 559 * @param[in] number: registration number 560 * @param[in] number_type: value of number type from 561 * 128-143: national or international, may contain prefix and/or escape digits 562 * 144-159: international, includes country code prefix, add "+" if needed 563 * 160-175: national, but no prefix nor escape digits 564 * @param[in] service_type: service type (unknown/voice/fax) 565 * @return 566 * - ESP_OK: response for AT+CNUM command is sent to lower layer 567 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 568 * - ESP_FAIL: others 569 * 570 */ 571 esp_err_t esp_hf_ag_cnum_response(esp_bd_addr_t remote_addr, char *number, int number_type, esp_hf_subscriber_service_type_t service_type); 572 573 /** 574 * 575 * @brief Inform HF Client that AG Provided in-band ring tone or not. 576 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 577 * 578 * @param[in] remote_addr: remote bluetooth device address 579 * @param[in] state: in-band ring tone state 580 * @return 581 * - ESP_OK: information of in-band ring tone is sent to lower layer 582 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 583 * - ESP_ERR_INVALID_ARG: if arguments are invalid 584 * - ESP_FAIL: others 585 * 586 */ 587 esp_err_t esp_hf_ag_bsir(esp_bd_addr_t remote_addr, esp_hf_in_band_ring_state_t state); 588 589 /** 590 * 591 * @brief Answer Incoming Call from AG. 592 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 593 * 594 * @param[in] remote_addr: remote bluetooth device address 595 * @param[in] num_active: the number of active call 596 * @param[in] num_held: the number of held call 597 * @param[in] call_state: call state 598 * @param[in] call_setup_state: call setup state 599 * @param[in] number: number of the incoming call 600 * @param[in] call_addr_type: call address type 601 * @return 602 * - ESP_OK: answer incoming call is sent to lower layer 603 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 604 * - ESP_FAIL: others 605 * 606 */ 607 esp_err_t esp_hf_ag_answer_call(esp_bd_addr_t remote_addr, int num_active, int num_held, 608 esp_hf_call_status_t call_state, esp_hf_call_setup_status_t call_setup_state, 609 char *number, esp_hf_call_addr_type_t call_addr_type); 610 611 /** 612 * 613 * @brief Reject Incoming Call from AG. 614 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 615 * 616 * @param[in] remote_addr: remote bluetooth device address 617 * @param[in] num_active: the number of active call 618 * @param[in] num_held: the number of held call 619 * @param[in] call_state: call state 620 * @param[in] call_setup_state: call setup state 621 * @param[in] number: number of the incoming call 622 * @param[in] call_addr_type: call address type 623 * @return 624 * - ESP_OK: reject incoming call is sent to lower layer 625 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 626 * - ESP_FAIL: others 627 * 628 */ 629 esp_err_t esp_hf_ag_reject_call(esp_bd_addr_t remote_addr, int num_active, int num_held, 630 esp_hf_call_status_t call_state, esp_hf_call_setup_status_t call_setup_state, 631 char *number, esp_hf_call_addr_type_t call_addr_type); 632 633 /** 634 * 635 * @brief Initiate a call from AG. 636 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 637 * If the AG is driven by the HF to call esp_hf_ag_out_call, it needs to response an OK or ERROR 638 * to HF. But if the AG is actively calling esp_hf_ag_out_call, it does not need to take a response 639 * to HF. 640 * 641 * @param[in] remote_addr: remote bluetooth device address 642 * @param[in] num_active: the number of active call 643 * @param[in] num_held: the number of held call 644 * @param[in] call_state: call state 645 * @param[in] call_setup_state: call setup state 646 * @param[in] number: number of the outgoing call 647 * @param[in] call_addr_type: call address type 648 * @return 649 * - ESP_OK: a call initiation is sent to lower layer 650 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 651 * - ESP_FAIL: others 652 * 653 */ 654 esp_err_t esp_hf_ag_out_call(esp_bd_addr_t remote_addr, int num_active, int num_held, 655 esp_hf_call_status_t call_state, esp_hf_call_setup_status_t call_setup_state, 656 char *number, esp_hf_call_addr_type_t call_addr_type); 657 658 /** 659 * 660 * @brief End an ongoing call. 661 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 662 * 663 * @param[in] remote_addr: remote bluetooth device address 664 * @param[in] num_active: the number of active call 665 * @param[in] num_held: the number of held call 666 * @param[in] call_state: call state 667 * @param[in] call_setup_state: call setup state 668 * @param[in] number: number of the call 669 * @param[in] call_addr_type: call address type 670 * @return 671 * - ESP_OK: end an ongoing call is sent to lower layer 672 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 673 * - ESP_FAIL: others 674 * 675 */ 676 esp_err_t esp_hf_ag_end_call(esp_bd_addr_t remote_addr, int num_active, int num_held, 677 esp_hf_call_status_t call_state, esp_hf_call_setup_status_t call_setup_state, 678 char *number, esp_hf_call_addr_type_t call_addr_type); 679 680 /** 681 * @brief Register AG data output function. 682 * The callback is only used in the case that Voice Over HCI is enabled. 683 * 684 * @param[in] recv: HFP client incoming data callback function 685 * @param[in] send: HFP client outgoing data callback function 686 * 687 * @return 688 * - ESP_OK: success 689 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 690 * - ESP_FAIL: if callback is a NULL function pointer 691 * 692 */ 693 esp_err_t esp_hf_ag_register_data_callback(esp_hf_incoming_data_cb_t recv, esp_hf_outgoing_data_cb_t send); 694 695 /** 696 * 697 * @brief Get the number of packets received and sent 698 * 699 * This function is only used in the case that Voice Over HCI is enabled and the audio state is connected. 700 * When the operation is completed, the callback function will be called with ESP_HF_PKT_STAT_NUMS_GET_EVT. 701 * 702 * @param[in] sync_conn_handle: the (e)SCO connection handle 703 * 704 * @return 705 * - ESP_OK: if the request is sent successfully 706 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 707 * - ESP_FAIL: others 708 * 709 */ 710 esp_err_t esp_hf_ag_pkt_stat_nums_get(uint16_t sync_conn_handle); 711 712 /** 713 * @brief Trigger the lower-layer to fetch and send audio data. 714 * 715 * This function is only used in the case that Voice Over HCI is enabled. 716 * As a precondition to use this API, Service Level Connection shall exist with HFP client. 717 * After this function is called, lower layer will invoke esp_hf_client_outgoing_data_cb_t to fetch data 718 * 719 */ 720 void esp_hf_ag_outgoing_data_ready(void); 721 722 #ifdef __cplusplus 723 } 724 #endif 725 726 #endif //__ESP_HF_AG_API_H__ 727
