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