ble_audio.h
Go to the documentation of this file.
1 /**
2 ****************************************************************************************
3 *
4 * @file ble_audio.h
5 *
6 * @brief BLE Audio API
7 *
8 ****************************************************************************************
9 * @attention
10 #####Copyright (c) 2019 GOODIX
11 All rights reserved.
12
13 Redistribution and use in source and binary forms, with or without
14 modification, are permitted provided that the following conditions are met:
15 * Redistributions of source code must retain the above copyright
16 notice, this list of conditions and the following disclaimer.
17 * Redistributions in binary form must reproduce the above copyright
18 notice, this list of conditions and the following disclaimer in the
19 documentation and/or other materials provided with the distribution.
20 * Neither the name of GOODIX nor the names of its contributors may be used
21 to endorse or promote products derived from this software without
22 specific prior written permission.
23
24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 POSSIBILITY OF SUCH DAMAGE.
35 *****************************************************************************************
36 */
37 #ifndef __BLE_AUDIO_H__
38 #define __BLE_AUDIO_H__
39
40 #if (CFG_SNIFFER)
41
42 /**
43 * @addtogroup BLE
44 * @{
45 * @brief Definitions and prototypes for the BLE SDK interface.
46 */
47
48 /**
49 * @addtogroup BLE_AUDIO Audio Library
50 * @{
51 * @brief Definitions and prototypes for the Audio Application interface.
52 */
53
54 #include "ble_gapc.h"
55 #include "ble_error.h"
56
57 #include <stdint.h> // Standard Integer
58 #include <string.h>
59 #include <stdbool.h>
60
61 /**
62 * @defgroup BLE_AUDIO_ENUM Enumerations
63 * @{
64 */
65 /** @brief Switch role type */
66 typedef enum
67 {
68 AUDIO_SWITCH_ROLE_SINK_TYPE = 1 << 0, /**< Switch role for sink link. */
69 AUDIO_SWITCH_ROLE_SNIFFER_TYPE = 1 << 1, /**< Switch role for sniffer link. */
70 } audio_switch_role_type_t;
71
72 /**
73 * @brief Definition of operation code used in the asynchronous operations
74 */
75 typedef enum
76 {
77 AUDIO_OPCODE_SWITCH_ROLE, /**< Switch Role. */
78 AUDIO_OPCODE_TIME_SYNC, /**< Time Sync. */
79 AUDIO_OPCODE_CREATE_SNIFFER, /**<Create Sniffer. */
80 AUDIO_OPCODE_SYNC_INFO, /**<Sync info. */
81 AUDIO_OPCODE_READ_EVENT_COUNT, /**<Read event count. */
82 } audio_op_id_t;
83
84 /**@brief Synchronization information type. */
85 typedef enum
86 {
87 SYNC_INFO_LECB_CONN = 0x00, /**< Synchronize lecb connection information. */
88 SYNC_INFO_LECB_CREDIT, /**< Synchronize lecb credit information. */
89 SYNC_INFO_SEC, /**< Synchronize security information. */
90 } audio_sync_info_type_t;
91 /** @} */
92
93 /**
94 * @defgroup BLE_AUDIO_STRUCT Structures
95 * @{
96 */
97 /** @brief Command Complete Event structure. */
98 typedef struct
99 {
100 audio_op_id_t op_id; /**< Operation code. @see audio_op_id_t */
101 uint16_t error_code; /**< Error code. @see uint16_t */
102 } audio_op_cmp_evt_t;
103
104 /** @brief Switch Role Indication structure. */
105 typedef struct
106 {
107 uint8_t switch_type; /**< Switch role type. */
108 } audio_switch_role_ind_t;
109
110 /** @brief Structure for LE Credit Based Connection Created indication. */
111 typedef struct
112 {
113 uint8_t status; /**< Status. */
114 uint16_t le_psm; /**< Le_psm number. */
115 uint16_t local_cid; /**< The local source channel id. */
116 uint16_t peer_credits; /**< It indicates the number of LE-frames that the peer device can receive. */
117 uint16_t peer_mtu; /**< It indicates the maximum SDU size (in octets) that the L2CAP layer entity sending the LE Credit Based Connection Request can receive on this channel. */
118 uint16_t peer_mps; /**< It indicates the maximum payload size (in octets) that the L2CAP layer entity sending the LE Credit Based Connection Request is capable of receiving on this channe. */
119 } audio_lecb_conn_ind_t;
120
121 /** @brief Structure for event count indication. */
122 typedef struct
123 {
124 uint16_t event_count; /**< Event count number. */
125 } audio_event_count_ind_t;
126
127 /** @brief Audio Callback function structure. */
128 typedef struct
129 {
130 /**@brief This callback function is called when the cmd has completed.
131 * @param[in] conidx Connection index for connection control operations. It is set to zero for non-connection operations.
132 * @param[in] param Info of the operation. @see audio_op_cmp_evt_t
133 */
134 void (*app_audio_opera_cmp_evt_cb)(uint8_t conidx, const audio_op_cmp_evt_t *param);
135
136 /**@brief This callback function is called when receiving Sniffer Created indication.
137 * @param[in] conidx Connection index.
138 * @param[in] param Connection info. @see gap_conn_cmp_t
139 */
140 void (*app_audio_sniffer_created_ind_cb)(uint8_t conidx, const gap_conn_cmp_t *param);
141
142 /**@brief This callback function will be called when switch role has completed.
143 * @param[in] conidx Connection index.
144 * @param[in] param Switch role info. @see audio_switch_role_ind_t
145 */
146 void (*app_audio_rcv_switch_role_ind_cb)(uint8_t conidx, const audio_switch_role_ind_t *param);
147
148 /**@brief This callback function is called when receiving the sync information of LE Credit Based connection.
149 * @param[in] conidx Connection index.
150 * @param[in] param LE Credit Based Connection information. @see audio_lecb_conn_ind_t
151 */
152 void (*app_audio_rcv_sync_lecb_ind_cb)(uint8_t conidx, audio_lecb_conn_ind_t *param);
153
154 /**@brief This callback function is called when receiving the event count indication.
155 * @param[in] conidx Connection index.
156 * @param[in] param Event count info. @see audio_event_count_ind_t
157 */
158 void (*app_audio_rcv_event_count_ind_cb)(uint8_t conidx, audio_event_count_ind_t *param);
159
160 }audio_cb_fun_t;
161 /** @} */
162
163 /**
164 * @defgroup BLE_AUDIO_FUNCTION Functions
165 * @{
166 */
167 /**
168 ****************************************************************************************
169 * @brief Register the callback function.
170 * @note When APP is initialized, this function should be called, and the parameter cb must point to a global.
171 *
172 * @param[in] cb: Pointer to the Callback function.
173 ****************************************************************************************
174 */
175 void ble_audio_callback_register(audio_cb_fun_t* cb);
176
177 /**
178 ****************************************************************************************
179 * @brief Switch role.
180 *
181 * @param[in] conidx: Connection index.
182 * @param[in] switch_type: Swich role type, @see audio_switch_role_type_t
183 *
184 * @retval uint16_t @see uint16_t
185 ****************************************************************************************
186 */
187 uint16_t ble_audio_role_switch(uint8_t conidx, uint8_t switch_type);
188
189 /**
190 ****************************************************************************************
191 * @brief Time Sync
192 *
193 * @param[in] conidx: Connection index.
194 * @param[in] time_sync_en: Enable time sync.
195 * @param[in] sync_pulse_sel: Synchronization pulse selection.
196 *
197 * @retval uint16_t @see uint16_t
198 ****************************************************************************************
199 */
200 uint16_t ble_audio_time_sync(uint8_t conidx, uint8_t time_sync_en, uint8_t sync_pulse_sel);
201
202
203 /**
204 ****************************************************************************************
205 * @brief Create sniffer link.
206 *
207 * @param[in] source_connidx: Connection index for the source link (between active headset and phone).
208 * @param[in] sink_connidx: Connection index for the sink link (between left headset and right headset).
209 *
210 * @note This API is asynchronous.
211 * @note app_audio_rcv_sniffer_created_cmp_cb (see @ref audio_cb_fun_t)
212 * will be called once the operation has completed.
213 ****************************************************************************************
214 */
215 uint16_t ble_audio_sniffer_create(uint8_t source_connidx, uint8_t sink_connidx);
216
217
218 /**
219 ****************************************************************************************
220 * @brief Synchronization information for the peer audio device.
221 *
222 * @param[in] sync_info_type: Synchronization information type.
223 * @param[in] source_connidx: Connection index for the source link.
224 * @param[in] sink_connidx: Connection index for the sink link.
225 *
226 * @retval ::SDK_SUCCESS Synchronization information type is successfully set to the BLE stack.
227 * @retval ::SDK_ERR_INVALID_PARAM The parameter is invalid, such as the source_connidx or sink_connidx is invalid value.
228 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
229 ****************************************************************************************
230 */
231 uint16_t ble_audio_sync_info_send (audio_sync_info_type_t sync_info_type, uint8_t source_connidx, uint8_t sink_connidx);
232
233 /**
234 ****************************************************************************************
235 * @brief Read event count.
236 *
237 * @param[in] connidx: Connection index for the link.
238 *
239 * @note This API is asynchronous.
240 *
241 * @retval ::SDK_SUCCESS Operation is successfully set to the BLE stack.
242 * @retval ::SDK_ERR_INVALID_PARAM The parameter is invalid, such as the connidx invalid value.
243 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
244 ****************************************************************************************
245 */
246 uint16_t ble_audio_event_count_read(uint8_t connidx);
247 /** @} */
248 /** @} */
249 /** @} */
250
251 #endif //#if (CFG_SNIFFER)
252 #endif //#ifndef __BLE_AUDIO_H__
ble_error.h
File that contains error codes.
ble_gapc.h
BLE GAPC API.