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 : #if defined(CONFIG_BT_TBS_CLIENT_BEARER_PROVIDER_NAME)
173 : /**
174 : * @brief Callback function for bt_ccp_call_control_client_read_bearer_provider_name().
175 : *
176 : * This callback is called once the read bearer provider name procedure is completed.
177 : *
178 : * @param client Call Control Client instance pointer.
179 : * @param err Error value. 0 on success, GATT error on positive
180 : * value or errno on negative value.
181 : * @param name The bearer provider name. NULL if @p err is not 0.
182 : */
183 : void (*bearer_provider_name)(struct bt_ccp_call_control_client_bearer *bearer, int err,
184 : const char *name);
185 : #endif /* CONFIG_BT_TBS_CLIENT_BEARER_PROVIDER_NAME */
186 :
187 : /** @cond INTERNAL_HIDDEN */
188 : /** Internally used field for list handling */
189 : sys_snode_t _node;
190 : /** @endcond */
191 : };
192 :
193 : /**
194 : * @brief Discovers the Telephone Bearer Service (TBS) support on a remote device.
195 : *
196 : * This will discover the Telephone Bearer Service (TBS) and Generic Telephone Bearer Service (GTBS)
197 : * on the remote device.
198 : *
199 : * @kconfig_dep{CONFIG_BT_CCP_CALL_CONTROL_CLIENT}.
200 : *
201 : * @param conn Connection to a remote server.
202 : * @param out_client Pointer to client instance on success
203 : *
204 : * @retval 0 Success
205 : * @retval -EINVAL @p conn or @p out_client is NULL
206 : * @retval -ENOTCONN @p conn is not connected
207 : * @retval -ENOMEM Could not allocated memory for the request
208 : * @retval -EBUSY Already doing discovery for @p conn
209 : * @retval -ENOEXEC Rejected by the GATT layer
210 : */
211 1 : int bt_ccp_call_control_client_discover(struct bt_conn *conn,
212 : struct bt_ccp_call_control_client **out_client);
213 :
214 : /**
215 : * @brief Register callbacks for the Call Control Client
216 : *
217 : * @param cb The callback struct
218 : *
219 : * @retval 0 Success
220 : * @retval -EINVAL @p cb is NULL
221 : * @retval -EEXISTS @p cb is already registered
222 : */
223 1 : int bt_ccp_call_control_client_register_cb(struct bt_ccp_call_control_client_cb *cb);
224 :
225 : /**
226 : * @brief Unregister callbacks for the Call Control Client
227 : *
228 : * @param cb The callback struct
229 : *
230 : * @retval 0 Success
231 : * @retval -EINVAL @p cb is NULL
232 : * @retval -EALREADY @p cb is not registered
233 : */
234 1 : int bt_ccp_call_control_client_unregister_cb(struct bt_ccp_call_control_client_cb *cb);
235 :
236 : /**
237 : * @brief Get the bearers of a client instance
238 : *
239 : * @param[in] client The client to get the bearers of.
240 : * @param[out] bearers The bearers struct that will be populated with the bearers of @p client.
241 :
242 : * @retval 0 Success
243 : * @retval -EINVAL @p client or @p bearers is NULL
244 : */
245 1 : int bt_ccp_call_control_client_get_bearers(struct bt_ccp_call_control_client *client,
246 : struct bt_ccp_call_control_client_bearers *bearers);
247 :
248 : /**
249 : * @brief Read the bearer provider name of a remote TBS bearer.
250 : *
251 : * @kconfig_dep{CONFIG_BT_TBS_CLIENT_BEARER_PROVIDER_NAME}
252 : *
253 : * @param bearer The bearer to read the name from
254 : *
255 : * @retval 0 Success
256 : * @retval -EINVAL @p bearer is NULL
257 : * @retval -EFAULT @p bearer has not been discovered
258 : * @retval -EEXIST A @ref bt_ccp_call_control_client could not be identified for @p bearer
259 : * @retval -EBUSY The @ref bt_ccp_call_control_client identified by @p bearer is busy, or the TBS
260 : * instance of @p bearer is busy.
261 : * @retval -ENOTCONN The @ref bt_ccp_call_control_client identified by @p bearer is not connected
262 : */
263 1 : int bt_ccp_call_control_client_read_bearer_provider_name(
264 : struct bt_ccp_call_control_client_bearer *bearer);
265 : /** @} */ /* End of group bt_ccp_call_control_client */
266 : #ifdef __cplusplus
267 : }
268 : #endif
269 :
270 : /**
271 : * @}
272 : */
273 :
274 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CCP_H_ */
|
