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