Line data Source code
1 1 : /**
2 : * @file
3 : * @brief Public APIs for Bluetooth Telephone Bearer Service.
4 : *
5 : * Copyright (c) 2020 Bose Corporation
6 : * Copyright (c) 2021 Nordic Semiconductor ASA
7 : *
8 : * SPDX-License-Identifier: Apache-2.0
9 : */
10 :
11 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_TBS_H_
12 : #define ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_TBS_H_
13 :
14 : /**
15 : * @brief Telephone Bearer Service (TBS)
16 : *
17 : * @defgroup bt_tbs Telephone Bearer Service (TBS)
18 : *
19 : * @since 3.0
20 : * @version 0.8.0
21 : *
22 : * @ingroup bluetooth
23 : * @{
24 : *
25 : * The Telephone Bearer Service (TBS) provide procedures to discover telephone bearers and control
26 : * calls.
27 : */
28 :
29 : #include <stdint.h>
30 : #include <stdbool.h>
31 :
32 : #include <zephyr/bluetooth/conn.h>
33 : #include <zephyr/sys/slist.h>
34 : #include <zephyr/sys/util_macro.h>
35 :
36 : #ifdef __cplusplus
37 : extern "C" {
38 : #endif
39 :
40 : /**
41 : * @name Call States
42 : * @{
43 : */
44 : /** A remote party is calling (incoming call). */
45 1 : #define BT_TBS_CALL_STATE_INCOMING 0x00
46 : /**
47 : * The process to call the remote party has started on the server, but the remote party is not
48 : * being alerted (outgoing call).
49 : */
50 1 : #define BT_TBS_CALL_STATE_DIALING 0x01
51 : /** A remote party is being alerted (outgoing call). */
52 1 : #define BT_TBS_CALL_STATE_ALERTING 0x02
53 : /** The call is in an active conversation. */
54 1 : #define BT_TBS_CALL_STATE_ACTIVE 0x03
55 : /**
56 : * The call is connected but held locally. Locally Held implies that either the server or the
57 : * client can affect the state.
58 : */
59 1 : #define BT_TBS_CALL_STATE_LOCALLY_HELD 0x04
60 : /**
61 : *The call is connected but held remotely. Remotely Held means that the state is controlled by the
62 : * remote party of a call.
63 : */
64 1 : #define BT_TBS_CALL_STATE_REMOTELY_HELD 0x05
65 : /** The call is connected but held both locally and remotely. */
66 1 : #define BT_TBS_CALL_STATE_LOCALLY_AND_REMOTELY_HELD 0x06
67 : /** @} */
68 :
69 : /**
70 : * @name Terminate Reason
71 : * @{
72 : */
73 : /** The URI value used to originate a call was formed improperly. */
74 1 : #define BT_TBS_REASON_BAD_REMOTE_URI 0x00
75 : /** The call failed. */
76 1 : #define BT_TBS_REASON_CALL_FAILED 0x01
77 : /** The remote party ended the call. */
78 1 : #define BT_TBS_REASON_REMOTE_ENDED_CALL 0x02
79 : /** The call ended from the server. */
80 1 : #define BT_TBS_REASON_SERVER_ENDED_CALL 0x03
81 : /** The line was busy. */
82 1 : #define BT_TBS_REASON_LINE_BUSY 0x04
83 : /** Network congestion. */
84 1 : #define BT_TBS_REASON_NETWORK_CONGESTED 0x05
85 : /** The client terminated the call. */
86 1 : #define BT_TBS_REASON_CLIENT_TERMINATED 0x06
87 : /** No service. */
88 1 : #define BT_TBS_REASON_NO_SERVICE 0x07
89 : /** No answer. */
90 1 : #define BT_TBS_REASON_NO_ANSWER 0x08
91 : /** Unspecified. */
92 1 : #define BT_TBS_REASON_UNSPECIFIED 0x09
93 : /** @} */
94 :
95 : /**
96 : * @name Control point error codes
97 : * @{
98 : */
99 : /** The opcode write was successful. */
100 1 : #define BT_TBS_RESULT_CODE_SUCCESS 0x00
101 : /** An invalid opcode was used for the Call Control Point write. */
102 1 : #define BT_TBS_RESULT_CODE_OPCODE_NOT_SUPPORTED 0x01
103 : /** The requested operation cannot be completed. */
104 1 : #define BT_TBS_RESULT_CODE_OPERATION_NOT_POSSIBLE 0x02
105 : /** The Call Index used for the Call Control Point write is invalid. */
106 1 : #define BT_TBS_RESULT_CODE_INVALID_CALL_INDEX 0x03
107 : /**
108 : * The opcode written to the Call Control Point was received when the current Call State for the
109 : * Call Index was not in the expected state.
110 : */
111 1 : #define BT_TBS_RESULT_CODE_STATE_MISMATCH 0x04
112 : /** Lack of internal resources to complete the requested action. */
113 1 : #define BT_TBS_RESULT_CODE_OUT_OF_RESOURCES 0x05
114 : /** The Outgoing URI is incorrect or invalid when an Originate opcode is sent. */
115 1 : #define BT_TBS_RESULT_CODE_INVALID_URI 0x06
116 : /** @} */
117 :
118 : /**
119 : * @name Optional feature bits
120 : *
121 : * Optional features that can be supported. See bt_tbs_client_read_optional_opcodes() on how to
122 : * read these from a remote device
123 : * @{
124 : */
125 : /** Local Hold and Local Retrieve Call Control Point Opcodes supported */
126 1 : #define BT_TBS_FEATURE_HOLD BIT(0)
127 : /** Join Call Control Point Opcode supported */
128 1 : #define BT_TBS_FEATURE_JOIN BIT(1)
129 : /** All Control Point Opcodes supported */
130 1 : #define BT_TBS_FEATURE_ALL (BT_TBS_FEATURE_HOLD | BT_TBS_FEATURE_JOIN)
131 : /** @} */
132 :
133 : /**
134 : * @name Signal strength value limits
135 : * @{
136 : */
137 : /** No service */
138 1 : #define BT_TBS_SIGNAL_STRENGTH_NO_SERVICE 0
139 : /** Maximum signal strength */
140 1 : #define BT_TBS_SIGNAL_STRENGTH_MAX 100
141 : /** Signal strength is unknown */
142 1 : #define BT_TBS_SIGNAL_STRENGTH_UNKNOWN 255
143 : /** @} */
144 :
145 : /**
146 : * @name Bearer Technology
147 : * @{
148 : */
149 : /** 3G */
150 1 : #define BT_TBS_TECHNOLOGY_3G 0x01
151 : /** 4G */
152 1 : #define BT_TBS_TECHNOLOGY_4G 0x02
153 : /** Long-term evolution (LTE) */
154 1 : #define BT_TBS_TECHNOLOGY_LTE 0x03
155 : /** Wifi */
156 1 : #define BT_TBS_TECHNOLOGY_WIFI 0x04
157 : /** 5G */
158 1 : #define BT_TBS_TECHNOLOGY_5G 0x05
159 : /** Global System for Mobile Communications (GSM) */
160 1 : #define BT_TBS_TECHNOLOGY_GSM 0x06
161 : /** Code-Division Multiple Access (CDMA) */
162 1 : #define BT_TBS_TECHNOLOGY_CDMA 0x07
163 : /** 2G */
164 1 : #define BT_TBS_TECHNOLOGY_2G 0x08
165 : /** Wideband Code-Division Multiple Access (WCDMA) */
166 1 : #define BT_TBS_TECHNOLOGY_WCDMA 0x09
167 : /** @} */
168 :
169 : /**
170 : * @name Call status flags bitfield
171 : * @{
172 : */
173 : /** Inband ringtone enabled */
174 1 : #define BT_TBS_STATUS_FLAG_INBAND_RINGTONE BIT(0)
175 : /** Server is in silent mod */
176 1 : #define BT_TBS_STATUS_FLAG_SILENT_MOD BIT(1)
177 : /** @} */
178 :
179 : /**
180 : * @name Call flags bitfield
181 : * @{
182 : */
183 : /** If set, call is outgoing else incoming */
184 1 : #define BT_TBS_CALL_FLAG_OUTGOING BIT(0)
185 : /** If set call is withheld, else not withheld */
186 1 : #define BT_TBS_CALL_FLAG_WITHHELD BIT(1)
187 : /** If set call is withheld by network, else provided by network */
188 1 : #define BT_TBS_CALL_FLAG_WITHHELD_BY_NETWORK BIT(2)
189 : /** @} */
190 :
191 : /**
192 : * @brief The GTBS index denotes whenever a callback is from a
193 : * Generic Telephone Bearer Service (GTBS) instance, or
194 : * whenever the client should perform on action on the GTBS instance of the
195 : * server, rather than any of the specific Telephone Bearer Service instances.
196 : */
197 1 : #define BT_TBS_GTBS_INDEX 0xFF
198 :
199 : /** @brief Opaque Telephone Bearer Service instance. */
200 : struct bt_tbs_instance;
201 :
202 : /**
203 : * @brief Callback function for client originating a call.
204 : *
205 : * @param conn The connection used.
206 : * @param call_index The call index.
207 : * @param uri The URI. The value may change, so should be
208 : * copied if persistence is wanted.
209 : *
210 : * @return true if the call request was accepted and remote party is alerted.
211 : */
212 1 : typedef bool (*bt_tbs_originate_call_cb)(struct bt_conn *conn,
213 : uint8_t call_index,
214 : const char *uri);
215 :
216 : /**
217 : * @brief Callback function for client terminating a call.
218 : *
219 : * The call may be either terminated by the client or the server.
220 : *
221 : * @param conn The connection used.
222 : * @param call_index The call index.
223 : * @param reason The termination BT_TBS_REASON_* reason.
224 : */
225 1 : typedef void (*bt_tbs_terminate_call_cb)(struct bt_conn *conn,
226 : uint8_t call_index,
227 : uint8_t reason);
228 :
229 : /**
230 : * @brief Callback function for client joining calls.
231 : *
232 : * @param conn The connection used.
233 : * @param call_index_count The number of call indexes to join.
234 : * @param call_indexes The call indexes.
235 : */
236 1 : typedef void (*bt_tbs_join_calls_cb)(struct bt_conn *conn,
237 : uint8_t call_index_count,
238 : const uint8_t *call_indexes);
239 :
240 : /**
241 : * @brief Callback function for client request call state change
242 : *
243 : * @param conn The connection used.
244 : * @param call_index The call index.
245 : */
246 1 : typedef void (*bt_tbs_call_change_cb)(struct bt_conn *conn,
247 : uint8_t call_index);
248 :
249 : /**
250 : * @brief Callback function for authorizing a client.
251 : *
252 : * @param conn The connection used.
253 : *
254 : * @return true if authorized, false otherwise
255 : */
256 1 : typedef bool (*bt_tbs_authorize_cb)(struct bt_conn *conn);
257 :
258 : /**
259 : * @brief Struct to hold the Telephone Bearer Service callbacks
260 : *
261 : * These can be registered for usage with bt_tbs_register_cb().
262 : */
263 1 : struct bt_tbs_cb {
264 : /** Client originating call */
265 1 : bt_tbs_originate_call_cb originate_call;
266 : /** Client terminating call */
267 1 : bt_tbs_terminate_call_cb terminate_call;
268 : /** Client holding call */
269 1 : bt_tbs_call_change_cb hold_call;
270 : /** Client accepting call */
271 1 : bt_tbs_call_change_cb accept_call;
272 : /** Client retrieving call */
273 1 : bt_tbs_call_change_cb retrieve_call;
274 : /** Client joining calls */
275 1 : bt_tbs_join_calls_cb join_calls;
276 : /** Callback to authorize a client */
277 1 : bt_tbs_authorize_cb authorize;
278 : };
279 :
280 : /**
281 : * @brief Accept an alerting call.
282 : *
283 : * @param call_index The index of the call that will be accepted.
284 : *
285 : * @return int BT_TBS_RESULT_CODE_* if positive or 0,
286 : * errno value if negative.
287 : */
288 1 : int bt_tbs_accept(uint8_t call_index);
289 :
290 : /**
291 : * @brief Hold a call.
292 : *
293 : * @param call_index The index of the call that will be held.
294 : *
295 : * @return int BT_TBS_RESULT_CODE_* if positive or 0,
296 : * errno value if negative.
297 : */
298 1 : int bt_tbs_hold(uint8_t call_index);
299 :
300 : /**
301 : * @brief Retrieve a call.
302 : *
303 : * @param call_index The index of the call that will be retrieved.
304 : *
305 : * @return int BT_TBS_RESULT_CODE_* if positive or 0,
306 : * errno value if negative.
307 : */
308 1 : int bt_tbs_retrieve(uint8_t call_index);
309 :
310 : /**
311 : * @brief Terminate a call.
312 : *
313 : * @param call_index The index of the call that will be terminated.
314 : *
315 : * @return int BT_TBS_RESULT_CODE_* if positive or 0,
316 : * errno value if negative.
317 : */
318 1 : int bt_tbs_terminate(uint8_t call_index);
319 :
320 : /**
321 : * @brief Originate a call
322 : *
323 : * @param[in] bearer_index The index of the Telephone Bearer.
324 : * @param[in] uri The remote URI.
325 : * @param[out] call_index Pointer to a value where the new call_index will be
326 : * stored.
327 : *
328 : * @return int A call index on success (positive value),
329 : * errno value on fail.
330 : */
331 1 : int bt_tbs_originate(uint8_t bearer_index, char *uri, uint8_t *call_index);
332 :
333 : /**
334 : * @brief Join calls
335 : *
336 : * @param call_index_cnt The number of call indexes to join
337 : * @param call_indexes Array of call indexes to join.
338 : *
339 : * @return int BT_TBS_RESULT_CODE_* if positive or 0,
340 : * errno value if negative.
341 : */
342 1 : int bt_tbs_join(uint8_t call_index_cnt, uint8_t *call_indexes);
343 :
344 : /**
345 : * @brief Notify the server that the remote party answered the call.
346 : *
347 : * @param call_index The index of the call that was answered.
348 : *
349 : * @return int BT_TBS_RESULT_CODE_* if positive or 0,
350 : * errno value if negative.
351 : */
352 1 : int bt_tbs_remote_answer(uint8_t call_index);
353 :
354 : /**
355 : * @brief Notify the server that the remote party held the call.
356 : *
357 : * @param call_index The index of the call that was held.
358 : *
359 : * @return int BT_TBS_RESULT_CODE_* if positive or 0,
360 : * errno value if negative.
361 : */
362 1 : int bt_tbs_remote_hold(uint8_t call_index);
363 :
364 : /**
365 : * @brief Notify the server that the remote party retrieved the call.
366 : *
367 : * @param call_index The index of the call that was retrieved.
368 : *
369 : * @return int BT_TBS_RESULT_CODE_* if positive or 0,
370 : * errno value if negative.
371 : */
372 1 : int bt_tbs_remote_retrieve(uint8_t call_index);
373 :
374 : /**
375 : * @brief Notify the server that the remote party terminated the call.
376 : *
377 : * @param call_index The index of the call that was terminated.
378 : *
379 : * @return int BT_TBS_RESULT_CODE_* if positive or 0,
380 : * errno value if negative.
381 : */
382 1 : int bt_tbs_remote_terminate(uint8_t call_index);
383 :
384 : /**
385 : * @brief Notify the server of an incoming call.
386 : *
387 : * @param bearer_index The index of the Telephone Bearer.
388 : * @param to The URI that is receiving the call.
389 : * @param from The URI of the remote caller.
390 : * @param friendly_name The friendly name of the remote caller.
391 : *
392 : * @return int New call index if positive or 0,
393 : * errno value if negative.
394 : */
395 1 : int bt_tbs_remote_incoming(uint8_t bearer_index, const char *to,
396 : const char *from, const char *friendly_name);
397 :
398 : /**
399 : * @brief Set a new bearer provider.
400 : *
401 : * @param bearer_index The index of the Telephone Bearer or BT_TBS_GTBS_INDEX
402 : * for GTBS.
403 : * @param name The new bearer provider name.
404 : *
405 : * @return int BT_TBS_RESULT_CODE_* if positive or 0,
406 : * errno value if negative.
407 : */
408 1 : int bt_tbs_set_bearer_provider_name(uint8_t bearer_index, const char *name);
409 :
410 : /**
411 : * @brief Set a new bearer technology.
412 : *
413 : * @param bearer_index The index of the Telephone Bearer or BT_TBS_GTBS_INDEX
414 : * for GTBS.
415 : * @param new_technology The new bearer technology.
416 : *
417 : * @return int BT_TBS_RESULT_CODE_* if positive or 0,
418 : * errno value if negative.
419 : */
420 1 : int bt_tbs_set_bearer_technology(uint8_t bearer_index, uint8_t new_technology);
421 :
422 : /**
423 : * @brief Update the signal strength reported by the server.
424 : *
425 : * @param bearer_index The index of the Telephone Bearer or
426 : * BT_TBS_GTBS_INDEX for GTBS.
427 : * @param new_signal_strength The new signal strength.
428 : *
429 : * @return int BT_TBS_RESULT_CODE_* if positive or 0,
430 : * errno value if negative.
431 : */
432 1 : int bt_tbs_set_signal_strength(uint8_t bearer_index,
433 : uint8_t new_signal_strength);
434 :
435 : /**
436 : * @brief Sets the feature and status value.
437 : *
438 : * @param bearer_index The index of the Telephone Bearer or BT_TBS_GTBS_INDEX
439 : * for GTBS.
440 : * @param status_flags The new feature and status value.
441 : *
442 : * @return int BT_TBS_RESULT_CODE_* if positive or 0,
443 : * errno value if negative.
444 : */
445 1 : int bt_tbs_set_status_flags(uint8_t bearer_index, uint16_t status_flags);
446 :
447 : /**
448 : * @brief Sets the URI scheme list of a bearer.
449 : *
450 : * @param bearer_index The index of the Telephone Bearer.
451 : * @param uri_list List of URI prefixes (e.g. {"skype", "tel"}).
452 : * @param uri_count Number of URI prefixies in @p uri_list.
453 : *
454 : * @return BT_TBS_RESULT_CODE_* if positive or 0, errno value if negative.
455 : */
456 1 : int bt_tbs_set_uri_scheme_list(uint8_t bearer_index, const char **uri_list,
457 : uint8_t uri_count);
458 : /**
459 : * @brief Register the callbacks for TBS.
460 : *
461 : * @param cbs Pointer to the callback structure.
462 : */
463 1 : void bt_tbs_register_cb(struct bt_tbs_cb *cbs);
464 :
465 0 : struct bt_tbs_register_param {
466 : /** The name of the provider, for example a cellular service provider */
467 1 : char *provider_name;
468 :
469 : /**
470 : * @brief The Uniform Caller Identifier of the bearer
471 : *
472 : * See the Uniform Caller Identifiers table in Bluetooth Assigned Numbers
473 : */
474 1 : char *uci;
475 :
476 : /**
477 : * The Uniform Resource Identifiers schemes supported by this bearer as an UTF-8 string
478 : *
479 : * See https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml for possible values.
480 : * If multiple values are used, these shall be comma separated, e.g. "tel,skype".
481 : */
482 1 : char *uri_schemes_supported;
483 :
484 : /**
485 : * @brief Whether this bearer shall be registered as a Generic Telephone Bearer server
486 : *
487 : * A GTBS shall be registered before any non-GTBS services. There can only be a single GTBS
488 : * registered.
489 : */
490 1 : bool gtbs;
491 :
492 : /**
493 : * @brief Whether the application will need to authorize changes to calls
494 : *
495 : * If set to false then the service will automatically accept write requests from clients.
496 : */
497 1 : bool authorization_required;
498 :
499 : /**
500 : * @brief The technology of the bearer
501 : *
502 : * See the BT_TBS_TECHNOLOGY_* values.
503 : */
504 1 : uint8_t technology;
505 :
506 : /**
507 : * @brief The optional supported features of the bearer
508 : *
509 : * See the BT_TBS_FEATURE_* values.
510 : */
511 1 : uint8_t supported_features;
512 : };
513 :
514 : /**
515 : * @brief Register a Telephone Bearer
516 : *
517 : * This will register a Telephone Bearer Service (TBS) (or a Generic Telephone Bearer service
518 : * (GTBS)) with the provided parameters.
519 : *
520 : * As per the TBS specification, the GTBS shall be instantiated for the feature, and as such a GTBS
521 : * shall always be registered before any TBS can be registered.
522 : * Similarly, all TBS shall be unregistered before the GTBS can be unregistered with
523 : * bt_tbs_unregister_bearer().
524 : *
525 : * @param param The parameters to initialize the bearer.
526 :
527 : * @retval index The bearer index if return value is >= 0
528 : * @retval -EINVAL @p param contains invalid data
529 : * @retval -EALREADY @p param.gtbs is true and GTBS has already been registered
530 : * @retval -EAGAIN @p param.gtbs is false and GTBS has not been registered
531 : * @retval -ENOMEM @p param.gtbs is false and no more TBS can be registered (see
532 : * @kconfig{CONFIG_BT_TBS_BEARER_COUNT})
533 : * @retval -ENOEXEC The service failed to be registered
534 : */
535 1 : int bt_tbs_register_bearer(const struct bt_tbs_register_param *param);
536 :
537 : /**
538 : * @brief Unregister a Telephone Bearer
539 : *
540 : * This will unregister a Telephone Bearer Service (TBS) (or a Generic Telephone Bearer service
541 : * (GTBS)) with the provided parameters. The bearer shall be registered first by
542 : * bt_tbs_register_bearer() before it can be unregistered.
543 : *
544 : * Similarly, all TBS shall be unregistered before the GTBS can be unregistered with.
545 : *
546 : * @param bearer_index The index of the bearer to unregister.
547 : *
548 : * @retval 0 Success
549 : * @retval -EINVAL @p bearer_index is invalid
550 : * @retval -EALREADY The bearer identified by @p bearer_index is not registered
551 : * @retval -EAGAIN The bearer identified by @p bearer_index is GTBS and there are TBS instances
552 : * registered.
553 : * @retval -ENOEXEC The service failed to be unregistered
554 : */
555 1 : int bt_tbs_unregister_bearer(uint8_t bearer_index);
556 :
557 : /** @brief Prints all calls of all services to the debug log */
558 1 : void bt_tbs_dbg_print_calls(void);
559 :
560 : /** Struct to hold a call state */
561 1 : struct bt_tbs_client_call_state {
562 : /** Index of the call */
563 1 : uint8_t index;
564 : /** State of the call (see BT_TBS_CALL_STATE_*) */
565 1 : uint8_t state;
566 : /** Call flags (see BT_TBS_CALL_FLAG_*) */
567 1 : uint8_t flags;
568 : } __packed;
569 :
570 : /** Struct to hold a call as the Telephone Bearer Service client */
571 1 : struct bt_tbs_client_call {
572 : /** Call information */
573 1 : struct bt_tbs_client_call_state call_info;
574 : /** The remove URI */
575 1 : char *remote_uri;
576 : };
577 :
578 : /**
579 : * @brief Callback function for ccp_discover.
580 : *
581 : * @param conn The connection that was used to discover CCP for a
582 : * device.
583 : * @param err Error value. BT_TBS_CLIENT_RESULT_CODE_*,
584 : * GATT error or errno value.
585 : * @param tbs_count Number of TBS instances on peer device.
586 : * @param gtbs_found Whether or not the server has a Generic TBS instance.
587 : */
588 1 : typedef void (*bt_tbs_client_discover_cb)(struct bt_conn *conn, int err,
589 : uint8_t tbs_count, bool gtbs_found);
590 :
591 : /**
592 : * @brief Callback function for writing values to peer device.
593 : *
594 : * @param conn The connection used in the function.
595 : * @param err Error value. BT_TBS_CLIENT_RESULT_CODE_*,
596 : * GATT error or errno value.
597 : * @param inst_index The index of the TBS instance that was updated.
598 : */
599 1 : typedef void (*bt_tbs_client_write_value_cb)(struct bt_conn *conn, int err,
600 : uint8_t inst_index);
601 :
602 : /**
603 : * @brief Callback function for the CCP call control functions.
604 : *
605 : * @param conn The connection used in the function.
606 : * @param err Error value. BT_TBS_CLIENT_RESULT_CODE_*,
607 : * GATT error or errno value.
608 : * @param inst_index The index of the TBS instance that was updated.
609 : * @param call_index The call index. For #bt_tbs_client_originate_call this will
610 : * always be 0, and does not reflect the actual call index.
611 : */
612 1 : typedef void (*bt_tbs_client_cp_cb)(struct bt_conn *conn, int err,
613 : uint8_t inst_index, uint8_t call_index);
614 :
615 : /**
616 : * @brief Callback function for functions that read a string value.
617 : *
618 : * @param conn The connection used in the function.
619 : * @param err Error value. BT_TBS_CLIENT_RESULT_CODE_*,
620 : * GATT error or errno value.
621 : * @param inst_index The index of the TBS instance that was updated.
622 : * @param value The Null-terminated string value. The value is not kept
623 : * by the client, so must be copied to be saved.
624 : */
625 1 : typedef void (*bt_tbs_client_read_string_cb)(struct bt_conn *conn, int err,
626 : uint8_t inst_index,
627 : const char *value);
628 :
629 : /**
630 : * @brief Callback function for functions that read an integer value.
631 : *
632 : * @param conn The connection used in the function.
633 : * @param err Error value. BT_TBS_CLIENT_RESULT_CODE_*,
634 : * GATT error or errno value.
635 : * @param inst_index The index of the TBS instance that was updated.
636 : * @param value The integer value.
637 : */
638 1 : typedef void (*bt_tbs_client_read_value_cb)(struct bt_conn *conn, int err,
639 : uint8_t inst_index, uint32_t value);
640 :
641 : /**
642 : * @brief Callback function for ccp_read_termination_reason.
643 : *
644 : * @param conn The connection used in the function.
645 : * @param err Error value. BT_TBS_CLIENT_RESULT_CODE_*,
646 : * GATT error or errno value.
647 : * @param inst_index The index of the TBS instance that was updated.
648 : * @param call_index The call index.
649 : * @param reason The termination reason.
650 : */
651 1 : typedef void (*bt_tbs_client_termination_reason_cb)(struct bt_conn *conn,
652 : int err, uint8_t inst_index,
653 : uint8_t call_index,
654 : uint8_t reason);
655 :
656 : /**
657 : * @brief Callback function for ccp_read_current_calls.
658 : *
659 : * @param conn The connection used in the function.
660 : * @param err Error value. BT_TBS_CLIENT_RESULT_CODE_*,
661 : * GATT error or errno value.
662 : * @param inst_index The index of the TBS instance that was updated.
663 : * @param call_count Number of calls read.
664 : * @param calls Array of calls. The array is not kept by
665 : * the client, so must be copied to be saved.
666 : */
667 1 : typedef void (*bt_tbs_client_current_calls_cb)(struct bt_conn *conn, int err,
668 : uint8_t inst_index,
669 : uint8_t call_count,
670 : const struct bt_tbs_client_call *calls);
671 :
672 : /**
673 : * @brief Callback function for ccp_read_call_state.
674 : *
675 : * @param conn The connection used in the function.
676 : * @param err Error value. BT_TBS_CLIENT_RESULT_CODE_*,
677 : * GATT error or errno value.
678 : * @param inst_index The index of the TBS instance that was updated.
679 : * @param call_count Number of call states read.
680 : * @param call_states Array of call states. The array is not kept by
681 : * the client, so must be copied to be saved.
682 : */
683 1 : typedef void (*bt_tbs_client_call_states_cb)(struct bt_conn *conn, int err,
684 : uint8_t inst_index,
685 : uint8_t call_count,
686 : const struct bt_tbs_client_call_state *call_states);
687 :
688 : /**
689 : * @brief Struct to hold the Telephone Bearer Service client callbacks
690 : *
691 : * These can be registered for usage with bt_tbs_client_register_cb().
692 : */
693 1 : struct bt_tbs_client_cb {
694 : /** Discovery has completed */
695 1 : bt_tbs_client_discover_cb discover;
696 : #if defined(CONFIG_BT_TBS_CLIENT_ORIGINATE_CALL) || defined(__DOXYGEN__)
697 : /** Originate call has completed */
698 1 : bt_tbs_client_cp_cb originate_call;
699 : #endif /* defined(CONFIG_BT_TBS_CLIENT_ORIGINATE_CALL) */
700 : #if defined(CONFIG_BT_TBS_CLIENT_TERMINATE_CALL) || defined(__DOXYGEN__)
701 : /** Terminate call has completed */
702 1 : bt_tbs_client_cp_cb terminate_call;
703 : #endif /* defined(CONFIG_BT_TBS_CLIENT_TERMINATE_CALL) */
704 : #if defined(CONFIG_BT_TBS_CLIENT_HOLD_CALL) || defined(__DOXYGEN__)
705 : /** Hold call has completed */
706 1 : bt_tbs_client_cp_cb hold_call;
707 : #endif /* defined(CONFIG_BT_TBS_CLIENT_HOLD_CALL) */
708 : #if defined(CONFIG_BT_TBS_CLIENT_ACCEPT_CALL) || defined(__DOXYGEN__)
709 : /** Accept call has completed */
710 1 : bt_tbs_client_cp_cb accept_call;
711 : #endif /* defined(CONFIG_BT_TBS_CLIENT_ACCEPT_CALL) */
712 : #if defined(CONFIG_BT_TBS_CLIENT_RETRIEVE_CALL) || defined(__DOXYGEN__)
713 : /** Retrieve call has completed */
714 1 : bt_tbs_client_cp_cb retrieve_call;
715 : #endif /* defined(CONFIG_BT_TBS_CLIENT_RETRIEVE_CALL) */
716 : #if defined(CONFIG_BT_TBS_CLIENT_JOIN_CALLS) || defined(__DOXYGEN__)
717 : /** Join calls has completed */
718 1 : bt_tbs_client_cp_cb join_calls;
719 : #endif /* defined(CONFIG_BT_TBS_CLIENT_JOIN_CALLS) */
720 : #if defined(CONFIG_BT_TBS_CLIENT_BEARER_PROVIDER_NAME) || defined(__DOXYGEN__)
721 : /** Bearer provider name has been read */
722 1 : bt_tbs_client_read_string_cb bearer_provider_name;
723 : #endif /* defined(CONFIG_BT_TBS_CLIENT_BEARER_PROVIDER_NAME) */
724 : #if defined(CONFIG_BT_TBS_CLIENT_BEARER_UCI) || defined(__DOXYGEN__)
725 : /** Bearer UCI has been read */
726 1 : bt_tbs_client_read_string_cb bearer_uci;
727 : #endif /* defined(CONFIG_BT_TBS_CLIENT_BEARER_UCI) */
728 : #if defined(CONFIG_BT_TBS_CLIENT_BEARER_TECHNOLOGY) || defined(__DOXYGEN__)
729 : /** Bearer technology has been read */
730 1 : bt_tbs_client_read_value_cb technology;
731 : #endif /* defined(CONFIG_BT_TBS_CLIENT_BEARER_TECHNOLOGY) */
732 : #if defined(CONFIG_BT_TBS_CLIENT_BEARER_URI_SCHEMES_SUPPORTED_LIST) || defined(__DOXYGEN__)
733 : /** Bearer URI list has been read */
734 1 : bt_tbs_client_read_string_cb uri_list;
735 : #endif /* defined(CONFIG_BT_TBS_CLIENT_BEARER_URI_SCHEMES_SUPPORTED_LIST) */
736 : #if defined(CONFIG_BT_TBS_CLIENT_BEARER_SIGNAL_STRENGTH) || defined(__DOXYGEN__)
737 : /** Bearer signal strength has been read */
738 1 : bt_tbs_client_read_value_cb signal_strength;
739 : #endif /* defined(CONFIG_BT_TBS_CLIENT_BEARER_SIGNAL_STRENGTH) */
740 : #if defined(CONFIG_BT_TBS_CLIENT_READ_BEARER_SIGNAL_INTERVAL) || defined(__DOXYGEN__)
741 : /** Bearer signal interval has been read */
742 1 : bt_tbs_client_read_value_cb signal_interval;
743 : #endif /* defined(CONFIG_BT_TBS_CLIENT_READ_BEARER_SIGNAL_INTERVAL) */
744 : #if defined(CONFIG_BT_TBS_CLIENT_BEARER_LIST_CURRENT_CALLS) || defined(__DOXYGEN__)
745 : /** Bearer current calls has been read */
746 1 : bt_tbs_client_current_calls_cb current_calls;
747 : #endif /* defined(CONFIG_BT_TBS_CLIENT_BEARER_LIST_CURRENT_CALLS) */
748 : #if defined(CONFIG_BT_TBS_CLIENT_CCID) || defined(__DOXYGEN__)
749 : /** Bearer CCID has been read */
750 1 : bt_tbs_client_read_value_cb ccid;
751 : #endif /* defined(CONFIG_BT_TBS_CLIENT_CCID) */
752 : #if defined(CONFIG_BT_TBS_CLIENT_INCOMING_URI) || defined(__DOXYGEN__)
753 : /** Bearer call URI has been read */
754 1 : bt_tbs_client_read_string_cb call_uri;
755 : #endif /* defined(CONFIG_BT_TBS_CLIENT_INCOMING_URI) */
756 : #if defined(CONFIG_BT_TBS_CLIENT_STATUS_FLAGS) || defined(__DOXYGEN__)
757 : /** Bearer status flags has been read */
758 1 : bt_tbs_client_read_value_cb status_flags;
759 : #endif /* defined(CONFIG_BT_TBS_CLIENT_STATUS_FLAGS) */
760 : /** Bearer call states has been read */
761 1 : bt_tbs_client_call_states_cb call_state;
762 : #if defined(CONFIG_BT_TBS_CLIENT_OPTIONAL_OPCODES) || defined(__DOXYGEN__)
763 : /** Bearer optional opcodes has been read */
764 1 : bt_tbs_client_read_value_cb optional_opcodes;
765 : #endif /* defined(CONFIG_BT_TBS_CLIENT_OPTIONAL_OPCODES) */
766 : /** Bearer terminate reason has been read */
767 1 : bt_tbs_client_termination_reason_cb termination_reason;
768 : #if defined(CONFIG_BT_TBS_CLIENT_INCOMING_CALL) || defined(__DOXYGEN__)
769 : /** Bearer remote URI has been read */
770 1 : bt_tbs_client_read_string_cb remote_uri;
771 : #endif /* defined(CONFIG_BT_TBS_CLIENT_INCOMING_CALL) */
772 : #if defined(CONFIG_BT_TBS_CLIENT_CALL_FRIENDLY_NAME) || defined(__DOXYGEN__)
773 : /** Bearer friendly name has been read */
774 1 : bt_tbs_client_read_string_cb friendly_name;
775 : #endif /* defined(CONFIG_BT_TBS_CLIENT_CALL_FRIENDLY_NAME) */
776 :
777 : /** @internal Internally used field for list handling */
778 : sys_snode_t _node;
779 : };
780 :
781 : /**
782 : * @brief Discover TBS for a connection. This will start a GATT
783 : * discover and setup handles and subscriptions.
784 : *
785 : * @param conn The connection to discover TBS for.
786 : *
787 : * @return int 0 on success, GATT error value on fail.
788 : */
789 1 : int bt_tbs_client_discover(struct bt_conn *conn);
790 :
791 : /**
792 : * @brief Set the outgoing URI for a TBS instance on the peer device.
793 : *
794 : * @param conn The connection to the TBS server.
795 : * @param inst_index The index of the TBS instance.
796 : * @param uri The Null-terminated URI string.
797 : *
798 : * @return int 0 on success, errno value on fail.
799 : */
800 1 : int bt_tbs_client_set_outgoing_uri(struct bt_conn *conn, uint8_t inst_index,
801 : const char *uri);
802 :
803 : /**
804 : * @brief Set the signal strength reporting interval for a TBS instance.
805 : *
806 : * @param conn The connection to the TBS server.
807 : * @param inst_index The index of the TBS instance.
808 : * @param interval The interval to write (0-255 seconds).
809 : *
810 : * @return int 0 on success, errno value on fail.
811 : *
812 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_SET_BEARER_SIGNAL_INTERVAL} must be set
813 : * for this function to be effective.
814 : */
815 1 : int bt_tbs_client_set_signal_strength_interval(struct bt_conn *conn,
816 : uint8_t inst_index,
817 : uint8_t interval);
818 :
819 : /**
820 : * @brief Request to originate a call.
821 : *
822 : * @param conn The connection to the TBS server.
823 : * @param inst_index The index of the TBS instance.
824 : * @param uri The URI of the callee.
825 : *
826 : * @return int 0 on success, errno value on fail.
827 : *
828 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_ORIGINATE_CALL} must be set
829 : * for this function to be effective.
830 : */
831 1 : int bt_tbs_client_originate_call(struct bt_conn *conn, uint8_t inst_index,
832 : const char *uri);
833 :
834 : /**
835 : * @brief Request to terminate a call
836 : *
837 : * @param conn The connection to the TBS server.
838 : * @param inst_index The index of the TBS instance.
839 : * @param call_index The call index to terminate.
840 : *
841 : * @return int 0 on success, errno value on fail.
842 : *
843 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_TERMINATE_CALL} must be set
844 : * for this function to be effective.
845 : */
846 1 : int bt_tbs_client_terminate_call(struct bt_conn *conn, uint8_t inst_index,
847 : uint8_t call_index);
848 :
849 : /**
850 : * @brief Request to hold a call
851 : *
852 : * @param conn The connection to the TBS server.
853 : * @param inst_index The index of the TBS instance.
854 : * @param call_index The call index to place on hold.
855 : *
856 : * @return int 0 on success, errno value on fail.
857 : *
858 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_HOLD_CALL} must be set
859 : * for this function to be effective.
860 : */
861 1 : int bt_tbs_client_hold_call(struct bt_conn *conn, uint8_t inst_index,
862 : uint8_t call_index);
863 :
864 : /**
865 : * @brief Accept an incoming call
866 : *
867 : * @param conn The connection to the TBS server.
868 : * @param inst_index The index of the TBS instance.
869 : * @param call_index The call index to accept.
870 : *
871 : * @return int 0 on success, errno value on fail.
872 : *
873 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_ACCEPT_CALL} must be set
874 : * for this function to be effective.
875 : */
876 1 : int bt_tbs_client_accept_call(struct bt_conn *conn, uint8_t inst_index,
877 : uint8_t call_index);
878 :
879 : /**
880 : * @brief Retrieve call from (local) hold.
881 : *
882 : * @param conn The connection to the TBS server.
883 : * @param inst_index The index of the TBS instance.
884 : * @param call_index The call index to retrieve.
885 : *
886 : * @return int 0 on success, errno value on fail.
887 : *
888 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_RETRIEVE_CALL} must be set
889 : * for this function to be effective.
890 : */
891 1 : int bt_tbs_client_retrieve_call(struct bt_conn *conn, uint8_t inst_index,
892 : uint8_t call_index);
893 :
894 : /**
895 : * @brief Join multiple calls.
896 : *
897 : * @param conn The connection to the TBS server.
898 : * @param inst_index The index of the TBS instance.
899 : * @param call_indexes Array of call indexes.
900 : * @param count Number of call indexes in the call_indexes array.
901 : *
902 : * @return int 0 on success, errno value on fail.
903 : *
904 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_JOIN_CALLS} must be set
905 : * for this function to be effective.
906 : */
907 1 : int bt_tbs_client_join_calls(struct bt_conn *conn, uint8_t inst_index,
908 : const uint8_t *call_indexes, uint8_t count);
909 :
910 : /**
911 : * @brief Read the bearer provider name of a TBS instance.
912 : *
913 : * @param conn The connection to the TBS server.
914 : * @param inst_index The index of the TBS instance.
915 : *
916 : * @return int 0 on success, errno value on fail.
917 : *
918 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_BEARER_PROVIDER_NAME} must be set
919 : * for this function to be effective.
920 : */
921 1 : int bt_tbs_client_read_bearer_provider_name(struct bt_conn *conn,
922 : uint8_t inst_index);
923 :
924 : /**
925 : * @brief Read the UCI of a TBS instance.
926 : *
927 : * @param conn The connection to the TBS server.
928 : * @param inst_index The index of the TBS instance.
929 : *
930 : * @return int 0 on success, errno value on fail.
931 : *
932 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_BEARER_UCI} must be set
933 : * for this function to be effective.
934 : */
935 1 : int bt_tbs_client_read_bearer_uci(struct bt_conn *conn, uint8_t inst_index);
936 :
937 : /**
938 : * @brief Read the technology of a TBS instance.
939 : *
940 : * @param conn The connection to the TBS server.
941 : * @param inst_index The index of the TBS instance.
942 : *
943 : * @return int 0 on success, errno value on fail.
944 : *
945 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_BEARER_TECHNOLOGY} must be set
946 : * for this function to be effective.
947 : */
948 1 : int bt_tbs_client_read_technology(struct bt_conn *conn, uint8_t inst_index);
949 :
950 : /**
951 : * @brief Read the URI schemes list of a TBS instance.
952 : *
953 : * @param conn The connection to the TBS server.
954 : * @param inst_index The index of the TBS instance.
955 : *
956 : * @return int 0 on success, errno value on fail.
957 : *
958 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_BEARER_URI_SCHEMES_SUPPORTED_LIST} must be set
959 : * for this function to be effective.
960 : */
961 1 : int bt_tbs_client_read_uri_list(struct bt_conn *conn, uint8_t inst_index);
962 :
963 : /**
964 : * @brief Read the current signal strength of a TBS instance.
965 : *
966 : * @param conn The connection to the TBS server.
967 : * @param inst_index The index of the TBS instance.
968 : *
969 : * @return int 0 on success, errno value on fail.
970 : *
971 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_BEARER_SIGNAL_STRENGTH} must be set
972 : * for this function to be effective.
973 : */
974 1 : int bt_tbs_client_read_signal_strength(struct bt_conn *conn,
975 : uint8_t inst_index);
976 :
977 : /**
978 : * @brief Read the signal strength reporting interval of a TBS instance.
979 : *
980 : * @param conn The connection to the TBS server.
981 : * @param inst_index The index of the TBS instance.
982 : *
983 : * @return int 0 on success, errno value on fail.
984 : *
985 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_READ_BEARER_SIGNAL_INTERVAL} must be set
986 : * for this function to be effective.
987 : */
988 1 : int bt_tbs_client_read_signal_interval(struct bt_conn *conn,
989 : uint8_t inst_index);
990 :
991 : /**
992 : * @brief Read the list of current calls of a TBS instance.
993 : *
994 : * @param conn The connection to the TBS server.
995 : * @param inst_index The index of the TBS instance.
996 : *
997 : * @return int 0 on success, errno value on fail.
998 : *
999 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_BEARER_LIST_CURRENT_CALLS} must be set
1000 : * for this function to be effective.
1001 : */
1002 1 : int bt_tbs_client_read_current_calls(struct bt_conn *conn, uint8_t inst_index);
1003 :
1004 : /**
1005 : * @brief Read the content ID of a TBS instance.
1006 : *
1007 : * @param conn The connection to the TBS server.
1008 : * @param inst_index The index of the TBS instance.
1009 : *
1010 : * @return int 0 on success, errno value on fail.
1011 : *
1012 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_CCID} must be set
1013 : * for this function to be effective.
1014 : */
1015 1 : int bt_tbs_client_read_ccid(struct bt_conn *conn, uint8_t inst_index);
1016 :
1017 : /**
1018 : * @brief Read the call target URI of a TBS instance.
1019 : *
1020 : * @param conn The connection to the TBS server.
1021 : * @param inst_index The index of the TBS instance.
1022 : *
1023 : * @return int 0 on success, errno value on fail.
1024 : *
1025 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_INCOMING_URI} must be set
1026 : * for this function to be effective.
1027 : */
1028 1 : int bt_tbs_client_read_call_uri(struct bt_conn *conn, uint8_t inst_index);
1029 :
1030 : /**
1031 : * @brief Read the feature and status value of a TBS instance.
1032 : *
1033 : * @param conn The connection to the TBS server.
1034 : * @param inst_index The index of the TBS instance.
1035 : *
1036 : * @return int 0 on success, errno value on fail.
1037 : *
1038 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_STATUS_FLAGS} must be set
1039 : * for this function to be effective.
1040 : */
1041 1 : int bt_tbs_client_read_status_flags(struct bt_conn *conn, uint8_t inst_index);
1042 :
1043 : /**
1044 : * @brief Read the states of the current calls of a TBS instance.
1045 : *
1046 : * @param conn The connection to the TBS server.
1047 : * @param inst_index The index of the TBS instance.
1048 : *
1049 : * @return int 0 on success, errno value on fail.
1050 : */
1051 1 : int bt_tbs_client_read_call_state(struct bt_conn *conn, uint8_t inst_index);
1052 :
1053 : /**
1054 : * @brief Read the remote URI of a TBS instance.
1055 : *
1056 : * @param conn The connection to the TBS server.
1057 : * @param inst_index The index of the TBS instance.
1058 : *
1059 : * @return int 0 on success, errno value on fail.
1060 : *
1061 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_INCOMING_CALL} must be set
1062 : * for this function to be effective.
1063 : */
1064 1 : int bt_tbs_client_read_remote_uri(struct bt_conn *conn, uint8_t inst_index);
1065 :
1066 : /**
1067 : * @brief Read the friendly name of a call for a TBS instance.
1068 : *
1069 : * @param conn The connection to the TBS server.
1070 : * @param inst_index The index of the TBS instance.
1071 : *
1072 : * @return int 0 on success, errno value on fail.
1073 : *
1074 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_CALL_FRIENDLY_NAME} must be set
1075 : * for this function to be effective.
1076 : */
1077 1 : int bt_tbs_client_read_friendly_name(struct bt_conn *conn, uint8_t inst_index);
1078 :
1079 : /**
1080 : * @brief Read the supported opcode of a TBS instance.
1081 : *
1082 : * @param conn The connection to the TBS server.
1083 : * @param inst_index The index of the TBS instance.
1084 : *
1085 : * @return int 0 on success, errno value on fail.
1086 : *
1087 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_OPTIONAL_OPCODES} must be set
1088 : * for this function to be effective.
1089 : */
1090 1 : int bt_tbs_client_read_optional_opcodes(struct bt_conn *conn,
1091 : uint8_t inst_index);
1092 :
1093 : /**
1094 : * @brief Register the callbacks for CCP.
1095 : *
1096 : * @param cbs Pointer to the callback structure.
1097 : *
1098 : * @retval 0 Success
1099 : * @retval -EINVAL @p cbs is NULL
1100 : * @retval -EEXIST @p cbs is already registered
1101 : */
1102 1 : int bt_tbs_client_register_cb(struct bt_tbs_client_cb *cbs);
1103 :
1104 : /**
1105 : * @brief Look up Telephone Bearer Service instance by CCID
1106 : *
1107 : * @param conn The connection to the TBS server.
1108 : * @param ccid The CCID to lookup a service instance for.
1109 : *
1110 : * @return Pointer to a Telephone Bearer Service instance if found else NULL.
1111 : *
1112 : * @note @kconfig{CONFIG_BT_TBS_CLIENT_CCID} must be set
1113 : * for this function to be effective.
1114 : */
1115 1 : struct bt_tbs_instance *bt_tbs_client_get_by_ccid(const struct bt_conn *conn,
1116 : uint8_t ccid);
1117 :
1118 : #ifdef __cplusplus
1119 : }
1120 : #endif
1121 :
1122 : /** @} */
1123 :
1124 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_TBS_H_ */
|
