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 struct bt_pacs_cap { 41 /** Codec capability reference */ 42 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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_PROHIBITED if @p conn or @p dir are invalid 217 */ 218 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 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_ */ 239
