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 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(uint8_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 Register custom AT command. 121 * @param hfp_custom_at_command (with 'AT+' prefix) 122 */ 123 void hfp_ag_register_custom_at_command(hfp_custom_at_command_t * custom_at_command); 124 125 /** 126 * @brief Enable/Disable in-band ring tone. 127 * 128 * @param use_in_band_ring_tone 129 */ 130 void hfp_ag_set_use_in_band_ring_tone(int use_in_band_ring_tone); 131 132 133 // actions used by local device / user 134 135 /** 136 * @brief Establish RFCOMM connection, and perform service level connection agreement: 137 * - exchange of supported features 138 * - report Audio Gateway (AG) indicators and their status 139 * - enable indicator status update in the AG 140 * - accept the information about available codecs in the Hands-Free (HF), if sent 141 * - report own information describing the call hold and multiparty services, if possible 142 * - report which HF indicators are enabled on the AG, if possible 143 * The status of SLC connection establishment is reported via 144 * HFP_SUBEVENT_SERVICE_LEVEL_CONNECTION_ESTABLISHED. 145 * 146 * @param bd_addr of HF 147 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 148 * - ERROR_CODE_COMMAND_DISALLOWED if connection already exists or connection in wrong state, or 149 * - BTSTACK_MEMORY_ALLOC_FAILED 150 * 151 */ 152 uint8_t hfp_ag_establish_service_level_connection(bd_addr_t bd_addr); 153 154 /** 155 * @brief Release the RFCOMM channel and the audio connection between the HF and the AG. 156 * If the audio connection exists, it will be released. 157 * The status of releasing the SLC connection is reported via 158 * HFP_SUBEVENT_SERVICE_LEVEL_CONNECTION_RELEASED. 159 * 160 * @param acl_handle 161 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 162 */ 163 uint8_t hfp_ag_release_service_level_connection(hci_con_handle_t acl_handle); 164 165 /** 166 * @brief Establish audio connection. 167 * The status of Audio connection establishment is reported via HSP_SUBEVENT_AUDIO_CONNECTION_COMPLETE. 168 * 169 * @param acl_handle 170 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 171 */ 172 uint8_t hfp_ag_establish_audio_connection(hci_con_handle_t acl_handle); 173 174 /** 175 * @brief Release audio connection. 176 * The status of releasing the Audio connection is reported via HSP_SUBEVENT_AUDIO_DISCONNECTION_COMPLETE. 177 * 178 * @param acl_handle 179 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 180 */ 181 uint8_t hfp_ag_release_audio_connection(hci_con_handle_t acl_handle); 182 183 /** 184 * @brief Put the current call on hold, if it exists, and accept incoming call. 185 */ 186 void hfp_ag_answer_incoming_call(void); 187 188 /** 189 * @brief Join held call with active call. 190 */ 191 void hfp_ag_join_held_call(void); 192 193 /** 194 * @brief Reject incoming call, if exists, or terminate active call. 195 */ 196 void hfp_ag_terminate_call(void); 197 198 /** 199 * @brief Put incoming call on hold. 200 */ 201 void hfp_ag_hold_incoming_call(void); 202 203 /** 204 * @brief Accept the held incoming call. 205 */ 206 void hfp_ag_accept_held_incoming_call(void); 207 208 /** 209 * @brief Reject the held incoming call. 210 */ 211 void hfp_ag_reject_held_incoming_call(void); 212 213 /** 214 * @brief Set microphone gain. 215 * 216 * @param acl_handle 217 * @param gain Valid range: [0,15] 218 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 219 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 220 * - ERROR_CODE_COMMAND_DISALLOWED if invalid gain range 221 */ 222 uint8_t hfp_ag_set_microphone_gain(hci_con_handle_t acl_handle, int gain); 223 224 /** 225 * @brief Set speaker gain. 226 * 227 * @param acl_handle 228 * @param gain Valid range: [0,15] 229 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 230 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 231 * - ERROR_CODE_COMMAND_DISALLOWED if invalid gain range 232 */ 233 uint8_t hfp_ag_set_speaker_gain(hci_con_handle_t acl_handle, int gain); 234 235 /** 236 * @brief Set battery level. 237 * 238 * @param battery_level Valid range: [0,5] 239 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 240 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 241 * - ERROR_CODE_COMMAND_DISALLOWED if invalid battery level range 242 */ 243 uint8_t hfp_ag_set_battery_level(int battery_level); 244 245 /** 246 * @brief Clear last dialed number. 247 */ 248 void hfp_ag_clear_last_dialed_number(void); 249 250 /** 251 * @brief Set last dialed number. 252 */ 253 void hfp_ag_set_last_dialed_number(const char * number); 254 255 /** 256 * @brief Notify the HF that an incoming call is waiting 257 * during an ongoing call. The notification will be sent only if the HF has 258 * has previously enabled the "Call Waiting notification" in the AG. 259 * 260 * @param acl_handle 261 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 262 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 263 * - ERROR_CODE_COMMAND_DISALLOWED if call waiting notification is not enabled 264 */ 265 uint8_t hfp_ag_notify_incoming_call_waiting(hci_con_handle_t acl_handle); 266 267 // Voice Recognition 268 269 /** 270 * @brief Activate voice recognition and emit HFP_SUBEVENT_VOICE_RECOGNITION_ACTIVATED event with status ERROR_CODE_SUCCESS 271 * if successful. Prerequisite is established SLC. 272 * 273 * @param acl_handle 274 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 275 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 276 * - ERROR_CODE_COMMAND_DISALLOWED if feature HFP_(HF/AG)SF_VOICE_RECOGNITION_FUNCTION is not supported by HF and AG, or already activated 277 */ 278 uint8_t hfp_ag_activate_voice_recognition(hci_con_handle_t acl_handle); 279 280 /** 281 * @brief Deactivate voice recognition and emit HFP_SUBEVENT_VOICE_RECOGNITION_DEACTIVATED event with status ERROR_CODE_SUCCESS 282 * if successful. Prerequisite is established SLC. 283 * 284 * @param acl_handle 285 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 286 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 287 * - ERROR_CODE_COMMAND_DISALLOWED if feature HFP_(HF/AG)SF_VOICE_RECOGNITION_FUNCTION is not supported by HF and AG, or already deactivated 288 */ 289 uint8_t hfp_ag_deactivate_voice_recognition(hci_con_handle_t acl_handle); 290 291 /** 292 * @brief Notify HF that sound will be played and HFP_SUBEVENT_ENHANCED_VOICE_RECOGNITION_AG_IS_STARTING_SOUND event with status ERROR_CODE_SUCCESS 293 * if successful, otherwise ERROR_CODE_COMMAND_DISALLOWED. 294 * 295 * @param acl_handle 296 * @param activate 297 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 298 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 299 * - ERROR_CODE_COMMAND_DISALLOWED if feature HFP_(HF/AG)SF_ENHANCED_VOICE_RECOGNITION_STATUS is not supported by HF and AG 300 */ 301 uint8_t hfp_ag_enhanced_voice_recognition_report_sending_audio(hci_con_handle_t acl_handle); 302 303 /** 304 * @brief Notify HF that AG is ready for input and emit HFP_SUBEVENT_ENHANCED_VOICE_RECOGNITION_AG_READY_TO_ACCEPT_AUDIO_INPUT event with status ERROR_CODE_SUCCESS 305 * if successful, otherwise ERROR_CODE_COMMAND_DISALLOWED. 306 * 307 * @param acl_handle 308 * @param activate 309 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 310 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 311 * - ERROR_CODE_COMMAND_DISALLOWED if feature HFP_(HF/AG)SF_ENHANCED_VOICE_RECOGNITION_STATUS is not supported by HF and AG 312 */ 313 uint8_t hfp_ag_enhanced_voice_recognition_report_ready_for_audio(hci_con_handle_t acl_handle); 314 315 /** 316 * @brief Notify that AG is processing input and emit HFP_SUBEVENT_ENHANCED_VOICE_RECOGNITION_AG_IS_PROCESSING_AUDIO_INPUT event with status ERROR_CODE_SUCCESS 317 * if successful, otherwise ERROR_CODE_COMMAND_DISALLOWED. 318 * 319 * @param acl_handle 320 * @param activate 321 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 322 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 323 * - ERROR_CODE_COMMAND_DISALLOWED if feature HFP_(HF/AG)SF_ENHANCED_VOICE_RECOGNITION_STATUS is not supported by HF and AG 324 */ 325 uint8_t hfp_ag_enhanced_voice_recognition_report_processing_input(hci_con_handle_t acl_handle); 326 327 /** 328 * @brief Send enhanced audio recognition message and HFP_SUBEVENT_ENHANCED_VOICE_RECOGNITION_AG_MESSAGE_SENT event with status ERROR_CODE_SUCCESS 329 * if successful, otherwise ERROR_CODE_COMMAND_DISALLOWED. 330 * 331 * @param acl_handle 332 * @param activate 333 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 334 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, 335 - ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if the message size exceeds the HFP_MAX_VR_TEXT_SIZE, or the command does not fit into a single packet frame, 336 * - ERROR_CODE_COMMAND_DISALLOWED if HF and AG do not support features: HFP_(HF/AG)SF_ENHANCED_VOICE_RECOGNITION_STATUS and HFP_(HF/AG)SF_VOICE_RECOGNITION_TEXT 337 */ 338 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); 339 340 /** 341 * @brief Send a phone number back to the HF. 342 * 343 * @param acl_handle 344 * @param phone_number 345 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 346 */ 347 uint8_t hfp_ag_send_phone_number_for_voice_tag(hci_con_handle_t acl_handle, const char * phone_number); 348 349 /** 350 * @brief Reject sending a phone number to the HF. 351 * 352 * @param acl_handle 353 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 354 */ 355 uint8_t hfp_ag_reject_phone_number_for_voice_tag(hci_con_handle_t acl_handle); 356 357 /** 358 * @brief Store phone number with initiated call. 359 * @param type 360 * @param number 361 */ 362 void hfp_ag_set_clip(uint8_t type, const char * number); 363 364 365 // Cellular Actions 366 367 /** 368 * @brief Pass the accept incoming call event to the AG. 369 */ 370 void hfp_ag_incoming_call(void); 371 372 /** 373 * @brief Outgoing call initiated 374 */ 375 void hfp_ag_outgoing_call_initiated(void); 376 377 /** 378 * @brief Pass the reject outgoing call event to the AG. 379 */ 380 void hfp_ag_outgoing_call_rejected(void); 381 382 /** 383 * @brief Pass the accept outgoing call event to the AG. 384 */ 385 void hfp_ag_outgoing_call_accepted(void); 386 387 /** 388 * @brief Pass the outgoing call ringing event to the AG. 389 */ 390 void hfp_ag_outgoing_call_ringing(void); 391 392 /** 393 * @brief Pass the outgoing call established event to the AG. 394 */ 395 void hfp_ag_outgoing_call_established(void); 396 397 /** 398 * @brief Pass the call dropped event to the AG. 399 */ 400 void hfp_ag_call_dropped(void); 401 402 /** 403 * @brief Set network registration status. 404 * @param status 0 - not registered, 1 - registered 405 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 406 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 407 * - ERROR_CODE_COMMAND_DISALLOWED if invalid registration status 408 */ 409 uint8_t hfp_ag_set_registration_status(int registration_status); 410 411 /** 412 * @brief Set network signal strength. 413 * 414 * @param signal_strength [0-5] 415 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 416 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 417 * - ERROR_CODE_COMMAND_DISALLOWED if invalid signal strength range 418 */ 419 uint8_t hfp_ag_set_signal_strength(int signal_strength); 420 421 /** 422 * @brief Set roaming status. 423 * 424 * @param roaming_status 0 - no roaming, 1 - roaming active 425 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 426 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 427 * - ERROR_CODE_COMMAND_DISALLOWED if invalid roaming status 428 */ 429 uint8_t hfp_ag_set_roaming_status(int roaming_status); 430 431 /** 432 * @brief Set subcriber number information, e.g. the phone number 433 * @param numbers 434 * @param numbers_count 435 */ 436 void hfp_ag_set_subcriber_number_information(hfp_phone_number_t * numbers, int numbers_count); 437 438 /** 439 * @brief Called by cellular unit after a DTMF code was transmitted, so that the next one can be emitted. 440 * 441 * @param acl_handle 442 * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist 443 */ 444 uint8_t hfp_ag_send_dtmf_code_done(hci_con_handle_t acl_handle); 445 446 /** 447 * @brief Report Extended Audio Gateway Error result codes in the AG. 448 * Whenever there is an error relating to the functionality of the AG as a 449 * result of AT command, the AG shall send +CME ERROR: 450 * - +CME ERROR: 0 - AG failure 451 * - +CME ERROR: 1 - no connection to phone 452 * - +CME ERROR: 3 - operation not allowed 453 * - +CME ERROR: 4 - operation not supported 454 * - +CME ERROR: 5 - PH-SIM PIN required 455 * - +CME ERROR: 10 - SIM not inserted 456 * - +CME ERROR: 11 - SIM PIN required 457 * - +CME ERROR: 12 - SIM PUK required 458 * - +CME ERROR: 13 - SIM failure 459 * - +CME ERROR: 14 - SIM busy 460 * - +CME ERROR: 16 - incorrect password 461 * - +CME ERROR: 17 - SIM PIN2 required 462 * - +CME ERROR: 18 - SIM PUK2 required 463 * - +CME ERROR: 20 - memory full 464 * - +CME ERROR: 21 - invalid index 465 * - +CME ERROR: 23 - memory failure 466 * - +CME ERROR: 24 - text string too long 467 * - +CME ERROR: 25 - invalid characters in text string 468 * - +CME ERROR: 26 - dial string too long 469 * - +CME ERROR: 27 - invalid characters in dial string 470 * - +CME ERROR: 30 - no network service 471 * - +CME ERROR: 31 - network Timeout. 472 * - +CME ERROR: 32 - network not allowed – Emergency calls only 473 * 474 * @param acl_handle 475 * @param error 476 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 477 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 478 * - ERROR_CODE_COMMAND_DISALLOWED if extended audio gateway error report is disabled 479 */ 480 uint8_t hfp_ag_report_extended_audio_gateway_error_result_code(hci_con_handle_t acl_handle, hfp_cme_error_t error); 481 482 /** 483 * @brief Send unsolicited result code (most likely a response to a vendor-specific command not part of standard HFP). 484 * @note Emits HFP_SUBEVENT_COMPLETE when result code was sent 485 * 486 * @param unsolicited_result_code to send 487 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 488 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 489 * - ERROR_CODE_COMMAND_DISALLOWED if extended audio gateway error report is disabled 490 */ 491 uint8_t hfp_ag_send_unsolicited_result_code(hci_con_handle_t acl_handle, const char * unsolicited_result_code); 492 493 /** 494 * @brief Send result code for AT command received via HFP_SUBEVENT_CUSTOM_AT_COMMAND 495 * @note Emits HFP_SUBEVENT_COMPLETE when result code was sent 496 * 497 * @param ok for OK, or ERROR 498 * @return status ERROR_CODE_SUCCESS if successful, otherwise: 499 * - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or 500 * - ERROR_CODE_COMMAND_DISALLOWED if extended audio gateway error report is disabled 501 */ 502 uint8_t hfp_ag_send_command_result_code(hci_con_handle_t acl_handle, bool ok); 503 504 /** 505 * @brief De-Init HFP AG 506 */ 507 void hfp_ag_deinit(void); 508 509 /* API_END */ 510 511 // testing 512 hfp_ag_indicator_t * hfp_ag_get_ag_indicators(hfp_connection_t * hfp_connection); 513 514 // @return true to process even as normal, false to cause HFP AG to ignore event 515 void hfp_ag_register_custom_call_sm_handler(bool (*handler)(hfp_ag_call_event_t event)); 516 517 #if defined __cplusplus 518 } 519 #endif 520 521 #endif 522