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 MATTHIAS 24 * RINGWALD 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 Audio Gateway (AG) 40 * 41 */ 42 43 #ifndef btstack_hfp_ag_h 44 #define btstack_hfp_ag_h 45 46 #include "hci.h" 47 #include "classic/sdp_client_rfcomm.h" 48 #include "classic/hfp.h" 49 #include "classic/hfp_gsm_model.h" 50 51 #if defined __cplusplus 52 extern "C" { 53 #endif 54 55 /* API_START */ 56 typedef struct { 57 uint8_t type; 58 const char * number; 59 } hfp_phone_number_t; 60 61 /** 62 * @brief Create HFP Audio Gateway (AG) SDP service record. 63 * @param service 64 * @param rfcomm_channel_nr 65 * @param name 66 * @param ability_to_reject_call 67 * @param suported_features 32-bit bitmap, see HFP_AGSF_* values in hfp.h 68 * @param wide_band_speech supported 69 */ 70 void hfp_ag_create_sdp_record(uint8_t * service, uint32_t service_record_handle, int rfcomm_channel_nr, const char * name, uint8_t ability_to_reject_call, uint16_t supported_features, int wide_band_speech); 71 72 /** 73 * @brief Set up HFP Audio Gateway (AG) device without additional supported features. 74 * @param rfcomm_channel_nr 75 */ 76 void hfp_ag_init(uint16_t rfcomm_channel_nr); 77 78 /** 79 * @brief Set codecs. 80 * @param codecs_nr 81 * @param codecs 82 */ 83 void hfp_ag_init_codecs(int codecs_nr, const uint8_t * codecs); 84 85 /** 86 * @brief Set supported features. 87 * @param supported_features 32-bit bitmap, see HFP_AGSF_* values in hfp.h 88 */ 89 void hfp_ag_init_supported_features(uint32_t supported_features); 90 91 /** 92 * @brief Set AG indicators. 93 * @param indicators_nr 94 * @param indicators 95 */ 96 void hfp_ag_init_ag_indicators(int ag_indicators_nr, const hfp_ag_indicator_t * ag_indicators); 97 98 /** 99 * @brief Set HF indicators. 100 * @param indicators_nr 101 * @param indicators 102 */ 103 void hfp_ag_init_hf_indicators(int hf_indicators_nr, const hfp_generic_status_indicator_t * hf_indicators); 104 105 /** 106 * @brief Set Call Hold services. 107 * @param indicators_nr 108 * @param indicators 109 */ 110 void hfp_ag_init_call_hold_services(int call_hold_services_nr, const char * call_hold_services[]); 111 112 113 /** 114 * @brief Register callback for the HFP Audio Gateway (AG) client. 115 * @param callback 116 */ 117 void hfp_ag_register_packet_handler(btstack_packet_handler_t callback); 118 119 /** 120 * @brief Enable/Disable in-band ring tone. 121 * 122 * @param use_in_band_ring_tone 123 */ 124 void hfp_ag_set_use_in_band_ring_tone(int use_in_band_ring_tone); 125 126 127 // actions used by local device / user 128 129 /** 130 * @brief Establish RFCOMM connection, and perform service level connection agreement: 131 * - exchange of supported features 132 * - report Audio Gateway (AG) indicators and their status 133 * - enable indicator status update in the AG 134 * - accept the information about available codecs in the Hands-Free (HF), if sent 135 * - report own information describing the call hold and multiparty services, if possible 136 * - report which HF indicators are enabled on the AG, if possible 137 * The status of SLC connection establishment is reported via 138 * HFP_SUBEVENT_SERVICE_LEVEL_CONNECTION_ESTABLISHED. 139 * 140 * @param bd_addr of HF 141 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 142 * - ERROR_CODE_COMMAND_DISALLOWED if connection already exists or connection in wrong state, or 143 * - BTSTACK_MEMORY_ALLOC_FAILED 144 * 145 */ 146 uint8_t hfp_ag_establish_service_level_connection(bd_addr_t bd_addr); 147 148 /** 149 * @brief Release the RFCOMM channel and the audio connection between the HF and the AG. 150 * If the audio connection exists, it will be released. 151 * The status of releasing the SLC connection is reported via 152 * HFP_SUBEVENT_SERVICE_LEVEL_CONNECTION_RELEASED. 153 * 154 * @param acl_handle 155 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 156 */ 157 uint8_t hfp_ag_release_service_level_connection(hci_con_handle_t acl_handle); 158 159 /** 160 * @brief Establish audio connection. 161 * The status of Audio connection establishment is reported via is reported via HSP_SUBEVENT_AUDIO_CONNECTION_COMPLETE. 162 * 163 * @param acl_handle 164 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 165 */ 166 uint8_t hfp_ag_establish_audio_connection(hci_con_handle_t acl_handle); 167 168 /** 169 * @brief Release audio connection. 170 * The status of releasing the Audio connection is reported via is reported via HSP_SUBEVENT_AUDIO_DISCONNECTION_COMPLETE. 171 * 172 * @param acl_handle 173 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 174 */ 175 uint8_t hfp_ag_release_audio_connection(hci_con_handle_t acl_handle); 176 177 /** 178 * @brief Put the current call on hold, if it exists, and accept incoming call. 179 */ 180 void hfp_ag_answer_incoming_call(void); 181 182 /** 183 * @brief Join held call with active call. 184 */ 185 void hfp_ag_join_held_call(void); 186 187 /** 188 * @brief Reject incoming call, if exists, or terminate active call. 189 */ 190 void hfp_ag_terminate_call(void); 191 192 /* 193 * @brief Put incoming call on hold. 194 */ 195 void hfp_ag_hold_incoming_call(void); 196 197 /* 198 * @brief Accept the held incoming call. 199 */ 200 void hfp_ag_accept_held_incoming_call(void); 201 202 /* 203 * @brief Reject the held incoming call. 204 */ 205 void hfp_ag_reject_held_incoming_call(void); 206 207 /* 208 * @brief Set microphone gain. 209 * 210 * @param acl_handle 211 * @param gain Valid range: [0,15] 212 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 213 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 214 * - ERROR_CODE_COMMAND_DISALLOWED if invalid gain range 215 */ 216 uint8_t hfp_ag_set_microphone_gain(hci_con_handle_t acl_handle, int gain); 217 218 /* 219 * @brief Set speaker gain. 220 * 221 * @param acl_handle 222 * @param gain Valid range: [0,15] 223 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 224 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 225 * - ERROR_CODE_COMMAND_DISALLOWED if invalid gain range 226 */ 227 uint8_t hfp_ag_set_speaker_gain(hci_con_handle_t acl_handle, int gain); 228 229 /* 230 * @brief Set battery level. 231 * 232 * @param battery_level Valid range: [0,5] 233 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 234 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 235 * - ERROR_CODE_COMMAND_DISALLOWED if invalid battery level range 236 */ 237 uint8_t hfp_ag_set_battery_level(int battery_level); 238 239 /* 240 * @brief Clear last dialed number. 241 */ 242 void hfp_ag_clear_last_dialed_number(void); 243 244 /* 245 * @brief Set last dialed number. 246 */ 247 void hfp_ag_set_last_dialed_number(const char * number); 248 249 /* 250 * @brief Notify the HF that an incoming call is waiting 251 * during an ongoing call. The notification will be sent only if the HF has 252 * has previously enabled the "Call Waiting notification" in the AG. 253 * 254 * @param acl_handle 255 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 256 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 257 * - ERROR_CODE_COMMAND_DISALLOWED if call waiting notification is not enabled 258 */ 259 uint8_t hfp_ag_notify_incoming_call_waiting(hci_con_handle_t acl_handle); 260 261 // Voice Recognition 262 263 /* 264 * @brief Activate voice recognition and emit HFP_SUBEVENT_VOICE_RECOGNITION_STATUS event with status ERROR_CODE_SUCCESS 265 * if successful. The state field of this event is set to current voice recognition state: 1 for activated, 0 otherwise. 266 * Prerequisite is established SLC. 267 * 268 * @param acl_handle 269 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 270 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 271 * - ERROR_CODE_COMMAND_DISALLOWED if AG or HF does not support voice recognition, or already activated 272 */ 273 uint8_t hfp_ag_activate_voice_recognition(hci_con_handle_t acl_handle); 274 275 /* 276 * @brief Deactivate voice recognition and emit HFP_SUBEVENT_VOICE_RECOGNITION_STATUS event with status ERROR_CODE_SUCCESS 277 * if successful. The state field of this event is set to current voice recognition state: 1 for activated, 0 otherwise. 278 * Prerequisite is established SLC. 279 * 280 * @param acl_handle 281 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 282 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 283 * - ERROR_CODE_COMMAND_DISALLOWED if AG or HF does not support voice recognition, or already deactivated 284 */ 285 uint8_t hfp_ag_deactivate_voice_recognition(hci_con_handle_t acl_handle); 286 287 /** 288 * @brief Activate enhanced voice recognition (EVR) and emit HFP_SUBEVENT_ENHANCED_VOICE_RECOGNITION_STATUS event with status ERROR_CODE_SUCCESS 289 * if successful, otherwise ERROR_CODE_COMMAND_DISALLOWED. The state field of this event is to the current state of EVR: 1 if activated, otherwise 0. 290 * Prerequisite is established SLC. 291 * 292 * @param acl_handle 293 * @param activate 294 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 295 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 296 * - ERROR_CODE_COMMAND_DISALLOWED if AG or HF does not support enhanced voice recognition 297 */ 298 uint8_t hfp_ag_activate_enhanced_voice_recognition(hci_con_handle_t acl_handle); 299 300 /* 301 * @brief Notify HF that sound will be played. 302 * 303 * @param acl_handle 304 * @param activate 305 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 306 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 307 * - ERROR_CODE_COMMAND_DISALLOWED if AG or HF does not support enhanced voice recognition 308 */ 309 uint8_t hfp_ag_enhanced_voice_recognition_report_sending_audio(hci_con_handle_t acl_handle); 310 311 /* 312 * @brief Notify HF that AG is ready for input. 313 * 314 * @param acl_handle 315 * @param activate 316 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 317 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 318 * - ERROR_CODE_COMMAND_DISALLOWED if AG or HF does not support enhanced voice recognition 319 */ 320 uint8_t hfp_ag_enhanced_voice_recognition_report_ready_for_audio(hci_con_handle_t acl_handle); 321 322 /* 323 * @brief Notify that AG is processing input. 324 * 325 * @param acl_handle 326 * @param activate 327 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 328 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 329 * - ERROR_CODE_COMMAND_DISALLOWED if AG or HF does not support enhanced voice recognition 330 */ 331 uint8_t hfp_ag_enhanced_voice_recognition_report_processing_input(hci_con_handle_t acl_handle); 332 333 /* 334 * @brief Send enhanced audio recognition message. 335 * 336 * @param acl_handle 337 * @param activate 338 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 339 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 340 * - ERROR_CODE_COMMAND_DISALLOWED if AG or HF does not support enhanced voice recognition 341 */ 342 uint8_t hfp_ag_enhanced_voice_recognition_send_message(hci_con_handle_t acl_handle, hfp_voice_recognition_state_t state, hfp_voice_recognition_message_t msg); 343 344 /** 345 * @brief Deactivate enhanced voice recognition (EVR) and emit HFP_SUBEVENT_ENHANCED_VOICE_RECOGNITION_STATUS event with status ERROR_CODE_SUCCESS 346 * if successful, otherwise ERROR_CODE_COMMAND_DISALLOWED. The state field of this event is to the current state of EVR: 1 if activated, otherwise 0. 347 * Prerequisite is established SLC. 348 * 349 * @param acl_handle 350 * @param activate 351 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 352 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 353 * - ERROR_CODE_COMMAND_DISALLOWED if AG or HF does not support enhanced voice recognition 354 */ 355 uint8_t hfp_ag_deactivate_enhanced_voice_recognition(hci_con_handle_t acl_handle); 356 357 /* 358 * @brief Send a phone number back to the HF. 359 * 360 * @param acl_handle 361 * @param phone_number 362 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 363 */ 364 uint8_t hfp_ag_send_phone_number_for_voice_tag(hci_con_handle_t acl_handle, const char * phone_number); 365 366 /* 367 * @brief Reject sending a phone number to the HF. 368 * 369 * @param acl_handle 370 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 371 */ 372 uint8_t hfp_ag_reject_phone_number_for_voice_tag(hci_con_handle_t acl_handle); 373 374 /** 375 * @brief Store phone number with initiated call. 376 * @param type 377 * @param number 378 */ 379 void hfp_ag_set_clip(uint8_t type, const char * number); 380 381 382 // Cellular Actions 383 384 /** 385 * @brief Pass the accept incoming call event to the AG. 386 */ 387 void hfp_ag_incoming_call(void); 388 389 /** 390 * @brief Outgoing call initiated 391 */ 392 void hfp_ag_outgoing_call_initiated(const char * number); 393 394 /** 395 * @brief Pass the reject outgoing call event to the AG. 396 */ 397 void hfp_ag_outgoing_call_rejected(void); 398 399 /** 400 * @brief Pass the accept outgoing call event to the AG. 401 */ 402 void hfp_ag_outgoing_call_accepted(void); 403 404 /** 405 * @brief Pass the outgoing call ringing event to the AG. 406 */ 407 void hfp_ag_outgoing_call_ringing(void); 408 409 /** 410 * @brief Pass the outgoing call established event to the AG. 411 */ 412 void hfp_ag_outgoing_call_established(void); 413 414 /** 415 * @brief Pass the call droped event to the AG. 416 */ 417 void hfp_ag_call_dropped(void); 418 419 /* 420 * @brief Set network registration status. 421 * @param status 0 - not registered, 1 - registered 422 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 423 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 424 * - ERROR_CODE_COMMAND_DISALLOWED if invalid registration status 425 */ 426 uint8_t hfp_ag_set_registration_status(int registration_status); 427 428 /* 429 * @brief Set network signal strength. 430 * 431 * @param signal_strength [0-5] 432 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 433 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 434 * - ERROR_CODE_COMMAND_DISALLOWED if invalid signal strength range 435 */ 436 uint8_t hfp_ag_set_signal_strength(int signal_strength); 437 438 /* 439 * @brief Set roaming status. 440 * 441 * @param roaming_status 0 - no roaming, 1 - roaming active 442 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 443 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 444 * - ERROR_CODE_COMMAND_DISALLOWED if invalid roaming status 445 */ 446 uint8_t hfp_ag_set_roaming_status(int roaming_status); 447 448 /* 449 * @brief Set subcriber number information, e.g. the phone number 450 * @param numbers 451 * @param numbers_count 452 */ 453 void hfp_ag_set_subcriber_number_information(hfp_phone_number_t * numbers, int numbers_count); 454 455 /* 456 * @brief Called by cellular unit after a DTMF code was transmitted, so that the next one can be emitted. 457 * 458 * @param acl_handle 459 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 460 */ 461 uint8_t hfp_ag_send_dtmf_code_done(hci_con_handle_t acl_handle); 462 463 /** 464 * @brief Report Extended Audio Gateway Error result codes in the AG. 465 * Whenever there is an error relating to the functionality of the AG as a 466 * result of AT command, the AG shall send +CME ERROR: 467 * - +CME ERROR: 0 - AG failure 468 * - +CME ERROR: 1 - no connection to phone 469 * - +CME ERROR: 3 - operation not allowed 470 * - +CME ERROR: 4 - operation not supported 471 * - +CME ERROR: 5 - PH-SIM PIN required 472 * - +CME ERROR: 10 - SIM not inserted 473 * - +CME ERROR: 11 - SIM PIN required 474 * - +CME ERROR: 12 - SIM PUK required 475 * - +CME ERROR: 13 - SIM failure 476 * - +CME ERROR: 14 - SIM busy 477 * - +CME ERROR: 16 - incorrect password 478 * - +CME ERROR: 17 - SIM PIN2 required 479 * - +CME ERROR: 18 - SIM PUK2 required 480 * - +CME ERROR: 20 - memory full 481 * - +CME ERROR: 21 - invalid index 482 * - +CME ERROR: 23 - memory failure 483 * - +CME ERROR: 24 - text string too long 484 * - +CME ERROR: 25 - invalid characters in text string 485 * - +CME ERROR: 26 - dial string too long 486 * - +CME ERROR: 27 - invalid characters in dial string 487 * - +CME ERROR: 30 - no network service 488 * - +CME ERROR: 31 - network Timeout. 489 * - +CME ERROR: 32 - network not allowed – Emergency calls only 490 * 491 * @param acl_handle 492 * @param error 493 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 494 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 495 * - ERROR_CODE_COMMAND_DISALLOWED if extended audio gateway error report is disabled 496 */ 497 uint8_t hfp_ag_report_extended_audio_gateway_error_result_code(hci_con_handle_t acl_handle, hfp_cme_error_t error); 498 499 /** 500 * @brief De-Init HFP AG 501 */ 502 void hfp_ag_deinit(void); 503 504 /* API_END */ 505 506 // testing 507 hfp_ag_indicator_t * hfp_ag_get_ag_indicators(hfp_connection_t * hfp_connection); 508 509 #if defined __cplusplus 510 } 511 #endif 512 513 #endif 514