1 /*
2  * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #ifndef __ESP_L2CAP_BT_API_H__
8 #define __ESP_L2CAP_BT_API_H__
9 
10 #include "esp_err.h"
11 #include "esp_bt_defs.h"
12 
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16 
17 /**
18  * @brief L2CAP operation success and failure codes
19  */
20 typedef enum {
21     ESP_BT_L2CAP_SUCCESS   = 0,          /*!< Successful operation. */
22     ESP_BT_L2CAP_FAILURE,                /*!< Generic failure. */
23     ESP_BT_L2CAP_BUSY,                   /*!< Temporarily can not handle this request. */
24     ESP_BT_L2CAP_NO_RESOURCE,            /*!< No more resource */
25     ESP_BT_L2CAP_NEED_INIT,              /*!< L2CAP module shall init first */
26     ESP_BT_L2CAP_NEED_DEINIT,            /*!< L2CAP module shall deinit first */
27     ESP_BT_L2CAP_NO_CONNECTION,          /*!< Connection may have been closed */
28     ESP_BT_L2CAP_NO_SERVER,              /*!< No server */
29 } esp_bt_l2cap_status_t;
30 
31 /**
32  * @brief Security Setting Mask. Use these three mask mode:
33  *        1. ESP_BT_L2CAP_SEC_NONE
34  *        2. ESP_BT_L2CAP_SEC_AUTHENTICATE
35  *        3. (ESP_BT_L2CAP_SEC_ENCRYPT|ESP_BT_L2CAP_SEC_AUTHENTICATE)
36  */
37 #define ESP_BT_L2CAP_SEC_NONE            0x0000    /*!< No security */
38 #define ESP_BT_L2CAP_SEC_AUTHORIZE       0x0001    /*!< Authorization required */
39 #define ESP_BT_L2CAP_SEC_AUTHENTICATE    0x0012    /*!< Authentication required */
40 #define ESP_BT_L2CAP_SEC_ENCRYPT         0x0024    /*!< Encryption required */
41 typedef uint32_t esp_bt_l2cap_cntl_flags_t;
42 
43 /**
44  * @brief L2CAP callback function events
45  */
46 typedef enum {
47     ESP_BT_L2CAP_INIT_EVT                 = 0,      /*!< When L2CAP is initialized, the event comes */
48     ESP_BT_L2CAP_UNINIT_EVT               = 1,      /*!< When L2CAP is deinitialized, the event comes */
49     ESP_BT_L2CAP_OPEN_EVT                 = 16,     /*!< When L2CAP Client connection open, the event comes */
50     ESP_BT_L2CAP_CLOSE_EVT                = 17,     /*!< When L2CAP connection closed, the event comes */
51     ESP_BT_L2CAP_START_EVT                = 18,     /*!< When L2CAP server started, the event comes */
52     ESP_BT_L2CAP_CL_INIT_EVT              = 19,     /*!< When L2CAP client initiated a connection, the event comes */
53     ESP_BT_L2CAP_SRV_STOP_EVT             = 36,     /*!< When L2CAP server stopped, the event comes */
54 } esp_bt_l2cap_cb_event_t;
55 
56 /**
57  * @brief L2CAP callback parameters union
58  */
59 typedef union {
60     /**
61      * @brief ESP_BT_L2CAP_INIT_EVT
62      */
63     struct l2cap_init_evt_param {
64         esp_bt_l2cap_status_t  status;         /*!< status */
65     } init;                                    /*!< L2CAP callback param of ESP_BT_L2CAP_INIT_EVT */
66 
67     /**
68      * @brief ESP_BT_L2CAP_UNINIT_EVT
69      */
70     struct l2cap_uninit_evt_param {
71         esp_bt_l2cap_status_t  status;         /*!< status */
72     } uninit;                                  /*!< L2CAP callback param of ESP_BT_L2CAP_UNINIT_EVT */
73 
74     /**
75      * @brief ESP_BT_L2CAP_OPEN_EVT
76      */
77     struct l2cap_open_evt_param {
78         esp_bt_l2cap_status_t  status;         /*!< status */
79         uint32_t               handle;         /*!< The connection handle */
80         int                    fd;             /*!< File descriptor  */
81         esp_bd_addr_t          rem_bda;        /*!< The peer address */
82         int32_t                tx_mtu;         /*!< The transmit MTU */
83     } open;                                    /*!< L2CAP callback param of ESP_BT_L2CAP_OPEN_EVT */
84 
85     /**
86      * @brief ESP_BT_L2CAP_CLOSE_EVT
87      */
88     struct l2cap_close_evt_param {
89         esp_bt_l2cap_status_t  status;         /*!< status */
90         uint32_t               handle;         /*!< The connection handle */
91         bool                   async;          /*!< FALSE, if local initiates disconnect */
92     } close;                                   /*!< L2CAP callback param of ESP_BT_L2CAP_CLOSE_EVT */
93 
94     /**
95      * @brief ESP_BT_L2CAP_START_EVT
96      */
97     struct l2cap_start_evt_param {
98         esp_bt_l2cap_status_t  status;         /*!< status */
99         uint32_t               handle;         /*!< The connection handle */
100         uint8_t                sec_id;         /*!< security ID used by this server */
101     } start;                                   /*!< L2CAP callback param of ESP_BT_L2CAP_START_EVT */
102 
103     /**
104      * @brief ESP_BT_L2CAP_CL_INIT_EVT
105      */
106     struct l2cap_cl_init_evt_param {
107         esp_bt_l2cap_status_t  status;         /*!< status */
108         uint32_t               handle;         /*!< The connection handle */
109         uint8_t                sec_id;         /*!< security ID used by this server */
110     } cl_init;                                 /*!< L2CAP callback param of ESP_BT_L2CAP_CL_INIT_EVT */
111 
112     /**
113      * @brief ESP_BT_L2CAP_SRV_STOP_EVT
114      */
115     struct l2cap_srv_stop_evt_param {
116         esp_bt_l2cap_status_t  status;         /*!< status */
117         uint8_t                psm;            /*!< local psm */
118     } srv_stop;                                /*!< L2CAP callback param of ESP_BT_L2CAP_SRV_STOP_EVT */
119 
120 } esp_bt_l2cap_cb_param_t;
121 
122 /**
123  * @brief       L2CAP callback function type.
124  *
125  * @param       event:      Event type
126  * @param       param:      Point to callback parameter, currently is union type
127  */
128 typedef void (* esp_bt_l2cap_cb_t)(esp_bt_l2cap_cb_event_t event, esp_bt_l2cap_cb_param_t *param);
129 
130 /**
131  * @brief       This function is called to init callbacks with L2CAP module.
132  *
133  * @param[in]   callback:   pointer to the init callback function.
134  *
135  * @return
136  *              - ESP_OK: success
137  *              - other: failed
138  */
139 esp_err_t esp_bt_l2cap_register_callback(esp_bt_l2cap_cb_t callback);
140 
141 /**
142  * @brief       This function is called to init L2CAP module.
143  *              When the operation is completed, the callback function will be called with ESP_BT_L2CAP_INIT_EVT.
144  *              This function should be called after esp_bluedroid_enable() completes successfully.
145  *
146  * @return
147  *              - ESP_OK: success
148  *              - other: failed
149  */
150 esp_err_t esp_bt_l2cap_init(void);
151 
152 /**
153  * @brief       This function is called to uninit l2cap module.
154  *              The operation will close all active L2CAP connection first, then the callback function will be called
155  *              with ESP_BT_L2CAP_CLOSE_EVT, and the number of ESP_BT_L2CAP_CLOSE_EVT is equal to the number of connection.
156  *              When the operation is completed, the callback function will be called with ESP_BT_L2CAP_UNINIT_EVT.
157  *              This function should be called after esp_bt_l2cap_init() completes successfully.
158  *
159  * @return
160  *              - ESP_OK: success
161  *              - other: failed
162  */
163 esp_err_t esp_bt_l2cap_deinit(void);
164 
165 /**
166  * @brief       This function makes an L2CAP connection to a remote BD Address.
167  *              When the connection is initiated or failed to initiate, the callback is called with ESP_BT_L2CAP_CL_INIT_EVT.
168  *              When the connection is established or failed, the callback is called with ESP_BT_L2CAP_OPEN_EVT.
169  *              This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().
170  *
171  * @param[in]   cntl_flag:    Lower 16-bit security settings mask.
172  * @param[in]   remote_psm:   Remote device bluetooth Profile PSM.
173  * @param[in]   peer_bd_addr: Remote device bluetooth device address.
174  *
175  * @return
176  *              - ESP_OK: success
177  *              - other: failed
178  */
179 esp_err_t esp_bt_l2cap_connect(esp_bt_l2cap_cntl_flags_t cntl_flag, uint16_t remote_psm, esp_bd_addr_t peer_bd_addr);
180 
181 /**
182  * @brief       This function create a L2CAP server and starts listening for an
183  *              L2CAP connection request from a remote Bluetooth device.
184  *              When the server is started successfully, the callback is called with ESP_BT_L2CAP_START_EVT.
185  *              When the connection is established, the callback is called with ESP_BT_L2CAP_OPEN_EVT.
186  *              This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().
187  *
188  * @param[in]   cntl_flag:    Lower 16-bit security settings mask.
189  * @param[in]   local_psm:    Dynamic PSM.
190  *
191  * @return
192  *              - ESP_OK: success
193  *              - other: failed
194  */
195 esp_err_t esp_bt_l2cap_start_srv(esp_bt_l2cap_cntl_flags_t cntl_flag, uint16_t local_psm);
196 
197 /**
198  * @brief       This function stops all L2CAP servers.
199  *              The operation will close all active L2CAP connection first, then the callback function will be called
200  *              with ESP_BT_L2CAP_CLOSE_EVT, and the number of ESP_BT_L2CAP_CLOSE_EVT is equal to the number of connection.
201  *              When the operation is completed, the callback is called with ESP_BT_L2CAP_SRV_STOP_EVT.
202  *              This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().
203  *
204  * @return
205  *              - ESP_OK: success
206  *              - other: failed
207  */
208 
209 esp_err_t esp_bt_l2cap_stop_all_srv(void);
210 
211 /**
212  * @brief       This function stops a specific L2CAP server.
213  *              The operation will close all active L2CAP connection first on the specific L2CAP server, then the callback function will
214  *              be called with ESP_BT_L2CAP_CLOSE_EVT, and the number of ESP_BT_L2CAP_CLOSE_EVT is equal to the number of connection.
215  *              When the operation is completed, the callback is called with ESP_BT_L2CAP_SRV_STOP_EVT.
216  *              This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().
217  *
218  * @param[in]   local_psm:    Dynamic PSM.
219  *
220  * @return
221  *              - ESP_OK: success
222  *              - other: failed
223  */
224 esp_err_t esp_bt_l2cap_stop_srv(uint16_t local_psm);
225 
226 /**
227  * @brief       This function is used to register VFS.
228  *              Only supports write, read and close.
229  *              This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().
230  *
231  * @return
232  *              - ESP_OK: success
233  *              - other: failed
234  */
235 esp_err_t esp_bt_l2cap_vfs_register(void);
236 
237 /**
238  * @brief       This function is used to unregister VFS.
239  *              This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().
240  *
241  * @return
242  *              - ESP_OK: success
243  *              - other: failed
244  */
245 esp_err_t esp_bt_l2cap_vfs_unregister(void);
246 
247 #ifdef __cplusplus
248 }
249 #endif
250 
251 #endif ///__ESP_L2CAP_BT_API_H__
252