1 /* 2 * Copyright (C) 2014 BlueKitchen GmbH 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions 6 * are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 3. Neither the name of the copyright holders nor the names of 14 * contributors may be used to endorse or promote products derived 15 * from this software without specific prior written permission. 16 * 4. Any redistribution, use, or modification is done solely for 17 * personal benefit and not for any commercial purpose or for 18 * monetary gain. 19 * 20 * THIS SOFTWARE IS PROVIDED BY BLUEKITCHEN GMBH AND CONTRIBUTORS 21 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BLUEKITCHEN 24 * GMBH OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 26 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 27 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 30 * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31 * SUCH DAMAGE. 32 * 33 * Please inquire about commercial licensing options at 34 * [email protected] 35 * 36 */ 37 38 /** 39 * @title HFP Hands-Free (HF) 40 * 41 */ 42 43 #ifndef BTSTACK_HFP_HF_H 44 #define BTSTACK_HFP_HF_H 45 46 #include "hci.h" 47 #include "classic/sdp_client_rfcomm.h" 48 #include "classic/hfp.h" 49 50 #if defined __cplusplus 51 extern "C" { 52 #endif 53 54 /* API_START */ 55 56 /** 57 * @brief Create HFP Hands-Free (HF) SDP service record. 58 * @param service 59 * @param rfcomm_channel_nr 60 * @param name or NULL for default value. Provide "" (empty string) to skip attribute 61 * @param supported_features 32-bit bitmap, see HFP_HFSF_* values in hfp.h 62 * @param codecs_nr number of codecs in codecs argument 63 * @param codecs 64 */ 65 void hfp_hf_create_sdp_record_with_codecs(uint8_t * service, uint32_t service_record_handle, int rfcomm_channel_nr, 66 const char * name, uint16_t supported_features, uint8_t codecs_nr, const uint8_t * codecs); 67 68 /** 69 * @brief Set up HFP Hands-Free (HF) device without additional supported features. 70 * @param rfcomm_channel_nr 71 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 72 * - L2CAP_SERVICE_ALREADY_REGISTERED, 73 * - RFCOMM_SERVICE_ALREADY_REGISTERED or 74 * - BTSTACK_MEMORY_ALLOC_FAILED if allocation of any of RFCOMM or L2CAP services failed 75 */ 76 uint8_t hfp_hf_init(uint8_t rfcomm_channel_nr); 77 78 /** 79 * @brief Set codecs. 80 * @param codecs_nr number of codecs in codecs argument 81 * @param codecs 82 */ 83 void hfp_hf_init_codecs(uint8_t codecs_nr, const uint8_t * codecs); 84 85 /** 86 * @brief Set supported features. 87 * @param supported_features 32-bit bitmap, see HFP_HFSF_* values in hfp.h 88 */ 89 void hfp_hf_init_supported_features(uint32_t supported_features); 90 91 /** 92 * @brief Set HF indicators. 93 * @param indicators_nr 94 * @param indicators 95 */ 96 void hfp_hf_init_hf_indicators(int indicators_nr, const uint16_t * indicators); 97 98 99 /** 100 * @brief Register callback for the HFP Hands-Free (HF) client. 101 * @param callback 102 */ 103 void hfp_hf_register_packet_handler(btstack_packet_handler_t callback); 104 105 /** 106 * @brief Set microphone gain used during SLC for Volume Synchronization. 107 * 108 * @param gain Valid range: [0,15] 109 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 110 * - ERROR_CODE_INVALID_HCI_COMMAND_PARAMETERS if invalid gain range 111 */ 112 uint8_t hfp_hf_set_default_microphone_gain(uint8_t gain); 113 114 /** 115 * @brief Set speaker gain used during SLC for Volume Synchronization. 116 * 117 * @param gain Valid range: [0,15] 118 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 119 * - ERROR_CODE_INVALID_HCI_COMMAND_PARAMETERS if invalid gain range 120 */ 121 uint8_t hfp_hf_set_default_speaker_gain(uint8_t gain); 122 123 /** 124 * @brief Establish RFCOMM connection with the AG with given Bluetooth address, 125 * and perform service level connection (SLC) agreement: 126 * - exchange supported features 127 * - retrieve Audio Gateway (AG) indicators and their status 128 * - enable indicator status update in the AG 129 * - notify the AG about its own available codecs, if possible 130 * - retrieve the AG information describing the call hold and multiparty services, if possible 131 * - retrieve which HF indicators are enabled on the AG, if possible 132 * The status of SLC connection establishment is reported via 133 * HFP_SUBEVENT_SERVICE_LEVEL_CONNECTION_ESTABLISHED. 134 * 135 * @param bd_addr Bluetooth address of the AG 136 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 137 * - ERROR_CODE_COMMAND_DISALLOWED if connection already exists, or 138 * - BTSTACK_MEMORY_ALLOC_FAILED 139 */ 140 uint8_t hfp_hf_establish_service_level_connection(bd_addr_t bd_addr); 141 142 /** 143 * @brief Release the RFCOMM channel and the audio connection between the HF and the AG. 144 * The status of releasing the SLC connection is reported via 145 * HFP_SUBEVENT_SERVICE_LEVEL_CONNECTION_RELEASED. 146 * 147 * @param acl_handle 148 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 149 */ 150 uint8_t hfp_hf_release_service_level_connection(hci_con_handle_t acl_handle); 151 152 /** 153 * @brief Enable status update for all indicators in the AG. 154 * The status field of the HFP_SUBEVENT_COMPLETE reports if the command was accepted. 155 * The status of an AG indicator is reported via HFP_SUBEVENT_AG_INDICATOR_STATUS_CHANGED. 156 * 157 * @param acl_handle 158 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 159 */ 160 uint8_t hfp_hf_enable_status_update_for_all_ag_indicators(hci_con_handle_t acl_handle); 161 162 /** 163 * @brief Disable status update for all indicators in the AG. 164 * The status field of the HFP_SUBEVENT_COMPLETE reports if the command was accepted. 165 * 166 * @param acl_handle 167 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 168 */ 169 uint8_t hfp_hf_disable_status_update_for_all_ag_indicators(hci_con_handle_t acl_handle); 170 171 /** 172 * @brief Enable or disable status update for the individual indicators in the AG using bitmap. 173 * The status field of the HFP_SUBEVENT_COMPLETE reports if the command was accepted. 174 * The status of an AG indicator is reported via HFP_SUBEVENT_AG_INDICATOR_STATUS_CHANGED. 175 * 176 * @param acl_handle 177 * @param indicators_status_bitmap 32-bit bitmap, 0 - indicator is disabled, 1 - indicator is enabled 178 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 179 */ 180 uint8_t hfp_hf_set_status_update_for_individual_ag_indicators(hci_con_handle_t acl_handle, uint32_t indicators_status_bitmap); 181 182 /** 183 * @brief Query the name of the currently selected Network operator by AG. 184 * 185 * The name is restricted to max 16 characters. The result is reported via 186 * HFP_SUBEVENT_NETWORK_OPERATOR_CHANGED subtype 187 * containing network operator mode, format and name. 188 * If no operator is selected, format and operator are omitted. 189 * 190 * @param acl_handle 191 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 192 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 193 * - ERROR_CODE_COMMAND_DISALLOWED if connection in wrong state 194 */ 195 uint8_t hfp_hf_query_operator_selection(hci_con_handle_t acl_handle); 196 197 /** 198 * @brief Enable Extended Audio Gateway Error result codes in the AG. 199 * Whenever there is an error relating to the functionality of the AG as a 200 * result of AT command, the AG shall send +CME ERROR. This error is reported via 201 * HFP_SUBEVENT_EXTENDED_AUDIO_GATEWAY_ERROR, see hfp_cme_error_t in hfp.h 202 * 203 * @param acl_handle 204 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 205 */ 206 uint8_t hfp_hf_enable_report_extended_audio_gateway_error_result_code(hci_con_handle_t acl_handle); 207 208 /** 209 * @brief Disable Extended Audio Gateway Error result codes in the AG. 210 * 211 * @param acl_handle 212 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 213 */ 214 uint8_t hfp_hf_disable_report_extended_audio_gateway_error_result_code(hci_con_handle_t acl_handle); 215 216 /** 217 * @brief Establish audio connection. 218 * The status of audio connection establishment is reported via HFP_SUBEVENT_AUDIO_CONNECTION_ESTABLISHED. 219 * 220 * @param acl_handle 221 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 222 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 223 * - ERROR_CODE_COMMAND_DISALLOWED if connection in wrong state 224 */ 225 uint8_t hfp_hf_establish_audio_connection(hci_con_handle_t acl_handle); 226 227 /** 228 * @brief Release audio connection. 229 * The status of releasing of the audio connection is reported via 230 * HFP_SUBEVENT_AUDIO_CONNECTION_RELEASED. 231 * 232 * @param acl_handle 233 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 234 */ 235 uint8_t hfp_hf_release_audio_connection(hci_con_handle_t acl_handle); 236 237 /** 238 * @brief Answer incoming call. 239 * 240 * @param acl_handle 241 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 242 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 243 * - ERROR_CODE_COMMAND_DISALLOWED if answering incoming call with wrong callsetup status 244 */ 245 uint8_t hfp_hf_answer_incoming_call(hci_con_handle_t acl_handle); 246 247 /** 248 * @brief Reject incoming call. 249 * 250 * @param acl_handle 251 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 252 */ 253 uint8_t hfp_hf_reject_incoming_call(hci_con_handle_t acl_handle); 254 255 /** 256 * @brief Release all held calls or sets User Determined User Busy (UDUB) for a waiting call. 257 * 258 * @param acl_handle 259 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 260 */ 261 uint8_t hfp_hf_user_busy(hci_con_handle_t acl_handle); 262 263 /** 264 * @brief Release all active calls (if any exist) and accepts the other (held or waiting) call. 265 * 266 * @param acl_handle 267 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 268 */ 269 uint8_t hfp_hf_end_active_and_accept_other(hci_con_handle_t acl_handle); 270 271 /** 272 * @brief Place all active calls (if any exist) on hold and accepts the other (held or waiting) call. 273 * 274 * @param acl_handle 275 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 276 */ 277 uint8_t hfp_hf_swap_calls(hci_con_handle_t acl_handle); 278 279 /** 280 * @brief Add a held call to the conversation. 281 * 282 * @param acl_handle 283 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 284 */ 285 uint8_t hfp_hf_join_held_call(hci_con_handle_t acl_handle); 286 287 /** 288 * @brief Connect the two calls and disconnects the subscriber from both calls (Explicit Call Transfer). 289 * 290 * @param acl_handle 291 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 292 */ 293 uint8_t hfp_hf_connect_calls(hci_con_handle_t acl_handle); 294 295 /** 296 * @brief Terminate an incoming or an outgoing call. HFP_SUBEVENT_CALL_TERMINATED is sent upon call termination. 297 * 298 * @param acl_handle 299 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 300 */ 301 uint8_t hfp_hf_terminate_call(hci_con_handle_t acl_handle); 302 303 /** 304 * @brief Terminate all held calls. 305 * 306 * @param acl_handle 307 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 308 */ 309 uint8_t hfp_hf_terminate_held_calls(hci_con_handle_t acl_handle); 310 311 /** 312 * @brief Initiate outgoing voice call by providing the destination phone number to the AG. 313 * 314 * @param acl_handle 315 * @param number 316 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 317 */ 318 uint8_t hfp_hf_dial_number(hci_con_handle_t acl_handle, char * number); 319 320 /** 321 * @brief Initiate outgoing voice call using the memory dialing feature of the AG. 322 * 323 * @param acl_handle 324 * @param memory_id 325 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 326 */ 327 uint8_t hfp_hf_dial_memory(hci_con_handle_t acl_handle, int memory_id); 328 329 /** 330 * @brief Initiate outgoing voice call by recalling the last number dialed by the AG. 331 * 332 * @param acl_handle 333 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 334 */ 335 uint8_t hfp_hf_redial_last_number(hci_con_handle_t acl_handle); 336 337 /** 338 * @brief Enable the “Call Waiting notification” function in the AG. 339 * The AG shall send the corresponding result code to the HF whenever 340 * an incoming call is waiting during an ongoing call. In that event, 341 * the HFP_SUBEVENT_CALL_WAITING_NOTIFICATION is emitted. 342 * 343 * @param acl_handle 344 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 345 */ 346 uint8_t hfp_hf_activate_call_waiting_notification(hci_con_handle_t acl_handle); 347 348 /** 349 * @brief Disable the “Call Waiting notification” function in the AG. 350 * 351 * @param acl_handle 352 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 353 */ 354 uint8_t hfp_hf_deactivate_call_waiting_notification(hci_con_handle_t acl_handle); 355 356 /** 357 * @brief Enable the “Calling Line Identification notification” function in the AG. 358 * The AG shall issue the corresponding result code just after every RING indication, 359 * when the HF is alerted in an incoming call. In that event, 360 * the HFP_SUBEVENT_CALLING_LINE_INDETIFICATION_NOTIFICATION is emitted. 361 * @param acl_handle 362 */ 363 uint8_t hfp_hf_activate_calling_line_notification(hci_con_handle_t acl_handle); 364 365 /** 366 * @brief Disable the “Calling Line Identification notification” function in the AG. 367 * 368 * @param acl_handle 369 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 370 */ 371 uint8_t hfp_hf_deactivate_calling_line_notification(hci_con_handle_t acl_handle); 372 373 374 /** 375 * @brief Deactivate echo canceling (EC) and noise reduction (NR) in the AG and emit 376 * HFP_SUBEVENT_ECHO_CANCELING_NOISE_REDUCTION_DEACTIVATE with status ERROR_CODE_SUCCESS if AG supports EC and AG. 377 * If the AG supports its own embedded echo canceling and/or noise reduction function, 378 * it shall have EC and NR activated until this function is called. 379 * 380 * @param acl_handle 381 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 382 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 383 * - ERROR_CODE_COMMAND_DISALLOWED if HFP_(HF/AG)SF_EC_NR_FUNCTION feature is not supported by AG and HF 384 */ 385 uint8_t hfp_hf_deactivate_echo_canceling_and_noise_reduction(hci_con_handle_t acl_handle); 386 387 /** 388 * @brief Activate voice recognition and emit HFP_SUBEVENT_VOICE_RECOGNITION_ACTIVATED event with status ERROR_CODE_SUCCESS 389 * if successful, otherwise ERROR_CODE_COMMAND_DISALLOWED. Prerequisite is established SLC. 390 * 391 * @param acl_handle 392 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 393 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 394 * - ERROR_CODE_COMMAND_DISALLOWED if feature HFP_(HF/AG)SF_VOICE_RECOGNITION_FUNCTION is not supported by HF and AG, or already activated 395 */ 396 uint8_t hfp_hf_activate_voice_recognition(hci_con_handle_t acl_handle); 397 398 /** 399 * @brief Dectivate voice recognition and emit HFP_SUBEVENT_VOICE_RECOGNITION_DEACTIVATED event with status ERROR_CODE_SUCCESS 400 * if successful, otherwise ERROR_CODE_COMMAND_DISALLOWED. Prerequisite is established SLC. 401 * 402 * @param acl_handle 403 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 404 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 405 * - ERROR_CODE_COMMAND_DISALLOWED if feature HFP_(HF/AG)SF_VOICE_RECOGNITION_FUNCTION is not supported by HF and AG, or already activated 406 */ 407 uint8_t hfp_hf_deactivate_voice_recognition(hci_con_handle_t acl_handle); 408 409 410 /** 411 * @brief Indicate that the HF is ready to accept audio. Prerequisite is established voice recognition session. 412 * The HF may call this function during an ongoing AVR (Audio Voice Recognition) session to terminate audio output from 413 * the AG (if there is any) and prepare the AG for new audio input. 414 * 415 * @param acl_handle 416 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 417 * - ERROR_CODE_COMMAND_DISALLOWED if feature HFP_(HF/AG)SF_ENHANCED_VOICE_RECOGNITION_STATUS is not supported by HF and AG, or wrong VRA status 418 */ 419 uint8_t hfp_hf_enhanced_voice_recognition_report_ready_for_audio(hci_con_handle_t acl_handle); 420 421 422 /** 423 * @brief Set microphone gain. 424 * 425 * @param acl_handle 426 * @param gain Valid range: [0,15] 427 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 428 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 429 * - ERROR_CODE_COMMAND_DISALLOWED if invalid gain range 430 */ 431 uint8_t hfp_hf_set_microphone_gain(hci_con_handle_t acl_handle, int gain); 432 433 /** 434 * @brief Set speaker gain. 435 * 436 * @param acl_handle 437 * @param gain Valid range: [0,15] 438 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 439 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 440 * - ERROR_CODE_COMMAND_DISALLOWED if invalid gain range 441 */ 442 uint8_t hfp_hf_set_speaker_gain(hci_con_handle_t acl_handle, int gain); 443 444 /** 445 * @brief Instruct the AG to transmit a DTMF code. 446 * 447 * @param acl_handle 448 * @param dtmf_code 449 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 450 */ 451 uint8_t hfp_hf_send_dtmf_code(hci_con_handle_t acl_handle, char code); 452 453 /** 454 * @brief Read numbers from the AG for the purpose of creating 455 * a unique voice tag and storing the number and its linked voice 456 * tag in the HF’s memory. 457 * The number is reported via HFP_SUBEVENT_NUMBER_FOR_VOICE_TAG. 458 * 459 * @param acl_handle 460 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 461 */ 462 uint8_t hfp_hf_request_phone_number_for_voice_tag(hci_con_handle_t acl_handle); 463 464 /** 465 * @brief Query the list of current calls in AG. 466 * The result is received via HFP_SUBEVENT_ENHANCED_CALL_STATUS. 467 * 468 * @param acl_handle 469 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 470 */ 471 uint8_t hfp_hf_query_current_call_status(hci_con_handle_t acl_handle); 472 473 /** 474 * @brief Release a call with index in the AG. 475 * 476 * @param acl_handle 477 * @param index 478 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 479 */ 480 uint8_t hfp_hf_release_call_with_index(hci_con_handle_t acl_handle, int index); 481 482 /** 483 * @brief Place all parties of a multiparty call on hold with the 484 * exception of the specified call. 485 * 486 * @param acl_handle 487 * @param index 488 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 489 */ 490 uint8_t hfp_hf_private_consultation_with_call(hci_con_handle_t acl_handle, int index); 491 492 /** 493 * @brief Query the status of the “Response and Hold” state of the AG. 494 * The result is reported via HFP_SUBEVENT_RESPONSE_AND_HOLD_STATUS. 495 * 496 * @param acl_handle 497 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 498 */ 499 uint8_t hfp_hf_rrh_query_status(hci_con_handle_t acl_handle); 500 501 /** 502 * @brief Put an incoming call on hold in the AG. 503 * 504 * @param acl_handle 505 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 506 */ 507 uint8_t hfp_hf_rrh_hold_call(hci_con_handle_t acl_handle); 508 509 /** 510 * @brief Accept held incoming call in the AG. 511 * 512 * @param acl_handle 513 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 514 */ 515 uint8_t hfp_hf_rrh_accept_held_call(hci_con_handle_t acl_handle); 516 517 /** 518 * @brief Reject held incoming call in the AG. 519 * 520 * @param acl_handle 521 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 522 */ 523 uint8_t hfp_hf_rrh_reject_held_call(hci_con_handle_t acl_handle); 524 525 /** 526 * @brief Query the AG subscriber number. The result is reported via HFP_SUBEVENT_SUBSCRIBER_NUMBER_INFORMATION. 527 * 528 * @param acl_handle 529 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 530 */ 531 uint8_t hfp_hf_query_subscriber_number(hci_con_handle_t acl_handle); 532 533 /** 534 * @brief Set HF indicator. 535 * 536 * @param acl_handle 537 * @param assigned_number 538 * @param value 539 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 540 */ 541 uint8_t hfp_hf_set_hf_indicator(hci_con_handle_t acl_handle, int assigned_number, int value); 542 543 /** 544 * @brief Tests if in-band ringtone is active on AG (requires SLC) 545 * 546 * @param acl_handler 547 * @return 0 if unknown acl_handle or in-band ring-tone disabled, otherwise 1 548 */ 549 int hfp_hf_in_band_ringtone_active(hci_con_handle_t acl_handle); 550 551 /** 552 * @brief Provide Apple Accessory information after SLC 553 * @param vendor_id 554 * @param product_id 555 * @param version 556 * @param features bitmask: bit 0 = reserved, bit 1 = battery reporting, bit 2 = docked or powered, bit 3 = Siri 557 */ 558 void hfp_hf_apple_set_identification(uint16_t vendor_id, uint16_t product_id, const char * version, uint8_t features); 559 560 /** 561 * @brief Set Apple Accessory Battery Level 562 * @param battery_level range: 0..9 563 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_INVALID_HCI_COMMAND_PARAMETERS battery level out of range 564 */ 565 uint8_t hfp_hf_apple_set_battery_level(uint8_t battery_level); 566 567 /** 568 * @brief Set Apple Accessory Docked State 569 * @param docked 0 = undocked, 1 = docked 570 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_INVALID_HCI_COMMAND_PARAMETERS docked state invalid 571 */ 572 uint8_t hfp_hf_apple_set_docked_state(uint8_t docked); 573 574 /** 575 * @brief Send AT command (most likely a vendor-specific command not part of standard HFP). 576 * @note Result (OK/ERROR) is reported via HFP_SUBEVENT_CUSTOM_AT_MESSAGE_SENT 577 * To receive potential unsolicited result code, add ENABLE_HFP_AT_MESSAGES to get all message via HFP_SUBEVENT_AT_MESSAGE_RECEIVED 578 * 579 * @param acl_handle 580 * @param at_command to send 581 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 582 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 583 * - ERROR_CODE_COMMAND_DISALLOWED if extended audio gateway error report is disabled 584 */ 585 uint8_t hfp_hf_send_at_command(hci_con_handle_t acl_handle, const char * at_command); 586 587 /** 588 * @brief Register custom AT command. 589 * @param hfp_custom_at_command (with '+' prefix) 590 */ 591 void hfp_hf_register_custom_at_command(hfp_custom_at_command_t * custom_at_command); 592 593 /** 594 * @brief De-Init HFP HF 595 */ 596 void hfp_hf_deinit(void); 597 598 /** 599 * @brief Create HFP Hands-Free (HF) SDP service record. 600 * @deprecated Use hfp_hf_create_sdp_record_with_codecs instead 601 * @param service 602 * @param rfcomm_channel_nr 603 * @param name 604 * @param suported_features 32-bit bitmap, see HFP_HFSF_* values in hfp.h 605 * @param wide_band_speech supported 606 */ 607 void hfp_hf_create_sdp_record(uint8_t * service, uint32_t service_record_handle, int rfcomm_channel_nr, const char * name, uint16_t supported_features, int wide_band_speech); 608 609 /* API_END */ 610 611 #if defined __cplusplus 612 } 613 #endif 614 615 #endif // BTSTACK_HFP_HF_H 616