Line data Source code
1 1 : /** @file
2 : * @brief Handsfree Profile handling.
3 : */
4 :
5 : /*
6 : * Copyright (c) 2015-2016 Intel Corporation
7 : *
8 : * SPDX-License-Identifier: Apache-2.0
9 : */
10 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_HFP_HF_H_
11 : #define ZEPHYR_INCLUDE_BLUETOOTH_HFP_HF_H_
12 :
13 : /**
14 : * @brief Hands Free Profile (HFP)
15 : * @defgroup bt_hfp Hands Free Profile (HFP)
16 : * @ingroup bluetooth
17 : * @{
18 : */
19 :
20 : #include <zephyr/bluetooth/bluetooth.h>
21 :
22 : #ifdef __cplusplus
23 : extern "C" {
24 : #endif
25 :
26 : /* HFP CODEC IDs */
27 0 : #define BT_HFP_HF_CODEC_CVSD 0x01
28 0 : #define BT_HFP_HF_CODEC_MSBC 0x02
29 0 : #define BT_HFP_HF_CODEC_LC3_SWB 0x03
30 :
31 : struct bt_hfp_hf;
32 :
33 : struct bt_hfp_hf_call;
34 :
35 : /** @brief HFP profile application callback */
36 1 : struct bt_hfp_hf_cb {
37 : /** HF connected callback to application
38 : *
39 : * If this callback is provided it will be called whenever the
40 : * connection completes.
41 : *
42 : * @param conn Connection object.
43 : * @param hf HFP HF object.
44 : */
45 1 : void (*connected)(struct bt_conn *conn, struct bt_hfp_hf *hf);
46 : /** HF disconnected callback to application
47 : *
48 : * If this callback is provided it will be called whenever the
49 : * connection gets disconnected, including when a connection gets
50 : * rejected or cancelled or any error in SLC establishment.
51 : * And the HFP HF object will be freed after the registered
52 : * callback `disconnected` returned.
53 : *
54 : * @param hf HFP HF object.
55 : */
56 1 : void (*disconnected)(struct bt_hfp_hf *hf);
57 : /** HF SCO/eSCO connected Callback
58 : *
59 : * If this callback is provided it will be called whenever the
60 : * SCO/eSCO connection completes.
61 : *
62 : * @param hf HFP HF object.
63 : * @param sco_conn SCO/eSCO Connection object.
64 : */
65 1 : void (*sco_connected)(struct bt_hfp_hf *hf, struct bt_conn *sco_conn);
66 : /** HF SCO/eSCO disconnected Callback
67 : *
68 : * If this callback is provided it will be called whenever the
69 : * SCO/eSCO connection gets disconnected.
70 : *
71 : * @param conn SCO/eSCO Connection object.
72 : * @param reason BT_HCI_ERR_* reason for the disconnection.
73 : */
74 1 : void (*sco_disconnected)(struct bt_conn *sco_conn, uint8_t reason);
75 : /** HF indicator Callback
76 : *
77 : * This callback provides service indicator value to the application
78 : *
79 : * @param hf HFP HF object.
80 : * @param value service indicator value received from the AG.
81 : */
82 1 : void (*service)(struct bt_hfp_hf *hf, uint32_t value);
83 : /** HF call outgoing Callback
84 : *
85 : * This callback provides the outgoing call status to
86 : * the application.
87 : *
88 : * @param hf HFP HF object.
89 : * @param call HFP HF call object.
90 : */
91 1 : void (*outgoing)(struct bt_hfp_hf *hf, struct bt_hfp_hf_call *call);
92 : /** HF call outgoing call is ringing Callback
93 : *
94 : * This callback provides the outgoing call is ringing
95 : * status to the application.
96 : *
97 : * @param call HFP HF call object.
98 : */
99 1 : void (*remote_ringing)(struct bt_hfp_hf_call *call);
100 : /** HF call incoming Callback
101 : *
102 : * This callback provides the incoming call status to
103 : * the application.
104 : *
105 : * @param hf HFP HF object.
106 : * @param call HFP HF call object.
107 : */
108 1 : void (*incoming)(struct bt_hfp_hf *hf, struct bt_hfp_hf_call *call);
109 : /** HF incoming call on hold Callback
110 : *
111 : * This callback provides the incoming call on hold status to
112 : * the application.
113 : *
114 : * @param call HFP HF call object.
115 : */
116 1 : void (*incoming_held)(struct bt_hfp_hf_call *call);
117 : /** HF call accept Callback
118 : *
119 : * This callback provides the incoming/outgoing call active
120 : * status to the application.
121 : *
122 : * @param call HFP HF call object.
123 : */
124 1 : void (*accept)(struct bt_hfp_hf_call *call);
125 : /** HF call reject Callback
126 : *
127 : * This callback provides the incoming/outgoing call reject
128 : * status to the application.
129 : *
130 : * @param call HFP HF call object.
131 : */
132 1 : void (*reject)(struct bt_hfp_hf_call *call);
133 : /** HF call terminate Callback
134 : *
135 : * This callback provides the incoming/outgoing call terminate
136 : * status to the application.
137 : *
138 : * @param call HFP HF call object.
139 : */
140 1 : void (*terminate)(struct bt_hfp_hf_call *call);
141 : /** HF call held Callback
142 : *
143 : * This callback provides call held to the application
144 : *
145 : * @param call HFP HF call object.
146 : */
147 1 : void (*held)(struct bt_hfp_hf_call *call);
148 : /** HF call retrieve Callback
149 : *
150 : * This callback provides call retrieved to the application
151 : *
152 : * @param call HFP HF call object.
153 : */
154 1 : void (*retrieve)(struct bt_hfp_hf_call *call);
155 : /** HF indicator Callback
156 : *
157 : * This callback provides signal indicator value to the application
158 : *
159 : * @param hf HFP HF object.
160 : * @param value signal indicator value received from the AG.
161 : */
162 1 : void (*signal)(struct bt_hfp_hf *hf, uint32_t value);
163 : /** HF indicator Callback
164 : *
165 : * This callback provides roaming indicator value to the application
166 : *
167 : * @param hf HFP HF object.
168 : * @param value roaming indicator value received from the AG.
169 : */
170 1 : void (*roam)(struct bt_hfp_hf *hf, uint32_t value);
171 : /** HF indicator Callback
172 : *
173 : * This callback battery service indicator value to the application
174 : *
175 : * @param hf HFP HF object.
176 : * @param value battery indicator value received from the AG.
177 : */
178 1 : void (*battery)(struct bt_hfp_hf *hf, uint32_t value);
179 : /** HF incoming call Ring indication callback to application
180 : *
181 : * If this callback is provided it will be called whenever there
182 : * is an incoming call.
183 : *
184 : * @param call HFP HF call object.
185 : */
186 1 : void (*ring_indication)(struct bt_hfp_hf_call *call);
187 : /** HF call dialing Callback
188 : *
189 : * This callback provides call dialing result to the application.
190 : *
191 : * @param hf HFP HF object.
192 : * @param err Result of calling dialing.
193 : */
194 1 : void (*dialing)(struct bt_hfp_hf *hf, int err);
195 : /** HF calling line identification notification callback to application
196 : *
197 : * If this callback is provided it will be called whenever there
198 : * is a unsolicited result code +CLIP.
199 : * If @kconfig{CONFIG_BT_HFP_HF_CLI} is not enabled, the unsolicited
200 : * result code +CLIP will be ignored. And the callback will not be
201 : * notified.
202 : *
203 : * @param call HFP HF call object.
204 : * @param number Notified phone number.
205 : * @param type Specify the format of the phone number.
206 : */
207 1 : void (*clip)(struct bt_hfp_hf_call *call, char *number, uint8_t type);
208 : /** HF microphone gain notification callback to application
209 : *
210 : * If this callback is provided it will be called whenever there
211 : * is a unsolicited result code +VGM.
212 : * If @kconfig{CONFIG_BT_HFP_HF_VOLUME} is not enabled, the unsolicited
213 : * result code +VGM will be ignored. And the callback will not be
214 : * notified.
215 : *
216 : * @param hf HFP HF object.
217 : * @param gain Microphone gain.
218 : */
219 1 : void (*vgm)(struct bt_hfp_hf *hf, uint8_t gain);
220 : /** HF speaker gain notification callback to application
221 : *
222 : * If this callback is provided it will be called whenever there
223 : * is a unsolicited result code +VGS.
224 : * If @kconfig{CONFIG_BT_HFP_HF_VOLUME} is not enabled, the unsolicited
225 : * result code +VGS will be ignored. And the callback will not be
226 : * notified.
227 : *
228 : * @param hf HFP HF object.
229 : * @param gain Speaker gain.
230 : */
231 1 : void (*vgs)(struct bt_hfp_hf *hf, uint8_t gain);
232 : /** HF in-band ring tone notification callback to application
233 : *
234 : * If this callback is provided it will be called whenever there
235 : * is a unsolicited result code +BSIR issued by the AG to
236 : * indicate to the HF that the in-band ring tone setting
237 : * has been locally changed.
238 : *
239 : * @param hf HFP HF object.
240 : * @param inband In-band ring tone status from the AG.
241 : */
242 1 : void (*inband_ring)(struct bt_hfp_hf *hf, bool inband);
243 : /** HF network operator notification callback to application
244 : *
245 : * If this callback is provided it will be called whenever there
246 : * is a response code +COPS issued by the AG to
247 : * response the AT+COPS? command issued by the HF by calling
248 : * function `bt_hfp_hf_get_operator`.
249 : *
250 : * @param hf HFP HF object.
251 : * @param mode Current mode.
252 : * @param format Format of the `operator` parameter string.
253 : * It should be zero.
254 : * @param operator A string in alphanumeric format
255 : * representing the name of the network
256 : * operator.
257 : */
258 1 : void (*operator)(struct bt_hfp_hf *hf, uint8_t mode, uint8_t format, char *operator);
259 : /** Codec negotiate callback
260 : *
261 : * If this callback is provided it will be called whenever the
262 : * unsolicited codec negotiation response received.
263 : * There are two cases when the callback triggered,
264 : * Case 1, the codec id can be accepted, the function
265 : * `bt_hfp_hf_select_codec` should be called to accept the codec
266 : * id.
267 : * Case 2, the codec id can not be accepted, the function
268 : * `bt_hfp_hf_set_codecs` should be called to trigger codec ID
269 : * to be re-selected.
270 : * If the callback is not provided by application, the function
271 : * `bt_hfp_hf_select_codec` will be called to accept the codec
272 : * id.
273 : * Refers to BT_HFP_HF_CODEC_XXX for codec id value.
274 : * If @kconfig{CONFIG_BT_HFP_HF_CODEC_NEG} is not enabled, the
275 : * unsolicited result code +BCS will be ignored. And the callback
276 : * will not be notified.
277 : *
278 : * @param hf HFP HF object.
279 : * @param id Negotiated Codec ID.
280 : */
281 : void (*codec_negotiate)(struct bt_hfp_hf *hf, uint8_t id);
282 : /** HF ECNR turns off callback
283 : *
284 : * If this callback is provided it will be called whenever the
285 : * response of ECNR turning off is received from AG.
286 : * If @kconfig{CONFIG_BT_HFP_HF_ECNR} is not enabled, the
287 : * callback will not be notified.
288 : *
289 : * @param hf HFP HF object.
290 : * @param err The result of request.
291 : */
292 1 : void (*ecnr_turn_off)(struct bt_hfp_hf *hf, int err);
293 : /** HF call waiting notification callback to application
294 : *
295 : * If this callback is provided it will be called whenever there
296 : * is a unsolicited result code +CCWA.
297 : * This notification can be enabled/disabled by calling function
298 : * `bt_hfp_hf_call_waiting_notify`.
299 : * If @kconfig{CONFIG_BT_HFP_HF_3WAY_CALL} is not enabled, the
300 : * unsolicited result code +CCWA will be ignored. And the callback
301 : * will not be notified.
302 : *
303 : * @param call HFP HF call object.
304 : * @param number Notified phone number.
305 : * @param type Specify the format of the phone number.
306 : */
307 1 : void (*call_waiting)(struct bt_hfp_hf_call *call, char *number, uint8_t type);
308 : /** Voice recognition activation/deactivation callback
309 : *
310 : * If this callback is provided it will be called whenever the
311 : * unsolicited result code +BVRA is notified the HF when the
312 : * voice recognition function in the AG is activated/deactivated
313 : * autonomously from the AG.
314 : * If @kconfig{CONFIG_BT_HFP_HF_VOICE_RECG} is not enabled, the
315 : * unsolicited result code +BVRA will be ignored. And the callback
316 : * will not be notified.
317 : *
318 : * @param hf HFP HF object.
319 : * @param activate Voice recognition activation/deactivation.
320 : */
321 1 : void (*voice_recognition)(struct bt_hfp_hf *hf, bool activate);
322 : /** Voice recognition engine state callback
323 : *
324 : * If this callback is provided it will be called whenever the
325 : * unsolicited result code `+BVRA: 1,<vrecstate>` is received from AG.
326 : * `<vrecstate>`: Bitmask that reflects the current state of the voice
327 : * recognition engine on the AG.
328 : * Bit 0 - If it is 1, the AG is ready to accept audio input
329 : * Bit 1 - If it is 1, the AG is sending audio to the HF
330 : * Bit 2 - If it is 1, the AG is processing the audio input
331 : * If @kconfig{CONFIG_BT_HFP_HF_ENH_VOICE_RECG} is not enabled, the
332 : * unsolicited result code +BVRA will be ignored. And the callback
333 : * will not be notified.
334 : *
335 : * @param hf HFP HF object.
336 : * @param state Value of `<vrecstate>`.
337 : */
338 1 : void (*vre_state)(struct bt_hfp_hf *hf, uint8_t state);
339 : /** Textual representation callback
340 : *
341 : * If this callback is provided it will be called whenever the
342 : * unsolicited result code `+BVRA: 1,<vrecstate>,
343 : * <textualRepresentation>` is received from AG.
344 : * `<textualRepresentation>: <textID>,<textType>,<textOperation>,
345 : * <string>`.
346 : * `<textID>`: Unique ID of the current text as a hexadecimal string
347 : * (a maximum of 4 characters in length, but less than 4 characters
348 : * in length is valid).
349 : * `<textType>`: ID of the textType from the following list:
350 : * 0 - Text recognized by the AG from the audio input provided by the HF
351 : * 1 - Text of the audio output from the AG
352 : * 2 - Text of the audio output from the AG that contains a question
353 : * 3 - Text of the audio output from the AG that contains an error
354 : * description
355 : * `<textOperation>`: ID of the operation of the text
356 : * 1 - NewText: Indicates that a new text started. Shall be used when the
357 : * `<textID>` changes
358 : * 2 - Replace: Replace any existing text with the same `<textID>` and
359 : * same `<textType>`
360 : * 3 - Append: Attach new text to existing text and keep the same
361 : * `<textID>` and same `<textType>`
362 : * `<string>`: The `<string>` parameter shall be a UTF-8 text string and
363 : * shall always be contained within double quotes.
364 : * If @kconfig{CONFIG_BT_HFP_HF_VOICE_RECG_TEXT} is not enabled, the
365 : * unsolicited result code +BVRA will be ignored. And the callback
366 : * will not be notified.
367 : *
368 : * @param hf HFP HF object.
369 : * @param id Value of `<textID>`.
370 : * @param type Value of `<textType>`.
371 : * @param operation Value of `<textOperation>`.
372 : * @param text Value of `<string>`.
373 : */
374 1 : void (*textual_representation)(struct bt_hfp_hf *hf, char *id, uint8_t type,
375 : uint8_t operation, char *text);
376 : /** Request phone number callback
377 : *
378 : * If this callback is provided it will be called whenever the
379 : * result code `+BINP: <Phone number>` is received from AG.
380 : * If the request is failed, the `number` will be NULL.
381 : *
382 : * @param hf HFP HF object.
383 : * @param number Value of `<Phone number>`.
384 : */
385 1 : void (*request_phone_number)(struct bt_hfp_hf *hf, const char *number);
386 :
387 : /** Query subscriber number callback
388 : *
389 : * If this callback is provided it will be called whenever the
390 : * result code `+CUNM: [<alpha>],<number>, <type>,[<speed> ,<service>]`
391 : * is received from AG.
392 : * `<alpha>`: This optional field is not supported, and shall be left
393 : * blank.
394 : * `<number>`: Quoted string containing the phone number in the format
395 : * specified by `<type>`.
396 : * `<type>` field specifies the format of the phone number provided,
397 : * and can be one of the following values:
398 : * - values 128-143: The phone number format may be a national or
399 : * international format, and may contain prefix and/or escape digits.
400 : * No changes on the number presentation are required.
401 : * - values 144-159: The phone number format is an international
402 : * number, including the country code prefix. If the plus sign ("+")
403 : * is not included as part of the number and shall be added by the AG
404 : * as needed.
405 : * - values 160-175: National number. No prefix nor escape digits
406 : * included.
407 : * `<speed>`: This optional field is not supported, and shall be left
408 : * blank.
409 : * `<service>`: Indicates which service this phone number relates to.
410 : * Shall be either 4 (voice) or 5 (fax).
411 : *
412 : * @param hf HFP HF object.
413 : * @param number Value of `<number>` without quotes.
414 : * @param type Value of `<type>`.
415 : * @param service Value of `<service>`.
416 : */
417 1 : void (*subscriber_number)(struct bt_hfp_hf *hf, const char *number, uint8_t type,
418 : uint8_t service);
419 : };
420 :
421 : /** @brief Register HFP HF profile
422 : *
423 : * Register Handsfree profile callbacks to monitor the state and get the
424 : * required HFP details to display.
425 : *
426 : * @param cb callback structure.
427 : *
428 : * @return 0 in case of success or negative value in case of error.
429 : */
430 1 : int bt_hfp_hf_register(struct bt_hfp_hf_cb *cb);
431 :
432 : /** @brief Initiate the service level connection establishment procedure
433 : *
434 : * Initiate the service level connection establishment procedure on the
435 : * ACL connection specified by the parameter `conn` using the specific
436 : * RFCOMM channel discovered by the function `bt_br_discovery_start`.
437 : *
438 : * The parameter `hf` is a output parameter. When the service level
439 : * connection establishment procedure is initiated without any error,
440 : * the HFP HF object is allocated and it will be returned via the parameter
441 : * `hf` if the parameter `hf` is not a NULL pointer.
442 : *
443 : * When service level conenction is established, the registered callback
444 : * `connected` will be triggered to notify the application that the service
445 : * level connection establishment procedure is done. And the HFP HF object
446 : * is valid at this time. It means after the function is called without
447 : * any error, all interfaces provided by HFP HF can only be called after
448 : * the registered callback `connected` is triggered.
449 : *
450 : * @param conn ACL connection object.
451 : * @param hf Created HFP HF object.
452 : * @param channel Peer RFCOMM channel to be connected.
453 : *
454 : * @return 0 in case of success or negative value in case of error.
455 : */
456 1 : int bt_hfp_hf_connect(struct bt_conn *conn, struct bt_hfp_hf **hf, uint8_t channel);
457 :
458 : /** @brief Release the service level connection
459 : *
460 : * Release the service level connection from the peer device.
461 : *
462 : * The function can only be called after the registered callback `connected`
463 : * is triggered.
464 : *
465 : * If the function is called without any error, the HFP HF object is
466 : * invalid at this time. All interfaces provided by HFP HF should not
467 : * be called anymore.
468 : *
469 : * If the service level connection is released, the registered callback
470 : * `disconnected` will be triggered to notify the application that the
471 : * service level connection release procedure is done. And the HFP HF
472 : * object will be freed after the registered callback `disconnected`
473 : * returned.
474 : *
475 : * @param hf HFP HF object.
476 : *
477 : * @return 0 in case of success or negative value in case of error.
478 : */
479 1 : int bt_hfp_hf_disconnect(struct bt_hfp_hf *hf);
480 :
481 : /** @brief Handsfree HF enable/disable Calling Line Identification (CLI) Notification
482 : *
483 : * Enable/disable Calling Line Identification (CLI) Notification.
484 : * The AT command `AT+CLIP` will be sent to the AG to enable/disable the CLI
485 : * unsolicited result code +CLIP when calling the function.
486 : * If @kconfig{CONFIG_BT_HFP_HF_CLI} is not enabled, the error `-ENOTSUP` will
487 : * be returned if the function called.
488 : *
489 : * @param hf HFP HF object.
490 : * @param enable Enable/disable CLI.
491 : *
492 : * @return 0 in case of success or negative value in case of error.
493 : */
494 1 : int bt_hfp_hf_cli(struct bt_hfp_hf *hf, bool enable);
495 :
496 : /** @brief Handsfree HF report Gain of Microphone (VGM)
497 : *
498 : * Report Gain of Microphone (VGM).
499 : * The AT command `AT+VGM=<gain>` will be sent to the AG to report its
500 : * current microphone gain level setting to the AG.
501 : * `<gain>` is a decimal numeric constant, relating to a particular
502 : * (implementation dependent) volume level controlled by the HF.
503 : * This command does not change the microphone gain of the AG; it simply
504 : * indicates the current value of the microphone gain in the HF.
505 : * If @kconfig{CONFIG_BT_HFP_HF_VOLUME} is not enabled, the error `-ENOTSUP`
506 : * will be returned if the function called.
507 : * For "Volume Level Synchronization", the HF application could call
508 : * the function to set VGM gain value in HF connection callback
509 : * function. Then after the HF connection callback returned, VGM gain
510 : * will be sent to HFP AG.
511 : *
512 : * @param hf HFP HF object.
513 : * @param gain Gain of microphone.
514 : *
515 : * @return 0 in case of success or negative value in case of error.
516 : */
517 1 : int bt_hfp_hf_vgm(struct bt_hfp_hf *hf, uint8_t gain);
518 :
519 : /** @brief Handsfree HF report Gain of Speaker (VGS)
520 : *
521 : * Report Gain of Speaker (VGS).
522 : * The AT command `AT+VGS=<gain>` will be sent to the AG to report its
523 : * current speaker gain level setting to the AG.
524 : * `<gain>` is a decimal numeric constant, relating to a particular
525 : * (implementation dependent) volume level controlled by the HF.
526 : * This command does not change the speaker gain of the AG; it simply
527 : * indicates the current value of the speaker gain in the HF.
528 : * If @kconfig{CONFIG_BT_HFP_HF_VOLUME} is not enabled, the error `-ENOTSUP`
529 : * will be returned if the function called.
530 : * For "Volume Level Synchronization", the HF application could call
531 : * the function to set VGS gain value in HF connection callback
532 : * function. Then after the HF connection callback returned, VGS gain
533 : * will be sent to HFP AG.
534 : *
535 : * @param hf HFP HF object.
536 : * @param gain Gain of speaker.
537 : *
538 : * @return 0 in case of success or negative value in case of error.
539 : */
540 1 : int bt_hfp_hf_vgs(struct bt_hfp_hf *hf, uint8_t gain);
541 :
542 : /** @brief Handsfree HF requests currently selected operator
543 : *
544 : * Send the AT+COPS? (Read) command to find the currently
545 : * selected operator.
546 : *
547 : * @param hf HFP HF object.
548 : *
549 : * @return 0 in case of success or negative value in case of error.
550 : */
551 1 : int bt_hfp_hf_get_operator(struct bt_hfp_hf *hf);
552 :
553 : /** @brief Handsfree HF accept the incoming call
554 : *
555 : * Send the ATA command to accept the incoming call.
556 : * OR, send the AT+BTRH=1 command to accept a held incoming
557 : * call.
558 : *
559 : * @note It cannot be used when multiple calls are ongoing.
560 : *
561 : * @param call HFP HF call object.
562 : *
563 : * @return 0 in case of success or negative value in case of error.
564 : */
565 1 : int bt_hfp_hf_accept(struct bt_hfp_hf_call *call);
566 :
567 : /** @brief Handsfree HF reject the incoming call
568 : *
569 : * Send the AT+CHUP command to reject the incoming call.
570 : * OR, send the AT+BTRH=2 command to reject a held incoming
571 : * call.
572 : *
573 : * @note It cannot be used when multiple calls are ongoing.
574 : *
575 : * @param call HFP HF call object.
576 : *
577 : * @return 0 in case of success or negative value in case of error.
578 : */
579 1 : int bt_hfp_hf_reject(struct bt_hfp_hf_call *call);
580 :
581 : /** @brief Handsfree HF terminate the incoming call
582 : *
583 : * Send the AT+CHUP command to terminate the incoming call.
584 : *
585 : * @note It cannot be used when multiple calls are ongoing.
586 : *
587 : * @param call HFP HF call object.
588 : *
589 : * @return 0 in case of success or negative value in case of error.
590 : */
591 1 : int bt_hfp_hf_terminate(struct bt_hfp_hf_call *call);
592 :
593 : /** @brief Handsfree HF put the incoming call on hold
594 : *
595 : * Send the AT+BTRH=0 command to put the incoming call on hold.
596 : * If the incoming call has been held, the callback `on_hold` will
597 : * be triggered.
598 : *
599 : * @note It cannot be used when multiple calls are ongoing.
600 : *
601 : * @param call HFP HF call object.
602 : *
603 : * @return 0 in case of success or negative value in case of error.
604 : */
605 1 : int bt_hfp_hf_hold_incoming(struct bt_hfp_hf_call *call);
606 :
607 : /** @brief Handsfree HF query respond and hold status of AG
608 : *
609 : * Send the AT+BTRH? command to query respond and hold status of AG.
610 : * The status respond and hold will be notified through callback
611 : * `on_hold`.
612 : *
613 : * @param hf HFP HF object.
614 : *
615 : * @return 0 in case of success or negative value in case of error.
616 : */
617 1 : int bt_hfp_hf_query_respond_hold_status(struct bt_hfp_hf *hf);
618 :
619 : /** @brief Handsfree HF phone number call
620 : *
621 : * Initiate outgoing voice calls by providing the destination phone
622 : * number to the AG.
623 : * Send the ATDdd…dd command to start phone number call.
624 : * The result of the command will be notified through the callback
625 : * `dialing`.
626 : *
627 : * @param hf HFP HF object.
628 : * @param number Phone number.
629 : *
630 : * @return 0 in case of success or negative value in case of error.
631 : */
632 1 : int bt_hfp_hf_number_call(struct bt_hfp_hf *hf, const char *number);
633 :
634 : /** @brief Handsfree HF memory dialing call
635 : *
636 : * Initiate outgoing voice calls using the memory dialing feature
637 : * of the AG.
638 : * Send the ATD>Nan... command to start memory dialing.
639 : * The result of the command will be notified through the callback
640 : * `dialing`.
641 : *
642 : * @param hf HFP HF object.
643 : * @param location Memory location.
644 : *
645 : * @return 0 in case of success or negative value in case of error.
646 : */
647 1 : int bt_hfp_hf_memory_dial(struct bt_hfp_hf *hf, const char *location);
648 :
649 : /** @brief Handsfree HF redial last number
650 : *
651 : * Initiate outgoing voice calls by recalling the last number
652 : * dialed by the AG.
653 : * Send the AT+BLDN command to recall the last number.
654 : * The result of the command will be notified through the callback
655 : * `dialing`.
656 : *
657 : * @param hf HFP HF object.
658 : *
659 : * @return 0 in case of success or negative value in case of error.
660 : */
661 1 : int bt_hfp_hf_redial(struct bt_hfp_hf *hf);
662 :
663 : /** @brief Handsfree HF setup audio connection
664 : *
665 : * Setup audio conenction by sending AT+BCC.
666 : * If @kconfig{CONFIG_BT_HFP_HF_CODEC_NEG} is not enabled, the error
667 : * `-ENOTSUP` will be returned if the function called.
668 : *
669 : * @param hf HFP HF object.
670 : *
671 : * @return 0 in case of success or negative value in case of error.
672 : */
673 1 : int bt_hfp_hf_audio_connect(struct bt_hfp_hf *hf);
674 :
675 : /** @brief Handsfree HF set selected codec id
676 : *
677 : * Set selected codec id by sending AT+BCS. The function is used to
678 : * response the codec negotiation request notified by callback
679 : * `codec_negotiate`. The parameter `codec_id` should be same as
680 : * `id` of callback `codec_negotiate` if the id could be supported.
681 : * Or, call `bt_hfp_hf_set_codecs` to notify the AG Codec IDs supported
682 : * by HFP HF.
683 : * If @kconfig{CONFIG_BT_HFP_HF_CODEC_NEG} is not enabled, the error
684 : * `-ENOTSUP` will be returned if the function called.
685 : *
686 : * @param hf HFP HF object.
687 : * @param codec_id Selected codec id.
688 : *
689 : * @return 0 in case of success or negative value in case of error.
690 : */
691 1 : int bt_hfp_hf_select_codec(struct bt_hfp_hf *hf, uint8_t codec_id);
692 :
693 : /** @brief Handsfree HF set supported codec ids
694 : *
695 : * Set supported codec ids by sending AT+BAC. This function is used
696 : * to notify AG the supported Codec IDs of HF.
697 : * If @kconfig{CONFIG_BT_HFP_HF_CODEC_NEG} is not enabled, the error
698 : * `-ENOTSUP` will be returned if the function called.
699 : *
700 : * @param hf HFP HF object.
701 : * @param codec_ids Supported codec IDs.
702 : *
703 : * @return 0 in case of success or negative value in case of error.
704 : */
705 1 : int bt_hfp_hf_set_codecs(struct bt_hfp_hf *hf, uint8_t codec_ids);
706 :
707 : /** @brief Handsfree HF turns off AG's EC and NR
708 : *
709 : * Turn off the AG's EC and NR by sending `AT+NREC=0`.
710 : * The result of the command is notified through the callback
711 : * `ecnr_turn_off`.
712 : * If @kconfig{CONFIG_BT_HFP_HF_ECNR} is not enabled, the error
713 : * `-ENOTSUP` will be returned if the function called.
714 : *
715 : * @param hf HFP HF object.
716 : *
717 : * @return 0 in case of success or negative value in case of error.
718 : */
719 1 : int bt_hfp_hf_turn_off_ecnr(struct bt_hfp_hf *hf);
720 :
721 : /** @brief Handsfree HF enable/disable call waiting notification
722 : *
723 : * Enable call waiting notification by sending `AT+CCWA=1`.
724 : * Disable call waiting notification by sending `AT+CCWA=0`.
725 : * If @kconfig{CONFIG_BT_HFP_HF_3WAY_CALL} is not enabled, the error
726 : * `-ENOTSUP` will be returned if the function called.
727 : *
728 : * @param hf HFP HF object.
729 : * @param enable Enable/disable.
730 : *
731 : * @return 0 in case of success or negative value in case of error.
732 : */
733 1 : int bt_hfp_hf_call_waiting_notify(struct bt_hfp_hf *hf, bool enable);
734 :
735 : /** @brief Handsfree HF release all held calls
736 : *
737 : * Release all held calls by sending `AT+CHLD=0`.
738 : * If @kconfig{CONFIG_BT_HFP_HF_3WAY_CALL} is not enabled, the error
739 : * `-ENOTSUP` will be returned if the function called.
740 : *
741 : * @param hf HFP HF object.
742 : *
743 : * @return 0 in case of success or negative value in case of error.
744 : */
745 1 : int bt_hfp_hf_release_all_held(struct bt_hfp_hf *hf);
746 :
747 : /** @brief Handsfree HF set User Determined User Busy (UDUB) for a waiting call
748 : *
749 : * Set User Determined User Busy (UDUB) for a waiting call
750 : * by sending `AT+CHLD=0`.
751 : * If @kconfig{CONFIG_BT_HFP_HF_3WAY_CALL} is not enabled, the error
752 : * `-ENOTSUP` will be returned if the function called.
753 : *
754 : * @param hf HFP HF object.
755 : *
756 : * @return 0 in case of success or negative value in case of error.
757 : */
758 1 : int bt_hfp_hf_set_udub(struct bt_hfp_hf *hf);
759 :
760 : /** @brief Handsfree HF release all active calls and accept other call
761 : *
762 : * Release all active calls (if any exist) and accepts the other
763 : * (held or waiting) call by sending `AT+CHLD=1`.
764 : * If @kconfig{CONFIG_BT_HFP_HF_3WAY_CALL} is not enabled, the error
765 : * `-ENOTSUP` will be returned if the function called.
766 : *
767 : * @param hf HFP HF object.
768 : *
769 : * @return 0 in case of success or negative value in case of error.
770 : */
771 1 : int bt_hfp_hf_release_active_accept_other(struct bt_hfp_hf *hf);
772 :
773 : /** @brief Handsfree HF hold all active calls and accept other call
774 : *
775 : * Hold all active calls (if any exist) and accepts the other
776 : * (held or waiting) call by sending `AT+CHLD=2`.
777 : * If @kconfig{CONFIG_BT_HFP_HF_3WAY_CALL} is not enabled, the error
778 : * `-ENOTSUP` will be returned if the function called.
779 : *
780 : * @param hf HFP HF object.
781 : *
782 : * @return 0 in case of success or negative value in case of error.
783 : */
784 1 : int bt_hfp_hf_hold_active_accept_other(struct bt_hfp_hf *hf);
785 :
786 : /** @brief Handsfree HF add a held call to the conversation
787 : *
788 : * Add a held call to the conversation by sending `AT+CHLD=3`.
789 : * If @kconfig{CONFIG_BT_HFP_HF_3WAY_CALL} is not enabled, the error
790 : * `-ENOTSUP` will be returned if the function called.
791 : *
792 : * @param hf HFP HF object.
793 : *
794 : * @return 0 in case of success or negative value in case of error.
795 : */
796 1 : int bt_hfp_hf_join_conversation(struct bt_hfp_hf *hf);
797 :
798 : /** @brief Handsfree HF explicit call transfer
799 : *
800 : * Connects the two calls and disconnects the subscriber from
801 : * both calls (Explicit Call Transfer) by sending `AT+CHLD=4`.
802 : * If @kconfig{CONFIG_BT_HFP_HF_3WAY_CALL} is not enabled, the error
803 : * `-ENOTSUP` will be returned if the function called.
804 : *
805 : * @param hf HFP HF object.
806 : *
807 : * @return 0 in case of success or negative value in case of error.
808 : */
809 1 : int bt_hfp_hf_explicit_call_transfer(struct bt_hfp_hf *hf);
810 :
811 : /** @brief Handsfree HF release call with specified index
812 : *
813 : * Release call with specified index by sending `AT+CHLD=1<idx>`.
814 : * `<idx>` is index of specified call.
815 : * If @kconfig{CONFIG_BT_HFP_HF_ECC} is not enabled, the error
816 : * `-ENOTSUP` will be returned if the function called.
817 : *
818 : * @param call HFP HF call object.
819 : *
820 : * @return 0 in case of success or negative value in case of error.
821 : */
822 1 : int bt_hfp_hf_release_specified_call(struct bt_hfp_hf_call *call);
823 :
824 : /** @brief Handsfree HF request private consultation mode with specified call
825 : *
826 : * Request private consultation mode with specified call (Place all calls
827 : * on hold EXCEPT the call indicated by `<idx>`.) by sending
828 : * `AT+CHLD=2<idx>`.
829 : * `<idx>` is index of specified call.
830 : * If @kconfig{CONFIG_BT_HFP_HF_ECC} is not enabled, the error
831 : * `-ENOTSUP` will be returned if the function called.
832 : *
833 : * @param call HFP HF call object.
834 : *
835 : * @return 0 in case of success or negative value in case of error.
836 : */
837 1 : int bt_hfp_hf_private_consultation_mode(struct bt_hfp_hf_call *call);
838 :
839 : /** @brief Handsfree HF enable/disable the voice recognition function
840 : *
841 : * Enables/disables the voice recognition function in the AG.
842 : * If @kconfig{CONFIG_BT_HFP_HF_VOICE_RECG} is not enabled, the error
843 : * `-ENOTSUP` will be returned if the function called.
844 : *
845 : * @param hf HFP HF object.
846 : * @param activate Activate/deactivate the voice recognition function.
847 : *
848 : * @return 0 in case of success or negative value in case of error.
849 : */
850 1 : int bt_hfp_hf_voice_recognition(struct bt_hfp_hf *hf, bool activate);
851 :
852 : /** @brief Handsfree HF indicate that the HF is ready to accept audio
853 : *
854 : * This value indicates that the HF is ready to accept audio when
855 : * the Audio Connection is first established. The HF shall only send
856 : * this value if the eSCO link has been established.
857 : * If @kconfig{CONFIG_BT_HFP_HF_ENH_VOICE_RECG} is not enabled, the error
858 : * `-ENOTSUP` will be returned if the function called.
859 : *
860 : * @param hf HFP HF object.
861 : *
862 : * @return 0 in case of success or negative value in case of error.
863 : */
864 1 : int bt_hfp_hf_ready_to_accept_audio(struct bt_hfp_hf *hf);
865 :
866 : /** @brief Handsfree HF attach a phone number for a voice tag
867 : *
868 : * Send AT command "AT+BINP=1" to request phone number to the AG.
869 : *
870 : * @param hf HFP HF object.
871 : *
872 : * @return 0 in case of success or negative value in case of error.
873 : */
874 1 : int bt_hfp_hf_request_phone_number(struct bt_hfp_hf *hf);
875 :
876 : /** @brief Handsfree HF Transmit A specific DTMF Code
877 : *
878 : * During an ongoing call, the HF transmits the AT+VTS command to
879 : * instruct the AG to transmit a specific DTMF code to its network
880 : * connection.
881 : * The set of the code is "0-9,#,*,A-D".
882 : *
883 : * @param call HFP HF call object.
884 : * @param code A specific DTMF code.
885 : *
886 : * @return 0 in case of success or negative value in case of error.
887 : */
888 1 : int bt_hfp_hf_transmit_dtmf_code(struct bt_hfp_hf_call *call, char code);
889 :
890 : /** @brief Handsfree HF Query Subscriber Number Information
891 : *
892 : * It allows HF to query the AG subscriber number by sending `AT+CNUM`.
893 : *
894 : * @param hf HFP HF object.
895 : *
896 : * @return 0 in case of success or negative value in case of error.
897 : */
898 1 : int bt_hfp_hf_query_subscriber(struct bt_hfp_hf *hf);
899 :
900 : /* HFP HF Indicators */
901 0 : enum hfp_hf_ag_indicators {
902 : HF_SERVICE_IND = 0, /* AG service indicator */
903 : HF_CALL_IND, /* AG call indicator */
904 : HF_CALL_SETUP_IND, /* AG call setup indicator */
905 : HF_CALL_HELD_IND, /* AG call held indicator */
906 : HF_SIGNAL_IND, /* AG signal indicator */
907 : HF_ROAM_IND, /* AG roaming indicator */
908 : HF_BATTERY_IND /* AG battery indicator */
909 : };
910 :
911 : /** @brief Handsfree HF set AG indicator activated/deactivated status
912 : *
913 : * It allows HF to issue the AT+BIA command if it needs to change the
914 : * activated/deactivated status of indicators in the AG.
915 : * The index of all indicators can be activated/deactivated are
916 : * defined in `enum hfp_hf_ag_indicators`.
917 : * The each bit of parameter `status` represents the indicator status
918 : * corresponding to the index. Such as, value 0b111110 of `status`
919 : * means the AG indicator `service` is required to be deactivated.
920 : * Others are required to be activated.
921 : *
922 : * @param hf HFP HF object.
923 : * @param status The activated/deactivated bitmap status of AG indicators.
924 : *
925 : * @return 0 in case of success or negative value in case of error.
926 : */
927 1 : int bt_hfp_hf_indicator_status(struct bt_hfp_hf *hf, uint8_t status);
928 :
929 : /** @brief Handsfree HF enable/disable enhanced safety
930 : *
931 : * It allows HF to transfer of HF indicator enhanced safety value.
932 : * If @kconfig{CONFIG_BT_HFP_HF_HF_INDICATOR_ENH_SAFETY} is not enabled,
933 : * the error `-ENOTSUP` will be returned if the function called.
934 : *
935 : * @param hf HFP HF object.
936 : * @param enable The enhanced safety is enabled/disabled.
937 : *
938 : * @return 0 in case of success or negative value in case of error.
939 : */
940 1 : int bt_hfp_hf_enhanced_safety(struct bt_hfp_hf *hf, bool enable);
941 :
942 : /** @brief Handsfree HF remaining battery level
943 : *
944 : * It allows HF to transfer of HF indicator remaining battery level value.
945 : * If @kconfig{CONFIG_BT_HFP_HF_HF_INDICATOR_BATTERY} is not enabled,
946 : * the error `-ENOTSUP` will be returned if the function called.
947 : *
948 : * @param hf HFP HF object.
949 : * @param level The remaining battery level.
950 : *
951 : * @return 0 in case of success or negative value in case of error.
952 : */
953 1 : int bt_hfp_hf_battery(struct bt_hfp_hf *hf, uint8_t level);
954 :
955 : #ifdef __cplusplus
956 : }
957 : #endif
958 :
959 : /**
960 : * @}
961 : */
962 :
963 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_HFP_HF_H_ */
|
