hfp_hf.h (66a048ab906a04706fe3948e52f9291ec7110b9c) hfp_hf.h (a0ffb263e02c613f9155d5035f68cb0ad7b80d74)
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

--- 43 unchanged lines hidden (view full) ---

52#if defined __cplusplus
53extern "C" {
54#endif
55
56/* API_START */
57
58/**
59 * @brief Create HFP Hands-Free (HF) SDP service record.
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

--- 43 unchanged lines hidden (view full) ---

52#if defined __cplusplus
53extern "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
60 */
61void hfp_hf_create_sdp_record(uint8_t * service, uint32_t service_record_handle, int rfcomm_channel_nr, const char * name, uint16_t supported_features);
62
63/**
64 */
65void 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/**
64 * @brief Intialize HFP Hands-Free (HF) device.
65 * TODO: move optional params into setters
68 * @brief Set up HFP Hands-Free (HF) device without additional supported features.
69 * @param rfcomm_channel_nr
66 */
70 */
67void hfp_hf_init(uint16_t rfcomm_channel_nr, uint32_t supported_features, uint16_t * indicators, int indicators_nr, uint32_t indicators_status);
71void hfp_hf_init(uint16_t rfcomm_channel_nr);
68
72
69void hfp_hf_set_codecs(uint8_t * codecs, int codecs_nr);
73/**
74 * @brief Set codecs.
75 * @param codecs_nr
76 * @param codecs
77 */
78void hfp_hf_init_codecs(int codecs_nr, uint8_t * codecs);
70
79
71void hfp_hf_set_supported_features(uint32_t supported_features);
80/**
81 * @brief Set supported features.
82 * @param supported_features 32-bit bitmap, see HFP_HFSF_* values in hfp.h
83 */
84void hfp_hf_init_supported_features(uint32_t supported_features);
72
73/**
85
86/**
87 * @brief Set HF indicators.
88 * @param indicators_nr
89 * @param indicators
90 */
91void hfp_hf_init_hf_indicators(int indicators_nr, uint16_t * indicators);
92
93
94/**
74 * @brief Register callback for the HFP Hands-Free (HF) client.
95 * @brief Register callback for the HFP Hands-Free (HF) client.
96 * @param callback
75 */
76void hfp_hf_register_packet_handler(hfp_callback_t callback);
77
78/**
97 */
98void hfp_hf_register_packet_handler(hfp_callback_t callback);
99
100/**
79 * @brief Establish RFCOMM connection, and perform service level connection agreement:
80 * - exchange of supported features
101 * @brief Establish RFCOMM connection with the AG with given Bluetooth address,
102 * and perform service level connection (SLC) agreement:
103 * - exchange supported features
81 * - retrieve Audio Gateway (AG) indicators and their status
82 * - enable indicator status update in the AG
83 * - notify the AG about its own available codecs, if possible
84 * - retrieve the AG information describing the call hold and multiparty services, if possible
85 * - retrieve which HF indicators are enabled on the AG, if possible
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
86 */
87void hfp_hf_establish_service_level_connection(bd_addr_t bd_addr);
88
89/**
90 * @brief Release the RFCOMM channel and the audio connection between the HF and the AG.
113 */
114void 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.
91 * TODO: trigger release of the audio connection
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
92 */
93void hfp_hf_release_service_level_connection(bd_addr_t bd_addr);
94
95/**
122 */
123void hfp_hf_release_service_level_connection(bd_addr_t bd_addr);
124
125/**
96 * @brief Deactivate/reactivate status update for all indicators in the AG.
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
97 */
98void hfp_hf_enable_status_update_for_all_ag_indicators(bd_addr_t bd_addr);
99
131 */
132void 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 */
100void hfp_hf_disable_status_update_for_all_ag_indicators(bd_addr_t bd_addr);
101
102/**
139void hfp_hf_disable_status_update_for_all_ag_indicators(bd_addr_t bd_addr);
140
141/**
103 * @brief Deactivate/reactivate status update for the individual indicators in the AG using bitmap.
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
104 */
105void hfp_hf_set_status_update_for_individual_ag_indicators(bd_addr_t bd_addr, uint32_t indicators_status_bitmap);
106
148 */
149void hfp_hf_set_status_update_for_individual_ag_indicators(bd_addr_t bd_addr, uint32_t indicators_status_bitmap);
150
107
108/**
151/**
109 * @brief Find out the name of the currently selected Network operator by AG.
110 * The name is restricted to max 16 characters.
111 *
112 * TODO: what is the result of this?
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
113 */
114void hfp_hf_query_operator_selection(bd_addr_t bd_addr);
115
116/**
160 */
161void hfp_hf_query_operator_selection(bd_addr_t bd_addr);
162
163/**
117 * @brief Enable/disable Extended Audio Gateway Error result codes in the AG.
164 * @brief Enable Extended Audio Gateway Error result codes in the AG.
118 * Whenever there is an error relating to the functionality of the AG as a
165 * Whenever there is an error relating to the functionality of the AG as a
119 * result of AT command, the AG shall send +CME ERROR:
120 * - +CME ERROR: 0 - AG failure
121 * - +CME ERROR: 1 - no connection to phone
122 * - +CME ERROR: 3 - operation not allowed
123 * - +CME ERROR: 4 - operation not supported
124 * - +CME ERROR: 5 - PH-SIM PIN required
125 * - +CME ERROR: 10 - SIM not inserted
126 * - +CME ERROR: 11 - SIM PIN required
127 * - +CME ERROR: 12 - SIM PUK required
128 * - +CME ERROR: 13 - SIM failure
129 * - +CME ERROR: 14 - SIM busy
130 * - +CME ERROR: 16 - incorrect password
131 * - +CME ERROR: 17 - SIM PIN2 required
132 * - +CME ERROR: 18 - SIM PUK2 required
133 * - +CME ERROR: 20 - memory full
134 * - +CME ERROR: 21 - invalid index
135 * - +CME ERROR: 23 - memory failure
136 * - +CME ERROR: 24 - text string too long
137 * - +CME ERROR: 25 - invalid characters in text string
138 * - +CME ERROR: 26 - dial string too long
139 * - +CME ERROR: 27 - invalid characters in dial string
140 * - +CME ERROR: 30 - no network service
141 * - +CME ERROR: 31 - network Timeout.
142 * - +CME ERROR: 32 - network not allowed – Emergency calls only
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
143 */
144void hfp_hf_enable_report_extended_audio_gateway_error_result_code(bd_addr_t bd_addr);
170 */
171void hfp_hf_enable_report_extended_audio_gateway_error_result_code(bd_addr_t bd_addr);
145void hfp_hf_disable_report_extended_audio_gateway_error_result_code(bd_addr_t bd_addr);
146
147/**
172
173/**
148 * @brief
174 * @brief Disable Extended Audio Gateway Error result codes in the AG.
175 *
176 * @param bd_addr Bluetooth address of the AG
149 */
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 */
150void hfp_hf_establish_audio_connection(bd_addr_t bd_addr);
151
152/**
186void hfp_hf_establish_audio_connection(bd_addr_t bd_addr);
187
188/**
153 * @brief
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
154 */
155void hfp_hf_release_audio_connection(bd_addr_t bd_addr);
156
157/**
194 */
195void hfp_hf_release_audio_connection(bd_addr_t bd_addr);
196
197/**
158 * @brief
198 * @brief Answer incoming call.
199 * @param bd_addr Bluetooth address of the AG
159 */
160void hfp_hf_answer_incoming_call(bd_addr_t bd_addr);
161
162/**
200 */
201void hfp_hf_answer_incoming_call(bd_addr_t bd_addr);
202
203/**
163 * @brief
204 * @brief Reject incoming call.
205 * @param bd_addr Bluetooth address of the AG
164 */
206 */
165void hfp_hf_reject_call(bd_addr_t bd_addr);
207void hfp_hf_reject_incoming_call(bd_addr_t bd_addr);
166
167/**
208
209/**
168 * @brief
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
169 */
170void hfp_hf_user_busy(bd_addr_t addr);
171
172/**
212 */
213void hfp_hf_user_busy(bd_addr_t addr);
214
215/**
173 * @brief
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
174 */
175void hfp_hf_end_active_and_accept_other(bd_addr_t addr);
176
177/**
218 */
219void hfp_hf_end_active_and_accept_other(bd_addr_t addr);
220
221/**
178 * @brief
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
179 */
180void hfp_hf_swap_calls(bd_addr_t addr);
181
182/**
224 */
225void hfp_hf_swap_calls(bd_addr_t addr);
226
227/**
183 * @brief
228 * @brief Add a held call to the conversation.
229 * @param bd_addr Bluetooth address of the AG
184 */
185void hfp_hf_join_held_call(bd_addr_t addr);
186
187/**
230 */
231void hfp_hf_join_held_call(bd_addr_t addr);
232
233/**
188 * @brief
234 * @brief Connect the two calls and disconnects the subscriber from both calls (Explicit Call
235Transfer).
236 * @param bd_addr Bluetooth address of the AG
189 */
190void hfp_hf_connect_calls(bd_addr_t addr);
191
192/**
237 */
238void hfp_hf_connect_calls(bd_addr_t addr);
239
240/**
193 * @brief
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
194 */
195void hfp_hf_terminate_call(bd_addr_t bd_addr);
196
197/**
244 */
245void hfp_hf_terminate_call(bd_addr_t bd_addr);
246
247/**
198 * @brief
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
199 */
200void hfp_hf_dial_number(bd_addr_t bd_addr, char * number);
201
202/**
251 */
252void hfp_hf_dial_number(bd_addr_t bd_addr, char * number);
253
254/**
203 * @brief
204 * TODO: use int for number instead of string?
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
205 */
258 */
206void hfp_hf_dial_memory(bd_addr_t bd_addr, char * number);
259void hfp_hf_dial_memory(bd_addr_t bd_addr, int memory_id);
207
208/**
260
261/**
209 * @brief
262 * @brief Initiate outgoing voice call by recalling the last number dialed by the AG.
263 * @param bd_addr Bluetooth address of the AG
210 */
211void hfp_hf_redial_last_number(bd_addr_t bd_addr);
212
213/*
264 */
265void hfp_hf_redial_last_number(bd_addr_t bd_addr);
266
267/*
214 * @brief
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
215 */
216void hfp_hf_activate_call_waiting_notification(bd_addr_t bd_addr);
217
218/*
274 */
275void hfp_hf_activate_call_waiting_notification(bd_addr_t bd_addr);
276
277/*
219 * @brief
278 * @brief Disable the “Call Waiting notification” function in the AG.
279 * @param bd_addr Bluetooth address of the AG
220 */
221void hfp_hf_deactivate_call_waiting_notification(bd_addr_t bd_addr);
222
223/*
280 */
281void hfp_hf_deactivate_call_waiting_notification(bd_addr_t bd_addr);
282
283/*
224 * @brief
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
225 */
226void hfp_hf_activate_calling_line_notification(bd_addr_t bd_addr);
227
228/*
289 */
290void hfp_hf_activate_calling_line_notification(bd_addr_t bd_addr);
291
292/*
229 * @brief
293 * @brief Disable the “Calling Line Identification notification” function in the AG.
294 * @param bd_addr Bluetooth address of the AG
230 */
231void hfp_hf_deactivate_calling_line_notification(bd_addr_t bd_addr);
232
233
234/*
295 */
296void hfp_hf_deactivate_calling_line_notification(bd_addr_t bd_addr);
297
298
299/*
235 * @brief
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
236 */
237void hfp_hf_activate_echo_canceling_and_noise_reduction(bd_addr_t bd_addr);
238
239/*
306 */
307void hfp_hf_activate_echo_canceling_and_noise_reduction(bd_addr_t bd_addr);
308
309/*
240 * @brief
310 * @brief Deactivate echo canceling and noise reduction in the AG.
241 */
242void hfp_hf_deactivate_echo_canceling_and_noise_reduction(bd_addr_t bd_addr);
243
244/*
311 */
312void hfp_hf_deactivate_echo_canceling_and_noise_reduction(bd_addr_t bd_addr);
313
314/*
245 * @brief
315 * @brief Activate voice recognition function.
316 * @param bd_addr Bluetooth address of the AG
246 */
247void hfp_hf_activate_voice_recognition_notification(bd_addr_t bd_addr);
248
249/*
317 */
318void hfp_hf_activate_voice_recognition_notification(bd_addr_t bd_addr);
319
320/*
250 * @brief
321 * @brief Dectivate voice recognition function.
322 * @param bd_addr Bluetooth address of the AG
251 */
252void hfp_hf_deactivate_voice_recognition_notification(bd_addr_t bd_addr);
253
254/*
323 */
324void hfp_hf_deactivate_voice_recognition_notification(bd_addr_t bd_addr);
325
326/*
255 * @brief
327 * @brief Set microphone gain.
328 * @param bd_addr Bluetooth address of the AG
329 * @param gain Valid range: [0,15]
256 */
257void hfp_hf_set_microphone_gain(bd_addr_t bd_addr, int gain);
258
259/*
330 */
331void hfp_hf_set_microphone_gain(bd_addr_t bd_addr, int gain);
332
333/*
260 * @brief
334 * @brief Set speaker gain.
335 * @param bd_addr Bluetooth address of the AG
336 * @param gain Valid range: [0,15]
261 */
262void hfp_hf_set_speaker_gain(bd_addr_t bd_addr, int gain);
263
264/*
337 */
338void hfp_hf_set_speaker_gain(bd_addr_t bd_addr, int gain);
339
340/*
265 * @brief
341 * @brief Instruct the AG to transmit a DTMF code.
342 * @param bd_addr Bluetooth address of the AG
343 * @param dtmf_code
266 */
267void hfp_hf_send_dtmf_code(bd_addr_t bd_addr, char code);
268
269/*
344 */
345void hfp_hf_send_dtmf_code(bd_addr_t bd_addr, char code);
346
347/*
270 * @brief
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
271 */
272void hfp_hf_request_phone_number_for_voice_tag(bd_addr_t addr);
273
274/*
353 */
354void hfp_hf_request_phone_number_for_voice_tag(bd_addr_t addr);
355
356/*
275 * @brief
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
276 */
277void hfp_hf_query_current_call_status(bd_addr_t addr);
278
279/*
360 */
361void hfp_hf_query_current_call_status(bd_addr_t addr);
362
363/*
280 * @brief
364 * @brief Release a call with index in the AG.
365 * @param bd_addr Bluetooth address of the AG
366 * @param index
281 */
282void hfp_hf_release_call_with_index(bd_addr_t addr, int index);
283
284/*
367 */
368void hfp_hf_release_call_with_index(bd_addr_t addr, int index);
369
370/*
285 * @brief
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
286 */
287void hfp_hf_private_consultation_with_call(bd_addr_t addr, int index);
288
289/*
375 */
376void hfp_hf_private_consultation_with_call(bd_addr_t addr, int index);
377
378/*
290 * @brief
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
291 */
292void hfp_hf_rrh_query_status(bd_addr_t addr);
293
294/*
382 */
383void hfp_hf_rrh_query_status(bd_addr_t addr);
384
385/*
295 * @brief
386 * @brief Put an incoming call on hold in the AG.
387 * @param bd_addr Bluetooth address of the AG
296 */
297void hfp_hf_rrh_hold_call(bd_addr_t addr);
298
299/*
388 */
389void hfp_hf_rrh_hold_call(bd_addr_t addr);
390
391/*
300 * @brief
392 * @brief Accept held incoming call in the AG.
393 * @param bd_addr Bluetooth address of the AG
301 */
302void hfp_hf_rrh_accept_held_call(bd_addr_t addr);
303
304/*
394 */
395void hfp_hf_rrh_accept_held_call(bd_addr_t addr);
396
397/*
305 * @brief
398 * @brief Reject held incoming call in the AG.
399 * @param bd_addr Bluetooth address of the AG
306 */
307void hfp_hf_rrh_reject_held_call(bd_addr_t addr);
308
309/*
400 */
401void hfp_hf_rrh_reject_held_call(bd_addr_t addr);
402
403/*
310 * @brief
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
311 */
312void hfp_hf_query_subscriber_number(bd_addr_t addr);
313
314/*
407 */
408void hfp_hf_query_subscriber_number(bd_addr_t addr);
409
410/*
315 * @brief
411 * @brief Set HF indicator.
412 * @param bd_addr Bluetooth address of the AG
413 * @param assigned_number
414 * @param value
316 */
317void hfp_hf_set_hf_indicator(bd_addr_t addr, int assigned_number, int value);
318
319/* API_END */
320
321#if defined __cplusplus
322}
323#endif
324
325#endif // __BTSTACK_HFP_HF_H
415 */
416void 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