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 #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 #define BT_TBS_CALL_STATE_DIALING 0x01 51 /** A remote party is being alerted (outgoing call). */ 52 #define BT_TBS_CALL_STATE_ALERTING 0x02 53 /** The call is in an active conversation. */ 54 #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 #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 #define BT_TBS_CALL_STATE_REMOTELY_HELD 0x05 65 /** The call is connected but held both locally and remotely. */ 66 #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 #define BT_TBS_REASON_BAD_REMOTE_URI 0x00 75 /** The call failed. */ 76 #define BT_TBS_REASON_CALL_FAILED 0x01 77 /** The remote party ended the call. */ 78 #define BT_TBS_REASON_REMOTE_ENDED_CALL 0x02 79 /** The call ended from the server. */ 80 #define BT_TBS_REASON_SERVER_ENDED_CALL 0x03 81 /** The line was busy. */ 82 #define BT_TBS_REASON_LINE_BUSY 0x04 83 /** Network congestion. */ 84 #define BT_TBS_REASON_NETWORK_CONGESTED 0x05 85 /** The client terminated the call. */ 86 #define BT_TBS_REASON_CLIENT_TERMINATED 0x06 87 /** No service. */ 88 #define BT_TBS_REASON_NO_SERVICE 0x07 89 /** No answer. */ 90 #define BT_TBS_REASON_NO_ANSWER 0x08 91 /** Unspecified. */ 92 #define BT_TBS_REASON_UNSPECIFIED 0x09 93 /** @} */ 94 95 /** 96 * @name Control point error codes 97 * @{ 98 */ 99 /** The opcode write was successful. */ 100 #define BT_TBS_RESULT_CODE_SUCCESS 0x00 101 /** An invalid opcode was used for the Call Control Point write. */ 102 #define BT_TBS_RESULT_CODE_OPCODE_NOT_SUPPORTED 0x01 103 /** The requested operation cannot be completed. */ 104 #define BT_TBS_RESULT_CODE_OPERATION_NOT_POSSIBLE 0x02 105 /** The Call Index used for the Call Control Point write is invalid. */ 106 #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 #define BT_TBS_RESULT_CODE_STATE_MISMATCH 0x04 112 /** Lack of internal resources to complete the requested action. */ 113 #define BT_TBS_RESULT_CODE_OUT_OF_RESOURCES 0x05 114 /** The Outgoing URI is incorrect or invalid when an Originate opcode is sent. */ 115 #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 #define BT_TBS_FEATURE_HOLD BIT(0) 127 /** Join Call Control Point Opcode supported */ 128 #define BT_TBS_FEATURE_JOIN BIT(1) 129 /** All Control Point Opcodes supported */ 130 #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 #define BT_TBS_SIGNAL_STRENGTH_NO_SERVICE 0 139 /** Maximum signal strength */ 140 #define BT_TBS_SIGNAL_STRENGTH_MAX 100 141 /** Signal strength is unknown */ 142 #define BT_TBS_SIGNAL_STRENGTH_UNKNOWN 255 143 /** @} */ 144 145 /** 146 * @name Bearer Technology 147 * @{ 148 */ 149 /** 3G */ 150 #define BT_TBS_TECHNOLOGY_3G 0x01 151 /** 4G */ 152 #define BT_TBS_TECHNOLOGY_4G 0x02 153 /** Long-term evolution (LTE) */ 154 #define BT_TBS_TECHNOLOGY_LTE 0x03 155 /** Wifi */ 156 #define BT_TBS_TECHNOLOGY_WIFI 0x04 157 /** 5G */ 158 #define BT_TBS_TECHNOLOGY_5G 0x05 159 /** Global System for Mobile Communications (GSM) */ 160 #define BT_TBS_TECHNOLOGY_GSM 0x06 161 /** Code-Division Multiple Access (CDMA) */ 162 #define BT_TBS_TECHNOLOGY_CDMA 0x07 163 /** 2G */ 164 #define BT_TBS_TECHNOLOGY_2G 0x08 165 /** Wideband Code-Division Multiple Access (WCDMA) */ 166 #define BT_TBS_TECHNOLOGY_WCDMA 0x09 167 /** @} */ 168 169 /** 170 * @name Call status flags bitfield 171 * @{ 172 */ 173 /** Inband ringtone enabled */ 174 #define BT_TBS_STATUS_FLAG_INBAND_RINGTONE BIT(0) 175 /** Server is in silent mod */ 176 #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 #define BT_TBS_CALL_FLAG_OUTGOING BIT(0) 185 /** If set call is withheld, else not withheld */ 186 #define BT_TBS_CALL_FLAG_WITHHELD BIT(1) 187 /** If set call is withheld by network, else provided by network */ 188 #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 #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 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 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 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 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 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 struct bt_tbs_cb { 264 /** Client originating call */ 265 bt_tbs_originate_call_cb originate_call; 266 /** Client terminating call */ 267 bt_tbs_terminate_call_cb terminate_call; 268 /** Client holding call */ 269 bt_tbs_call_change_cb hold_call; 270 /** Client accepting call */ 271 bt_tbs_call_change_cb accept_call; 272 /** Client retrieving call */ 273 bt_tbs_call_change_cb retrieve_call; 274 /** Client joining calls */ 275 bt_tbs_join_calls_cb join_calls; 276 /** Callback to authorize a client */ 277 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 void bt_tbs_register_cb(struct bt_tbs_cb *cbs); 464 465 /** Parameters for registering a Telephone Bearer Service */ 466 struct bt_tbs_register_param { 467 /** The name of the provider, for example a cellular service provider */ 468 char *provider_name; 469 470 /** 471 * @brief The Uniform Caller Identifier of the bearer 472 * 473 * See the Uniform Caller Identifiers table in Bluetooth Assigned Numbers 474 */ 475 char *uci; 476 477 /** 478 * The Uniform Resource Identifiers schemes supported by this bearer as an UTF-8 string 479 * 480 * See https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml for possible values. 481 * If multiple values are used, these shall be comma separated, e.g. "tel,skype". 482 */ 483 char *uri_schemes_supported; 484 485 /** 486 * @brief Whether this bearer shall be registered as a Generic Telephone Bearer server 487 * 488 * A GTBS shall be registered before any non-GTBS services. There can only be a single GTBS 489 * registered. 490 */ 491 bool gtbs; 492 493 /** 494 * @brief Whether the application will need to authorize changes to calls 495 * 496 * If set to false then the service will automatically accept write requests from clients. 497 */ 498 bool authorization_required; 499 500 /** 501 * @brief The technology of the bearer 502 * 503 * See the BT_TBS_TECHNOLOGY_* values. 504 */ 505 uint8_t technology; 506 507 /** 508 * @brief The optional supported features of the bearer 509 * 510 * See the BT_TBS_FEATURE_* values. 511 */ 512 uint8_t supported_features; 513 }; 514 515 /** 516 * @brief Register a Telephone Bearer 517 * 518 * This will register a Telephone Bearer Service (TBS) (or a Generic Telephone Bearer service 519 * (GTBS)) with the provided parameters. 520 * 521 * As per the TBS specification, the GTBS shall be instantiated for the feature, and as such a GTBS 522 * shall always be registered before any TBS can be registered. 523 * Similarly, all TBS shall be unregistered before the GTBS can be unregistered with 524 * bt_tbs_unregister_bearer(). 525 * 526 * @param param The parameters to initialize the bearer. 527 528 * @retval index The bearer index if return value is >= 0 529 * @retval -EINVAL @p param contains invalid data 530 * @retval -EALREADY @p param.gtbs is true and GTBS has already been registered 531 * @retval -EAGAIN @p param.gtbs is false and GTBS has not been registered 532 * @retval -ENOMEM @p param.gtbs is false and no more TBS can be registered (see 533 * @kconfig{CONFIG_BT_TBS_BEARER_COUNT}) 534 * @retval -ENOEXEC The service failed to be registered 535 */ 536 int bt_tbs_register_bearer(const struct bt_tbs_register_param *param); 537 538 /** 539 * @brief Unregister a Telephone Bearer 540 * 541 * This will unregister a Telephone Bearer Service (TBS) (or a Generic Telephone Bearer service 542 * (GTBS)) with the provided parameters. The bearer shall be registered first by 543 * bt_tbs_register_bearer() before it can be unregistered. 544 * 545 * Similarly, all TBS shall be unregistered before the GTBS can be unregistered with. 546 * 547 * @param bearer_index The index of the bearer to unregister. 548 * 549 * @retval 0 Success 550 * @retval -EINVAL @p bearer_index is invalid 551 * @retval -EALREADY The bearer identified by @p bearer_index is not registered 552 * @retval -EAGAIN The bearer identified by @p bearer_index is GTBS and there are TBS instances 553 * registered. 554 * @retval -ENOEXEC The service failed to be unregistered 555 */ 556 int bt_tbs_unregister_bearer(uint8_t bearer_index); 557 558 /** @brief Prints all calls of all services to the debug log */ 559 void bt_tbs_dbg_print_calls(void); 560 561 /** Struct to hold a call state */ 562 struct bt_tbs_client_call_state { 563 /** Index of the call */ 564 uint8_t index; 565 /** State of the call (see BT_TBS_CALL_STATE_*) */ 566 uint8_t state; 567 /** Call flags (see BT_TBS_CALL_FLAG_*) */ 568 uint8_t flags; 569 } __packed; 570 571 /** Struct to hold a call as the Telephone Bearer Service client */ 572 struct bt_tbs_client_call { 573 /** Call information */ 574 struct bt_tbs_client_call_state call_info; 575 /** The remove URI */ 576 char *remote_uri; 577 }; 578 579 /** 580 * @brief Callback function for ccp_discover. 581 * 582 * @param conn The connection that was used to discover CCP for a 583 * device. 584 * @param err Error value. BT_TBS_CLIENT_RESULT_CODE_*, 585 * GATT error or errno value. 586 * @param tbs_count Number of TBS instances on peer device. 587 * @param gtbs_found Whether or not the server has a Generic TBS instance. 588 */ 589 typedef void (*bt_tbs_client_discover_cb)(struct bt_conn *conn, int err, 590 uint8_t tbs_count, bool gtbs_found); 591 592 /** 593 * @brief Callback function for writing values to peer device. 594 * 595 * @param conn The connection used in the function. 596 * @param err Error value. BT_TBS_CLIENT_RESULT_CODE_*, 597 * GATT error or errno value. 598 * @param inst_index The index of the TBS instance that was updated. 599 */ 600 typedef void (*bt_tbs_client_write_value_cb)(struct bt_conn *conn, int err, 601 uint8_t inst_index); 602 603 /** 604 * @brief Callback function for the CCP call control functions. 605 * 606 * @param conn The connection used in the function. 607 * @param err Error value. BT_TBS_CLIENT_RESULT_CODE_*, 608 * GATT error or errno value. 609 * @param inst_index The index of the TBS instance that was updated. 610 * @param call_index The call index. For #bt_tbs_client_originate_call this will 611 * always be 0, and does not reflect the actual call index. 612 */ 613 typedef void (*bt_tbs_client_cp_cb)(struct bt_conn *conn, int err, 614 uint8_t inst_index, uint8_t call_index); 615 616 /** 617 * @brief Callback function for functions that read a string value. 618 * 619 * @param conn The connection used in the function. 620 * @param err Error value. BT_TBS_CLIENT_RESULT_CODE_*, 621 * GATT error or errno value. 622 * @param inst_index The index of the TBS instance that was updated. 623 * @param value The Null-terminated string value. The value is not kept 624 * by the client, so must be copied to be saved. 625 */ 626 typedef void (*bt_tbs_client_read_string_cb)(struct bt_conn *conn, int err, 627 uint8_t inst_index, 628 const char *value); 629 630 /** 631 * @brief Callback function for functions that read an integer value. 632 * 633 * @param conn The connection used in the function. 634 * @param err Error value. BT_TBS_CLIENT_RESULT_CODE_*, 635 * GATT error or errno value. 636 * @param inst_index The index of the TBS instance that was updated. 637 * @param value The integer value. 638 */ 639 typedef void (*bt_tbs_client_read_value_cb)(struct bt_conn *conn, int err, 640 uint8_t inst_index, uint32_t value); 641 642 /** 643 * @brief Callback function for ccp_read_termination_reason. 644 * 645 * @param conn The connection used in the function. 646 * @param err Error value. BT_TBS_CLIENT_RESULT_CODE_*, 647 * GATT error or errno value. 648 * @param inst_index The index of the TBS instance that was updated. 649 * @param call_index The call index. 650 * @param reason The termination reason. 651 */ 652 typedef void (*bt_tbs_client_termination_reason_cb)(struct bt_conn *conn, 653 int err, uint8_t inst_index, 654 uint8_t call_index, 655 uint8_t reason); 656 657 /** 658 * @brief Callback function for ccp_read_current_calls. 659 * 660 * @param conn The connection used in the function. 661 * @param err Error value. BT_TBS_CLIENT_RESULT_CODE_*, 662 * GATT error or errno value. 663 * @param inst_index The index of the TBS instance that was updated. 664 * @param call_count Number of calls read. 665 * @param calls Array of calls. The array is not kept by 666 * the client, so must be copied to be saved. 667 */ 668 typedef void (*bt_tbs_client_current_calls_cb)(struct bt_conn *conn, int err, 669 uint8_t inst_index, 670 uint8_t call_count, 671 const struct bt_tbs_client_call *calls); 672 673 /** 674 * @brief Callback function for ccp_read_call_state. 675 * 676 * @param conn The connection used in the function. 677 * @param err Error value. BT_TBS_CLIENT_RESULT_CODE_*, 678 * GATT error or errno value. 679 * @param inst_index The index of the TBS instance that was updated. 680 * @param call_count Number of call states read. 681 * @param call_states Array of call states. The array is not kept by 682 * the client, so must be copied to be saved. 683 */ 684 typedef void (*bt_tbs_client_call_states_cb)(struct bt_conn *conn, int err, 685 uint8_t inst_index, 686 uint8_t call_count, 687 const struct bt_tbs_client_call_state *call_states); 688 689 /** 690 * @brief Struct to hold the Telephone Bearer Service client callbacks 691 * 692 * These can be registered for usage with bt_tbs_client_register_cb(). 693 */ 694 struct bt_tbs_client_cb { 695 /** Discovery has completed */ 696 bt_tbs_client_discover_cb discover; 697 #if defined(CONFIG_BT_TBS_CLIENT_ORIGINATE_CALL) || defined(__DOXYGEN__) 698 /** Originate call has completed */ 699 bt_tbs_client_cp_cb originate_call; 700 #endif /* defined(CONFIG_BT_TBS_CLIENT_ORIGINATE_CALL) */ 701 #if defined(CONFIG_BT_TBS_CLIENT_TERMINATE_CALL) || defined(__DOXYGEN__) 702 /** Terminate call has completed */ 703 bt_tbs_client_cp_cb terminate_call; 704 #endif /* defined(CONFIG_BT_TBS_CLIENT_TERMINATE_CALL) */ 705 #if defined(CONFIG_BT_TBS_CLIENT_HOLD_CALL) || defined(__DOXYGEN__) 706 /** Hold call has completed */ 707 bt_tbs_client_cp_cb hold_call; 708 #endif /* defined(CONFIG_BT_TBS_CLIENT_HOLD_CALL) */ 709 #if defined(CONFIG_BT_TBS_CLIENT_ACCEPT_CALL) || defined(__DOXYGEN__) 710 /** Accept call has completed */ 711 bt_tbs_client_cp_cb accept_call; 712 #endif /* defined(CONFIG_BT_TBS_CLIENT_ACCEPT_CALL) */ 713 #if defined(CONFIG_BT_TBS_CLIENT_RETRIEVE_CALL) || defined(__DOXYGEN__) 714 /** Retrieve call has completed */ 715 bt_tbs_client_cp_cb retrieve_call; 716 #endif /* defined(CONFIG_BT_TBS_CLIENT_RETRIEVE_CALL) */ 717 #if defined(CONFIG_BT_TBS_CLIENT_JOIN_CALLS) || defined(__DOXYGEN__) 718 /** Join calls has completed */ 719 bt_tbs_client_cp_cb join_calls; 720 #endif /* defined(CONFIG_BT_TBS_CLIENT_JOIN_CALLS) */ 721 #if defined(CONFIG_BT_TBS_CLIENT_BEARER_PROVIDER_NAME) || defined(__DOXYGEN__) 722 /** Bearer provider name has been read */ 723 bt_tbs_client_read_string_cb bearer_provider_name; 724 #endif /* defined(CONFIG_BT_TBS_CLIENT_BEARER_PROVIDER_NAME) */ 725 #if defined(CONFIG_BT_TBS_CLIENT_BEARER_UCI) || defined(__DOXYGEN__) 726 /** Bearer UCI has been read */ 727 bt_tbs_client_read_string_cb bearer_uci; 728 #endif /* defined(CONFIG_BT_TBS_CLIENT_BEARER_UCI) */ 729 #if defined(CONFIG_BT_TBS_CLIENT_BEARER_TECHNOLOGY) || defined(__DOXYGEN__) 730 /** Bearer technology has been read */ 731 bt_tbs_client_read_value_cb technology; 732 #endif /* defined(CONFIG_BT_TBS_CLIENT_BEARER_TECHNOLOGY) */ 733 #if defined(CONFIG_BT_TBS_CLIENT_BEARER_URI_SCHEMES_SUPPORTED_LIST) || defined(__DOXYGEN__) 734 /** Bearer URI list has been read */ 735 bt_tbs_client_read_string_cb uri_list; 736 #endif /* defined(CONFIG_BT_TBS_CLIENT_BEARER_URI_SCHEMES_SUPPORTED_LIST) */ 737 #if defined(CONFIG_BT_TBS_CLIENT_BEARER_SIGNAL_STRENGTH) || defined(__DOXYGEN__) 738 /** Bearer signal strength has been read */ 739 bt_tbs_client_read_value_cb signal_strength; 740 #endif /* defined(CONFIG_BT_TBS_CLIENT_BEARER_SIGNAL_STRENGTH) */ 741 #if defined(CONFIG_BT_TBS_CLIENT_READ_BEARER_SIGNAL_INTERVAL) || defined(__DOXYGEN__) 742 /** Bearer signal interval has been read */ 743 bt_tbs_client_read_value_cb signal_interval; 744 #endif /* defined(CONFIG_BT_TBS_CLIENT_READ_BEARER_SIGNAL_INTERVAL) */ 745 #if defined(CONFIG_BT_TBS_CLIENT_BEARER_LIST_CURRENT_CALLS) || defined(__DOXYGEN__) 746 /** Bearer current calls has been read */ 747 bt_tbs_client_current_calls_cb current_calls; 748 #endif /* defined(CONFIG_BT_TBS_CLIENT_BEARER_LIST_CURRENT_CALLS) */ 749 #if defined(CONFIG_BT_TBS_CLIENT_CCID) || defined(__DOXYGEN__) 750 /** Bearer CCID has been read */ 751 bt_tbs_client_read_value_cb ccid; 752 #endif /* defined(CONFIG_BT_TBS_CLIENT_CCID) */ 753 #if defined(CONFIG_BT_TBS_CLIENT_INCOMING_URI) || defined(__DOXYGEN__) 754 /** Bearer call URI has been read */ 755 bt_tbs_client_read_string_cb call_uri; 756 #endif /* defined(CONFIG_BT_TBS_CLIENT_INCOMING_URI) */ 757 #if defined(CONFIG_BT_TBS_CLIENT_STATUS_FLAGS) || defined(__DOXYGEN__) 758 /** Bearer status flags has been read */ 759 bt_tbs_client_read_value_cb status_flags; 760 #endif /* defined(CONFIG_BT_TBS_CLIENT_STATUS_FLAGS) */ 761 /** Bearer call states has been read */ 762 bt_tbs_client_call_states_cb call_state; 763 #if defined(CONFIG_BT_TBS_CLIENT_OPTIONAL_OPCODES) || defined(__DOXYGEN__) 764 /** Bearer optional opcodes has been read */ 765 bt_tbs_client_read_value_cb optional_opcodes; 766 #endif /* defined(CONFIG_BT_TBS_CLIENT_OPTIONAL_OPCODES) */ 767 /** Bearer terminate reason has been read */ 768 bt_tbs_client_termination_reason_cb termination_reason; 769 #if defined(CONFIG_BT_TBS_CLIENT_INCOMING_CALL) || defined(__DOXYGEN__) 770 /** Bearer remote URI has been read */ 771 bt_tbs_client_read_string_cb remote_uri; 772 #endif /* defined(CONFIG_BT_TBS_CLIENT_INCOMING_CALL) */ 773 #if defined(CONFIG_BT_TBS_CLIENT_CALL_FRIENDLY_NAME) || defined(__DOXYGEN__) 774 /** Bearer friendly name has been read */ 775 bt_tbs_client_read_string_cb friendly_name; 776 #endif /* defined(CONFIG_BT_TBS_CLIENT_CALL_FRIENDLY_NAME) */ 777 778 /** @cond INTERNAL_HIDDEN */ 779 /** Internally used field for list handling */ 780 sys_snode_t _node; 781 /** @endcond */ 782 }; 783 784 /** 785 * @brief Discover TBS for a connection. This will start a GATT 786 * discover and setup handles and subscriptions. 787 * 788 * @param conn The connection to discover TBS for. 789 * 790 * @return int 0 on success, GATT error value on fail. 791 */ 792 int bt_tbs_client_discover(struct bt_conn *conn); 793 794 /** 795 * @brief Set the outgoing URI for a TBS instance on the peer device. 796 * 797 * @param conn The connection to the TBS server. 798 * @param inst_index The index of the TBS instance. 799 * @param uri The Null-terminated URI string. 800 * 801 * @return int 0 on success, errno value on fail. 802 */ 803 int bt_tbs_client_set_outgoing_uri(struct bt_conn *conn, uint8_t inst_index, 804 const char *uri); 805 806 /** 807 * @brief Set the signal strength reporting interval for a TBS instance. 808 * 809 * @param conn The connection to the TBS server. 810 * @param inst_index The index of the TBS instance. 811 * @param interval The interval to write (0-255 seconds). 812 * 813 * @return int 0 on success, errno value on fail. 814 * 815 * @note @kconfig{CONFIG_BT_TBS_CLIENT_SET_BEARER_SIGNAL_INTERVAL} must be set 816 * for this function to be effective. 817 */ 818 int bt_tbs_client_set_signal_strength_interval(struct bt_conn *conn, 819 uint8_t inst_index, 820 uint8_t interval); 821 822 /** 823 * @brief Request to originate a call. 824 * 825 * @param conn The connection to the TBS server. 826 * @param inst_index The index of the TBS instance. 827 * @param uri The URI of the callee. 828 * 829 * @return int 0 on success, errno value on fail. 830 * 831 * @note @kconfig{CONFIG_BT_TBS_CLIENT_ORIGINATE_CALL} must be set 832 * for this function to be effective. 833 */ 834 int bt_tbs_client_originate_call(struct bt_conn *conn, uint8_t inst_index, 835 const char *uri); 836 837 /** 838 * @brief Request to terminate a call 839 * 840 * @param conn The connection to the TBS server. 841 * @param inst_index The index of the TBS instance. 842 * @param call_index The call index to terminate. 843 * 844 * @return int 0 on success, errno value on fail. 845 * 846 * @note @kconfig{CONFIG_BT_TBS_CLIENT_TERMINATE_CALL} must be set 847 * for this function to be effective. 848 */ 849 int bt_tbs_client_terminate_call(struct bt_conn *conn, uint8_t inst_index, 850 uint8_t call_index); 851 852 /** 853 * @brief Request to hold a call 854 * 855 * @param conn The connection to the TBS server. 856 * @param inst_index The index of the TBS instance. 857 * @param call_index The call index to place on hold. 858 * 859 * @return int 0 on success, errno value on fail. 860 * 861 * @note @kconfig{CONFIG_BT_TBS_CLIENT_HOLD_CALL} must be set 862 * for this function to be effective. 863 */ 864 int bt_tbs_client_hold_call(struct bt_conn *conn, uint8_t inst_index, 865 uint8_t call_index); 866 867 /** 868 * @brief Accept an incoming call 869 * 870 * @param conn The connection to the TBS server. 871 * @param inst_index The index of the TBS instance. 872 * @param call_index The call index to accept. 873 * 874 * @return int 0 on success, errno value on fail. 875 * 876 * @note @kconfig{CONFIG_BT_TBS_CLIENT_ACCEPT_CALL} must be set 877 * for this function to be effective. 878 */ 879 int bt_tbs_client_accept_call(struct bt_conn *conn, uint8_t inst_index, 880 uint8_t call_index); 881 882 /** 883 * @brief Retrieve call from (local) hold. 884 * 885 * @param conn The connection to the TBS server. 886 * @param inst_index The index of the TBS instance. 887 * @param call_index The call index to retrieve. 888 * 889 * @return int 0 on success, errno value on fail. 890 * 891 * @note @kconfig{CONFIG_BT_TBS_CLIENT_RETRIEVE_CALL} must be set 892 * for this function to be effective. 893 */ 894 int bt_tbs_client_retrieve_call(struct bt_conn *conn, uint8_t inst_index, 895 uint8_t call_index); 896 897 /** 898 * @brief Join multiple calls. 899 * 900 * @param conn The connection to the TBS server. 901 * @param inst_index The index of the TBS instance. 902 * @param call_indexes Array of call indexes. 903 * @param count Number of call indexes in the call_indexes array. 904 * 905 * @return int 0 on success, errno value on fail. 906 * 907 * @note @kconfig{CONFIG_BT_TBS_CLIENT_JOIN_CALLS} must be set 908 * for this function to be effective. 909 */ 910 int bt_tbs_client_join_calls(struct bt_conn *conn, uint8_t inst_index, 911 const uint8_t *call_indexes, uint8_t count); 912 913 /** 914 * @brief Read the bearer provider name of a TBS instance. 915 * 916 * @param conn The connection to the TBS server. 917 * @param inst_index The index of the TBS instance. 918 * 919 * @return int 0 on success, errno value on fail. 920 * 921 * @note @kconfig{CONFIG_BT_TBS_CLIENT_BEARER_PROVIDER_NAME} must be set 922 * for this function to be effective. 923 */ 924 int bt_tbs_client_read_bearer_provider_name(struct bt_conn *conn, 925 uint8_t inst_index); 926 927 /** 928 * @brief Read the UCI of a TBS instance. 929 * 930 * @param conn The connection to the TBS server. 931 * @param inst_index The index of the TBS instance. 932 * 933 * @return int 0 on success, errno value on fail. 934 * 935 * @note @kconfig{CONFIG_BT_TBS_CLIENT_BEARER_UCI} must be set 936 * for this function to be effective. 937 */ 938 int bt_tbs_client_read_bearer_uci(struct bt_conn *conn, uint8_t inst_index); 939 940 /** 941 * @brief Read the technology of a TBS instance. 942 * 943 * @param conn The connection to the TBS server. 944 * @param inst_index The index of the TBS instance. 945 * 946 * @return int 0 on success, errno value on fail. 947 * 948 * @note @kconfig{CONFIG_BT_TBS_CLIENT_BEARER_TECHNOLOGY} must be set 949 * for this function to be effective. 950 */ 951 int bt_tbs_client_read_technology(struct bt_conn *conn, uint8_t inst_index); 952 953 /** 954 * @brief Read the URI schemes list of a TBS instance. 955 * 956 * @param conn The connection to the TBS server. 957 * @param inst_index The index of the TBS instance. 958 * 959 * @return int 0 on success, errno value on fail. 960 * 961 * @note @kconfig{CONFIG_BT_TBS_CLIENT_BEARER_URI_SCHEMES_SUPPORTED_LIST} must be set 962 * for this function to be effective. 963 */ 964 int bt_tbs_client_read_uri_list(struct bt_conn *conn, uint8_t inst_index); 965 966 /** 967 * @brief Read the current signal strength of a TBS instance. 968 * 969 * @param conn The connection to the TBS server. 970 * @param inst_index The index of the TBS instance. 971 * 972 * @return int 0 on success, errno value on fail. 973 * 974 * @note @kconfig{CONFIG_BT_TBS_CLIENT_BEARER_SIGNAL_STRENGTH} must be set 975 * for this function to be effective. 976 */ 977 int bt_tbs_client_read_signal_strength(struct bt_conn *conn, 978 uint8_t inst_index); 979 980 /** 981 * @brief Read the signal strength reporting interval of a TBS instance. 982 * 983 * @param conn The connection to the TBS server. 984 * @param inst_index The index of the TBS instance. 985 * 986 * @return int 0 on success, errno value on fail. 987 * 988 * @note @kconfig{CONFIG_BT_TBS_CLIENT_READ_BEARER_SIGNAL_INTERVAL} must be set 989 * for this function to be effective. 990 */ 991 int bt_tbs_client_read_signal_interval(struct bt_conn *conn, 992 uint8_t inst_index); 993 994 /** 995 * @brief Read the list of current calls of a TBS instance. 996 * 997 * @param conn The connection to the TBS server. 998 * @param inst_index The index of the TBS instance. 999 * 1000 * @return int 0 on success, errno value on fail. 1001 * 1002 * @note @kconfig{CONFIG_BT_TBS_CLIENT_BEARER_LIST_CURRENT_CALLS} must be set 1003 * for this function to be effective. 1004 */ 1005 int bt_tbs_client_read_current_calls(struct bt_conn *conn, uint8_t inst_index); 1006 1007 /** 1008 * @brief Read the content ID of a TBS instance. 1009 * 1010 * @param conn The connection to the TBS server. 1011 * @param inst_index The index of the TBS instance. 1012 * 1013 * @return int 0 on success, errno value on fail. 1014 * 1015 * @note @kconfig{CONFIG_BT_TBS_CLIENT_CCID} must be set 1016 * for this function to be effective. 1017 */ 1018 int bt_tbs_client_read_ccid(struct bt_conn *conn, uint8_t inst_index); 1019 1020 /** 1021 * @brief Read the call target URI of a TBS instance. 1022 * 1023 * @param conn The connection to the TBS server. 1024 * @param inst_index The index of the TBS instance. 1025 * 1026 * @return int 0 on success, errno value on fail. 1027 * 1028 * @note @kconfig{CONFIG_BT_TBS_CLIENT_INCOMING_URI} must be set 1029 * for this function to be effective. 1030 */ 1031 int bt_tbs_client_read_call_uri(struct bt_conn *conn, uint8_t inst_index); 1032 1033 /** 1034 * @brief Read the feature and status value of a TBS instance. 1035 * 1036 * @param conn The connection to the TBS server. 1037 * @param inst_index The index of the TBS instance. 1038 * 1039 * @return int 0 on success, errno value on fail. 1040 * 1041 * @note @kconfig{CONFIG_BT_TBS_CLIENT_STATUS_FLAGS} must be set 1042 * for this function to be effective. 1043 */ 1044 int bt_tbs_client_read_status_flags(struct bt_conn *conn, uint8_t inst_index); 1045 1046 /** 1047 * @brief Read the states of the current calls of a TBS instance. 1048 * 1049 * @param conn The connection to the TBS server. 1050 * @param inst_index The index of the TBS instance. 1051 * 1052 * @return int 0 on success, errno value on fail. 1053 */ 1054 int bt_tbs_client_read_call_state(struct bt_conn *conn, uint8_t inst_index); 1055 1056 /** 1057 * @brief Read the remote URI of a TBS instance. 1058 * 1059 * @param conn The connection to the TBS server. 1060 * @param inst_index The index of the TBS instance. 1061 * 1062 * @return int 0 on success, errno value on fail. 1063 * 1064 * @note @kconfig{CONFIG_BT_TBS_CLIENT_INCOMING_CALL} must be set 1065 * for this function to be effective. 1066 */ 1067 int bt_tbs_client_read_remote_uri(struct bt_conn *conn, uint8_t inst_index); 1068 1069 /** 1070 * @brief Read the friendly name of a call for a TBS instance. 1071 * 1072 * @param conn The connection to the TBS server. 1073 * @param inst_index The index of the TBS instance. 1074 * 1075 * @return int 0 on success, errno value on fail. 1076 * 1077 * @note @kconfig{CONFIG_BT_TBS_CLIENT_CALL_FRIENDLY_NAME} must be set 1078 * for this function to be effective. 1079 */ 1080 int bt_tbs_client_read_friendly_name(struct bt_conn *conn, uint8_t inst_index); 1081 1082 /** 1083 * @brief Read the supported opcode of a TBS instance. 1084 * 1085 * @param conn The connection to the TBS server. 1086 * @param inst_index The index of the TBS instance. 1087 * 1088 * @return int 0 on success, errno value on fail. 1089 * 1090 * @note @kconfig{CONFIG_BT_TBS_CLIENT_OPTIONAL_OPCODES} must be set 1091 * for this function to be effective. 1092 */ 1093 int bt_tbs_client_read_optional_opcodes(struct bt_conn *conn, 1094 uint8_t inst_index); 1095 1096 /** 1097 * @brief Register the callbacks for CCP. 1098 * 1099 * @param cbs Pointer to the callback structure. 1100 * 1101 * @retval 0 Success 1102 * @retval -EINVAL @p cbs is NULL 1103 * @retval -EEXIST @p cbs is already registered 1104 */ 1105 int bt_tbs_client_register_cb(struct bt_tbs_client_cb *cbs); 1106 1107 /** 1108 * @brief Look up Telephone Bearer Service instance by CCID 1109 * 1110 * @param conn The connection to the TBS server. 1111 * @param ccid The CCID to lookup a service instance for. 1112 * 1113 * @return Pointer to a Telephone Bearer Service instance if found else NULL. 1114 * 1115 * @note @kconfig{CONFIG_BT_TBS_CLIENT_CCID} must be set 1116 * for this function to be effective. 1117 */ 1118 struct bt_tbs_instance *bt_tbs_client_get_by_ccid(const struct bt_conn *conn, 1119 uint8_t ccid); 1120 1121 #ifdef __cplusplus 1122 } 1123 #endif 1124 1125 /** @} */ 1126 1127 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_TBS_H_ */ 1128
