Line data Source code
1 1 : /** @file
2 : * @brief Handsfree Profile Audio Gateway handling.
3 : */
4 :
5 : /*
6 : * Copyright (c) 2015-2016 Intel Corporation
7 : * Copyright 2023-2024 NXP
8 : *
9 : * SPDX-License-Identifier: Apache-2.0
10 : */
11 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_HFP_AG_H_
12 : #define ZEPHYR_INCLUDE_BLUETOOTH_HFP_AG_H_
13 :
14 : /**
15 : * @brief Hands Free Profile - Audio Gateway (HFP-AG)
16 : * @defgroup bt_hfp_ag Hands Free Profile - Audio Gateway (HFP-AG)
17 : * @ingroup bluetooth
18 : * @{
19 : */
20 :
21 : #include <zephyr/bluetooth/bluetooth.h>
22 :
23 : #ifdef __cplusplus
24 : extern "C" {
25 : #endif
26 :
27 : /* HFP AG Indicators */
28 0 : enum bt_hfp_ag_indicator {
29 : BT_HFP_AG_SERVICE_IND = 0, /* Service availability indicator */
30 : BT_HFP_AG_CALL_IND = 1, /* call status indicator */
31 : BT_HFP_AG_CALL_SETUP_IND = 2, /* Call set up status indicator */
32 : BT_HFP_AG_CALL_HELD_IND = 3, /* Call hold status indicator */
33 : BT_HFP_AG_SIGNAL_IND = 4, /* Signal strength indicator */
34 : BT_HFP_AG_ROAM_IND = 5, /* Roaming status indicator */
35 : BT_HFP_AG_BATTERY_IND = 6, /* Battery change indicator */
36 : BT_HFP_AG_IND_MAX /* Indicator MAX value */
37 : };
38 :
39 : /* HFP CODEC */
40 0 : #define BT_HFP_AG_CODEC_CVSD 0x01
41 0 : #define BT_HFP_AG_CODEC_MSBC 0x02
42 0 : #define BT_HFP_AG_CODEC_LC3_SWB 0x03
43 :
44 : struct bt_hfp_ag;
45 : struct bt_hfp_ag_call;
46 :
47 : /** @typedef bt_hfp_ag_query_subscriber_func_t
48 : * @brief Query subscriber number callback function
49 : *
50 : * When AG wants to send subscriber number information, all information
51 : * will be passed through the callback. And the subscriber number
52 : * information will be sent out in this function.
53 : *
54 : * @param ag HFP AG object.
55 : * @param number Subscriber number.
56 : * @param type Type of subscriber number specifies the format of the phone number provided,
57 : * and can be one of the following values:
58 : * - values 128-143: The phone number format may be a national or international
59 : * format, and may contain prefix and/or escape digits. No changes on the number
60 : * presentation are required.
61 : * - values 144-159: The phone number format is an international number, including
62 : * the country code prefix. If the plus sign ("+") is not included as part of the
63 : * number and shall be added by the AG as needed.
64 : * - values 160-175: National number. No prefix nor escape digits included.
65 : * @param service Service of subscriber number indicates which service this phone number relates
66 : * to. Shall be either 4 (voice) or 5 (fax).
67 : *
68 : * @return 0 if should continue to the next subscriber number information.
69 : * @return negative value to stop.
70 : */
71 1 : typedef int (*bt_hfp_ag_query_subscriber_func_t)(struct bt_hfp_ag *ag, char *number, uint8_t type,
72 : uint8_t service);
73 :
74 : /* HF indicators */
75 0 : enum hfp_ag_hf_indicators {
76 : HFP_AG_ENHANCED_SAFETY_IND = 1, /* Enhanced Safety */
77 : HFP_AG_BATTERY_LEVEL_IND = 2, /* Remaining level of Battery */
78 : };
79 :
80 : /* The status of the call */
81 0 : enum __packed bt_hfp_ag_call_status {
82 : BT_HFP_AG_CALL_STATUS_ACTIVE = 0, /* Call is active */
83 : BT_HFP_AG_CALL_STATUS_HELD = 1, /* Call is on hold */
84 : BT_HFP_AG_CALL_STATUS_DIALING = 2, /* Outgoing call is being dialed */
85 : BT_HFP_AG_CALL_STATUS_ALERTING = 3, /* Outgoing call is being alerted */
86 : BT_HFP_AG_CALL_STATUS_INCOMING = 4, /* Incoming call is came */
87 : BT_HFP_AG_CALL_STATUS_WAITING = 5, /* Incoming call is waiting */
88 : BT_HFP_AG_CALL_STATUS_INCOMING_HELD = 6 /* Call held by Response and Hold */
89 : };
90 :
91 : /* The direction of the call */
92 0 : enum __packed bt_hfp_ag_call_dir {
93 : BT_HFP_AG_CALL_DIR_OUTGOING = 0, /* It is a outgoing call */
94 : BT_HFP_AG_CALL_DIR_INCOMING = 1, /* It is a incoming call */
95 : };
96 :
97 : /** @brief The ongoing call
98 : *
99 : * @param number Phone number terminated with '\0' of the call.
100 : * @param type Specify the format of the phone number.
101 : * @param dir Call direction.
102 : * @param status The status of the call.
103 : */
104 1 : struct bt_hfp_ag_ongoing_call {
105 0 : char number[CONFIG_BT_HFP_AG_PHONE_NUMBER_MAX_LEN + 1];
106 0 : uint8_t type;
107 0 : enum bt_hfp_ag_call_dir dir;
108 0 : enum bt_hfp_ag_call_status status;
109 : };
110 :
111 : /** @brief HFP profile AG application callback */
112 1 : struct bt_hfp_ag_cb {
113 : /** HF AG connected callback to application
114 : *
115 : * If this callback is provided it will be called whenever the
116 : * AG connection completes.
117 : *
118 : * @param conn Connection object.
119 : * @param ag HFP AG object.
120 : */
121 1 : void (*connected)(struct bt_conn *conn, struct bt_hfp_ag *ag);
122 : /** HF disconnected callback to application
123 : *
124 : * If this callback is provided it will be called whenever the
125 : * connection gets disconnected, including when a connection gets
126 : * rejected or cancelled or any error in SLC establishment.
127 : *
128 : * @param ag HFP AG object.
129 : */
130 1 : void (*disconnected)(struct bt_hfp_ag *ag);
131 : /** HF SCO/eSCO connected Callback
132 : *
133 : * If this callback is provided it will be called whenever the
134 : * SCO/eSCO connection completes.
135 : *
136 : * @param ag HFP AG object.
137 : * @param sco_conn SCO/eSCO Connection object.
138 : */
139 1 : void (*sco_connected)(struct bt_hfp_ag *ag, struct bt_conn *sco_conn);
140 : /** HF SCO/eSCO disconnected Callback
141 : *
142 : * If this callback is provided it will be called whenever the
143 : * SCO/eSCO connection gets disconnected.
144 : *
145 : * @param conn SCO/eSCO Connection object.
146 : * @param reason BT_HCI_ERR_* reason for the disconnection.
147 : */
148 1 : void (*sco_disconnected)(struct bt_conn *sco_conn, uint8_t reason);
149 :
150 : /** Get ongoing call information Callback
151 : *
152 : * If this callback is provided it will be called whenever the AT command `AT+CIND?` is
153 : * received from HF has been sent.
154 : * After the callback notified, the ongoing calls should be set via function
155 : * `bt_hfp_ag_ongoing_calls()` within the timeout
156 : * @kconfig{CONFIG_BT_HFP_AG_GET_ONGOING_CALL_TIMEOUT}.
157 : *
158 : * @param ag HFP AG object.
159 : *
160 : * @note The AG is in SLC establishment phase. The AG callback `connected()` is not
161 : * notified at this time.
162 : *
163 : * @return 0 in case of success. The response `+CIND` will be sent after the function
164 : * `bt_hfp_ag_ongoing_calls()` called or after the time exceeds
165 : * @kconfig{CONFIG_BT_HFP_AG_GET_ONGOING_CALL_TIMEOUT}. Or negative value in case
166 : * of error. The response `+CIND` will be replied immediately.
167 : */
168 1 : int (*get_ongoing_call)(struct bt_hfp_ag *ag);
169 :
170 : /** HF memory dialing request Callback
171 : *
172 : * If this callback is provided it will be called whenever a
173 : * new call is requested with memory dialing from HF.
174 : * Get the phone number according to the given AG memory location.
175 : *
176 : * @param ag HFP AG object.
177 : * @param location AG memory location
178 : * @param number Dialing number
179 : *
180 : * @return 0 in case of success or negative value in case of error.
181 : */
182 1 : int (*memory_dial)(struct bt_hfp_ag *ag, const char *location, char **number);
183 :
184 : /** HF phone number calling request Callback
185 : *
186 : * If this callback is provided it will be called whenever a
187 : * new call is requested with specific phone number from HF.
188 : * When the callback is triggered, the application needs to start
189 : * dialing the number with the passed phone number.
190 : * If the callback is invalid, the phone number dialing from HF
191 : * cannot be supported.
192 : *
193 : * @param ag HFP AG object.
194 : * @param number Dialing number
195 : *
196 : * @return 0 in case of success or negative value in case of error.
197 : */
198 1 : int (*number_call)(struct bt_hfp_ag *ag, const char *number);
199 :
200 : /** HF outgoing Callback
201 : *
202 : * If this callback is provided it will be called whenever a
203 : * new call is outgoing.
204 : *
205 : * @param ag HFP AG object.
206 : * @param call HFP AG call object.
207 : * @param number Dialing number
208 : */
209 1 : void (*outgoing)(struct bt_hfp_ag *ag, struct bt_hfp_ag_call *call, const char *number);
210 :
211 : /** HF incoming Callback
212 : *
213 : * If this callback is provided it will be called whenever a
214 : * new call is incoming.
215 : *
216 : * @param ag HFP AG object.
217 : * @param call HFP AG call object.
218 : * @param number Incoming number
219 : */
220 1 : void (*incoming)(struct bt_hfp_ag *ag, struct bt_hfp_ag_call *call, const char *number);
221 :
222 : /** HF incoming call is held Callback
223 : *
224 : * If this callback is provided it will be called whenever the
225 : * incoming call is held but not accepted.
226 : *
227 : * @param call HFP AG call object.
228 : */
229 1 : void (*incoming_held)(struct bt_hfp_ag_call *call);
230 :
231 : /** HF ringing Callback
232 : *
233 : * If this callback is provided it will be called whenever the
234 : * call is in the ringing
235 : *
236 : * @param call HFP AG call object.
237 : * @param in_bond true - in-bond ringing, false - No in-bond ringing
238 : */
239 1 : void (*ringing)(struct bt_hfp_ag_call *call, bool in_band);
240 :
241 : /** HF call accept Callback
242 : *
243 : * If this callback is provided it will be called whenever the
244 : * call is accepted.
245 : *
246 : * @param call HFP AG call object.
247 : */
248 1 : void (*accept)(struct bt_hfp_ag_call *call);
249 :
250 : /** HF call held Callback
251 : *
252 : * If this callback is provided it will be called whenever the
253 : * call is held.
254 : *
255 : * @param call HFP AG call object.
256 : */
257 1 : void (*held)(struct bt_hfp_ag_call *call);
258 :
259 : /** HF call retrieve Callback
260 : *
261 : * If this callback is provided it will be called whenever the
262 : * call is retrieved.
263 : *
264 : * @param call HFP AG call object.
265 : */
266 1 : void (*retrieve)(struct bt_hfp_ag_call *call);
267 :
268 : /** HF call reject Callback
269 : *
270 : * If this callback is provided it will be called whenever the
271 : * call is rejected.
272 : *
273 : * @param call HFP AG call object.
274 : */
275 1 : void (*reject)(struct bt_hfp_ag_call *call);
276 :
277 : /** HF call terminate Callback
278 : *
279 : * If this callback is provided it will be called whenever the
280 : * call is terminated.
281 : *
282 : * @param call HFP AG call object.
283 : */
284 1 : void (*terminate)(struct bt_hfp_ag_call *call);
285 :
286 : /** Supported codec Ids callback
287 : *
288 : * If this callback is provided it will be called whenever the
289 : * supported codec ids are updated.
290 : *
291 : * @param ag HFP AG object.
292 : */
293 1 : void (*codec)(struct bt_hfp_ag *ag, uint32_t ids);
294 :
295 : /** Codec negotiate callback
296 : *
297 : * If this callback is provided it will be called whenever the
298 : * codec negotiation succeeded or failed.
299 : *
300 : * @param ag HFP AG object.
301 : * @param err Result of codec negotiation.
302 : */
303 1 : void (*codec_negotiate)(struct bt_hfp_ag *ag, int err);
304 :
305 : /** Audio connection request callback
306 : *
307 : * If this callback is provided it will be called whenever the
308 : * audio conenction request is triggered by HF.
309 : * When AT+BCC AT command received, it means the procedure of
310 : * establishment of audio connection is triggered by HF.
311 : * If the callback is provided by application, AG needs to
312 : * start the codec connection procedure by calling
313 : * function `bt_hfp_ag_audio_connect` in application layer.
314 : * Or, the codec conenction procedure will be started with
315 : * default codec id `BT_HFP_AG_CODEC_CVSD`.
316 : *
317 : * @param ag HFP AG object.
318 : * @param err Result of codec negotiation.
319 : */
320 1 : void (*audio_connect_req)(struct bt_hfp_ag *ag);
321 :
322 : /** HF VGM setting callback
323 : *
324 : * If this callback is provided it will be called whenever the
325 : * VGM gain setting is informed from HF.
326 : *
327 : * @param ag HFP AG object.
328 : * @param gain HF microphone gain value.
329 : */
330 1 : void (*vgm)(struct bt_hfp_ag *ag, uint8_t gain);
331 :
332 : /** HF VGS setting callback
333 : *
334 : * If this callback is provided it will be called whenever the
335 : * VGS gain setting is informed from HF.
336 : *
337 : * @param ag HFP AG object.
338 : * @param gain HF speaker gain value.
339 : */
340 1 : void (*vgs)(struct bt_hfp_ag *ag, uint8_t gain);
341 :
342 : /** HF ECNR turns off callback
343 : *
344 : * If this callback is provided it will be called whenever the
345 : * ECNR turning off request is received from HF.
346 : * If the callback is NULL or @kconfig{CONFIG_BT_HFP_AG_ECNR}
347 : * is not enabled, the response result code of AT command
348 : * will be an AT ERROR.
349 : *
350 : * @param ag HFP AG object.
351 : */
352 1 : void (*ecnr_turn_off)(struct bt_hfp_ag *ag);
353 :
354 : /** HF explicit call transfer callback
355 : *
356 : * If this callback is provided it will be called whenever the
357 : * AT+CHLD=4 is sent from HF.
358 : * When the callback is notified, the application should connect
359 : * the two calls and disconnects the subscriber from both calls
360 : * (Explicit Call Transfer).
361 : * After the callback returned, the call objects will be invalid.
362 : * If the callback is NULL, the response result code of AT command
363 : * will be an AT ERROR.
364 : * If @kconfig{CONFIG_BT_HFP_AG_3WAY_CALL} is not enabled, the
365 : * callback will not be notified.
366 : *
367 : * @param ag HFP AG object.
368 : */
369 1 : void (*explicit_call_transfer)(struct bt_hfp_ag *ag);
370 :
371 : /** Voice recognition activation/deactivation callback
372 : *
373 : * If this callback is provided it will be called whenever the
374 : * voice recognition activation is changed.
375 : * If voice recognition is activated, the upper layer should
376 : * call `bt_hfp_ag_audio_connect` with appropriate codec ID to
377 : * setup audio connection.
378 : * If the callback is not provided by upper layer, the function
379 : * `bt_hfp_ag_audio_connect` will be called with default codec
380 : * ID `BT_HFP_AG_CODEC_CVSD`.
381 : * If @kconfig{CONFIG_BT_HFP_AG_VOICE_RECG} is not enabled,
382 : * the callback will not be notified.
383 : *
384 : * @param ag HFP AG object.
385 : * @param activate Voice recognition activation/deactivation.
386 : */
387 1 : void (*voice_recognition)(struct bt_hfp_ag *ag, bool activate);
388 :
389 : /** Ready to accept audio callback
390 : *
391 : * If this callback is provided it will be called whenever the
392 : * HF is ready to accept audio.
393 : * If the feature `Enhanced Voice Recognition Status` is supported
394 : * by HF, the callback will be notified if the AT command `AT+BVRA=2`
395 : * is received. The HF may send this value during an ongoing VR
396 : * (Voice Recognition) session to terminate audio output from the
397 : * AG (if there is any) and prepare the AG for new audio input.
398 : * Or, the callback will be notified after the voice recognition
399 : * is activated.
400 : * If @kconfig{CONFIG_BT_HFP_AG_ENH_VOICE_RECG} is not enabled,
401 : * the callback will not be notified.
402 : *
403 : * @param ag HFP AG object.
404 : */
405 1 : void (*ready_to_accept_audio)(struct bt_hfp_ag *ag);
406 :
407 : /** Request phone number callback
408 : *
409 : * If this callback is provided it will be called whenever the
410 : * AT command `AT+BINP=1` is received.
411 : * If the upper layer accepts the request, it shall obtain a
412 : * phone number.
413 : * If the upper layer rejects the request, it shall return a
414 : * an error.
415 : * If @kconfig{CONFIG_BT_HFP_AG_VOICE_TAG} is not enabled,
416 : * the callback will not be notified.
417 : *
418 : * @param ag HFP AG object.
419 : * @param number Phone number of voice tag.
420 : *
421 : * @return 0 in case of success or negative value in case of error.
422 : */
423 1 : int (*request_phone_number)(struct bt_hfp_ag *ag, char **number);
424 :
425 : /** Transmit a DTMF Code callback
426 : *
427 : * If this callback is provided it will be called whenever the
428 : * AT command `AT+VTS=<code>` is received.
429 : * During an ongoing call, the HF transmits the AT+VTS command
430 : * to instruct the AG to transmit a specific DTMF code to its
431 : * network connection.
432 : *
433 : * @param ag HFP AG object.
434 : * @param code A specific DTMF code.
435 : */
436 1 : void (*transmit_dtmf_code)(struct bt_hfp_ag *ag, char code);
437 :
438 : /** Get subscriber number callback
439 : *
440 : * If this callback is provided it will be called whenever the
441 : * AT command `AT+CNUM` is received.
442 : *
443 : * @param ag HFP AG object.
444 : * @param func Query subscriber number callback.
445 : *
446 : * @return 0 in case of success or negative value in case of error.
447 : */
448 1 : int (*subscriber_number)(struct bt_hfp_ag *ag, bt_hfp_ag_query_subscriber_func_t func);
449 :
450 : /** HF indicator value callback
451 : *
452 : * If this callback is provided it will be called whenever the
453 : * AT command `AT+BIEV` is received.
454 : * If @kconfig{CONFIG_BT_HFP_AG_HF_INDICATORS} is not enabled,
455 : * the callback will not be notified.
456 : *
457 : * @param ag HFP AG object.
458 : * @param indicator HF indicator
459 : * @param value The value of specific indicator
460 : */
461 1 : void (*hf_indicator_value)(struct bt_hfp_ag *ag, enum hfp_ag_hf_indicators indicator,
462 : uint32_t value);
463 : };
464 :
465 : /** @brief Register HFP AG profile
466 : *
467 : * Register Handsfree profile AG callbacks to monitor the state and get the
468 : * required HFP details to display.
469 : *
470 : * @param cb callback structure.
471 : *
472 : * @return 0 in case of success or negative value in case of error.
473 : */
474 1 : int bt_hfp_ag_register(struct bt_hfp_ag_cb *cb);
475 :
476 : /** @brief Create the hfp ag session
477 : *
478 : * Create the hfp ag session
479 : *
480 : * @param conn ACL connection object.
481 : * @param ag Created HFP AG object.
482 : * @param channel Peer rfcomm channel to be connected.
483 : *
484 : * @return 0 in case of success or negative value in case of error.
485 : */
486 1 : int bt_hfp_ag_connect(struct bt_conn *conn, struct bt_hfp_ag **ag, uint8_t channel);
487 :
488 : /** @brief Disconnect the hfp ag session
489 : *
490 : * Disconnect the hfp ag session
491 : *
492 : * @param ag HFP AG object.
493 : *
494 : * @return 0 in case of success or negative value in case of error.
495 : */
496 1 : int bt_hfp_ag_disconnect(struct bt_hfp_ag *ag);
497 :
498 : /** @brief Notify HFP Unit of an incoming call
499 : *
500 : * Notify HFP Unit of an incoming call.
501 : *
502 : * @param ag HFP AG object.
503 : * @param number Dialing number.
504 : *
505 : * @return 0 in case of success or negative value in case of error.
506 : */
507 1 : int bt_hfp_ag_remote_incoming(struct bt_hfp_ag *ag, const char *number);
508 :
509 : /** @brief Put the incoming call on hold
510 : *
511 : * Put the incoming call on hold.
512 : *
513 : * @param call HFP AG call object.
514 : *
515 : * @return 0 in case of success or negative value in case of error.
516 : */
517 1 : int bt_hfp_ag_hold_incoming(struct bt_hfp_ag_call *call);
518 :
519 : /** @brief Reject the incoming call
520 : *
521 : * Reject the incoming call.
522 : *
523 : * @param call HFP AG call object.
524 : *
525 : * @return 0 in case of success or negative value in case of error.
526 : */
527 1 : int bt_hfp_ag_reject(struct bt_hfp_ag_call *call);
528 :
529 : /** @brief Accept the incoming call
530 : *
531 : * Accept the incoming call.
532 : *
533 : * @param call HFP AG call object.
534 : *
535 : * @return 0 in case of success or negative value in case of error.
536 : */
537 1 : int bt_hfp_ag_accept(struct bt_hfp_ag_call *call);
538 :
539 : /** @brief Terminate the active/hold call
540 : *
541 : * Terminate the active/hold call.
542 : *
543 : * @param call HFP AG call object.
544 : *
545 : * @return 0 in case of success or negative value in case of error.
546 : */
547 1 : int bt_hfp_ag_terminate(struct bt_hfp_ag_call *call);
548 :
549 : /** @brief Retrieve the held call
550 : *
551 : * Retrieve the held call.
552 : *
553 : * @param call HFP AG call object.
554 : *
555 : * @return 0 in case of success or negative value in case of error.
556 : */
557 1 : int bt_hfp_ag_retrieve(struct bt_hfp_ag_call *call);
558 :
559 : /** @brief Hold the active call
560 : *
561 : * Hold the active call.
562 : *
563 : * @param call HFP AG call object.
564 : *
565 : * @return 0 in case of success or negative value in case of error.
566 : */
567 1 : int bt_hfp_ag_hold(struct bt_hfp_ag_call *call);
568 :
569 : /** @brief Dial a call
570 : *
571 : * Dial a call.
572 : *
573 : * @param ag HFP AG object.
574 : * @param number Dialing number.
575 : *
576 : * @return 0 in case of success or negative value in case of error.
577 : */
578 1 : int bt_hfp_ag_outgoing(struct bt_hfp_ag *ag, const char *number);
579 :
580 : /** @brief Notify HFP Unit that the remote starts ringing
581 : *
582 : * Notify HFP Unit that the remote starts ringing.
583 : *
584 : * @param call HFP AG call object.
585 : *
586 : * @return 0 in case of success or negative value in case of error.
587 : */
588 1 : int bt_hfp_ag_remote_ringing(struct bt_hfp_ag_call *call);
589 :
590 : /** @brief Notify HFP Unit that the remote rejects the call
591 : *
592 : * Notify HFP Unit that the remote rejects the call.
593 : *
594 : * @param call HFP AG call object.
595 : *
596 : * @return 0 in case of success or negative value in case of error.
597 : */
598 1 : int bt_hfp_ag_remote_reject(struct bt_hfp_ag_call *call);
599 :
600 : /** @brief Notify HFP Unit that the remote accepts the call
601 : *
602 : * Notify HFP Unit that the remote accepts the call.
603 : *
604 : * @param call HFP AG call object.
605 : *
606 : * @return 0 in case of success or negative value in case of error.
607 : */
608 1 : int bt_hfp_ag_remote_accept(struct bt_hfp_ag_call *call);
609 :
610 : /** @brief Notify HFP Unit that the remote terminates the active/hold call
611 : *
612 : * Notify HFP Unit that the remote terminates the active/hold call.
613 : *
614 : * @param call HFP AG call object.
615 : *
616 : * @return 0 in case of success or negative value in case of error.
617 : */
618 1 : int bt_hfp_ag_remote_terminate(struct bt_hfp_ag_call *call);
619 :
620 : /** @brief explicit call transfer
621 : *
622 : * Connects the two calls and disconnects the subscriber from
623 : * both calls (Explicit Call Transfer).
624 : * If @kconfig{CONFIG_BT_HFP_AG_3WAY_CALL} is not enabled, the error
625 : * `-ENOTSUP` will be returned if the function called.
626 : *
627 : * @param ag HFP AG object.
628 : *
629 : * @return 0 in case of success or negative value in case of error.
630 : */
631 1 : int bt_hfp_ag_explicit_call_transfer(struct bt_hfp_ag *ag);
632 :
633 : /** @brief Set the HF microphone gain
634 : *
635 : * Set the HF microphone gain
636 : *
637 : * @param ag HFP AG object.
638 : * @param vgm Microphone gain value.
639 : *
640 : * @return 0 in case of success or negative value in case of error.
641 : */
642 1 : int bt_hfp_ag_vgm(struct bt_hfp_ag *ag, uint8_t vgm);
643 :
644 : /** @brief Set the HF speaker gain
645 : *
646 : * Set the HF speaker gain
647 : *
648 : * @param ag HFP AG object.
649 : * @param vgs Speaker gain value.
650 : *
651 : * @return 0 in case of success or negative value in case of error.
652 : */
653 1 : int bt_hfp_ag_vgs(struct bt_hfp_ag *ag, uint8_t vgs);
654 :
655 : /** @brief Set currently network operator
656 : *
657 : * Set currently network operator.
658 : *
659 : * @param ag HFP AG object.
660 : * @param mode Current mode and provides no information with regard
661 : * to the name of the operator.
662 : * @param name A string in alphanumeric format representing the
663 : * name of the network operator. This string shall
664 : * not exceed 16 characters.
665 : *
666 : * @return 0 in case of success or negative value in case of error.
667 : */
668 1 : int bt_hfp_ag_set_operator(struct bt_hfp_ag *ag, uint8_t mode, char *name);
669 :
670 : /** @brief Create audio connection
671 : *
672 : * Create audio conenction by HFP AG. There are two setups included,
673 : * Codec connection and audio connection.
674 : * The codec connection will be established firstly if the codec
675 : * negotiation are supported by both side. If the passed codec id
676 : * is not same as the last codec connection, the codec connection
677 : * procedure will be triggered.
678 : * After the codec conenction is established, the audio conenction
679 : * will be started.
680 : * The passed codec id could be one of BT_HFP_AG_CODEC_XXX. If the
681 : * codec negotiation feature is supported by both side, the codec id
682 : * could be one of the bitmaps of `ids` notified by callback `codec`.
683 : * Or, the `id` should be BT_HFP_AG_CODEC_CVSD.
684 : *
685 : * @param ag HFP AG object.
686 : * @param id Codec Id.
687 : *
688 : * @return 0 in case of success or negative value in case of error.
689 : */
690 1 : int bt_hfp_ag_audio_connect(struct bt_hfp_ag *ag, uint8_t id);
691 :
692 : /** @brief Set In-Band Ring Tone
693 : *
694 : * Set In-Band Ring Tone.
695 : *
696 : * @param ag HFP AG object.
697 : * @param inband In-band or no in-band.
698 : *
699 : * @return 0 in case of success or negative value in case of error.
700 : */
701 1 : int bt_hfp_ag_inband_ringtone(struct bt_hfp_ag *ag, bool inband);
702 :
703 : /** @brief Enable/disable the voice recognition function
704 : *
705 : * Enables/disables the voice recognition function.
706 : * If @kconfig{CONFIG_BT_HFP_AG_VOICE_RECG} is not enabled, the error
707 : * `-ENOTSUP` will be returned if the function called.
708 : *
709 : * @param ag HFP AG object.
710 : * @param activate Activate/deactivate the voice recognition function.
711 : *
712 : * @return 0 in case of success or negative value in case of error.
713 : */
714 1 : int bt_hfp_ag_voice_recognition(struct bt_hfp_ag *ag, bool activate);
715 :
716 : /** @brief set voice recognition engine state
717 : *
718 : * It is used to set the voice recognition engine state.
719 : * The unsolicited result code `+BVRA: 1,<vrecstate>` will be sent.
720 : * `<vrecstate>`: Bitmask that reflects the current state of the voice
721 : * recognition engine on the AG.
722 : * Bit 0 - If it is 1, the AG is ready to accept audio input
723 : * Bit 1 - If it is 1, the AG is sending audio to the HF
724 : * Bit 2 - If it is 1, the AG is processing the audio input
725 : * If @kconfig{CONFIG_BT_HFP_AG_ENH_VOICE_RECG} is not enabled, the error
726 : * `-ENOTSUP` will be returned if the function called.
727 : *
728 : * @param ag HFP AG object.
729 : * @param state The value of `<vrecstate>`.
730 : *
731 : * @return 0 in case of success or negative value in case of error.
732 : */
733 1 : int bt_hfp_ag_vre_state(struct bt_hfp_ag *ag, uint8_t state);
734 :
735 : /** @brief set voice recognition engine state and textual representation
736 : *
737 : * It is used to set the voice recognition engine state with
738 : * textual representation.
739 : * unsolicited result code `+BVRA: 1,<vrecstate>,
740 : * <textualRepresentation>` will be sent.
741 : * `<vrecstate>` is same as parameter `state` of function
742 : * `bt_hfp_ag_vre_state`.
743 : * `<textualRepresentation>: <textID>,<textType>,<textOperation>,
744 : * <string>`.
745 : * `<textID>`: Unique ID of the current text as a hexadecimal string
746 : * (a maximum of 4 characters in length, but less than 4 characters
747 : * in length is valid).
748 : * `<textType>`: ID of the textType from the following list:
749 : * 0 - Text recognized by the AG from the audio input provided by the HF
750 : * 1 - Text of the audio output from the AG
751 : * 2 - Text of the audio output from the AG that contains a question
752 : * 3 - Text of the audio output from the AG that contains an error
753 : * description
754 : * `<textOperation>`: ID of the operation of the text
755 : * 1 - NewText: Indicates that a new text started. Shall be used when the
756 : * `<textID>` changes
757 : * 2 - Replace: Replace any existing text with the same `<textID>` and
758 : * same `<textType>`
759 : * 3 - Append: Attach new text to existing text and keep the same
760 : * `<textID>` and same `<textType>`
761 : * `<string>`: The `<string>` parameter shall be a UTF-8 text string and
762 : * shall always be contained within double quotes.
763 : * If @kconfig{CONFIG_BT_HFP_AG_VOICE_RECG_TEXT} is not enabled, the error
764 : * `-ENOTSUP` will be returned if the function called.
765 : *
766 : * @param ag HFP AG object.
767 : * @param state The value of `<vrecstate>`.
768 : * @param id Value of `<textID>`.
769 : * @param type Value of `<textType>`.
770 : * @param operation Value of `<textOperation>`.
771 : * @param text Value of `<string>`.
772 : *
773 : * @return 0 in case of success or negative value in case of error.
774 : */
775 1 : int bt_hfp_ag_vre_textual_representation(struct bt_hfp_ag *ag, uint8_t state, const char *id,
776 : uint8_t type, uint8_t operation, const char *text);
777 :
778 : /** @brief Set signal strength
779 : *
780 : * Set signal strength.
781 : *
782 : * @param ag HFP AG object.
783 : * @param strength Signal strength.
784 : *
785 : * @return 0 in case of success or negative value in case of error.
786 : */
787 1 : int bt_hfp_ag_signal_strength(struct bt_hfp_ag *ag, uint8_t strength);
788 :
789 : /** @brief Set roaming status
790 : *
791 : * Set roaming status.
792 : *
793 : * @param ag HFP AG object.
794 : * @param status Roaming status.
795 : *
796 : * @return 0 in case of success or negative value in case of error.
797 : */
798 1 : int bt_hfp_ag_roaming_status(struct bt_hfp_ag *ag, uint8_t status);
799 :
800 : /** @brief Set battery level
801 : *
802 : * Set battery level.
803 : *
804 : * @param ag HFP AG object.
805 : * @param level battery level.
806 : *
807 : * @return 0 in case of success or negative value in case of error.
808 : */
809 1 : int bt_hfp_ag_battery_level(struct bt_hfp_ag *ag, uint8_t level);
810 :
811 : /** @brief Set service availability
812 : *
813 : * Set service availability.
814 : *
815 : * @param ag HFP AG object.
816 : * @param available service availability
817 : *
818 : * @return 0 in case of success or negative value in case of error.
819 : */
820 1 : int bt_hfp_ag_service_availability(struct bt_hfp_ag *ag, bool available);
821 :
822 : /** @brief Activate/deactivate HF indicator
823 : *
824 : * It allows HF to issue the +BIND unsolicited result code to
825 : * activate/deactivate of the AG’s supported HF Indicators.
826 : * The indicator of supported indicators can be activated/deactivated
827 : * are defined in `enum hfp_ag_hf_indicators`.
828 : * `BT_HFP_AG_HF_INDICATOR_ENH_SAFETY` is used to support
829 : * `Enhanced Safety`. Only the configuration has been enabled, the
830 : * `indicator` can be HFP_AG_ENHANCED_SAFETY_IND.
831 : * `BT_HFP_AG_HF_INDICATOR_BATTERY` is used to support
832 : * `Remaining level of Battery`. Only the configuration has been
833 : * enabled, the `indicator` can be HFP_AG_BATTERY_LEVEL_IND.
834 : * If @kconfig{CONFIG_BT_HFP_HF_HF_INDICATORS} is not enabled, the error
835 : * `-ENOTSUP` will be returned if the function called.
836 : *
837 : * @param ag HFP AG object.
838 : * @param indicator The indicator of the AG’s supported HF Indicators.
839 : * @param enable enable/disable specific HF Indicator.
840 : *
841 : * @return 0 in case of success or negative value in case of error.
842 : */
843 1 : int bt_hfp_ag_hf_indicator(struct bt_hfp_ag *ag, enum hfp_ag_hf_indicators indicator, bool enable);
844 :
845 : /** @brief Set the ongoing calls
846 : *
847 : * It is used to set the ongoing calls when AT command `AT+CIND?` is received.
848 : *
849 : * @param ag HFP AG object.
850 : * @param calls Ongoing calls.
851 : * @param count Ongoing call count.
852 : *
853 : * @return 0 in case of success or negative value in case of error.
854 : */
855 1 : int bt_hfp_ag_ongoing_calls(struct bt_hfp_ag *ag, struct bt_hfp_ag_ongoing_call *calls,
856 : size_t count);
857 :
858 : #ifdef __cplusplus
859 : }
860 : #endif
861 :
862 : /**
863 : * @}
864 : */
865 :
866 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_HFP_HF_H_ */
|
