Line data Source code
1 1 : /**
2 : * @file
3 : * @brief Bluetooth Call Control Profile (CCP) APIs.
4 : */
5 :
6 : /*
7 : * Copyright (c) 2024 Nordic Semiconductor ASA
8 : *
9 : * SPDX-License-Identifier: Apache-2.0
10 : */
11 :
12 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CCP_H_
13 : #define ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CCP_H_
14 :
15 : /**
16 : * @brief Call Control Profile (CCP)
17 : *
18 : * @defgroup bt_ccp Call Control Profile (CCP)
19 : *
20 : * @since 3.7
21 : * @version 0.1.0
22 : *
23 : * @ingroup bluetooth
24 : * @{
25 : *
26 : * Call Control Profile (CCP) provides procedures to initiate and control calls.
27 : * It provides the Call Control Client and the Call Control Server roles,
28 : * where the former is usually placed on resource constrained devices like headphones,
29 : * and the latter placed on more powerful devices like phones and PCs.
30 : *
31 : * The profile is not limited to carrier phone calls and can be used with common applications like
32 : * Discord and Teams.
33 : */
34 :
35 : #include <stddef.h>
36 :
37 : #include <zephyr/autoconf.h>
38 : #include <zephyr/bluetooth/audio/tbs.h>
39 : #include <zephyr/bluetooth/conn.h>
40 : #include <zephyr/sys/slist.h>
41 :
42 : #ifdef __cplusplus
43 : extern "C" {
44 : #endif
45 : /**
46 : * @defgroup bt_ccp_call_control_server CCP Call Control Server APIs
47 : * @ingroup bt_ccp
48 : * @{
49 : */
50 : /** @brief Abstract Call Control Server Telephone Bearer structure. */
51 : struct bt_ccp_call_control_server_bearer;
52 :
53 : /**
54 : * @brief Register a Telephone Bearer
55 : *
56 : * This will register a Telephone Bearer Service (TBS) (or a Generic Telephone Bearer service
57 : * (GTBS)) with the provided parameters.
58 : *
59 : * As per the TBS specification, the GTBS shall be instantiated for the feature,
60 : * and as such a GTBS shall always be registered before any TBS can be registered.
61 : * Similarly, all TBS shall be unregistered before the GTBS can be unregistered with
62 : * bt_ccp_call_control_server_unregister_bearer().
63 : *
64 : * @param[in] param The parameters to initialize the bearer.
65 : * @param[out] bearer Pointer to the initialized bearer.
66 : *
67 : * @retval 0 Success
68 : * @retval -EINVAL @p param contains invalid data
69 : * @retval -EALREADY @p param.gtbs is true and GTBS has already been registered
70 : * @retval -EAGAIN @p param.gtbs is false and GTBS has not been registered
71 : * @retval -ENOMEM @p param.gtbs is false and no more TBS can be registered (see
72 : * @kconfig{CONFIG_BT_TBS_BEARER_COUNT})
73 : * @retval -ENOEXEC The service failed to be registered
74 : */
75 1 : int bt_ccp_call_control_server_register_bearer(const struct bt_tbs_register_param *param,
76 : struct bt_ccp_call_control_server_bearer **bearer);
77 :
78 : /**
79 : * @brief Unregister a Telephone Bearer
80 : *
81 : * This will unregister a Telephone Bearer Service (TBS) (or a Generic Telephone Bearer service
82 : * (GTBS)) with the provided parameters. The bearer shall be registered first by
83 : * bt_ccp_call_control_server_register_bearer() before it can be unregistered.
84 : *
85 : * All TBS shall be unregistered before the GTBS can be unregistered with.
86 : *
87 : * @param bearer The bearer to unregister.
88 : *
89 : * @retval 0 Success
90 : * @retval -EINVAL @p bearer is NULL
91 : * @retval -EALREADY The bearer is not registered
92 : * @retval -ENOEXEC The service failed to be unregistered
93 : */
94 1 : int bt_ccp_call_control_server_unregister_bearer(struct bt_ccp_call_control_server_bearer *bearer);
95 :
96 : /**
97 : * @brief Set a new bearer provider name.
98 : *
99 : * @param bearer The bearer to set the name for.
100 : * @param name The new bearer provider name.
101 : *
102 : * @retval 0 Success
103 : * @retval -EINVAL @p bearer or @p name is NULL, or @p name is the empty string or @p name is larger
104 : * than @kconfig{CONFIG_BT_TBS_MAX_PROVIDER_NAME_LENGTH}
105 : * @retval -EFAULT @p bearer is not registered
106 : */
107 1 : int bt_ccp_call_control_server_set_bearer_provider_name(
108 : struct bt_ccp_call_control_server_bearer *bearer, const char *name);
109 :
110 : /**
111 : * @brief Get the bearer provider name.
112 : *
113 : * @param[in] bearer The bearer to get the name for.
114 : * @param[out] name Pointer that will be updated to be the bearer provider name.
115 : *
116 : * @retval 0 Success
117 : * @retval -EINVAL @p bearer or @p name is NULL
118 : * @retval -EFAULT @p bearer is not registered
119 : */
120 1 : int bt_ccp_call_control_server_get_bearer_provider_name(
121 : struct bt_ccp_call_control_server_bearer *bearer, const char **name);
122 :
123 : /** @} */ /* End of group bt_ccp_call_control_server */
124 :
125 : /**
126 : * @defgroup bt_ccp_call_control_client CCP Call Control Client APIs
127 : * @ingroup bt_ccp
128 : * @{
129 : */
130 : /** Abstract Call Control Client structure. */
131 : struct bt_ccp_call_control_client;
132 :
133 : /** Abstract Call Control Client bearer structure. */
134 : struct bt_ccp_call_control_client_bearer;
135 :
136 : /** Struct with information about bearers of a client */
137 1 : struct bt_ccp_call_control_client_bearers {
138 : #if defined(CONFIG_BT_TBS_CLIENT_GTBS)
139 : /** The GTBS bearer. */
140 : struct bt_ccp_call_control_client_bearer *gtbs_bearer;
141 : #endif /* CONFIG_BT_TBS_CLIENT_GTBS */
142 :
143 : #if defined(CONFIG_BT_TBS_CLIENT_TBS)
144 : /** Number of TBS bearers in @p tbs_bearers */
145 : size_t tbs_count;
146 :
147 : /** Array of pointers of TBS bearers */
148 : struct bt_ccp_call_control_client_bearer
149 : *tbs_bearers[CONFIG_BT_CCP_CALL_CONTROL_CLIENT_BEARER_COUNT];
150 : #endif /* CONFIG_BT_TBS_CLIENT_TBS */
151 : };
152 :
153 : /**
154 : * @brief Struct to hold the Telephone Bearer Service client callbacks
155 : *
156 : * These can be registered for usage with bt_tbs_client_register_cb().
157 : */
158 1 : struct bt_ccp_call_control_client_cb {
159 : /**
160 : * @brief Callback function for bt_ccp_call_control_client_discover().
161 : *
162 : * This callback is called once the discovery procedure is completed.
163 : *
164 : * @param client Call Control Client pointer.
165 : * @param err Error value. 0 on success, GATT error on positive
166 : * value or errno on negative value.
167 : * @param bearers The bearers found.
168 : */
169 1 : void (*discover)(struct bt_ccp_call_control_client *client, int err,
170 : struct bt_ccp_call_control_client_bearers *bearers);
171 :
172 : /** @cond INTERNAL_HIDDEN */
173 : /** Internally used field for list handling */
174 : sys_snode_t _node;
175 : /** @endcond */
176 : };
177 :
178 : /**
179 : * @brief Discovers the Telephone Bearer Service (TBS) support on a remote device.
180 : *
181 : * This will discover the Telephone Bearer Service (TBS) and Generic Telephone Bearer Service (GTBS)
182 : * on the remote device.
183 : *
184 : * @kconfig_dep{CONFIG_BT_CCP_CALL_CONTROL_CLIENT}.
185 : *
186 : * @param conn Connection to a remote server.
187 : * @param out_client Pointer to client instance on success
188 : *
189 : * @retval 0 Success
190 : * @retval -EINVAL @p conn or @p out_client is NULL
191 : * @retval -ENOTCONN @p conn is not connected
192 : * @retval -ENOMEM Could not allocated memory for the request
193 : * @retval -EBUSY Already doing discovery for @p conn
194 : * @retval -ENOEXEC Rejected by the GATT layer
195 : */
196 1 : int bt_ccp_call_control_client_discover(struct bt_conn *conn,
197 : struct bt_ccp_call_control_client **out_client);
198 :
199 : /**
200 : * @brief Register callbacks for the Call Control Client
201 : *
202 : * @param cb The callback struct
203 : *
204 : * @retval 0 Success
205 : * @retval -EINVAL @p cb is NULL
206 : * @retval -EEXISTS @p cb is already registered
207 : */
208 1 : int bt_ccp_call_control_client_register_cb(struct bt_ccp_call_control_client_cb *cb);
209 :
210 : /**
211 : * @brief Unregister callbacks for the Call Control Client
212 : *
213 : * @param cb The callback struct
214 : *
215 : * @retval 0 Success
216 : * @retval -EINVAL @p cb is NULL
217 : * @retval -EALREADY @p cb is not registered
218 : */
219 1 : int bt_ccp_call_control_client_unregister_cb(struct bt_ccp_call_control_client_cb *cb);
220 :
221 : /**
222 : * @brief Get the bearers of a client instance
223 : *
224 : * @param[in] client The client to get the bearers of.
225 : * @param[out] bearers The bearers struct that will be populated with the bearers of @p client.
226 :
227 : * @retval 0 Success
228 : * @retval -EINVAL @p client or @p bearers is NULL
229 : */
230 1 : int bt_ccp_call_control_client_get_bearers(struct bt_ccp_call_control_client *client,
231 : struct bt_ccp_call_control_client_bearers *bearers);
232 :
233 : /** @} */ /* End of group bt_ccp_call_control_client */
234 : #ifdef __cplusplus
235 : }
236 : #endif
237 :
238 : /**
239 : * @}
240 : */
241 :
242 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CCP_H_ */
|
