Line data Source code
1 1 : /**
2 : * @file
3 : * @brief Bluetooth Volume Offset Control Service (VOCS) APIs.
4 : */
5 :
6 : /*
7 : * Copyright (c) 2020-2024 Nordic Semiconductor ASA
8 : *
9 : * SPDX-License-Identifier: Apache-2.0
10 : */
11 :
12 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_VOCS_H_
13 : #define ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_VOCS_H_
14 :
15 : /**
16 : * @brief Volume Offset Control Service (VOCS)
17 : *
18 : * @defgroup bt_vocs Volume Offset Control Service (VOCS)
19 : *
20 : * @since 2.6
21 : * @version 0.8.0
22 : *
23 : * @ingroup bluetooth
24 : * @{
25 : *
26 : * The Volume Offset Control Service is a secondary service, and as such should not be used own its
27 : * own, but rather in the context of another (primary) service.
28 : *
29 : * This API implements both the server and client functionality.
30 : * Note that the API abstracts away the change counter in the volume offset control state and will
31 : * automatically handle any changes to that. If out of date, the client implementation will
32 : * autonomously read the change counter value when executing a write request.
33 : */
34 :
35 : #include <stdint.h>
36 : #include <stdbool.h>
37 :
38 : #include <zephyr/bluetooth/conn.h>
39 :
40 : #ifdef __cplusplus
41 : extern "C" {
42 : #endif
43 :
44 : /**
45 : * @name Volume Offset Control Service Error codes
46 : * @{
47 : */
48 : /**
49 : * The Change_Counter operand value does not match the Change_Counter field value of the Volume
50 : * Offset State characteristic.
51 : */
52 1 : #define BT_VOCS_ERR_INVALID_COUNTER 0x80
53 : /** An invalid opcode has been used in a control point procedure. */
54 1 : #define BT_VOCS_ERR_OP_NOT_SUPPORTED 0x81
55 : /** An operand value used in a control point procedure is outside the permissible range. */
56 1 : #define BT_VOCS_ERR_OUT_OF_RANGE 0x82
57 : /** @} */
58 :
59 : /**
60 : * @name Volume Offset Control Service offset limits
61 : * @{
62 : */
63 : /** Minimum offset value */
64 1 : #define BT_VOCS_MIN_OFFSET -255
65 : /** Maximum offset value */
66 1 : #define BT_VOCS_MAX_OFFSET 255
67 : /** @} */
68 :
69 : /** @brief Opaque Volume Offset Control Service instance. */
70 : struct bt_vocs;
71 :
72 : /** @brief Structure for registering a Volume Offset Control Service instance. */
73 1 : struct bt_vocs_register_param {
74 : /** Audio Location bitmask */
75 1 : uint32_t location;
76 :
77 : /** Boolean to set whether the location is writable by clients */
78 1 : bool location_writable;
79 :
80 : /** Initial volume offset (-255 to 255) */
81 1 : int16_t offset;
82 :
83 : /** Initial audio output description */
84 1 : char *output_desc;
85 :
86 : /** Boolean to set whether the description is writable by clients */
87 1 : bool desc_writable;
88 :
89 : /** Pointer to the callback structure. */
90 1 : struct bt_vocs_cb *cb;
91 : };
92 :
93 : /** @brief Structure for discovering a Volume Offset Control Service instance. */
94 1 : struct bt_vocs_discover_param {
95 : /**
96 : * @brief The start handle of the discovering.
97 : *
98 : * Typically the @p start_handle of a @ref bt_gatt_include.
99 : */
100 1 : uint16_t start_handle;
101 : /**
102 : * @brief The end handle of the discovering.
103 : *
104 : * Typically the @p end_handle of a @ref bt_gatt_include.
105 : */
106 1 : uint16_t end_handle;
107 : };
108 :
109 : /**
110 : * @brief Get a free service instance of Volume Offset Control Service from the pool.
111 : *
112 : * @return Volume Offset Control Service instance in case of success or NULL in case of error.
113 : */
114 1 : struct bt_vocs *bt_vocs_free_instance_get(void);
115 :
116 : /**
117 : * @brief Get the service declaration attribute.
118 : *
119 : * The first service attribute returned can be included in any other GATT service.
120 : *
121 : * @param vocs Volume Offset Control Service instance.
122 : *
123 : * @return Pointer to the attributes of the service.
124 : */
125 1 : void *bt_vocs_svc_decl_get(struct bt_vocs *vocs);
126 :
127 : /**
128 : * @brief Get the connection pointer of a client instance
129 : *
130 : * Get the Bluetooth connection pointer of a Audio Input Control Service
131 : * client instance.
132 : *
133 : * @param vocs Audio Input Control Service client instance pointer.
134 : * @param conn Connection pointer.
135 : *
136 : * @return 0 if success, errno on failure.
137 : */
138 1 : int bt_vocs_client_conn_get(const struct bt_vocs *vocs, struct bt_conn **conn);
139 :
140 : /**
141 : * @brief Register the Volume Offset Control Service instance.
142 : *
143 : * @param vocs Volume Offset Control Service instance.
144 : * @param param Volume Offset Control Service register parameters.
145 : *
146 : * @return 0 if success, errno on failure.
147 : */
148 1 : int bt_vocs_register(struct bt_vocs *vocs,
149 : const struct bt_vocs_register_param *param);
150 :
151 : /**
152 : * @brief Callback function for the offset state.
153 : *
154 : * Called when the value is read, or if the value is changed by either the server or client.
155 : *
156 : * @param inst The instance pointer.
157 : * @param err Error value. 0 on success, GATT error on positive value
158 : * or errno on negative value.
159 : * For notifications, this will always be 0.
160 : * @param offset The offset value.
161 : */
162 1 : typedef void (*bt_vocs_state_cb)(struct bt_vocs *inst, int err, int16_t offset);
163 :
164 : /**
165 : * @brief Callback function for setting offset.
166 : *
167 : * @param inst The instance pointer.
168 : * @param err Error value. 0 on success, GATT error on positive value
169 : * or errno on negative value.
170 : */
171 1 : typedef void (*bt_vocs_set_offset_cb)(struct bt_vocs *inst, int err);
172 :
173 : /**
174 : * @brief Callback function for the location.
175 : *
176 : * Called when the value is read, or if the value is changed by either the server or client.
177 : *
178 : * @param inst The instance pointer.
179 : * @param err Error value. 0 on success, GATT error on positive value
180 : * or errno on negative value.
181 : * For notifications, this will always be 0.
182 : * @param location The location value.
183 : */
184 1 : typedef void (*bt_vocs_location_cb)(struct bt_vocs *inst, int err,
185 : uint32_t location);
186 :
187 : /**
188 : * @brief Callback function for the description.
189 : *
190 : * Called when the value is read, or if the value is changed by either the server or client.
191 : *
192 : * @param inst The instance pointer.
193 : * @param err Error value. 0 on success, GATT error on positive value
194 : * or errno on negative value.
195 : * For notifications, this will always be 0.
196 : * @param description The description as an UTF-8 encoded string.
197 : */
198 1 : typedef void (*bt_vocs_description_cb)(struct bt_vocs *inst, int err,
199 : char *description);
200 :
201 : /**
202 : * @brief Callback function for bt_vocs_discover.
203 : *
204 : * This callback should be overwritten by the primary service that
205 : * includes the Volume Control Offset Service client, and should thus not be
206 : * set by the application.
207 : *
208 : * @param inst The instance pointer.
209 : * @param err Error value. 0 on success, GATT error on positive value
210 : * or errno on negative value.
211 : * For notifications, this will always be 0.
212 : */
213 1 : typedef void (*bt_vocs_discover_cb)(struct bt_vocs *inst, int err);
214 :
215 : /**
216 : * @brief Struct to hold the Volume Offset Control Service callbacks
217 : *
218 : * These can be registered for usage with bt_vocs_client_cb_register() or bt_vocs_register()
219 : * depending on the role.
220 : */
221 1 : struct bt_vocs_cb {
222 : /** The offset state has changed */
223 1 : bt_vocs_state_cb state;
224 : /** The location has changed */
225 1 : bt_vocs_location_cb location;
226 : /** The Description has changed */
227 1 : bt_vocs_description_cb description;
228 :
229 : #if defined(CONFIG_BT_VOCS_CLIENT) || defined(__DOXYGEN__)
230 : /**
231 : * The discovery procedure has completed
232 : *
233 : * Only settable for the client and requires enabling@kconfig{CONFIG_BT_VOCS_CLIENT}.
234 : */
235 1 : bt_vocs_discover_cb discover;
236 : /**
237 : * The set offset procedure has completed
238 : *
239 : * Only settable for the client and requires enabling@kconfig{CONFIG_BT_VOCS_CLIENT}.
240 : */
241 1 : bt_vocs_set_offset_cb set_offset;
242 : #endif /* CONFIG_BT_VOCS_CLIENT */
243 : };
244 :
245 : /**
246 : * @brief Read the Volume Offset Control Service offset state.
247 : *
248 : * The value is returned in the bt_vocs_cb.state callback.
249 : *
250 : * @param inst Pointer to the Volume Offset Control Service instance.
251 : *
252 : * @return 0 on success, GATT error value on fail.
253 : */
254 1 : int bt_vocs_state_get(struct bt_vocs *inst);
255 :
256 : /**
257 : * @brief Set the Volume Offset Control Service offset state.
258 : *
259 : * @param inst Pointer to the Volume Offset Control Service instance.
260 : * @param offset The offset to set (-255 to 255).
261 : *
262 : * @return 0 on success, GATT error value on fail.
263 : */
264 1 : int bt_vocs_state_set(struct bt_vocs *inst, int16_t offset);
265 :
266 : /**
267 : * @brief Read the Volume Offset Control Service location.
268 : *
269 : * The value is returned in the bt_vocs_cb.location callback.
270 : *
271 : * @param inst Pointer to the Volume Offset Control Service instance.
272 : *
273 : * @return 0 on success, GATT error value on fail.
274 : */
275 1 : int bt_vocs_location_get(struct bt_vocs *inst);
276 :
277 : /**
278 : * @brief Set the Volume Offset Control Service location.
279 : *
280 : * @param inst Pointer to the Volume Offset Control Service instance.
281 : * @param location The location to set.
282 : *
283 : * @return 0 on success, GATT error value on fail.
284 : */
285 1 : int bt_vocs_location_set(struct bt_vocs *inst, uint32_t location);
286 :
287 : /**
288 : * @brief Read the Volume Offset Control Service output description.
289 : *
290 : * The value is returned in the bt_vocs_cb.description callback.
291 : *
292 : * @param inst Pointer to the Volume Offset Control Service instance.
293 : *
294 : * @return 0 on success, GATT error value on fail.
295 : */
296 1 : int bt_vocs_description_get(struct bt_vocs *inst);
297 :
298 : /**
299 : * @brief Set the Volume Offset Control Service description.
300 : *
301 : * @param inst Pointer to the Volume Offset Control Service instance.
302 : * @param description The UTF-8 encoded string description to set.
303 : *
304 : * @return 0 on success, GATT error value on fail.
305 : */
306 1 : int bt_vocs_description_set(struct bt_vocs *inst, const char *description);
307 :
308 : /**
309 : * @brief Registers the callbacks for the Volume Offset Control Service client.
310 : *
311 : * @param inst Pointer to the Volume Offset Control Service client instance.
312 : * @param cb Pointer to the callback structure.
313 : */
314 1 : void bt_vocs_client_cb_register(struct bt_vocs *inst, struct bt_vocs_cb *cb);
315 :
316 : /**
317 : * @brief Returns a pointer to a Volume Offset Control Service client instance.
318 : *
319 : * @return Pointer to the instance, or NULL if no free instances are left.
320 : */
321 1 : struct bt_vocs *bt_vocs_client_free_instance_get(void);
322 :
323 : /**
324 : * @brief Discover a Volume Offset Control Service.
325 : *
326 : * Attempts to discover a Volume Offset Control Service on a server given the @p param.
327 : *
328 : * @param conn Connection to the peer with the Volume Offset Control Service.
329 : * @param inst Pointer to the Volume Offset Control Service client instance.
330 : * @param param Pointer to the parameters.
331 : *
332 : * @return 0 on success, errno on fail.
333 : */
334 1 : int bt_vocs_discover(struct bt_conn *conn, struct bt_vocs *inst,
335 : const struct bt_vocs_discover_param *param);
336 :
337 : #ifdef __cplusplus
338 : }
339 : #endif
340 :
341 : /**
342 : * @}
343 : */
344 :
345 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_VOCS_H_ */
|
