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 struct bt_tbs_register_param { 466 /** The name of the provider, for example a cellular service provider */ 467 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 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 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 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 bool authorization_required; 498 499 /** 500 * @brief The technology of the bearer 501 * 502 * See the BT_TBS_TECHNOLOGY_* values. 503 */ 504 uint8_t technology; 505 506 /** 507 * @brief The optional supported features of the bearer 508 * 509 * See the BT_TBS_FEATURE_* values. 510 */ 511 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 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 int bt_tbs_unregister_bearer(uint8_t bearer_index); 556 557 /** @brief Prints all calls of all services to the debug log */ 558 void bt_tbs_dbg_print_calls(void); 559 560 /** Struct to hold a call state */ 561 struct bt_tbs_client_call_state { 562 /** Index of the call */ 563 uint8_t index; 564 /** State of the call (see BT_TBS_CALL_STATE_*) */ 565 uint8_t state; 566 /** Call flags (see BT_TBS_CALL_FLAG_*) */ 567 uint8_t flags; 568 } __packed; 569 570 /** Struct to hold a call as the Telephone Bearer Service client */ 571 struct bt_tbs_client_call { 572 /** Call information */ 573 struct bt_tbs_client_call_state call_info; 574 /** The remove URI */ 575 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 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 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 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 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 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 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 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 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 struct bt_tbs_client_cb { 694 /** Discovery has completed */ 695 bt_tbs_client_discover_cb discover; 696 #if defined(CONFIG_BT_TBS_CLIENT_ORIGINATE_CALL) || defined(__DOXYGEN__) 697 /** Originate call has completed */ 698 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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_ */ 1125
