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