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.