1 // Copyright 2018 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef __ESP_HF_CLIENT_API_H__ 16 #define __ESP_HF_CLIENT_API_H__ 17 18 #include "esp_err.h" 19 #include "esp_bt_defs.h" 20 #include "esp_hf_defs.h" 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 #define ESP_BT_HF_CLIENT_NUMBER_LEN (32) 27 #define ESP_BT_HF_CLIENT_OPERATOR_NAME_LEN (16) 28 29 /// Bluetooth HFP RFCOMM connection and service level connection status 30 typedef enum { 31 ESP_HF_CLIENT_CONNECTION_STATE_DISCONNECTED = 0, /*!< RFCOMM data link channel released */ 32 ESP_HF_CLIENT_CONNECTION_STATE_CONNECTING, /*!< connecting remote device on the RFCOMM data link*/ 33 ESP_HF_CLIENT_CONNECTION_STATE_CONNECTED, /*!< RFCOMM connection established */ 34 ESP_HF_CLIENT_CONNECTION_STATE_SLC_CONNECTED, /*!< service level connection established */ 35 ESP_HF_CLIENT_CONNECTION_STATE_DISCONNECTING, /*!< disconnecting with remote device on the RFCOMM dat link*/ 36 } esp_hf_client_connection_state_t; 37 38 /// Bluetooth HFP audio connection status 39 typedef enum { 40 ESP_HF_CLIENT_AUDIO_STATE_DISCONNECTED = 0, /*!< audio connection released */ 41 ESP_HF_CLIENT_AUDIO_STATE_CONNECTING, /*!< audio connection has been initiated */ 42 ESP_HF_CLIENT_AUDIO_STATE_CONNECTED, /*!< audio connection is established */ 43 ESP_HF_CLIENT_AUDIO_STATE_CONNECTED_MSBC, /*!< mSBC audio connection is established */ 44 } esp_hf_client_audio_state_t; 45 46 /// in-band ring tone state 47 typedef enum { 48 ESP_HF_CLIENT_IN_BAND_RINGTONE_NOT_PROVIDED = 0, 49 ESP_HF_CLIENT_IN_BAND_RINGTONE_PROVIDED, 50 } esp_hf_client_in_band_ring_state_t; 51 52 /* features masks of AG */ 53 #define ESP_HF_CLIENT_PEER_FEAT_3WAY 0x01 /* Three-way calling */ 54 #define ESP_HF_CLIENT_PEER_FEAT_ECNR 0x02 /* Echo cancellation and/or noise reduction */ 55 #define ESP_HF_CLIENT_PEER_FEAT_VREC 0x04 /* Voice recognition */ 56 #define ESP_HF_CLIENT_PEER_FEAT_INBAND 0x08 /* In-band ring tone */ 57 #define ESP_HF_CLIENT_PEER_FEAT_VTAG 0x10 /* Attach a phone number to a voice tag */ 58 #define ESP_HF_CLIENT_PEER_FEAT_REJECT 0x20 /* Ability to reject incoming call */ 59 #define ESP_HF_CLIENT_PEER_FEAT_ECS 0x40 /* Enhanced Call Status */ 60 #define ESP_HF_CLIENT_PEER_FEAT_ECC 0x80 /* Enhanced Call Control */ 61 #define ESP_HF_CLIENT_PEER_FEAT_EXTERR 0x100 /* Extended error codes */ 62 #define ESP_HF_CLIENT_PEER_FEAT_CODEC 0x200 /* Codec Negotiation */ 63 /* HFP 1.7+ */ 64 #define ESP_HF_CLIENT_PEER_FEAT_HF_IND 0x400 /* HF Indicators */ 65 #define ESP_HF_CLIENT_PEER_FEAT_ESCO_S4 0x800 /* eSCO S4 Setting Supported */ 66 67 /* CHLD feature masks of AG */ 68 #define ESP_HF_CLIENT_CHLD_FEAT_REL 0x01 /* 0 Release waiting call or held calls */ 69 #define ESP_HF_CLIENT_CHLD_FEAT_REL_ACC 0x02 /* 1 Release active calls and accept other waiting or held call */ 70 #define ESP_HF_CLIENT_CHLD_FEAT_REL_X 0x04 /* 1x Release specified active call only */ 71 #define ESP_HF_CLIENT_CHLD_FEAT_HOLD_ACC 0x08 /* 2 Active calls on hold and accept other waiting or held call */ 72 #define ESP_HF_CLIENT_CHLD_FEAT_PRIV_X 0x10 /* 2x Request private mode with specified call(put the rest on hold) */ 73 #define ESP_HF_CLIENT_CHLD_FEAT_MERGE 0x20 /* 3 Add held call to multiparty */ 74 #define ESP_HF_CLIENT_CHLD_FEAT_MERGE_DETACH 0x40 /* 4 Connect two calls and leave(disconnect from multiparty) */ 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_cb_event_t; 100 101 /// HFP client callback parameters 102 typedef union { 103 /** 104 * @brief ESP_HF_CLIENT_CONNECTION_STATE_EVT 105 */ 106 struct hf_client_conn_stat_param { 107 esp_hf_client_connection_state_t state; /*!< HF connection state */ 108 uint32_t peer_feat; /*!< AG supported features */ 109 uint32_t chld_feat; /*!< AG supported features on call hold and multiparty services */ 110 esp_bd_addr_t remote_bda; /*!< remote bluetooth device address */ 111 } conn_stat; /*!< HF callback param of ESP_HF_CLIENT_CONNECTION_STATE_EVT */ 112 113 /** 114 * @brief ESP_HF_CLIENT_AUDIO_STATE_EVT 115 */ 116 struct hf_client_audio_stat_param { 117 esp_hf_client_audio_state_t state; /*!< audio connection state */ 118 esp_bd_addr_t remote_bda; /*!< remote bluetooth device address */ 119 } audio_stat; /*!< HF callback param of ESP_HF_CLIENT_AUDIO_STATE_EVT */ 120 121 /** 122 * @brief ESP_HF_CLIENT_BVRA_EVT 123 */ 124 struct hf_client_bvra_param { 125 esp_hf_vr_state_t value; /*!< voice recognition state */ 126 } bvra; /*!< HF callback param of ESP_HF_CLIENT_BVRA_EVT */ 127 128 /** 129 * @brief ESP_HF_CLIENT_CIND_SERVICE_AVAILABILITY_EVT 130 */ 131 struct hf_client_service_availability_param { 132 esp_hf_network_state_t status; /*!< service availability status */ 133 } service_availability; /*!< HF callback param of ESP_HF_CLIENT_CIND_SERVICE_AVAILABILITY_EVT */ 134 135 /** 136 * @brief ESP_HF_CLIENT_CIND_ROAMING_STATUS_EVT 137 */ 138 struct hf_client_network_roaming_param { 139 esp_hf_roaming_status_t status; /*!< roaming status */ 140 } roaming; /*!< HF callback param of ESP_HF_CLIENT_CIND_ROAMING_STATUS_EVT */ 141 142 /** 143 * @brief ESP_HF_CLIENT_CIND_SIGNAL_STRENGTH_EVT 144 */ 145 struct hf_client_signal_strength_ind_param { 146 int value; /*!< signal strength value, ranges from 0 to 5 */ 147 } signal_strength; /*!< HF callback param of ESP_HF_CLIENT_CIND_SIGNAL_STRENGTH_EVT */ 148 149 /** 150 * @brief ESP_HF_CLIENT_CIND_BATTERY_LEVEL_EVT 151 */ 152 struct hf_client_battery_level_ind_param { 153 int value; /*!< battery charge value, ranges from 0 to 5 */ 154 } battery_level; /*!< HF callback param of ESP_HF_CLIENT_CIND_BATTERY_LEVEL_EVT */ 155 156 /** 157 * @brief ESP_HF_CLIENT_COPS_CURRENT_OPERATOR_EVT 158 */ 159 struct hf_client_current_operator_param { 160 const char *name; /*!< name of the network operator */ 161 } cops; /*!< HF callback param of ESP_HF_CLIENT_COPS_CURRENT_OPERATOR_EVT */ 162 163 /** 164 * @brief ESP_HF_CLIENT_CIND_CALL_EVT 165 */ 166 struct hf_client_call_ind_param { 167 esp_hf_call_status_t status; /*!< call status indicator */ 168 } call; /*!< HF callback param of ESP_HF_CLIENT_CIND_CALL_EVT */ 169 170 /** 171 * @brief ESP_HF_CLIENT_CIND_CALL_SETUP_EVT 172 */ 173 struct hf_client_call_setup_ind_param { 174 esp_hf_call_setup_status_t status; /*!< call setup status indicator */ 175 } call_setup; /*!< HF callback param of ESP_HF_CLIENT_BVRA_EVT */ 176 177 /** 178 * @brief ESP_HF_CLIENT_CIND_CALL_HELD_EVT 179 */ 180 struct hf_client_call_held_ind_param { 181 esp_hf_call_held_status_t status; /*!< bluetooth proprietary call hold status indicator */ 182 } call_held; /*!< HF callback param of ESP_HF_CLIENT_CIND_CALL_HELD_EVT */ 183 184 /** 185 * @brief ESP_HF_CLIENT_BTRH_EVT 186 */ 187 struct hf_client_btrh_param { 188 esp_hf_btrh_status_t status; /*!< call hold and response status result code */ 189 } btrh; /*!< HF callback param of ESP_HF_CLIENT_BRTH_EVT */ 190 191 /** 192 * @brief ESP_HF_CLIENT_CLIP_EVT 193 */ 194 struct hf_client_clip_param { 195 const char *number; /*!< phone number string of call */ 196 } clip; /*!< HF callback param of ESP_HF_CLIENT_CLIP_EVT */ 197 198 /** 199 * @brief ESP_HF_CLIENT_CCWA_EVT 200 */ 201 struct hf_client_ccwa_param { 202 const char *number; /*!< phone number string of waiting call */ 203 } ccwa; /*!< HF callback param of ESP_HF_CLIENT_BVRA_EVT */ 204 205 /** 206 * @brief ESP_HF_CLIENT_CLCC_EVT 207 */ 208 struct hf_client_clcc_param { 209 int idx; /*!< numbering(starting with 1) of the call */ 210 esp_hf_current_call_direction_t dir; /*!< direction of the call */ 211 esp_hf_current_call_status_t status; /*!< status of the call */ 212 esp_hf_current_call_mpty_type_t mpty; /*!< multi-party flag */ 213 char *number; /*!< phone number(optional) */ 214 } clcc; /*!< HF callback param of ESP_HF_CLIENT_CLCC_EVT */ 215 216 /** 217 * @brief ESP_HF_CLIENT_VOLUME_CONTROL_EVT 218 */ 219 struct hf_client_volume_control_param { 220 esp_hf_volume_control_target_t type; /*!< volume control target, speaker or microphone */ 221 int volume; /*!< gain, ranges from 0 to 15 */ 222 } volume_control; /*!< HF callback param of ESP_HF_CLIENT_VOLUME_CONTROL_EVT */ 223 224 /** 225 * @brief ESP_HF_CLIENT_AT_RESPONSE_EVT 226 */ 227 struct hf_client_at_response_param { 228 esp_hf_at_response_code_t code; /*!< AT response code */ 229 esp_hf_cme_err_t cme; /*!< Extended Audio Gateway Error Result Code */ 230 } at_response; /*!< HF callback param of ESP_HF_CLIENT_AT_RESPONSE_EVT */ 231 232 /** 233 * @brief ESP_HF_CLIENT_CNUM_EVT 234 */ 235 struct hf_client_cnum_param { 236 const char *number; /*!< phone number string */ 237 esp_hf_subscriber_service_type_t type; /*!< service type that the phone number relates to */ 238 } cnum; /*!< HF callback param of ESP_HF_CLIENT_CNUM_EVT */ 239 240 /** 241 * @brief ESP_HF_CLIENT_BSIR_EVT 242 */ 243 struct hf_client_bsirparam { 244 esp_hf_client_in_band_ring_state_t state; /*!< setting state of in-band ring tone */ 245 } bsir; /*!< HF callback param of ESP_HF_CLIENT_BSIR_EVT */ 246 247 /** 248 * @brief ESP_HF_CLIENT_BINP_EVT 249 */ 250 struct hf_client_binp_param { 251 const char *number; /*!< phone number corresponding to the last voice tag in the HF */ 252 } binp; /*!< HF callback param of ESP_HF_CLIENT_BINP_EVT */ 253 254 } esp_hf_client_cb_param_t; /*!< HFP client callback parameters */ 255 256 /** 257 * @brief HFP client incoming data callback function, the callback is useful in case of 258 * Voice Over HCI. 259 * @param[in] buf : pointer to incoming data(payload of HCI synchronous data packet), the 260 * buffer is allocated inside bluetooth protocol stack and will be released after 261 * invoke of the callback is finished. 262 * @param[in] len : size(in bytes) in buf 263 */ 264 typedef void (* esp_hf_client_incoming_data_cb_t)(const uint8_t *buf, uint32_t len); 265 266 /** 267 * @brief HFP client outgoing data callback function, the callback is useful in case of 268 * Voice Over HCI. Once audio connection is set up and the application layer has 269 * prepared data to send, the lower layer will call this function to read data 270 * and then send. This callback is supposed to be implemented as non-blocking, 271 * and if data is not enough, return value 0 is supposed. 272 * 273 * @param[in] buf : pointer to incoming data(payload of HCI synchronous data packet), the 274 * buffer is allocated inside bluetooth protocol stack and will be released after 275 * invoke of the callback is finished. 276 * 277 * @param[in] len : size(in bytes) in buf 278 * 279 * @return length of data successfully read 280 * 281 */ 282 typedef uint32_t (* esp_hf_client_outgoing_data_cb_t)(uint8_t *buf, uint32_t len); 283 284 /** 285 * @brief HFP client callback function type 286 * 287 * @param event : Event type 288 * 289 * @param param : Pointer to callback parameter 290 */ 291 typedef void (* esp_hf_client_cb_t)(esp_hf_client_cb_event_t event, esp_hf_client_cb_param_t *param); 292 293 /** 294 * @brief Register application callback function to HFP client module. 295 * This function should be called only after esp_bluedroid_enable() completes successfully. 296 * 297 * @param[in] callback: HFP client event callback function 298 * 299 * @return 300 * - ESP_OK: success 301 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 302 * - ESP_FAIL: if callback is a NULL function pointer 303 * 304 */ 305 esp_err_t esp_hf_client_register_callback(esp_hf_client_cb_t callback); 306 307 /** 308 * 309 * @brief Initialize the bluetooth HFP client module. 310 * This function should be called after esp_bluedroid_enable() completes successfully. 311 * 312 * @return 313 * - ESP_OK: if the initialization request is sent successfully 314 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 315 * - ESP_FAIL: others 316 * 317 */ 318 esp_err_t esp_hf_client_init(void); 319 320 /** 321 * 322 * @brief De-initialize for HFP client module. 323 * This function should be called only after esp_bluedroid_enable() completes successfully. 324 * 325 * @return 326 * - ESP_OK: success 327 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 328 * - ESP_FAIL: others 329 * 330 */ 331 esp_err_t esp_hf_client_deinit(void); 332 333 /** 334 * 335 * @brief Establish a Service Level Connection to remote bluetooth HFP audio gateway(AG) device. 336 * This function must be called after esp_hf_client_init() and before esp_hf_client_deinit(). 337 * 338 * @param[in] remote_bda: remote bluetooth device address 339 * 340 * @return 341 * - ESP_OK: connect request is sent to lower layer 342 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 343 * - ESP_FAIL: others 344 * 345 */ 346 esp_err_t esp_hf_client_connect(esp_bd_addr_t remote_bda); 347 348 /** 349 * 350 * @brief Disconnect from the remote HFP audio gateway. 351 * This function must be called after esp_hf_client_init() and before esp_hf_client_deinit(). 352 * 353 * @param[in] remote_bda: remote bluetooth device address 354 * 355 * @return 356 * - ESP_OK: disconnect request is sent to lower layer 357 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 358 * - ESP_FAIL: others 359 * 360 */ 361 esp_err_t esp_hf_client_disconnect(esp_bd_addr_t remote_bda); 362 363 /** 364 * 365 * @brief Create audio connection with remote HFP AG. 366 * As a precondition to use this API, Service Level Connection shall exist with AG. 367 * 368 * @param[in] remote_bda: remote bluetooth device address 369 * @return 370 * - ESP_OK: disconnect request is sent to lower layer 371 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 372 * - ESP_FAIL: others 373 * 374 */ 375 esp_err_t esp_hf_client_connect_audio(esp_bd_addr_t remote_bda); 376 377 /** 378 * 379 * @brief Release the established audio connection with remote HFP AG. 380 * As a precondition to use this API, Service Level Connection shall exist with AG. 381 * 382 * @param[in] remote_bda: remote bluetooth device address 383 * @return 384 * - ESP_OK: disconnect request is sent to lower layer 385 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 386 * - ESP_FAIL: others 387 * 388 */ 389 esp_err_t esp_hf_client_disconnect_audio(esp_bd_addr_t remote_bda); 390 391 /** 392 * 393 * @brief Enable voice recognition in the AG. 394 * As a precondition to use this API, Service Level Connection shall exist with AG. 395 * 396 * @return 397 * - ESP_OK: disconnect request is sent to lower layer 398 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 399 * - ESP_FAIL: others 400 * 401 */ 402 esp_err_t esp_hf_client_start_voice_recognition(void); 403 404 /** 405 * 406 * @brief Disable voice recognition in the AG. 407 * As a precondition to use this API, Service Level Connection shall exist with AG. 408 * 409 * @return 410 * - ESP_OK: disconnect request is sent to lower layer 411 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 412 * - ESP_FAIL: others 413 * 414 */ 415 esp_err_t esp_hf_client_stop_voice_recognition(void); 416 417 /** 418 * 419 * @brief Volume synchronization with AG. 420 * As a precondition to use this API, Service Level Connection shall exist with AG. 421 * 422 * @param[in] type: volume control target, speaker or microphone 423 * @param[in] volume: gain of the speaker of microphone, ranges 0 to 15 424 * 425 * @return 426 * - ESP_OK: disconnect request is sent to lower layer 427 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 428 * - ESP_FAIL: others 429 * 430 */ 431 esp_err_t esp_hf_client_volume_update(esp_hf_volume_control_target_t type, int volume); 432 433 /** 434 * 435 * @brief Place a call with a specified number, if number is NULL, last called number is called. 436 * As a precondition to use this API, Service Level Connection shall exist with AG. 437 * 438 * @param[in] number: number string of the call. If NULL, the last number is called(aka re-dial) 439 * 440 * @return 441 * - ESP_OK: disconnect request is sent to lower layer 442 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 443 * - ESP_FAIL: others 444 * 445 */ 446 esp_err_t esp_hf_client_dial(const char *number); 447 448 /** 449 * 450 * @brief Place a call with number specified by location(speed dial). 451 * As a precondition to use this API, Service Level Connection shall exist with AG. 452 * 453 * @param[in] location: location of the number in the memory 454 * 455 * @return 456 * - ESP_OK: disconnect request is sent to lower layer 457 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 458 * - ESP_FAIL: others 459 * 460 */ 461 462 esp_err_t esp_hf_client_dial_memory(int location); 463 464 /** 465 * 466 * @brief Send call hold and multiparty commands, or enhanced call control commands(Use AT+CHLD). 467 * As a precondition to use this API, Service Level Connection shall exist with AG. 468 * 469 * @param[in] chld: AT+CHLD call hold and multiparty handling AT command. 470 * @param[in] idx: used in Enhanced Call Control Mechanisms, used if chld is 471 * ESP_HF_CHLD_TYPE_REL_X or ESP_HF_CHLD_TYPE_PRIV_X 472 * 473 * @return 474 * - ESP_OK: disconnect request is sent to lower layer 475 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 476 * - ESP_FAIL: others 477 * 478 */ 479 esp_err_t esp_hf_client_send_chld_cmd(esp_hf_chld_type_t chld, int idx); 480 481 /** 482 * 483 * @brief Send response and hold action command(Send AT+BTRH command) 484 * As a precondition to use this API, Service Level Connection shall exist with AG. 485 * 486 * @param[in] btrh: response and hold action to send 487 * 488 * @return 489 * - ESP_OK: disconnect request is sent to lower layer 490 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 491 * - ESP_FAIL: others 492 * 493 */ 494 esp_err_t esp_hf_client_send_btrh_cmd(esp_hf_btrh_cmd_t btrh); 495 496 /** 497 * 498 * @brief Answer an incoming call(send ATA command). 499 * As a precondition to use this API, Service Level Connection shall exist with AG. 500 * 501 * @return 502 * - ESP_OK: disconnect request is sent to lower layer 503 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 504 * - ESP_FAIL: others 505 * 506 */ 507 esp_err_t esp_hf_client_answer_call(void); 508 509 /** 510 * 511 * @brief Reject an incoming call(send AT+CHUP command). 512 * As a precondition to use this API, Service Level Connection shall exist with AG. 513 * 514 * @return 515 * - ESP_OK: disconnect request is sent to lower layer 516 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 517 * - ESP_FAIL: others 518 * 519 */ 520 esp_err_t esp_hf_client_reject_call(void); 521 522 /** 523 * 524 * @brief Query list of current calls in AG(send AT+CLCC command). 525 * As a precondition to use this API, Service Level Connection shall exist with AG. 526 * 527 * @return 528 * - ESP_OK: disconnect request is sent to lower layer 529 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 530 * - ESP_FAIL: others 531 * 532 */ 533 esp_err_t esp_hf_client_query_current_calls(void); 534 535 /** 536 * 537 * @brief Query the name of currently selected network operator in AG(use AT+COPS commands). 538 * As a precondition to use this API, Service Level Connection shall exist with AG. 539 * 540 * @return 541 * - ESP_OK: disconnect request is sent to lower layer 542 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 543 * - ESP_FAIL: others 544 * 545 */ 546 esp_err_t esp_hf_client_query_current_operator_name(void); 547 548 /** 549 * 550 * @brief Get subscriber information number from AG(send AT+CNUM command) 551 * As a precondition to use this API, Service Level Connection shall exist with AG 552 * 553 * @return 554 * - ESP_OK: disconnect request is sent to lower layer 555 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 556 * - ESP_FAIL: others 557 * 558 */ 559 esp_err_t esp_hf_client_retrieve_subscriber_info(void); 560 561 /** 562 * 563 * @brief Transmit DTMF codes during an ongoing call(use AT+VTS commands) 564 * As a precondition to use this API, Service Level Connection shall exist with AG. 565 * 566 * @param[in] code: dtmf code, single ascii character in the set 0-9, #, *, A-D 567 * 568 * @return 569 * - ESP_OK: disconnect request is sent to lower layer 570 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 571 * - ESP_FAIL: others 572 * 573 */ 574 esp_err_t esp_hf_client_send_dtmf(char code); 575 576 /** 577 * 578 * @brief Request a phone number from AG corresponding to last voice tag recorded (send AT+BINP command). 579 * As a precondition to use this API, Service Level Connection shall exist with AG. 580 * 581 * @return 582 * - ESP_OK: disconnect request is sent to lower layer 583 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 584 * - ESP_FAIL: others 585 * 586 */ 587 esp_err_t esp_hf_client_request_last_voice_tag_number(void); 588 589 /** 590 * 591 * @brief Disable echo cancellation and noise reduction in the AG (use AT+NREC=0 command). 592 * As a precondition to use this API, Service Level Connection shall exist with AG 593 * 594 * @return 595 * - ESP_OK: NREC=0 request is sent to lower layer 596 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 597 * - ESP_FAIL: others 598 * 599 */ 600 esp_err_t esp_hf_client_send_nrec(void); 601 602 603 /** 604 * @brief Register HFP client data output function; the callback is only used in 605 * the case that Voice Over HCI is enabled. 606 * 607 * @param[in] recv: HFP client incoming data callback function 608 * 609 * @param[in] send: HFP client outgoing data callback function 610 * 611 * @return 612 * - ESP_OK: success 613 * - ESP_INVALID_STATE: if bluetooth stack is not yet enabled 614 * - ESP_FAIL: if callback is a NULL function pointer 615 * 616 */ 617 esp_err_t esp_hf_client_register_data_callback(esp_hf_client_incoming_data_cb_t recv, 618 esp_hf_client_outgoing_data_cb_t send); 619 620 /** 621 * @brief Trigger the lower-layer to fetch and send audio data. 622 * This function is only only used in the case that Voice Over HCI is enabled. After this 623 * function is called, lower layer will invoke esp_hf_client_outgoing_data_cb_t to fetch data. 624 * 625 * As a precondition to use this API, Service Level Connection shall exist with AG. 626 * 627 */ 628 void esp_hf_client_outgoing_data_ready(void); 629 630 631 /** 632 * @brief Initialize the down sampling converter. This is a utility function that can 633 * only be used in the case that Voice Over HCI is enabled. 634 * 635 * @param[in] src_sps: original samples per second(source audio data, i.e. 48000, 32000, 636 * 16000, 44100, 22050, 11025) 637 * @param[in] bits: number of bits per pcm sample (16) 638 * 639 * @param[in] channels: number of channels (i.e. mono(1), stereo(2)...) 640 */ 641 void esp_hf_client_pcm_resample_init(uint32_t src_sps, uint32_t bits, uint32_t channels); 642 643 /** 644 * @brief Deinitialize the down sampling converter. 645 */ 646 void esp_hf_client_pcm_resample_deinit(void); 647 648 /** 649 * @brief Down sampling utility to convert high sampling rate into 8K/16bits 1-channel mode PCM 650 * samples. This can only be used in the case that Voice Over HCI is enabled. 651 * 652 * @param[in] src: pointer to the buffer where the original sampling PCM are stored 653 * 654 * @param[in] in_bytes: length of the input PCM sample buffer in byte 655 * 656 * @param[in] dst: pointer to the buffer which is to be used to store the converted PCM samples 657 * 658 * @return number of samples converted 659 */ 660 int32_t esp_hf_client_pcm_resample(void *src, uint32_t in_bytes, void *dst); 661 662 #ifdef __cplusplus 663 } 664 #endif 665 666 667 #endif /* __ESP_HF_CLIENT_API_H__ */ 668
