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_ */
