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_CLIENT_API_H__ 8 #define __ESP_HF_CLIENT_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 #define ESP_BT_HF_CLIENT_NUMBER_LEN (32) 19 #define ESP_BT_HF_CLIENT_OPERATOR_NAME_LEN (16) 20 #define ESP_BT_HF_AT_SEND_XAPL_LEN (14) 21 22 /// Bluetooth HFP RFCOMM connection and service level connection status 23 typedef enum { 24 ESP_HF_CLIENT_CONNECTION_STATE_DISCONNECTED = 0, /*!< RFCOMM data link channel released */ 25 ESP_HF_CLIENT_CONNECTION_STATE_CONNECTING, /*!< connecting remote device on the RFCOMM data link*/ 26 ESP_HF_CLIENT_CONNECTION_STATE_CONNECTED, /*!< RFCOMM connection established */ 27 ESP_HF_CLIENT_CONNECTION_STATE_SLC_CONNECTED, /*!< service level connection established */ 28 ESP_HF_CLIENT_CONNECTION_STATE_DISCONNECTING, /*!< disconnecting with remote device on the RFCOMM dat link*/ 29 } esp_hf_client_connection_state_t; 30 31 /// Bluetooth HFP audio connection status 32 typedef enum { 33 ESP_HF_CLIENT_AUDIO_STATE_DISCONNECTED = 0, /*!< audio connection released */ 34 ESP_HF_CLIENT_AUDIO_STATE_CONNECTING, /*!< audio connection has been initiated */ 35 ESP_HF_CLIENT_AUDIO_STATE_CONNECTED, /*!< audio connection is established */ 36 ESP_HF_CLIENT_AUDIO_STATE_CONNECTED_MSBC, /*!< mSBC audio connection is established */ 37 } esp_hf_client_audio_state_t; 38 39 /// in-band ring tone state 40 typedef enum { 41 ESP_HF_CLIENT_IN_BAND_RINGTONE_NOT_PROVIDED = 0, 42 ESP_HF_CLIENT_IN_BAND_RINGTONE_PROVIDED, 43 } esp_hf_client_in_band_ring_state_t; 44 45 /* features masks of AG */ 46 #define ESP_HF_CLIENT_PEER_FEAT_3WAY 0x01 /* Three-way calling */ 47 #define ESP_HF_CLIENT_PEER_FEAT_ECNR 0x02 /* Echo cancellation and/or noise reduction */ 48 #define ESP_HF_CLIENT_PEER_FEAT_VREC 0x04 /* Voice recognition */ 49 #define ESP_HF_CLIENT_PEER_FEAT_INBAND 0x08 /* In-band ring tone */ 50 #define ESP_HF_CLIENT_PEER_FEAT_VTAG 0x10 /* Attach a phone number to a voice tag */ 51 #define ESP_HF_CLIENT_PEER_FEAT_REJECT 0x20 /* Ability to reject incoming call */ 52 #define ESP_HF_CLIENT_PEER_FEAT_ECS 0x40 /* Enhanced Call Status */ 53 #define ESP_HF_CLIENT_PEER_FEAT_ECC 0x80 /* Enhanced Call Control */ 54 #define ESP_HF_CLIENT_PEER_FEAT_EXTERR 0x100 /* Extended error codes */ 55 #define ESP_HF_CLIENT_PEER_FEAT_CODEC 0x200 /* Codec Negotiation */ 56 /* HFP 1.7+ */ 57 #define ESP_HF_CLIENT_PEER_FEAT_HF_IND 0x400 /* HF Indicators */ 58 #define ESP_HF_CLIENT_PEER_FEAT_ESCO_S4 0x800 /* eSCO S4 Setting Supported */ 59 60 /* CHLD feature masks of AG */ 61 #define ESP_HF_CLIENT_CHLD_FEAT_REL 0x01 /* 0 Release waiting call or held calls */ 62 #define ESP_HF_CLIENT_CHLD_FEAT_REL_ACC 0x02 /* 1 Release active calls and accept other waiting or held call */ 63 #define ESP_HF_CLIENT_CHLD_FEAT_REL_X 0x04 /* 1x Release specified active call only */ 64 #define ESP_HF_CLIENT_CHLD_FEAT_HOLD_ACC 0x08 /* 2 Active calls on hold and accept other waiting or held call */ 65 #define ESP_HF_CLIENT_CHLD_FEAT_PRIV_X 0x10 /* 2x Request private mode with specified call(put the rest on hold) */ 66 #define ESP_HF_CLIENT_CHLD_FEAT_MERGE 0x20 /* 3 Add held call to multiparty */ 67 #define ESP_HF_CLIENT_CHLD_FEAT_MERGE_DETACH 0x40 /* 4 Connect two calls and leave(disconnect from multiparty) */ 68 69 /* XAPL feature masks*/ 70 #define ESP_HF_CLIENT_XAPL_FEAT_RESERVED 0x01 /* reserved */ 71 #define ESP_HF_CLIENT_XAPL_FEAT_BATTERY_REPORT 0x02 /* The accessory supports battery reporting (reserved only for battery operated accessories) */ 72 #define ESP_HF_CLIENT_XAPL_FEAT_DOCKED 0x04 /* The accessory is docked or powered (reserved only for battery operated accessories). */ 73 #define ESP_HF_CLIENT_XAPL_FEAT_SIRI_STATUS_REPORT 0x08 /* The accessory supports Siri status reporting */ 74 #define ESP_HF_CLIENT_XAPL_NR_STATUS_REPORT 0x10 /* the accessory supports noise reduction (NR) status reporting */ 75 76 /// HF CLIENT callback events 77 typedef enum { 78 ESP_HF_CLIENT_CONNECTION_STATE_EVT = 0, /*!< connection state changed event */ 79 ESP_HF_CLIENT_AUDIO_STATE_EVT, /*!< audio connection state change event */ 80 ESP_HF_CLIENT_BVRA_EVT, /*!< voice recognition state change event */ 81 ESP_HF_CLIENT_CIND_CALL_EVT, /*!< call indication */ 82 ESP_HF_CLIENT_CIND_CALL_SETUP_EVT, /*!< call setup indication */ 83 ESP_HF_CLIENT_CIND_CALL_HELD_EVT, /*!< call held indication */ 84 ESP_HF_CLIENT_CIND_SERVICE_AVAILABILITY_EVT, /*!< network service availability indication */ 85 ESP_HF_CLIENT_CIND_SIGNAL_STRENGTH_EVT, /*!< signal strength indication */ 86 ESP_HF_CLIENT_CIND_ROAMING_STATUS_EVT, /*!< roaming status indication */ 87 ESP_HF_CLIENT_CIND_BATTERY_LEVEL_EVT, /*!< battery level indication */ 88 ESP_HF_CLIENT_COPS_CURRENT_OPERATOR_EVT, /*!< current operator information */ 89 ESP_HF_CLIENT_BTRH_EVT, /*!< call response and hold event */ 90 ESP_HF_CLIENT_CLIP_EVT, /*!< Calling Line Identification notification */ 91 ESP_HF_CLIENT_CCWA_EVT, /*!< call waiting notification */ 92 ESP_HF_CLIENT_CLCC_EVT, /*!< list of current calls notification */ 93 ESP_HF_CLIENT_VOLUME_CONTROL_EVT, /*!< audio volume control command from AG, provided by +VGM or +VGS message */ 94 ESP_HF_CLIENT_AT_RESPONSE_EVT, /*!< AT command response event */ 95 ESP_HF_CLIENT_CNUM_EVT, /*!< subscriber information response from AG */ 96 ESP_HF_CLIENT_BSIR_EVT, /*!< setting of in-band ring tone */ 97 ESP_HF_CLIENT_BINP_EVT, /*!< requested number of last voice tag from AG */ 98 ESP_HF_CLIENT_RING_IND_EVT, /*!< ring indication event */ 99 ESP_HF_CLIENT_PKT_STAT_NUMS_GET_EVT, /*!< requested number of packet different status */ 100 ESP_HF_CLIENT_PROF_STATE_EVT, /*!< Indicate HF CLIENT init or deinit complete */ 101 } esp_hf_client_cb_event_t; 102 103 /// HFP client callback parameters 104 typedef union { 105 /** 106 * @brief ESP_HF_CLIENT_CONNECTION_STATE_EVT 107 */ 108 struct hf_client_conn_stat_param { 109 esp_hf_client_connection_state_t state; /*!< HF connection state */ 110 uint32_t peer_feat; /*!< AG supported features */ 111 uint32_t chld_feat; /*!< AG supported features on call hold and multiparty services */ 112 esp_bd_addr_t remote_bda; /*!< remote bluetooth device address */ 113 } conn_stat; /*!< HF callback param of ESP_HF_CLIENT_CONNECTION_STATE_EVT */ 114 115 /** 116 * @brief ESP_HF_CLIENT_AUDIO_STATE_EVT 117 */ 118 struct hf_client_audio_stat_param { 119 esp_hf_client_audio_state_t state; /*!< audio connection state */ 120 esp_bd_addr_t remote_bda; /*!< remote bluetooth device address */ 121 uint16_t sync_conn_handle; /*!< (e)SCO connection handle */ 122 } audio_stat; /*!< HF callback param of ESP_HF_CLIENT_AUDIO_STATE_EVT */ 123 124 /** 125 * @brief ESP_HF_CLIENT_BVRA_EVT 126 */ 127 struct hf_client_bvra_param { 128 esp_hf_vr_state_t value; /*!< voice recognition state */ 129 } bvra; /*!< HF callback param of ESP_HF_CLIENT_BVRA_EVT */ 130 131 /** 132 * @brief ESP_HF_CLIENT_CIND_SERVICE_AVAILABILITY_EVT 133 */ 134 struct hf_client_service_availability_param { 135 esp_hf_network_state_t status; /*!< service availability status */ 136 } service_availability; /*!< HF callback param of ESP_HF_CLIENT_CIND_SERVICE_AVAILABILITY_EVT */ 137 138 /** 139 * @brief ESP_HF_CLIENT_CIND_ROAMING_STATUS_EVT 140 */ 141 struct hf_client_network_roaming_param { 142 esp_hf_roaming_status_t status; /*!< roaming status */ 143 } roaming; /*!< HF callback param of ESP_HF_CLIENT_CIND_ROAMING_STATUS_EVT */ 144 145 /** 146 * @brief ESP_HF_CLIENT_CIND_SIGNAL_STRENGTH_EVT 147 */ 148 struct hf_client_signal_strength_ind_param { 149 int value; /*!< signal strength value, ranges from 0 to 5 */ 150 } signal_strength; /*!< HF callback param of ESP_HF_CLIENT_CIND_SIGNAL_STRENGTH_EVT */ 151 152 /** 153 * @brief ESP_HF_CLIENT_CIND_BATTERY_LEVEL_EVT 154 */ 155 struct hf_client_battery_level_ind_param { 156 int value; /*!< battery charge value, ranges from 0 to 5 */ 157 } battery_level; /*!< HF callback param of ESP_HF_CLIENT_CIND_BATTERY_LEVEL_EVT */ 158 159 /** 160 * @brief ESP_HF_CLIENT_COPS_CURRENT_OPERATOR_EVT 161 */ 162 struct hf_client_current_operator_param { 163 const char *name; /*!< name of the network operator */ 164 } cops; /*!< HF callback param of ESP_HF_CLIENT_COPS_CURRENT_OPERATOR_EVT */ 165 166 /** 167 * @brief ESP_HF_CLIENT_CIND_CALL_EVT 168 */ 169 struct hf_client_call_ind_param { 170 esp_hf_call_status_t status; /*!< call status indicator */ 171 } call; /*!< HF callback param of ESP_HF_CLIENT_CIND_CALL_EVT */ 172 173 /** 174 * @brief ESP_HF_CLIENT_CIND_CALL_SETUP_EVT 175 */ 176 struct hf_client_call_setup_ind_param { 177 esp_hf_call_setup_status_t status; /*!< call setup status indicator */ 178 } call_setup; /*!< HF callback param of ESP_HF_CLIENT_BVRA_EVT */ 179 180 /** 181 * @brief ESP_HF_CLIENT_CIND_CALL_HELD_EVT 182 */ 183 struct hf_client_call_held_ind_param { 184 esp_hf_call_held_status_t status; /*!< bluetooth proprietary call hold status indicator */ 185 } call_held; /*!< HF callback param of ESP_HF_CLIENT_CIND_CALL_HELD_EVT */ 186 187 /** 188 * @brief ESP_HF_CLIENT_BTRH_EVT 189 */ 190 struct hf_client_btrh_param { 191 esp_hf_btrh_status_t status; /*!< call hold and response status result code */ 192 } btrh; /*!< HF callback param of ESP_HF_CLIENT_BRTH_EVT */ 193 194 /** 195 * @brief ESP_HF_CLIENT_CLIP_EVT 196 */ 197 struct hf_client_clip_param { 198 const char *number; /*!< phone number string of call */ 199 } clip; /*!< HF callback param of ESP_HF_CLIENT_CLIP_EVT */ 200 201 /** 202 * @brief ESP_HF_CLIENT_CCWA_EVT 203 */ 204 struct hf_client_ccwa_param { 205 const char *number; /*!< phone number string of waiting call */ 206 } ccwa; /*!< HF callback param of ESP_HF_CLIENT_BVRA_EVT */ 207 208 /** 209 * @brief ESP_HF_CLIENT_CLCC_EVT 210 */ 211 struct hf_client_clcc_param { 212 int idx; /*!< numbering(starting with 1) of the call */ 213 esp_hf_current_call_direction_t dir; /*!< direction of the call */ 214 esp_hf_current_call_status_t status; /*!< status of the call */ 215 esp_hf_current_call_mpty_type_t mpty; /*!< multi-party flag */ 216 char *number; /*!< phone number(optional) */ 217 } clcc; /*!< HF callback param of ESP_HF_CLIENT_CLCC_EVT */ 218 219 /** 220 * @brief ESP_HF_CLIENT_VOLUME_CONTROL_EVT 221 */ 222 struct hf_client_volume_control_param { 223 esp_hf_volume_control_target_t type; /*!< volume control target, speaker or microphone */ 224 int volume; /*!< gain, ranges from 0 to 15 */ 225 } volume_control; /*!< HF callback param of ESP_HF_CLIENT_VOLUME_CONTROL_EVT */ 226 227 /** 228 * @brief ESP_HF_CLIENT_AT_RESPONSE_EVT 229 */ 230 struct hf_client_at_response_param { 231 esp_hf_at_response_code_t code; /*!< AT response code */ 232 esp_hf_cme_err_t cme; /*!< Extended Audio Gateway Error Result Code */ 233 } at_response; /*!< HF callback param of ESP_HF_CLIENT_AT_RESPONSE_EVT */ 234 235 /** 236 * @brief ESP_HF_CLIENT_CNUM_EVT 237 */ 238 struct hf_client_cnum_param { 239 const char *number; /*!< phone number string */ 240 esp_hf_subscriber_service_type_t type; /*!< service type that the phone number relates to */ 241 } cnum; /*!< HF callback param of ESP_HF_CLIENT_CNUM_EVT */ 242 243 /** 244 * @brief ESP_HF_CLIENT_BSIR_EVT 245 */ 246 struct hf_client_bsirparam { 247 esp_hf_client_in_band_ring_state_t state; /*!< setting state of in-band ring tone */ 248 } bsir; /*!< HF callback param of ESP_HF_CLIENT_BSIR_EVT */ 249 250 /** 251 * @brief ESP_HF_CLIENT_BINP_EVT 252 */ 253 struct hf_client_binp_param { 254 const char *number; /*!< phone number corresponding to the last voice tag in the HF */ 255 } binp; /*!< HF callback param of ESP_HF_CLIENT_BINP_EVT */ 256 257 /** 258 * @brief ESP_HF_CLIENT_PKT_STAT_NUMS_GET_EVT 259 */ 260 struct hf_client_pkt_status_nums { 261 uint32_t rx_total; /*!< the total number of packets received */ 262 uint32_t rx_correct; /*!< the total number of packets data correctly received */ 263 uint32_t rx_err; /*!< the total number of packets data with possible invalid */ 264 uint32_t rx_none; /*!< the total number of packets data no received */ 265 uint32_t rx_lost; /*!< the total number of packets data partially lost */ 266 uint32_t tx_total; /*!< the total number of packets send */ 267 uint32_t tx_discarded; /*!< the total number of packets send lost */ 268 } pkt_nums; /*!< HF callback param of ESP_HF_CLIENT_PKT_STAT_NUMS_GET_EVT */ 269 270 /** 271 * @brief ESP_HF_CLIENT_PROF_STATE_EVT 272 */ 273 struct hf_client_prof_stat_param { 274 esp_hf_prof_state_t state; /*!< hf client profile state param */ 275 } prof_stat; /*!< status to indicate hf client prof init or deinit */ 276 277 } esp_hf_client_cb_param_t; /*!< HFP client callback parameters */ 278 279 /** 280 * @brief HFP client incoming data callback function, the callback is useful in case of 281 * Voice Over HCI. 282 * @param[in] buf : pointer to incoming data(payload of HCI synchronous data packet), the 283 * buffer is allocated inside bluetooth protocol stack and will be released after 284 * invoke of the callback is finished. 285 * @param[in] len : size(in bytes) in buf 286 */ 287 typedef void (* esp_hf_client_incoming_data_cb_t)(const uint8_t *buf, uint32_t len); 288 289 /** 290 * @brief HFP client outgoing data callback function, the callback is useful in case of 291 * Voice Over HCI. Once audio connection is set up and the application layer has 292 * prepared data to send, the lower layer will call this function to read data 293 * and then send. This callback is supposed to be implemented as non-blocking, 294 * and if data is not enough, return value 0 is supposed. 295 * 296 * @param[in] buf : pointer to incoming data(payload of HCI synchronous data packet), the 297 * buffer is allocated inside bluetooth protocol stack and will be released after 298 * invoke of the callback is finished. 299 * 300 * @param[in] len : size(in bytes) in buf 301 * 302 * @return length of data successfully read 303 * 304 */ 305 typedef uint32_t (* esp_hf_client_outgoing_data_cb_t)(uint8_t *buf, uint32_t len); 306 307 /** 308 * @brief HFP client callback function type 309 * 310 * @param event : Event type 311 * 312 * @param param : Pointer to callback parameter 313 */ 314 typedef void (* esp_hf_client_cb_t)(esp_hf_client_cb_event_t event, esp_hf_client_cb_param_t *param); 315 316 /** 317 * @brief Register application callback function to HFP client module. 318 * This function should be called only after esp_bluedroid_enable() completes successfully. 319 * 320 * @param[in] callback: HFP client event callback function 321 * 322 * @return 323 * - ESP_OK: success 324 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 325 * - ESP_FAIL: if callback is a NULL function pointer 326 * 327 */ 328 esp_err_t esp_hf_client_register_callback(esp_hf_client_cb_t callback); 329 330 /** 331 * 332 * @brief Initialize the bluetooth HFP client module. 333 * This function should be called after esp_bluedroid_enable() completes successfully. 334 * ESP_HF_CLIENT_PROF_STATE_EVT with ESP_HF_INIT_SUCCESS will reported to the APP layer. 335 * 336 * @return 337 * - ESP_OK: if the initialization request is sent successfully 338 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 339 * - ESP_FAIL: others 340 * 341 */ 342 esp_err_t esp_hf_client_init(void); 343 344 /** 345 * 346 * @brief De-initialize for HFP client module. 347 * This function should be called only after esp_bluedroid_enable() completes successfully. 348 * ESP_HF_CLIENT_PROF_STATE_EVT with ESP_HF_DEINIT_SUCCESS will reported to the APP layer. 349 * 350 * @return 351 * - ESP_OK: success 352 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 353 * - ESP_FAIL: others 354 * 355 */ 356 esp_err_t esp_hf_client_deinit(void); 357 358 /** 359 * 360 * @brief Establish a Service Level Connection to remote bluetooth HFP audio gateway(AG) device. 361 * This function must be called after esp_hf_client_init() and before esp_hf_client_deinit(). 362 * 363 * @param[in] remote_bda: remote bluetooth device address 364 * 365 * @return 366 * - ESP_OK: connect request is sent to lower layer 367 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 368 * - ESP_FAIL: others 369 * 370 */ 371 esp_err_t esp_hf_client_connect(esp_bd_addr_t remote_bda); 372 373 /** 374 * 375 * @brief Disconnect from the remote HFP audio gateway. 376 * This function must be called after esp_hf_client_init() and before esp_hf_client_deinit(). 377 * 378 * @param[in] remote_bda: remote bluetooth device address 379 * 380 * @return 381 * - ESP_OK: disconnect request is sent to lower layer 382 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 383 * - ESP_FAIL: others 384 * 385 */ 386 esp_err_t esp_hf_client_disconnect(esp_bd_addr_t remote_bda); 387 388 /** 389 * 390 * @brief Create audio connection with remote HFP AG. 391 * As a precondition to use this API, Service Level Connection shall exist with AG. 392 * 393 * @param[in] remote_bda: remote bluetooth device address 394 * @return 395 * - ESP_OK: connect audio request is sent to lower layer 396 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 397 * - ESP_FAIL: others 398 * 399 */ 400 esp_err_t esp_hf_client_connect_audio(esp_bd_addr_t remote_bda); 401 402 /** 403 * 404 * @brief Release the established audio connection with remote HFP AG. 405 * As a precondition to use this API, Service Level Connection shall exist with AG. 406 * 407 * @param[in] remote_bda: remote bluetooth device address 408 * @return 409 * - ESP_OK: disconnect audio request is sent to lower layer 410 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 411 * - ESP_FAIL: others 412 * 413 */ 414 esp_err_t esp_hf_client_disconnect_audio(esp_bd_addr_t remote_bda); 415 416 /** 417 * 418 * @brief Enable voice recognition in the AG. 419 * As a precondition to use this API, Service Level Connection shall exist with AG. 420 * 421 * @return 422 * - ESP_OK: starting voice recognition is sent to lower layer 423 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 424 * - ESP_FAIL: others 425 * 426 */ 427 esp_err_t esp_hf_client_start_voice_recognition(void); 428 429 /** 430 * 431 * @brief Disable voice recognition in the AG. 432 * As a precondition to use this API, Service Level Connection shall exist with AG. 433 * 434 * @return 435 * - ESP_OK: stopping voice recognition is sent to lower layer 436 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 437 * - ESP_FAIL: others 438 * 439 */ 440 esp_err_t esp_hf_client_stop_voice_recognition(void); 441 442 /** 443 * 444 * @brief Volume synchronization with AG. 445 * As a precondition to use this API, Service Level Connection shall exist with AG. 446 * 447 * @param[in] type: volume control target, speaker or microphone 448 * @param[in] volume: gain of the speaker of microphone, ranges 0 to 15 449 * 450 * @return 451 * - ESP_OK: volume update is sent to lower layer 452 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 453 * - ESP_FAIL: others 454 * 455 */ 456 esp_err_t esp_hf_client_volume_update(esp_hf_volume_control_target_t type, int volume); 457 458 /** 459 * 460 * @brief Place a call with a specified number, if number is NULL, last called number is called. 461 * As a precondition to use this API, Service Level Connection shall exist with AG. 462 * 463 * @param[in] number: number string of the call. If NULL, the last number is called(aka re-dial) 464 * 465 * @return 466 * - ESP_OK: a call placing is sent to lower layer 467 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 468 * - ESP_FAIL: others 469 * 470 */ 471 esp_err_t esp_hf_client_dial(const char *number); 472 473 /** 474 * 475 * @brief Place a call with number specified by location(speed dial). 476 * As a precondition to use this API, Service Level Connection shall exist with AG. 477 * 478 * @param[in] location: location of the number in the memory 479 * 480 * @return 481 * - ESP_OK: a memory call placing is sent to lower layer 482 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 483 * - ESP_FAIL: others 484 * 485 */ 486 487 esp_err_t esp_hf_client_dial_memory(int location); 488 489 /** 490 * 491 * @brief Send call hold and multiparty commands, or enhanced call control commands(Use AT+CHLD). 492 * As a precondition to use this API, Service Level Connection shall exist with AG. 493 * 494 * @param[in] chld: AT+CHLD call hold and multiparty handling AT command. 495 * @param[in] idx: used in Enhanced Call Control Mechanisms, used if chld is 496 * ESP_HF_CHLD_TYPE_REL_X or ESP_HF_CHLD_TYPE_PRIV_X 497 * 498 * @return 499 * - ESP_OK: command AT+CHLD is sent to lower layer 500 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 501 * - ESP_FAIL: others 502 * 503 */ 504 esp_err_t esp_hf_client_send_chld_cmd(esp_hf_chld_type_t chld, int idx); 505 506 /** 507 * 508 * @brief Send response and hold action command(Send AT+BTRH command) 509 * As a precondition to use this API, Service Level Connection shall exist with AG. 510 * 511 * @param[in] btrh: response and hold action to send 512 * 513 * @return 514 * - ESP_OK: command AT+BTRH is sent to lower layer 515 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 516 * - ESP_FAIL: others 517 * 518 */ 519 esp_err_t esp_hf_client_send_btrh_cmd(esp_hf_btrh_cmd_t btrh); 520 521 /** 522 * 523 * @brief Answer an incoming call(send ATA command). 524 * As a precondition to use this API, Service Level Connection shall exist with AG. 525 * 526 * @return 527 * - ESP_OK: a call answering is sent to lower layer 528 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 529 * - ESP_FAIL: others 530 * 531 */ 532 esp_err_t esp_hf_client_answer_call(void); 533 534 /** 535 * 536 * @brief Reject an incoming call or terminate an ongoing call(send AT+CHUP command). 537 * As a precondition to use this API, Service Level Connection shall exist with AG. 538 * 539 * @return 540 * - ESP_OK: the call rejecting is sent to lower layer 541 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 542 * - ESP_FAIL: others 543 * 544 */ 545 esp_err_t esp_hf_client_reject_call(void); 546 547 /** 548 * 549 * @brief Query list of current calls in AG(send AT+CLCC command). 550 * As a precondition to use this API, Service Level Connection shall exist with AG. 551 * 552 * @return 553 * - ESP_OK: query of current calls is sent to lower layer 554 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 555 * - ESP_FAIL: others 556 * 557 */ 558 esp_err_t esp_hf_client_query_current_calls(void); 559 560 /** 561 * 562 * @brief Query the name of currently selected network operator in AG(use AT+COPS commands). 563 * As a precondition to use this API, Service Level Connection shall exist with AG. 564 * 565 * @return 566 * - ESP_OK: query of current operator name 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_client_query_current_operator_name(void); 572 573 /** 574 * 575 * @brief Get subscriber information number from AG(send AT+CNUM command) 576 * As a precondition to use this API, Service Level Connection shall exist with AG 577 * 578 * @return 579 * - ESP_OK: the retrieving of subscriber information is sent to lower layer 580 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 581 * - ESP_FAIL: others 582 * 583 */ 584 esp_err_t esp_hf_client_retrieve_subscriber_info(void); 585 586 /** 587 * 588 * @brief Transmit DTMF codes during an ongoing call(use AT+VTS commands) 589 * As a precondition to use this API, Service Level Connection shall exist with AG. 590 * 591 * @param[in] code: dtmf code, single ascii character in the set 0-9, #, *, A-D 592 * 593 * @return 594 * - ESP_OK: the DTMF codes are sent to lower layer 595 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 596 * - ESP_FAIL: others 597 * 598 */ 599 esp_err_t esp_hf_client_send_dtmf(char code); 600 601 /** 602 * 603 * @brief Send command to enable Vendor specific feature to indicate battery level 604 * and docker status 605 * This is Apple-specific commands, but used by most device, including Android and Windows 606 * 607 * @param[in] information: XAPL vendorID-productID-version, such as "0505-1995-0610" 608 * vendorID: A string representation of the hex value of the vendor ID from the manufacturer, without the 0x prefix. 609 * productID: A string representation of the hex value of the product ID from the manufacturer, without the 0x prefix. 610 * version: The revision of the software 611 * @param[in] features: A base-10 representation of a bit field. such as ESP_HF_CLIENT_XAPL_FEAT_BATTERY_REPORT 612 * 613 * @return 614 * - ESP_OK: Feature enable request is sent to lower layer 615 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 616 * - ESP_FAIL: others 617 * 618 */ 619 esp_err_t esp_hf_client_send_xapl(char *information, uint32_t features); 620 621 /** 622 * 623 * @brief Send Battery level and docker status 624 * Enable this feature using XAPL command first 625 * This is Apple-specific commands, but used by most device, including Android and Windows 626 * 627 * 628 * @param[in] bat_level: Battery Level: value between 0 and 9 629 * @param[in] docked: Dock State: false = undocked, true = docked 630 * 631 * @return 632 * - ESP_OK: battery level is sent to lower layer 633 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 634 * - ESP_FAIL: others 635 * 636 */ 637 esp_err_t esp_hf_client_send_iphoneaccev(uint32_t bat_level, bool docked); 638 639 /** 640 * 641 * @brief Request a phone number from AG corresponding to last voice tag recorded (send AT+BINP command). 642 * As a precondition to use this API, Service Level Connection shall exist with AG. 643 * 644 * @return 645 * - ESP_OK: the phone number request corresponding to last voice tag recorded is sent to lower layer 646 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 647 * - ESP_FAIL: others 648 * 649 */ 650 esp_err_t esp_hf_client_request_last_voice_tag_number(void); 651 652 /** 653 * 654 * @brief Disable echo cancellation and noise reduction in the AG (use AT+NREC=0 command). 655 * As a precondition to use this API, Service Level Connection shall exist with AG 656 * 657 * @return 658 * - ESP_OK: NREC=0 request is sent to lower layer 659 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 660 * - ESP_FAIL: others 661 * 662 */ 663 esp_err_t esp_hf_client_send_nrec(void); 664 665 666 /** 667 * @brief Register HFP client data output function; the callback is only used in 668 * the case that Voice Over HCI is enabled. 669 * 670 * @param[in] recv: HFP client incoming data callback function 671 * 672 * @param[in] send: HFP client outgoing data callback function 673 * 674 * @return 675 * - ESP_OK: success 676 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 677 * - ESP_FAIL: if callback is a NULL function pointer 678 * 679 */ 680 esp_err_t esp_hf_client_register_data_callback(esp_hf_client_incoming_data_cb_t recv, 681 esp_hf_client_outgoing_data_cb_t send); 682 683 /** 684 * 685 * @brief Get the number of packets received and sent 686 * This function is only used in the case that Voice Over HCI is enabled and the audio state is connected. 687 * When the operation is completed, the callback function will be called with ESP_HF_CLIENT_PKT_STAT_NUMS_GET_EVT. 688 * 689 * @param[in] sync_conn_handle: the (e)SCO connection handle 690 * 691 * @return 692 * - ESP_OK: if the request is sent successfully 693 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled 694 * - ESP_FAIL: others 695 * 696 */ 697 esp_err_t esp_hf_client_pkt_stat_nums_get(uint16_t sync_conn_handle); 698 699 /** 700 * @brief Trigger the lower-layer to fetch and send audio data. 701 * This function is only only used in the case that Voice Over HCI is enabled. After this 702 * function is called, lower layer will invoke esp_hf_client_outgoing_data_cb_t to fetch data. 703 * 704 * As a precondition to use this API, Service Level Connection shall exist with AG. 705 * 706 */ 707 void esp_hf_client_outgoing_data_ready(void); 708 709 710 /** 711 * @brief Initialize the down sampling converter. This is a utility function that can 712 * only be used in the case that Voice Over HCI is enabled. 713 * 714 * @param[in] src_sps: original samples per second(source audio data, i.e. 48000, 32000, 715 * 16000, 44100, 22050, 11025) 716 * @param[in] bits: number of bits per pcm sample (16) 717 * 718 * @param[in] channels: number of channels (i.e. mono(1), stereo(2)...) 719 */ 720 void esp_hf_client_pcm_resample_init(uint32_t src_sps, uint32_t bits, uint32_t channels); 721 722 /** 723 * @brief Deinitialize the down sampling converter. 724 */ 725 void esp_hf_client_pcm_resample_deinit(void); 726 727 /** 728 * @brief Down sampling utility to convert high sampling rate into 8K/16bits 1-channel mode PCM 729 * samples. This can only be used in the case that Voice Over HCI is enabled. 730 * 731 * @param[in] src: pointer to the buffer where the original sampling PCM are stored 732 * 733 * @param[in] in_bytes: length of the input PCM sample buffer in byte 734 * 735 * @param[in] dst: pointer to the buffer which is to be used to store the converted PCM samples 736 * 737 * @return number of samples converted 738 */ 739 int32_t esp_hf_client_pcm_resample(void *src, uint32_t in_bytes, void *dst); 740 741 #ifdef __cplusplus 742 } 743 #endif 744 745 746 #endif /* __ESP_HF_CLIENT_API_H__ */ 747
