xref: /btstack/src/classic/hfp_hf.h (revision 3c65e7053eb0574febf31fb17a58168d45bb11e2)
13deb3ec6SMatthias Ringwald /*
23deb3ec6SMatthias Ringwald  * Copyright (C) 2014 BlueKitchen GmbH
33deb3ec6SMatthias Ringwald  *
43deb3ec6SMatthias Ringwald  * Redistribution and use in source and binary forms, with or without
53deb3ec6SMatthias Ringwald  * modification, are permitted provided that the following conditions
63deb3ec6SMatthias Ringwald  * are met:
73deb3ec6SMatthias Ringwald  *
83deb3ec6SMatthias Ringwald  * 1. Redistributions of source code must retain the above copyright
93deb3ec6SMatthias Ringwald  *    notice, this list of conditions and the following disclaimer.
103deb3ec6SMatthias Ringwald  * 2. Redistributions in binary form must reproduce the above copyright
113deb3ec6SMatthias Ringwald  *    notice, this list of conditions and the following disclaimer in the
123deb3ec6SMatthias Ringwald  *    documentation and/or other materials provided with the distribution.
133deb3ec6SMatthias Ringwald  * 3. Neither the name of the copyright holders nor the names of
143deb3ec6SMatthias Ringwald  *    contributors may be used to endorse or promote products derived
153deb3ec6SMatthias Ringwald  *    from this software without specific prior written permission.
163deb3ec6SMatthias Ringwald  * 4. Any redistribution, use, or modification is done solely for
173deb3ec6SMatthias Ringwald  *    personal benefit and not for any commercial purpose or for
183deb3ec6SMatthias Ringwald  *    monetary gain.
193deb3ec6SMatthias Ringwald  *
203deb3ec6SMatthias Ringwald  * THIS SOFTWARE IS PROVIDED BY BLUEKITCHEN GMBH AND CONTRIBUTORS
213deb3ec6SMatthias Ringwald  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
223deb3ec6SMatthias Ringwald  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
233deb3ec6SMatthias Ringwald  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL MATTHIAS
243deb3ec6SMatthias Ringwald  * RINGWALD OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
253deb3ec6SMatthias Ringwald  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
263deb3ec6SMatthias Ringwald  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
273deb3ec6SMatthias Ringwald  * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
283deb3ec6SMatthias Ringwald  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
293deb3ec6SMatthias Ringwald  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
303deb3ec6SMatthias Ringwald  * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
313deb3ec6SMatthias Ringwald  * SUCH DAMAGE.
323deb3ec6SMatthias Ringwald  *
333deb3ec6SMatthias Ringwald  * Please inquire about commercial licensing options at
343deb3ec6SMatthias Ringwald  * [email protected]
353deb3ec6SMatthias Ringwald  *
363deb3ec6SMatthias Ringwald  */
373deb3ec6SMatthias Ringwald 
38fe5a6c4eSMilanka Ringwald /**
39fe5a6c4eSMilanka Ringwald  * @title HFP Hands-Free (HF)
40fe5a6c4eSMilanka Ringwald  *
41fe5a6c4eSMilanka Ringwald  */
423deb3ec6SMatthias Ringwald 
4380e33422SMatthias Ringwald #ifndef BTSTACK_HFP_HF_H
4480e33422SMatthias Ringwald #define BTSTACK_HFP_HF_H
453deb3ec6SMatthias Ringwald 
463deb3ec6SMatthias Ringwald #include "hci.h"
47efda0b48SMatthias Ringwald #include "classic/sdp_client_rfcomm.h"
483edc84c5SMatthias Ringwald #include "classic/hfp.h"
493deb3ec6SMatthias Ringwald 
503deb3ec6SMatthias Ringwald #if defined __cplusplus
513deb3ec6SMatthias Ringwald extern "C" {
523deb3ec6SMatthias Ringwald #endif
533deb3ec6SMatthias Ringwald 
543deb3ec6SMatthias Ringwald /* API_START */
553deb3ec6SMatthias Ringwald 
563deb3ec6SMatthias Ringwald /**
573deb3ec6SMatthias Ringwald  * @brief Create HFP Hands-Free (HF) SDP service record.
58a0ffb263SMatthias Ringwald  * @param service
59a0ffb263SMatthias Ringwald  * @param rfcomm_channel_nr
60a0ffb263SMatthias Ringwald  * @param name
61a0ffb263SMatthias Ringwald  * @param suported_features 32-bit bitmap, see HFP_HFSF_* values in hfp.h
624f84bf36SMatthias Ringwald  * @param wide_band_speech supported
633deb3ec6SMatthias Ringwald  */
644f84bf36SMatthias Ringwald 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);
653deb3ec6SMatthias Ringwald 
663deb3ec6SMatthias Ringwald /**
67a0ffb263SMatthias Ringwald  * @brief Set up HFP Hands-Free (HF) device without additional supported features.
68a0ffb263SMatthias Ringwald  * @param rfcomm_channel_nr
69b4df8028SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise:
70b4df8028SMilanka Ringwald  *                  - L2CAP_SERVICE_ALREADY_REGISTERED,
71b4df8028SMilanka Ringwald  *                  - RFCOMM_SERVICE_ALREADY_REGISTERED or
72b4df8028SMilanka Ringwald  *                  - BTSTACK_MEMORY_ALLOC_FAILED if allocation of any of RFCOMM or L2CAP services failed
733deb3ec6SMatthias Ringwald  */
74b4df8028SMilanka Ringwald uint8_t hfp_hf_init(uint16_t rfcomm_channel_nr);
7566a048abSMatthias Ringwald 
76a0ffb263SMatthias Ringwald /**
77a0ffb263SMatthias Ringwald  * @brief Set codecs.
78a0ffb263SMatthias Ringwald  * @param codecs_nr
79a0ffb263SMatthias Ringwald  * @param codecs
80a0ffb263SMatthias Ringwald  */
817ca89cabSMatthias Ringwald void hfp_hf_init_codecs(int codecs_nr, const uint8_t * codecs);
823deb3ec6SMatthias Ringwald 
83a0ffb263SMatthias Ringwald /**
84a0ffb263SMatthias Ringwald  * @brief Set supported features.
85a0ffb263SMatthias Ringwald  * @param supported_features 32-bit bitmap, see HFP_HFSF_* values in hfp.h
86a0ffb263SMatthias Ringwald  */
87a0ffb263SMatthias Ringwald void hfp_hf_init_supported_features(uint32_t supported_features);
88a0ffb263SMatthias Ringwald 
89a0ffb263SMatthias Ringwald /**
90a0ffb263SMatthias Ringwald  * @brief Set HF indicators.
91a0ffb263SMatthias Ringwald  * @param indicators_nr
92a0ffb263SMatthias Ringwald  * @param indicators
93a0ffb263SMatthias Ringwald  */
947ca89cabSMatthias Ringwald void hfp_hf_init_hf_indicators(int indicators_nr, const uint16_t * indicators);
95a0ffb263SMatthias Ringwald 
9666a048abSMatthias Ringwald 
973deb3ec6SMatthias Ringwald /**
983deb3ec6SMatthias Ringwald  * @brief Register callback for the HFP Hands-Free (HF) client.
99a0ffb263SMatthias Ringwald  * @param callback
1003deb3ec6SMatthias Ringwald  */
10113839019SMatthias Ringwald void hfp_hf_register_packet_handler(btstack_packet_handler_t callback);
1023deb3ec6SMatthias Ringwald 
1033deb3ec6SMatthias Ringwald /**
104a0ffb263SMatthias Ringwald  * @brief Establish RFCOMM connection with the AG with given Bluetooth address,
105a0ffb263SMatthias Ringwald  * and perform service level connection (SLC) agreement:
106a0ffb263SMatthias Ringwald  * - exchange supported features
1073deb3ec6SMatthias Ringwald  * - retrieve Audio Gateway (AG) indicators and their status
1083deb3ec6SMatthias Ringwald  * - enable indicator status update in the AG
1093deb3ec6SMatthias Ringwald  * - notify the AG about its own available codecs, if possible
1103deb3ec6SMatthias Ringwald  * - retrieve the AG information describing the call hold and multiparty services, if possible
1113deb3ec6SMatthias Ringwald  * - retrieve which HF indicators are enabled on the AG, if possible
112a0ffb263SMatthias Ringwald  * The status of SLC connection establishment is reported via
113a0ffb263SMatthias Ringwald  * HFP_SUBEVENT_SERVICE_LEVEL_CONNECTION_ESTABLISHED.
114a0ffb263SMatthias Ringwald  *
115a0ffb263SMatthias Ringwald  * @param bd_addr Bluetooth address of the AG
1164eb3f1d8SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise:
117657bc59fSMilanka Ringwald  *              - ERROR_CODE_COMMAND_DISALLOWED if connection already exists, or
1184eb3f1d8SMilanka Ringwald  *              - BTSTACK_MEMORY_ALLOC_FAILED
1193deb3ec6SMatthias Ringwald  */
1204eb3f1d8SMilanka Ringwald uint8_t hfp_hf_establish_service_level_connection(bd_addr_t bd_addr);
1213deb3ec6SMatthias Ringwald 
1223deb3ec6SMatthias Ringwald /**
1233deb3ec6SMatthias Ringwald  * @brief Release the RFCOMM channel and the audio connection between the HF and the AG.
124a0ffb263SMatthias Ringwald  * The status of releasing the SLC connection is reported via
125a0ffb263SMatthias Ringwald  * HFP_SUBEVENT_SERVICE_LEVEL_CONNECTION_RELEASED.
126a0ffb263SMatthias Ringwald  *
127*3c65e705SMilanka Ringwald  * @param acl_handle
128657bc59fSMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
1293deb3ec6SMatthias Ringwald  */
130657bc59fSMilanka Ringwald uint8_t hfp_hf_release_service_level_connection(hci_con_handle_t acl_handle);
1313deb3ec6SMatthias Ringwald 
1323deb3ec6SMatthias Ringwald /**
133a0ffb263SMatthias Ringwald  * @brief Enable status update for all indicators in the AG.
134a0ffb263SMatthias Ringwald  * The status field of the HFP_SUBEVENT_COMPLETE reports if the command was accepted.
135a0ffb263SMatthias Ringwald  * The status of an AG indicator is reported via HFP_SUBEVENT_AG_INDICATOR_STATUS_CHANGED.
136a0ffb263SMatthias Ringwald  *
137*3c65e705SMilanka Ringwald  * @param acl_handle
138*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
1393deb3ec6SMatthias Ringwald  */
140*3c65e705SMilanka Ringwald uint8_t hfp_hf_enable_status_update_for_all_ag_indicators(hci_con_handle_t acl_handle);
14166a048abSMatthias Ringwald 
142a0ffb263SMatthias Ringwald /**
143a0ffb263SMatthias Ringwald  * @brief Disable status update for all indicators in the AG.
144a0ffb263SMatthias Ringwald  * The status field of the HFP_SUBEVENT_COMPLETE reports if the command was accepted.
145*3c65e705SMilanka Ringwald  *
146*3c65e705SMilanka Ringwald  * @param acl_handle
147*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
148a0ffb263SMatthias Ringwald  */
149*3c65e705SMilanka Ringwald uint8_t hfp_hf_disable_status_update_for_all_ag_indicators(hci_con_handle_t acl_handle);
1503deb3ec6SMatthias Ringwald 
1513deb3ec6SMatthias Ringwald /**
152a0ffb263SMatthias Ringwald  * @brief Enable or disable status update for the individual indicators in the AG using bitmap.
153a0ffb263SMatthias Ringwald  * The status field of the HFP_SUBEVENT_COMPLETE reports if the command was accepted.
154a0ffb263SMatthias Ringwald  * The status of an AG indicator is reported via HFP_SUBEVENT_AG_INDICATOR_STATUS_CHANGED.
155a0ffb263SMatthias Ringwald  *
156*3c65e705SMilanka Ringwald  * @param acl_handle
157a0ffb263SMatthias Ringwald  * @param indicators_status_bitmap 32-bit bitmap, 0 - indicator is disabled, 1 - indicator is enabled
158*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
1593deb3ec6SMatthias Ringwald  */
160*3c65e705SMilanka Ringwald uint8_t hfp_hf_set_status_update_for_individual_ag_indicators(hci_con_handle_t acl_handle, uint32_t indicators_status_bitmap);
1613deb3ec6SMatthias Ringwald 
1623deb3ec6SMatthias Ringwald /**
163a0ffb263SMatthias Ringwald  * @brief Query the name of the currently selected Network operator by AG.
16466a048abSMatthias Ringwald  *
165a0ffb263SMatthias Ringwald  * The name is restricted to max 16 characters. The result is reported via
166a0ffb263SMatthias Ringwald  * HFP_SUBEVENT_NETWORK_OPERATOR_CHANGED subtype
167a0ffb263SMatthias Ringwald  * containing network operator mode, format and name.
168a0ffb263SMatthias Ringwald  * If no operator is selected, format and operator are omitted.
169a0ffb263SMatthias Ringwald  *
170*3c65e705SMilanka Ringwald  * @param acl_handle
171*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise:
172*3c65e705SMilanka Ringwald  *              - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or
173*3c65e705SMilanka Ringwald  *              - ERROR_CODE_COMMAND_DISALLOWED if connection in wrong state
1743deb3ec6SMatthias Ringwald  */
175*3c65e705SMilanka Ringwald uint8_t hfp_hf_query_operator_selection(hci_con_handle_t acl_handle);
1763deb3ec6SMatthias Ringwald 
1773deb3ec6SMatthias Ringwald /**
178a0ffb263SMatthias Ringwald  * @brief Enable Extended Audio Gateway Error result codes in the AG.
1793deb3ec6SMatthias Ringwald  * Whenever there is an error relating to the functionality of the AG as a
180a0ffb263SMatthias Ringwald  * result of AT command, the AG shall send +CME ERROR. This error is reported via
181a0ffb263SMatthias Ringwald  * HFP_SUBEVENT_EXTENDED_AUDIO_GATEWAY_ERROR, see hfp_cme_error_t in hfp.h
182a0ffb263SMatthias Ringwald  *
183*3c65e705SMilanka Ringwald  * @param acl_handle
184*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
1853deb3ec6SMatthias Ringwald  */
186*3c65e705SMilanka Ringwald uint8_t hfp_hf_enable_report_extended_audio_gateway_error_result_code(hci_con_handle_t acl_handle);
187a0ffb263SMatthias Ringwald 
188a0ffb263SMatthias Ringwald /**
189a0ffb263SMatthias Ringwald  * @brief Disable Extended Audio Gateway Error result codes in the AG.
190a0ffb263SMatthias Ringwald  *
191*3c65e705SMilanka Ringwald  * @param acl_handle
192*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
193a0ffb263SMatthias Ringwald  */
194*3c65e705SMilanka Ringwald  uint8_t hfp_hf_disable_report_extended_audio_gateway_error_result_code(hci_con_handle_t acl_handle);
1953deb3ec6SMatthias Ringwald 
1963deb3ec6SMatthias Ringwald /**
197a0ffb263SMatthias Ringwald  * @brief Establish audio connection.
198*3c65e705SMilanka Ringwald  * The status of audio connection establishment is reported via HFP_SUBEVENT_AUDIO_CONNECTION_ESTABLISHED.
199*3c65e705SMilanka Ringwald  *
200*3c65e705SMilanka Ringwald  * @param acl_handle
201*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise:
202*3c65e705SMilanka Ringwald  *              - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or
203*3c65e705SMilanka Ringwald  *              - ERROR_CODE_COMMAND_DISALLOWED if connection in wrong state
2043deb3ec6SMatthias Ringwald  */
205*3c65e705SMilanka Ringwald uint8_t hfp_hf_establish_audio_connection(hci_con_handle_t acl_handle);
2063deb3ec6SMatthias Ringwald 
2073deb3ec6SMatthias Ringwald /**
208a0ffb263SMatthias Ringwald  * @brief Release audio connection.
209a0ffb263SMatthias Ringwald  * The status of releasing of the audio connection is reported via
210a0ffb263SMatthias Ringwald  * HFP_SUBEVENT_AUDIO_CONNECTION_RELEASED.
211a0ffb263SMatthias Ringwald  *
212*3c65e705SMilanka Ringwald  * @param acl_handle
213*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
2143deb3ec6SMatthias Ringwald  */
215*3c65e705SMilanka Ringwald uint8_t hfp_hf_release_audio_connection(hci_con_handle_t acl_handle);
2163deb3ec6SMatthias Ringwald 
217ce263fc8SMatthias Ringwald /**
218a0ffb263SMatthias Ringwald  * @brief Answer incoming call.
219*3c65e705SMilanka Ringwald  *
220*3c65e705SMilanka Ringwald  * @param acl_handle
221*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise:
222*3c65e705SMilanka Ringwald  *              - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or
223*3c65e705SMilanka Ringwald  *              - ERROR_CODE_COMMAND_DISALLOWED if answering incoming call with wrong callsetup status
224ce263fc8SMatthias Ringwald  */
225*3c65e705SMilanka Ringwald uint8_t hfp_hf_answer_incoming_call(hci_con_handle_t acl_handle);
226ce263fc8SMatthias Ringwald 
227ce263fc8SMatthias Ringwald /**
228a0ffb263SMatthias Ringwald  * @brief Reject incoming call.
229*3c65e705SMilanka Ringwald  *
230*3c65e705SMilanka Ringwald  * @param acl_handle
231*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
232ce263fc8SMatthias Ringwald  */
233*3c65e705SMilanka Ringwald uint8_t hfp_hf_reject_incoming_call(hci_con_handle_t acl_handle);
234ce263fc8SMatthias Ringwald 
235ce263fc8SMatthias Ringwald /**
236a0ffb263SMatthias Ringwald  * @brief Release all held calls or sets User Determined User Busy (UDUB) for a waiting call.
237*3c65e705SMilanka Ringwald  *
238*3c65e705SMilanka Ringwald  * @param acl_handle
239*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
240ce263fc8SMatthias Ringwald  */
241*3c65e705SMilanka Ringwald uint8_t hfp_hf_user_busy(hci_con_handle_t acl_handle);
242ce263fc8SMatthias Ringwald 
243ce263fc8SMatthias Ringwald /**
244a0ffb263SMatthias Ringwald  * @brief Release all active calls (if any exist) and accepts the other (held or waiting) call.
245*3c65e705SMilanka Ringwald  *
246*3c65e705SMilanka Ringwald  * @param acl_handle
247*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
248ce263fc8SMatthias Ringwald  */
249*3c65e705SMilanka Ringwald uint8_t hfp_hf_end_active_and_accept_other(hci_con_handle_t acl_handle);
250ce263fc8SMatthias Ringwald 
251ce263fc8SMatthias Ringwald /**
252a0ffb263SMatthias Ringwald  * @brief Place all active calls (if any exist) on hold and accepts the other (held or waiting) call.
253*3c65e705SMilanka Ringwald  *
254*3c65e705SMilanka Ringwald  * @param acl_handle
255*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
256ce263fc8SMatthias Ringwald  */
257*3c65e705SMilanka Ringwald uint8_t hfp_hf_swap_calls(hci_con_handle_t acl_handle);
258ce263fc8SMatthias Ringwald 
259ce263fc8SMatthias Ringwald /**
260a0ffb263SMatthias Ringwald  * @brief Add a held call to the conversation.
261*3c65e705SMilanka Ringwald  *
262*3c65e705SMilanka Ringwald  * @param acl_handle
263*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
264ce263fc8SMatthias Ringwald  */
265*3c65e705SMilanka Ringwald uint8_t hfp_hf_join_held_call(hci_con_handle_t acl_handle);
266ce263fc8SMatthias Ringwald 
267ce263fc8SMatthias Ringwald /**
268*3c65e705SMilanka Ringwald  * @brief Connect the two calls and disconnects the subscriber from both calls (Explicit Call Transfer).
269*3c65e705SMilanka Ringwald  *
270*3c65e705SMilanka Ringwald  * @param acl_handle
271*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
272ce263fc8SMatthias Ringwald  */
273*3c65e705SMilanka Ringwald uint8_t hfp_hf_connect_calls(hci_con_handle_t acl_handle);
274ce263fc8SMatthias Ringwald 
275ce263fc8SMatthias Ringwald /**
276*3c65e705SMilanka Ringwald  * @brief Terminate an incoming or an outgoing call. HFP_SUBEVENT_CALL_TERMINATED is sent upon call termination.
277*3c65e705SMilanka Ringwald  *
278*3c65e705SMilanka Ringwald  * @param acl_handle
279*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
280ce263fc8SMatthias Ringwald  */
281*3c65e705SMilanka Ringwald uint8_t hfp_hf_terminate_call(hci_con_handle_t acl_handle);
282ce263fc8SMatthias Ringwald 
283ce263fc8SMatthias Ringwald /**
284a0ffb263SMatthias Ringwald  * @brief Initiate outgoing voice call by providing the destination phone number to the AG.
285*3c65e705SMilanka Ringwald  *
286*3c65e705SMilanka Ringwald  * @param acl_handle
287a0ffb263SMatthias Ringwald  * @param number
288*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
289ce263fc8SMatthias Ringwald  */
290*3c65e705SMilanka Ringwald uint8_t hfp_hf_dial_number(hci_con_handle_t acl_handle, char * number);
291ce263fc8SMatthias Ringwald 
292ce263fc8SMatthias Ringwald /**
293a0ffb263SMatthias Ringwald  * @brief Initiate outgoing voice call using the memory dialing feature of the AG.
294*3c65e705SMilanka Ringwald  *
295*3c65e705SMilanka Ringwald  * @param acl_handle
296a0ffb263SMatthias Ringwald  * @param memory_id
297*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
298ce263fc8SMatthias Ringwald  */
299*3c65e705SMilanka Ringwald uint8_t hfp_hf_dial_memory(hci_con_handle_t acl_handle, int memory_id);
300ce263fc8SMatthias Ringwald 
301ce263fc8SMatthias Ringwald /**
302a0ffb263SMatthias Ringwald  * @brief Initiate outgoing voice call by recalling the last number dialed by the AG.
303*3c65e705SMilanka Ringwald  *
304*3c65e705SMilanka Ringwald  * @param acl_handle
305*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
306ce263fc8SMatthias Ringwald  */
307*3c65e705SMilanka Ringwald uint8_t hfp_hf_redial_last_number(hci_con_handle_t acl_handle);
308ce263fc8SMatthias Ringwald 
309ce263fc8SMatthias Ringwald /*
310a0ffb263SMatthias Ringwald  * @brief Enable the “Call Waiting notification” function in the AG.
311a0ffb263SMatthias Ringwald  * The AG shall send the corresponding result code to the HF whenever
312a0ffb263SMatthias Ringwald  * an incoming call is waiting during an ongoing call. In that event,
313a0ffb263SMatthias Ringwald  * the HFP_SUBEVENT_CALL_WAITING_NOTIFICATION is emitted.
314a0ffb263SMatthias Ringwald  *
315*3c65e705SMilanka Ringwald  * @param acl_handle
316*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
317ce263fc8SMatthias Ringwald  */
318*3c65e705SMilanka Ringwald uint8_t hfp_hf_activate_call_waiting_notification(hci_con_handle_t acl_handle);
319ce263fc8SMatthias Ringwald 
320ce263fc8SMatthias Ringwald /*
321a0ffb263SMatthias Ringwald  * @brief Disable the “Call Waiting notification” function in the AG.
322*3c65e705SMilanka Ringwald  *
323*3c65e705SMilanka Ringwald  * @param acl_handle
324*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
325ce263fc8SMatthias Ringwald  */
326*3c65e705SMilanka Ringwald uint8_t hfp_hf_deactivate_call_waiting_notification(hci_con_handle_t acl_handle);
327ce263fc8SMatthias Ringwald 
328ce263fc8SMatthias Ringwald /*
329a0ffb263SMatthias Ringwald  * @brief Enable the “Calling Line Identification notification” function in the AG.
330a0ffb263SMatthias Ringwald  * The AG shall issue the corresponding result code just after every RING indication,
331a0ffb263SMatthias Ringwald  * when the HF is alerted in an incoming call. In that event,
332a0ffb263SMatthias Ringwald  * the HFP_SUBEVENT_CALLING_LINE_INDETIFICATION_NOTIFICATION is emitted.
333*3c65e705SMilanka Ringwald  * @param acl_handle
334ce263fc8SMatthias Ringwald  */
335*3c65e705SMilanka Ringwald uint8_t hfp_hf_activate_calling_line_notification(hci_con_handle_t acl_handle);
336ce263fc8SMatthias Ringwald 
337ce263fc8SMatthias Ringwald /*
338a0ffb263SMatthias Ringwald  * @brief Disable the “Calling Line Identification notification” function in the AG.
339*3c65e705SMilanka Ringwald  *
340*3c65e705SMilanka Ringwald  * @param acl_handle
341*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
342ce263fc8SMatthias Ringwald  */
343*3c65e705SMilanka Ringwald uint8_t hfp_hf_deactivate_calling_line_notification(hci_con_handle_t acl_handle);
344ce263fc8SMatthias Ringwald 
345ce263fc8SMatthias Ringwald 
346ce263fc8SMatthias Ringwald /*
347a0ffb263SMatthias Ringwald  * @brief Activate echo canceling and noise reduction in the AG. By default,
348a0ffb263SMatthias Ringwald  * if the AG supports its own embedded echo canceling and/or noise reduction
349a0ffb263SMatthias Ringwald  * functions, it shall have them activated until this function is called.
350a0ffb263SMatthias Ringwald  * If the AG does not support any echo canceling and noise reduction functions,
351a0ffb263SMatthias Ringwald  * it shall respond with the ERROR indicator (TODO)
352*3c65e705SMilanka Ringwald  *
353*3c65e705SMilanka Ringwald  * @param acl_handle
354*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
355ce263fc8SMatthias Ringwald  */
356*3c65e705SMilanka Ringwald uint8_t hfp_hf_activate_echo_canceling_and_noise_reduction(hci_con_handle_t acl_handle);
357ce263fc8SMatthias Ringwald 
358ce263fc8SMatthias Ringwald /*
359a0ffb263SMatthias Ringwald  * @brief Deactivate echo canceling and noise reduction in the AG.
360*3c65e705SMilanka Ringwald  *
361*3c65e705SMilanka Ringwald  * @param acl_handle
362*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
363ce263fc8SMatthias Ringwald  */
364*3c65e705SMilanka Ringwald uint8_t hfp_hf_deactivate_echo_canceling_and_noise_reduction(hci_con_handle_t acl_handle);
365ce263fc8SMatthias Ringwald 
366ce263fc8SMatthias Ringwald /*
367a0ffb263SMatthias Ringwald  * @brief Activate voice recognition function.
368*3c65e705SMilanka Ringwald  *
369*3c65e705SMilanka Ringwald  * @param acl_handle
370*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
371ce263fc8SMatthias Ringwald  */
372be55a11dSMilanka Ringwald uint8_t hfp_hf_activate_voice_recognition_notification(hci_con_handle_t acl_handle);
373ce263fc8SMatthias Ringwald 
374ce263fc8SMatthias Ringwald /*
375a0ffb263SMatthias Ringwald  * @brief Dectivate voice recognition function.
376*3c65e705SMilanka Ringwald  *
377*3c65e705SMilanka Ringwald  * @param acl_handle
378*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
379ce263fc8SMatthias Ringwald  */
380be55a11dSMilanka Ringwald uint8_t hfp_hf_deactivate_voice_recognition_notification(hci_con_handle_t acl_handle);
381be55a11dSMilanka Ringwald 
382*3c65e705SMilanka Ringwald /*
383*3c65e705SMilanka Ringwald  * @brief Start enhanced voice recognition session.
384*3c65e705SMilanka Ringwald  *
385*3c65e705SMilanka Ringwald  * @param acl_handle
386*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise:
387*3c65e705SMilanka Ringwald  *              - ERROR_CODE_COMMAND_DISALLOWED if HF does not support it, or wrong VRA status
388*3c65e705SMilanka Ringwald  */
389db3cdbd4SMilanka Ringwald uint8_t hfp_hf_start_enhanced_voice_recognition_session(hci_con_handle_t acl_handle);
390be55a11dSMilanka Ringwald 
391*3c65e705SMilanka Ringwald /*
392*3c65e705SMilanka Ringwald  * @brief Stop enhanced voice recognition session.
393*3c65e705SMilanka Ringwald  *
394*3c65e705SMilanka Ringwald  * @param acl_handle
395*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise:
396*3c65e705SMilanka Ringwald  *              - ERROR_CODE_COMMAND_DISALLOWED if HF does not support it, or wrong VRA status
397*3c65e705SMilanka Ringwald  */
398db3cdbd4SMilanka Ringwald uint8_t hfp_hf_stop_enhanced_voice_recognition_session(hci_con_handle_t acl_handle);
399ce263fc8SMatthias Ringwald 
400ce263fc8SMatthias Ringwald /*
401a0ffb263SMatthias Ringwald  * @brief Set microphone gain.
402*3c65e705SMilanka Ringwald  *
403*3c65e705SMilanka Ringwald  * @param acl_handle
404a0ffb263SMatthias Ringwald  * @param gain Valid range: [0,15]
405*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise:
406*3c65e705SMilanka Ringwald  *              - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or
407*3c65e705SMilanka Ringwald  *              - ERROR_CODE_COMMAND_DISALLOWED if invalid gain range
408ce263fc8SMatthias Ringwald  */
409*3c65e705SMilanka Ringwald uint8_t hfp_hf_set_microphone_gain(hci_con_handle_t acl_handle, int gain);
410ce263fc8SMatthias Ringwald 
411ce263fc8SMatthias Ringwald /*
412a0ffb263SMatthias Ringwald  * @brief Set speaker gain.
413*3c65e705SMilanka Ringwald  *
414*3c65e705SMilanka Ringwald  * @param acl_handle
415a0ffb263SMatthias Ringwald  * @param gain Valid range: [0,15]
416*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise:
417*3c65e705SMilanka Ringwald  *              - ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist, or
418*3c65e705SMilanka Ringwald  *              - ERROR_CODE_COMMAND_DISALLOWED if invalid gain range
419ce263fc8SMatthias Ringwald  */
420*3c65e705SMilanka Ringwald uint8_t hfp_hf_set_speaker_gain(hci_con_handle_t acl_handle, int gain);
421ce263fc8SMatthias Ringwald 
422ce263fc8SMatthias Ringwald /*
423a0ffb263SMatthias Ringwald  * @brief Instruct the AG to transmit a DTMF code.
424*3c65e705SMilanka Ringwald  *
425*3c65e705SMilanka Ringwald  * @param acl_handle
426a0ffb263SMatthias Ringwald  * @param dtmf_code
427*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
428ce263fc8SMatthias Ringwald  */
429*3c65e705SMilanka Ringwald uint8_t hfp_hf_send_dtmf_code(hci_con_handle_t acl_handle, char code);
430ce263fc8SMatthias Ringwald 
431ce263fc8SMatthias Ringwald /*
432a0ffb263SMatthias Ringwald  * @brief Read numbers from the AG for the purpose of creating
433a0ffb263SMatthias Ringwald  * a unique voice tag and storing the number and its linked voice
434a0ffb263SMatthias Ringwald  * tag in the HF’s memory.
435a0ffb263SMatthias Ringwald  * The number is reported via HFP_SUBEVENT_NUMBER_FOR_VOICE_TAG.
436*3c65e705SMilanka Ringwald  *
437*3c65e705SMilanka Ringwald  * @param acl_handle
438*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
439ce263fc8SMatthias Ringwald  */
440*3c65e705SMilanka Ringwald uint8_t hfp_hf_request_phone_number_for_voice_tag(hci_con_handle_t acl_handle);
4413deb3ec6SMatthias Ringwald 
442667ec068SMatthias Ringwald /*
443a0ffb263SMatthias Ringwald  * @brief Query the list of current calls in AG.
444a0ffb263SMatthias Ringwald  * The result is received via HFP_SUBEVENT_ENHANCED_CALL_STATUS.
445*3c65e705SMilanka Ringwald  *
446*3c65e705SMilanka Ringwald  * @param acl_handle
447*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
448667ec068SMatthias Ringwald  */
449*3c65e705SMilanka Ringwald uint8_t hfp_hf_query_current_call_status(hci_con_handle_t acl_handle);
450667ec068SMatthias Ringwald 
451667ec068SMatthias Ringwald /*
452a0ffb263SMatthias Ringwald  * @brief Release a call with index in the AG.
453*3c65e705SMilanka Ringwald  *
454*3c65e705SMilanka Ringwald  * @param acl_handle
455a0ffb263SMatthias Ringwald  * @param index
456*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
457667ec068SMatthias Ringwald  */
458*3c65e705SMilanka Ringwald uint8_t hfp_hf_release_call_with_index(hci_con_handle_t acl_handle, int index);
459667ec068SMatthias Ringwald 
460667ec068SMatthias Ringwald /*
461a0ffb263SMatthias Ringwald  * @brief Place all parties of a multiparty call on hold with the
462a0ffb263SMatthias Ringwald  * exception of the specified call.
463*3c65e705SMilanka Ringwald  *
464*3c65e705SMilanka Ringwald  * @param acl_handle
465a0ffb263SMatthias Ringwald  * @param index
466*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
467667ec068SMatthias Ringwald  */
468*3c65e705SMilanka Ringwald uint8_t hfp_hf_private_consultation_with_call(hci_con_handle_t acl_handle, int index);
469667ec068SMatthias Ringwald 
470667ec068SMatthias Ringwald /*
471a0ffb263SMatthias Ringwald  * @brief Query the status of the “Response and Hold” state of the AG.
472a0ffb263SMatthias Ringwald  * The result is reported via HFP_SUBEVENT_RESPONSE_AND_HOLD_STATUS.
473*3c65e705SMilanka Ringwald  *
474*3c65e705SMilanka Ringwald  * @param acl_handle
475*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
476667ec068SMatthias Ringwald  */
477*3c65e705SMilanka Ringwald uint8_t hfp_hf_rrh_query_status(hci_con_handle_t acl_handle);
478667ec068SMatthias Ringwald 
479667ec068SMatthias Ringwald /*
480a0ffb263SMatthias Ringwald  * @brief Put an incoming call on hold in the AG.
481*3c65e705SMilanka Ringwald  *
482*3c65e705SMilanka Ringwald  * @param acl_handle
483*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
484667ec068SMatthias Ringwald  */
485*3c65e705SMilanka Ringwald uint8_t hfp_hf_rrh_hold_call(hci_con_handle_t acl_handle);
486667ec068SMatthias Ringwald 
487667ec068SMatthias Ringwald /*
488a0ffb263SMatthias Ringwald  * @brief Accept held incoming call in the AG.
489*3c65e705SMilanka Ringwald  *
490*3c65e705SMilanka Ringwald  * @param acl_handle
491*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
492667ec068SMatthias Ringwald  */
493*3c65e705SMilanka Ringwald uint8_t hfp_hf_rrh_accept_held_call(hci_con_handle_t acl_handle);
494667ec068SMatthias Ringwald 
495667ec068SMatthias Ringwald /*
496a0ffb263SMatthias Ringwald  * @brief Reject held incoming call in the AG.
497*3c65e705SMilanka Ringwald  *
498*3c65e705SMilanka Ringwald  * @param acl_handle
499*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
500667ec068SMatthias Ringwald  */
501*3c65e705SMilanka Ringwald uint8_t hfp_hf_rrh_reject_held_call(hci_con_handle_t acl_handle);
502667ec068SMatthias Ringwald 
503667ec068SMatthias Ringwald /*
504*3c65e705SMilanka Ringwald  * @brief Query the AG subscriber number. The result is reported via HFP_SUBEVENT_SUBSCRIBER_NUMBER_INFORMATION.
505*3c65e705SMilanka Ringwald  *
506*3c65e705SMilanka Ringwald  * @param acl_handle
507*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
508667ec068SMatthias Ringwald  */
509*3c65e705SMilanka Ringwald uint8_t hfp_hf_query_subscriber_number(hci_con_handle_t acl_handle);
510667ec068SMatthias Ringwald 
511667ec068SMatthias Ringwald /*
512a0ffb263SMatthias Ringwald  * @brief Set HF indicator.
513*3c65e705SMilanka Ringwald  *
514*3c65e705SMilanka Ringwald  * @param acl_handle
515a0ffb263SMatthias Ringwald  * @param assigned_number
516a0ffb263SMatthias Ringwald  * @param value
517*3c65e705SMilanka Ringwald  * @return status ERROR_CODE_SUCCESS if successful, otherwise ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if connection does not exist
518667ec068SMatthias Ringwald  */
519*3c65e705SMilanka Ringwald uint8_t hfp_hf_set_hf_indicator(hci_con_handle_t acl_handle, int assigned_number, int value);
520667ec068SMatthias Ringwald 
521d7f6b5cbSMatthias Ringwald /*
522d7f6b5cbSMatthias Ringwald  * @brief Tests if in-band ringtone is active on AG (requires SLC)
523*3c65e705SMilanka Ringwald  *
524*3c65e705SMilanka Ringwald  * @param acl_handler
525*3c65e705SMilanka Ringwald  * @return 0 if unknown acl_handle or in-band ring-tone disabled, otherwise 1
526d7f6b5cbSMatthias Ringwald  */
527d7f6b5cbSMatthias Ringwald int hfp_hf_in_band_ringtone_active(hci_con_handle_t acl_handle);
528d7f6b5cbSMatthias Ringwald 
52920b2edb6SMatthias Ringwald /**
53020b2edb6SMatthias Ringwald  * @brief De-Init HFP HF
53120b2edb6SMatthias Ringwald  */
53220b2edb6SMatthias Ringwald void hfp_hf_deinit(void);
53320b2edb6SMatthias Ringwald 
5343deb3ec6SMatthias Ringwald /* API_END */
5353deb3ec6SMatthias Ringwald 
5363deb3ec6SMatthias Ringwald #if defined __cplusplus
5373deb3ec6SMatthias Ringwald }
5383deb3ec6SMatthias Ringwald #endif
5393deb3ec6SMatthias Ringwald 
54080e33422SMatthias Ringwald #endif // BTSTACK_HFP_HF_H
541