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 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 61 * @param suported_features 32-bit bitmap, see HFP_HFSF_* values in hfp.h 62 * @param wide_band_speech supported 63 */ 64 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); 65 66 /** 67 * @brief Set up HFP Hands-Free (HF) device without additional supported features. 68 * @param rfcomm_channel_nr 69 */ 70 void hfp_hf_init(uint16_t rfcomm_channel_nr); 71 72 /** 73 * @brief Set codecs. 74 * @param codecs_nr 75 * @param codecs 76 */ 77 void hfp_hf_init_codecs(int codecs_nr, const uint8_t * codecs); 78 79 /** 80 * @brief Set supported features. 81 * @param supported_features 32-bit bitmap, see HFP_HFSF_* values in hfp.h 82 */ 83 void hfp_hf_init_supported_features(uint32_t supported_features); 84 85 /** 86 * @brief Set HF indicators. 87 * @param indicators_nr 88 * @param indicators 89 */ 90 void hfp_hf_init_hf_indicators(int indicators_nr, const uint16_t * indicators); 91 92 93 /** 94 * @brief Register callback for the HFP Hands-Free (HF) client. 95 * @param callback 96 */ 97 void hfp_hf_register_packet_handler(btstack_packet_handler_t callback); 98 99 /** 100 * @brief Establish RFCOMM connection with the AG with given Bluetooth address, 101 * and perform service level connection (SLC) agreement: 102 * - exchange supported features 103 * - retrieve Audio Gateway (AG) indicators and their status 104 * - enable indicator status update in the AG 105 * - notify the AG about its own available codecs, if possible 106 * - retrieve the AG information describing the call hold and multiparty services, if possible 107 * - retrieve which HF indicators are enabled on the AG, if possible 108 * The status of SLC connection establishment is reported via 109 * HFP_SUBEVENT_SERVICE_LEVEL_CONNECTION_ESTABLISHED. 110 * 111 * @param bd_addr Bluetooth address of the AG 112 */ 113 void hfp_hf_establish_service_level_connection(bd_addr_t bd_addr); 114 115 /** 116 * @brief Release the RFCOMM channel and the audio connection between the HF and the AG. 117 * The status of releasing the SLC connection is reported via 118 * HFP_SUBEVENT_SERVICE_LEVEL_CONNECTION_RELEASED. 119 * 120 * @param acl_handle of the AG 121 */ 122 void hfp_hf_release_service_level_connection(hci_con_handle_t acl_handle); 123 124 /** 125 * @brief Enable status update for all indicators in the AG. 126 * The status field of the HFP_SUBEVENT_COMPLETE reports if the command was accepted. 127 * The status of an AG indicator is reported via HFP_SUBEVENT_AG_INDICATOR_STATUS_CHANGED. 128 * 129 * @param acl_handle of the AG 130 */ 131 void hfp_hf_enable_status_update_for_all_ag_indicators(hci_con_handle_t acl_handle); 132 133 /** 134 * @brief Disable status update for all indicators in the AG. 135 * The status field of the HFP_SUBEVENT_COMPLETE reports if the command was accepted. 136 * @param acl_handle of the AG 137 */ 138 void hfp_hf_disable_status_update_for_all_ag_indicators(hci_con_handle_t acl_handle); 139 140 /** 141 * @brief Enable or disable status update for the individual indicators in the AG using bitmap. 142 * The status field of the HFP_SUBEVENT_COMPLETE reports if the command was accepted. 143 * The status of an AG indicator is reported via HFP_SUBEVENT_AG_INDICATOR_STATUS_CHANGED. 144 * 145 * @param acl_handle of the AG 146 * @param indicators_status_bitmap 32-bit bitmap, 0 - indicator is disabled, 1 - indicator is enabled 147 */ 148 void hfp_hf_set_status_update_for_individual_ag_indicators(hci_con_handle_t acl_handle, uint32_t indicators_status_bitmap); 149 150 /** 151 * @brief Query the name of the currently selected Network operator by AG. 152 * 153 * The name is restricted to max 16 characters. The result is reported via 154 * HFP_SUBEVENT_NETWORK_OPERATOR_CHANGED subtype 155 * containing network operator mode, format and name. 156 * If no operator is selected, format and operator are omitted. 157 * 158 * @param acl_handle of the AG 159 */ 160 void hfp_hf_query_operator_selection(hci_con_handle_t acl_handle); 161 162 /** 163 * @brief Enable Extended Audio Gateway Error result codes in the AG. 164 * Whenever there is an error relating to the functionality of the AG as a 165 * result of AT command, the AG shall send +CME ERROR. This error is reported via 166 * HFP_SUBEVENT_EXTENDED_AUDIO_GATEWAY_ERROR, see hfp_cme_error_t in hfp.h 167 * 168 * @param acl_handle of the AG 169 */ 170 void hfp_hf_enable_report_extended_audio_gateway_error_result_code(hci_con_handle_t acl_handle); 171 172 /** 173 * @brief Disable Extended Audio Gateway Error result codes in the AG. 174 * 175 * @param acl_handle of the AG 176 */ 177 void hfp_hf_disable_report_extended_audio_gateway_error_result_code(hci_con_handle_t acl_handle); 178 179 /** 180 * @brief Establish audio connection. 181 * The status of audio connection establishment is reported via 182 * HFP_SUBEVENT_AUDIO_CONNECTION_ESTABLISHED. 183 * @param acl_handle of the AG 184 */ 185 void hfp_hf_establish_audio_connection(hci_con_handle_t acl_handle); 186 187 /** 188 * @brief Release audio connection. 189 * The status of releasing of the audio connection is reported via 190 * HFP_SUBEVENT_AUDIO_CONNECTION_RELEASED. 191 * 192 * @param acl_handle of the AG 193 */ 194 void hfp_hf_release_audio_connection(hci_con_handle_t acl_handle); 195 196 /** 197 * @brief Answer incoming call. 198 * @param acl_handle of the AG 199 */ 200 void hfp_hf_answer_incoming_call(hci_con_handle_t acl_handle); 201 202 /** 203 * @brief Reject incoming call. 204 * @param acl_handle of the AG 205 */ 206 void hfp_hf_reject_incoming_call(hci_con_handle_t acl_handle); 207 208 /** 209 * @brief Release all held calls or sets User Determined User Busy (UDUB) for a waiting call. 210 * @param acl_handle of the AG 211 */ 212 void hfp_hf_user_busy(hci_con_handle_t acl_handle); 213 214 /** 215 * @brief Release all active calls (if any exist) and accepts the other (held or waiting) call. 216 * @param acl_handle of the AG 217 */ 218 void hfp_hf_end_active_and_accept_other(hci_con_handle_t acl_handle); 219 220 /** 221 * @brief Place all active calls (if any exist) on hold and accepts the other (held or waiting) call. 222 * @param acl_handle of the AG 223 */ 224 void hfp_hf_swap_calls(hci_con_handle_t acl_handle); 225 226 /** 227 * @brief Add a held call to the conversation. 228 * @param acl_handle of the AG 229 */ 230 void hfp_hf_join_held_call(hci_con_handle_t acl_handle); 231 232 /** 233 * @brief Connect the two calls and disconnects the subscriber from both calls (Explicit Call 234 Transfer). 235 * @param acl_handle of the AG 236 */ 237 void hfp_hf_connect_calls(hci_con_handle_t acl_handle); 238 239 /** 240 * @brief Terminate an incoming or an outgoing call. 241 * HFP_SUBEVENT_CALL_TERMINATED is sent upon call termination. 242 * @param acl_handle of the AG 243 */ 244 void hfp_hf_terminate_call(hci_con_handle_t acl_handle); 245 246 /** 247 * @brief Initiate outgoing voice call by providing the destination phone number to the AG. 248 * @param acl_handle of the AG 249 * @param number 250 */ 251 void hfp_hf_dial_number(hci_con_handle_t acl_handle, char * number); 252 253 /** 254 * @brief Initiate outgoing voice call using the memory dialing feature of the AG. 255 * @param acl_handle of the AG 256 * @param memory_id 257 */ 258 void hfp_hf_dial_memory(hci_con_handle_t acl_handle, int memory_id); 259 260 /** 261 * @brief Initiate outgoing voice call by recalling the last number dialed by the AG. 262 * @param acl_handle of the AG 263 */ 264 void hfp_hf_redial_last_number(hci_con_handle_t acl_handle); 265 266 /* 267 * @brief Enable the “Call Waiting notification” function in the AG. 268 * The AG shall send the corresponding result code to the HF whenever 269 * an incoming call is waiting during an ongoing call. In that event, 270 * the HFP_SUBEVENT_CALL_WAITING_NOTIFICATION is emitted. 271 * 272 * @param acl_handle of the AG 273 */ 274 void hfp_hf_activate_call_waiting_notification(hci_con_handle_t acl_handle); 275 276 /* 277 * @brief Disable the “Call Waiting notification” function in the AG. 278 * @param acl_handle of the AG 279 */ 280 void hfp_hf_deactivate_call_waiting_notification(hci_con_handle_t acl_handle); 281 282 /* 283 * @brief Enable the “Calling Line Identification notification” function in the AG. 284 * The AG shall issue the corresponding result code just after every RING indication, 285 * when the HF is alerted in an incoming call. In that event, 286 * the HFP_SUBEVENT_CALLING_LINE_INDETIFICATION_NOTIFICATION is emitted. 287 * @param acl_handle of the AG 288 */ 289 void hfp_hf_activate_calling_line_notification(hci_con_handle_t acl_handle); 290 291 /* 292 * @brief Disable the “Calling Line Identification notification” function in the AG. 293 * @param acl_handle of the AG 294 */ 295 void hfp_hf_deactivate_calling_line_notification(hci_con_handle_t acl_handle); 296 297 298 /* 299 * @brief Activate echo canceling and noise reduction in the AG. By default, 300 * if the AG supports its own embedded echo canceling and/or noise reduction 301 * functions, it shall have them activated until this function is called. 302 * If the AG does not support any echo canceling and noise reduction functions, 303 * it shall respond with the ERROR indicator (TODO) 304 * @param acl_handle of the AG 305 */ 306 void hfp_hf_activate_echo_canceling_and_noise_reduction(hci_con_handle_t acl_handle); 307 308 /* 309 * @brief Deactivate echo canceling and noise reduction in the AG. 310 */ 311 void hfp_hf_deactivate_echo_canceling_and_noise_reduction(hci_con_handle_t acl_handle); 312 313 /* 314 * @brief Activate voice recognition function. 315 * @param acl_handle of the AG 316 */ 317 uint8_t hfp_hf_activate_voice_recognition_notification(hci_con_handle_t acl_handle); 318 319 /* 320 * @brief Dectivate voice recognition function. 321 * @param acl_handle of the AG 322 */ 323 uint8_t hfp_hf_deactivate_voice_recognition_notification(hci_con_handle_t acl_handle); 324 325 uint8_t hfp_hf_start_enhanced_voice_recognition_session(hci_con_handle_t acl_handle); 326 327 uint8_t hfp_hf_stop_enhanced_voice_recognition_session(hci_con_handle_t acl_handle); 328 329 /* 330 * @brief Set microphone gain. 331 * @param acl_handle of the AG 332 * @param gain Valid range: [0,15] 333 */ 334 void hfp_hf_set_microphone_gain(hci_con_handle_t acl_handle, int gain); 335 336 /* 337 * @brief Set speaker gain. 338 * @param acl_handle of the AG 339 * @param gain Valid range: [0,15] 340 */ 341 void hfp_hf_set_speaker_gain(hci_con_handle_t acl_handle, int gain); 342 343 /* 344 * @brief Instruct the AG to transmit a DTMF code. 345 * @param acl_handle of the AG 346 * @param dtmf_code 347 */ 348 void hfp_hf_send_dtmf_code(hci_con_handle_t acl_handle, char code); 349 350 /* 351 * @brief Read numbers from the AG for the purpose of creating 352 * a unique voice tag and storing the number and its linked voice 353 * tag in the HF’s memory. 354 * The number is reported via HFP_SUBEVENT_NUMBER_FOR_VOICE_TAG. 355 * @param acl_handle of the AG 356 */ 357 void hfp_hf_request_phone_number_for_voice_tag(hci_con_handle_t acl_handle); 358 359 /* 360 * @brief Query the list of current calls in AG. 361 * The result is received via HFP_SUBEVENT_ENHANCED_CALL_STATUS. 362 * @param acl_handle of the AG 363 */ 364 void hfp_hf_query_current_call_status(hci_con_handle_t acl_handle); 365 366 /* 367 * @brief Release a call with index in the AG. 368 * @param acl_handle of the AG 369 * @param index 370 */ 371 void hfp_hf_release_call_with_index(hci_con_handle_t acl_handle, int index); 372 373 /* 374 * @brief Place all parties of a multiparty call on hold with the 375 * exception of the specified call. 376 * @param acl_handle of the AG 377 * @param index 378 */ 379 void hfp_hf_private_consultation_with_call(hci_con_handle_t acl_handle, int index); 380 381 /* 382 * @brief Query the status of the “Response and Hold” state of the AG. 383 * The result is reported via HFP_SUBEVENT_RESPONSE_AND_HOLD_STATUS. 384 * @param acl_handle of the AG 385 */ 386 void hfp_hf_rrh_query_status(hci_con_handle_t acl_handle); 387 388 /* 389 * @brief Put an incoming call on hold in the AG. 390 * @param acl_handle of the AG 391 */ 392 void hfp_hf_rrh_hold_call(hci_con_handle_t acl_handle); 393 394 /* 395 * @brief Accept held incoming call in the AG. 396 * @param acl_handle of the AG 397 */ 398 void hfp_hf_rrh_accept_held_call(hci_con_handle_t acl_handle); 399 400 /* 401 * @brief Reject held incoming call in the AG. 402 * @param acl_handle of the AG 403 */ 404 void hfp_hf_rrh_reject_held_call(hci_con_handle_t acl_handle); 405 406 /* 407 * @brief Query the AG subscriber number. 408 * The result is reported via HFP_SUBEVENT_SUBSCRIBER_NUMBER_INFORMATION. 409 * @param acl_handle of the AG 410 */ 411 void hfp_hf_query_subscriber_number(hci_con_handle_t acl_handle); 412 413 /* 414 * @brief Set HF indicator. 415 * @param acl_handle of the AG 416 * @param assigned_number 417 * @param value 418 */ 419 void hfp_hf_set_hf_indicator(hci_con_handle_t acl_handle, int assigned_number, int value); 420 421 /* 422 * @brief Tests if in-band ringtone is active on AG (requires SLC) 423 * @aram acl_handler of the AG 424 */ 425 int hfp_hf_in_band_ringtone_active(hci_con_handle_t acl_handle); 426 427 /** 428 * @brief De-Init HFP HF 429 */ 430 void hfp_hf_deinit(void); 431 432 /* API_END */ 433 434 #if defined __cplusplus 435 } 436 #endif 437 438 #endif // BTSTACK_HFP_HF_H 439