Line data Source code
1 1 : /**
2 : * @file
3 : * @brief Bluetooth Published Audio Capabilities Service (PACS) APIs
4 : */
5 :
6 : /* Copyright (c) 2021 Intel Corporation
7 : * Copyright (c) 2021-2024 Nordic Semiconductor ASA
8 : *
9 : * SPDX-License-Identifier: Apache-2.0
10 : */
11 :
12 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_PACS_H_
13 : #define ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_PACS_H_
14 :
15 : /**
16 : * @brief Published Audio Capabilities Service (PACS)
17 : *
18 : * @defgroup bt_pacs Published Audio Capabilities Service (PACS)
19 : *
20 : * @since 3.0
21 : * @version 0.8.0
22 : *
23 : * @ingroup bluetooth
24 : * @{
25 : *
26 : * The Published Audio Capabilities Service (PACS) is used to expose capabilities to remote devices.
27 : */
28 :
29 : #include <stdbool.h>
30 :
31 : #include <zephyr/bluetooth/audio/audio.h>
32 : #include <zephyr/bluetooth/conn.h>
33 : #include <zephyr/sys/slist.h>
34 :
35 : #ifdef __cplusplus
36 : extern "C" {
37 : #endif
38 :
39 : /** @brief Published Audio Capability structure. */
40 1 : struct bt_pacs_cap {
41 : /** Codec capability reference */
42 1 : const struct bt_audio_codec_cap *codec_cap;
43 :
44 : /** @cond INTERNAL_HIDDEN */
45 : /** Internally used field for list handling */
46 : sys_snode_t _node;
47 : /** @endcond */
48 : };
49 :
50 : /** Structure for registering PACS */
51 1 : struct bt_pacs_register_param {
52 : #if defined(CONFIG_BT_PAC_SNK) || defined(__DOXYGEN__)
53 : /**
54 : * @brief Enables or disables registration of Sink PAC Characteristic.
55 : */
56 1 : bool snk_pac;
57 : #endif /* CONFIG_BT_PAC_SNK */
58 :
59 : #if defined(CONFIG_BT_PAC_SNK_LOC) || defined(__DOXYGEN__)
60 : /**
61 : * @brief Enables or disables registration of Sink Location Characteristic.
62 : *
63 : * Registration of Sink Location is dependent on @ref bt_pacs_register_param.snk_pac
64 : * also being set.
65 : */
66 1 : bool snk_loc;
67 : #endif /* CONFIG_BT_PAC_SNK_LOC */
68 :
69 : #if defined(CONFIG_BT_PAC_SRC) || defined(__DOXYGEN__)
70 : /**
71 : * @brief Enables or disables registration of Source PAC Characteristic.
72 : */
73 1 : bool src_pac;
74 : #endif /* CONFIG_BT_PAC_SRC */
75 :
76 : #if defined(CONFIG_BT_PAC_SRC_LOC) || defined(__DOXYGEN__)
77 : /**
78 : * @brief Enables or disables registration of Source Location Characteristic.
79 : *
80 : * Registration of Source Location is dependent on @ref bt_pacs_register_param.src_pac
81 : * also being set.
82 : */
83 1 : bool src_loc;
84 : #endif /* CONFIG_BT_PAC_SRC_LOC */
85 : };
86 :
87 : /**
88 : * @typedef bt_pacs_cap_foreach_func_t
89 : * @brief Published Audio Capability iterator callback.
90 : *
91 : * @param cap Capability found.
92 : * @param user_data Data given.
93 : *
94 : * @return true to continue to the next capability
95 : * @return false to stop the iteration
96 : */
97 1 : typedef bool (*bt_pacs_cap_foreach_func_t)(const struct bt_pacs_cap *cap,
98 : void *user_data);
99 :
100 : /**
101 : * @brief Published Audio Capability iterator.
102 : *
103 : * Iterate capabilities with endpoint direction specified.
104 : *
105 : * @param dir Direction of the endpoint to look capability for.
106 : * @param func Callback function.
107 : * @param user_data Data to pass to the callback.
108 : */
109 1 : void bt_pacs_cap_foreach(enum bt_audio_dir dir,
110 : bt_pacs_cap_foreach_func_t func,
111 : void *user_data);
112 :
113 : /**
114 : * @brief Register the Published Audio Capability Service instance.
115 : *
116 : * @param param PACS register parameters.
117 : *
118 : * @retval 0 Success
119 : * @retval -EINVAL @p param is NULL or bad combination of values in @p param
120 : * @retval -EALREADY Already registered
121 : * @retval -ENOEXEC Request was rejected by GATT
122 : */
123 1 : int bt_pacs_register(const struct bt_pacs_register_param *param);
124 :
125 : /**
126 : * @brief Unregister the Published Audio Capability Service instance.
127 : *
128 : * @return 0 in case of success or negative value in case of error.
129 : */
130 1 : int bt_pacs_unregister(void);
131 :
132 : /**
133 : * @brief Register Published Audio Capability.
134 : *
135 : * Register Audio Local Capability.
136 : *
137 : * @param dir Direction of the endpoint to register capability for.
138 : * @param cap Capability structure.
139 : *
140 : * @return 0 in case of success or negative value in case of error.
141 : */
142 1 : int bt_pacs_cap_register(enum bt_audio_dir dir, struct bt_pacs_cap *cap);
143 :
144 : /**
145 : * @brief Unregister Published Audio Capability.
146 : *
147 : * Unregister Audio Local Capability.
148 : *
149 : * @param dir Direction of the endpoint to unregister capability for.
150 : * @param cap Capability structure.
151 : *
152 : * @return 0 in case of success or negative value in case of error.
153 : */
154 1 : int bt_pacs_cap_unregister(enum bt_audio_dir dir, struct bt_pacs_cap *cap);
155 :
156 : /**
157 : * @brief Set the location for an endpoint type
158 : *
159 : * @param dir Direction of the endpoints to change location for.
160 : * @param location The location to be set.
161 : *
162 : * @return 0 in case of success or negative value in case of error.
163 : */
164 1 : int bt_pacs_set_location(enum bt_audio_dir dir,
165 : enum bt_audio_location location);
166 :
167 : /**
168 : * @brief Set the available contexts for an endpoint type
169 : *
170 : * @param dir Direction of the endpoints to change available contexts for.
171 : * @param contexts The contexts to be set.
172 : *
173 : * @return 0 in case of success or negative value in case of error.
174 : */
175 1 : int bt_pacs_set_available_contexts(enum bt_audio_dir dir,
176 : enum bt_audio_context contexts);
177 :
178 : /**
179 : * @brief Get the available contexts for an endpoint type
180 : *
181 : * @param dir Direction of the endpoints to get contexts for.
182 : *
183 : * @return Bitmask of available contexts.
184 : */
185 1 : enum bt_audio_context bt_pacs_get_available_contexts(enum bt_audio_dir dir);
186 :
187 : /**
188 : * @brief Set the available contexts for a given connection
189 : *
190 : * This function sets the available contexts value for a given @p conn connection object.
191 : * If the @p contexts parameter is NULL the available contexts value is reset to default.
192 : * The default value of the available contexts is set using @ref bt_pacs_set_available_contexts
193 : * function.
194 : * The Available Context Value is reset to default on ACL disconnection.
195 : *
196 : * @param conn Connection object.
197 : * @param dir Direction of the endpoints to change available contexts for.
198 : * @param contexts The contexts to be set or NULL to reset to default.
199 : *
200 : * @return 0 in case of success or negative value in case of error.
201 : */
202 1 : int bt_pacs_conn_set_available_contexts_for_conn(struct bt_conn *conn, enum bt_audio_dir dir,
203 : enum bt_audio_context *contexts);
204 :
205 : /**
206 : * @brief Get the available contexts for a given connection
207 : *
208 : * This server function returns the available contexts value for a given @p conn connection object.
209 : * The value returned is the one set with @ref bt_pacs_conn_set_available_contexts_for_conn function
210 : * or the default value set with @ref bt_pacs_set_available_contexts function.
211 : *
212 : * @param conn Connection object.
213 : * @param dir Direction of the endpoints to get contexts for.
214 : *
215 : * @return Bitmask of available contexts.
216 : * @retval BT_AUDIO_CONTEXT_TYPE_NONE if @p conn or @p dir are invalid
217 : */
218 1 : enum bt_audio_context bt_pacs_get_available_contexts_for_conn(struct bt_conn *conn,
219 : enum bt_audio_dir dir);
220 :
221 : /**
222 : * @brief Set the supported contexts for an endpoint type
223 : *
224 : * @param dir Direction of the endpoints to change available contexts for.
225 : * @param contexts The contexts to be set.
226 : *
227 : * @return 0 in case of success or negative value in case of error.
228 : */
229 1 : int bt_pacs_set_supported_contexts(enum bt_audio_dir dir,
230 : enum bt_audio_context contexts);
231 :
232 : #ifdef __cplusplus
233 : }
234 : #endif
235 :
236 : /** @} */
237 :
238 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_PACS_H_ */
|
