Cordio Stack and Cordio Profiles  r2p3-02rel0
l2c_api.h
Go to the documentation of this file.
1 /*************************************************************************************************/
2 /*!
3  * \file
4  *
5  * \brief L2CAP subsystem API.
6  *
7  * Copyright (c) 2009-2018 Arm Ltd. All Rights Reserved.
8  * ARM Ltd. confidential and proprietary.
9  *
10  * IMPORTANT. Your use of this file is governed by a Software License Agreement
11  * ("Agreement") that must be accepted in order to download or otherwise receive a
12  * copy of this file. You may not use or copy this file for any purpose other than
13  * as described in the Agreement. If you do not agree to all of the terms of the
14  * Agreement do not use this file and delete all copies in your possession or control;
15  * if you do not have a copy of the Agreement, you must contact ARM Ltd. prior
16  * to any use, copying or further distribution of this software.
17  */
18 /*************************************************************************************************/
19 #ifndef L2C_API_H
20 #define L2C_API_H
21 
22 #include "dm_api.h"
23 #include "l2c_defs.h"
24 
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28 
29 /*! \addtogroup STACK_L2CAP_API
30  * \{ */
31 
32 /**************************************************************************************************
33  Macros
34 **************************************************************************************************/
35 
36 /** \name L2CAP Control Callback Events
37  * Control callback message events
38  */
39 /**@{*/
40 #define L2C_CTRL_FLOW_ENABLE_IND 0 /*!< \brief Data flow enabled */
41 #define L2C_CTRL_FLOW_DISABLE_IND 1 /*!< \brief Data flow disabled */
42 /**@}*/
43 
44 /*! \brief Invalid channel registration ID for connection oriented channels */
45 #define L2C_COC_REG_ID_NONE 0
46 
47 /*! \brief Invalid channel ID for connection oriented channels */
48 #define L2C_COC_CID_NONE 0
49 
50 /** \name L2CAP COC Channel Roles
51  * Connection oriented channel initiator/acceptor role
52  */
53 /**@{*/
54 #define L2C_COC_ROLE_NONE 0x00 /*!< \brief No role (unallocated) */
55 #define L2C_COC_ROLE_INITIATOR 0x01 /*!< \brief Channel initiator */
56 #define L2C_COC_ROLE_ACCEPTOR 0x02 /*!< \brief Channel acceptor */
57 /**@}*/
58 
59 /** \name L2CAP COC Data Confirm Codes
60  * Connection oriented channel data confirm status values
61  */
62 /**@{*/
63 #define L2C_COC_DATA_SUCCESS 0 /*!< \brief Data request successful */
64 #define L2C_COC_DATA_ERR_MEMORY 1 /*!< \brief Out of memory */
65 #define L2C_COC_DATA_ERR_OVERFLOW 2 /*!< \brief Transaction overflow */
66 /**@}*/
67 
68 /** \name L2CAP COC Callback Events
69  * Connection oriented channel callback events.
70  */
71 /**@{*/
72 #define L2C_COC_CBACK_START 0x70 /*!< \brief L2C callback event starting value */
73 /*! \brief COC callback events */
74 enum
75 {
76  L2C_COC_CONNECT_IND = L2C_COC_CBACK_START, /*!< \brief Channel connect indication */
77  L2C_COC_DISCONNECT_IND, /*!< \brief Channel disconnect indication */
78  L2C_COC_DATA_IND, /*!< \brief Received data indication */
79  L2C_COC_DATA_CNF /*!< \brief Transmit data confirm */
80 };
81 
82 #define L2C_COC_CBACK_CBACK_END L2C_COC_DATA_CNF /*!< \brief L2C callback event ending value */
83 /**@}*/
84 
85 /**************************************************************************************************
86  Data Types
87 **************************************************************************************************/
88 
89 /*! \brief Connection oriented channel registration ID */
91 
92 /*! \brief Connection oriented channel registration structure */
93 typedef struct
94 {
95  uint16_t psm; /*!< \brief Protocol service multiplexer */
96  uint16_t mps; /*!< \brief Maximum receive PDU fragment size */
97  uint16_t mtu; /*!< \brief Maximum receive data packet size */
98  uint16_t credits; /*!< \brief Data packet receive credits for this channel */
99  bool_t authoriz; /*!< \brief TRUE if authorization is required */
100  uint8_t secLevel; /*!< \brief Channel minimum security level requirements */
101  uint8_t role; /*!< \brief Channel initiator/acceptor role */
102 } l2cCocReg_t;
103 
104 /*! \brief Connection oriented channel connect indication structure */
105 typedef struct
106 {
107  wsfMsgHdr_t hdr; /*!< \brief Header structure */
108  uint16_t cid; /*!< \brief Local channel ID */
109  uint16_t peerMtu; /*!< \brief Data packet MTU peer can receive */
110  uint16_t psm; /*!< \brief Connected PSM */
112 
113 /*! \brief Connection oriented channel disconnect indication structure */
114 typedef struct
115 {
116  wsfMsgHdr_t hdr; /*!< \brief Header structure */
117  uint16_t cid; /*!< \brief Local channel ID */
118  uint16_t result; /*!< \brief Connection failure result code */
120 
121 /*! \brief Connection oriented channel data indication structure */
122 typedef struct
123 {
124  wsfMsgHdr_t hdr; /*!< \brief Header structure */
125  uint16_t cid; /*!< \brief Local channel ID */
126  uint8_t *pData; /*!< \brief Pointer to packet data */
127  uint16_t dataLen; /*!< \brief packet data length */
129 
130 /*! \brief Connection oriented channel disconnect indication structure */
131 typedef struct
132 {
133  wsfMsgHdr_t hdr; /*!< \brief Header structure */
134  uint16_t cid; /*!< \brief Local channel ID */
136 
137 /*!
138  * \brief Connection oriented channel event structure
139  *
140  * Connection oriented channel callback header parameters:
141  *
142  * \param hdr.event Callback event
143  * \param hdr.param DM connection ID
144  * \param hdr.status Event status (L2C_COC_DATA_CNF only)
145  */
146 typedef union
147 {
148  wsfMsgHdr_t hdr; /*!< \brief Header structure */
149  l2cCocConnectInd_t connectInd; /*!< \brief Channel connect indication */
150  l2cCocDisconnectInd_t disconnectInd; /*!< \brief Channel disconnect indication */
151  l2cCocDataInd_t dataInd; /*!< \brief Received data indication */
152  l2cCocDataCnf_t dataCnf; /*!< \brief Transmit data confirm */
153 } l2cCocEvt_t;
154 
155 /*! \brief Configurable parameters */
156 typedef struct
157 {
158  uint16_t reqTimeout; /*!< \brief Request timeout in seconds */
159 } l2cCfg_t;
160 
161 /*! \} */ /* STACK_L2CAP_API */
162 
163 /**************************************************************************************************
164  Global Variables;
165 **************************************************************************************************/
166 
167 /*! \addtogroup STACK_INIT
168  * \{ */
169 
170 /** \name L2CAP Configuration Structure
171  * Pointer to structure containing initialization details of the L2CAP Subsystem. To be configured
172  * by Application.
173  */
174 /**@{*/
175 /*! \brief Configuration pointer */
176 extern l2cCfg_t *pL2cCfg;
177 /**@}*/
178 
179 /*! \} */ /* STACK_INIT */
180 
181 /**************************************************************************************************
182  Callback Function Types
183 **************************************************************************************************/
184 
185 /*! \addtogroup STACK_L2CAP_API
186  * \{ */
187 
188 /*************************************************************************************************/
189 /*!
190  * \brief This callback function sends a received L2CAP packet to the client.
191  *
192  * \param handle The connection handle.
193  * \param len The length of the L2CAP payload data in pPacket.
194  * \param pPacket A buffer containing the packet.
195  *
196  * \return None.
197  */
198 /*************************************************************************************************/
199 typedef void (*l2cDataCback_t)(uint16_t handle, uint16_t len, uint8_t *pPacket);
200 
201 /*************************************************************************************************/
202 /*!
203  * \brief This callback function sends control messages to the client.
204  *
205  * \param pMsg Pointer to message structure.
206  *
207  * \return None.
208  */
209 /*************************************************************************************************/
210 typedef void (*l2cCtrlCback_t)(wsfMsgHdr_t *pMsg);
211 
212 /*************************************************************************************************/
213 /*!
214  * \brief This callback function sends data and other events to connection oriented
215  * channels clients.
216  *
217  * \param pMsg Pointer to message structure.
218  *
219  * \return None.
220  */
221 /*************************************************************************************************/
222 typedef void (*l2cCocCback_t)(l2cCocEvt_t *pMsg);
223 
224 /*************************************************************************************************/
225 /*!
226  * \brief This callback function is used for authoriztion of connection oriented channels.
227  *
228  * \param connId DM connection ID.
229  * \param regId The registration instance requiring authorization.
230  * \param psm The PSM of the registration instance.
231  *
232  * \return L2C_CONN_SUCCESS if authorization is successful, any other value for failure.
233  */
234 /*************************************************************************************************/
235 typedef uint16_t (*l2cCocAuthorCback_t)(dmConnId_t connId, l2cCocRegId_t regId, uint16_t psm);
236 
237 /**************************************************************************************************
238  Function Declarations
239 **************************************************************************************************/
240 
241 /** \name L2CAP Initialization
242  * Initialization and registration functions
243  */
244 /**@{*/
245 
246 /*************************************************************************************************/
247 /*!
248  * \brief Initialize L2C subsystem.
249  *
250  * \return None.
251  */
252 /*************************************************************************************************/
253 void L2cInit(void);
254 
255 /*************************************************************************************************/
256 /*!
257  * \brief Initialize L2C for operation as a Bluetooth LE master.
258  *
259  * \return None.
260  */
261 /*************************************************************************************************/
262 void L2cMasterInit(void);
263 
264 /*************************************************************************************************/
265 /*!
266  * \brief Initialize L2C for operation as a Bluetooth LE slave.
267  *
268  * \return None.
269  */
270 /*************************************************************************************************/
271 void L2cSlaveInit(void);
272 
273 /**@}*/
274 
275 /** \name L2CAP CID Functions
276  * Register and send data over a CID
277  */
278 /**@{*/
279 
280 /*************************************************************************************************/
281 /*!
282  * \brief called by the L2C client, such as ATT or SMP, to register for the given CID.
283  *
284  * \param cid channel identifier.
285  * \param dataCback Callback function for L2CAP data received for this CID.
286  * \param ctrlCback Callback function for control events for this CID.
287  *
288  * \return None.
289  */
290 /*************************************************************************************************/
291 void L2cRegister(uint16_t cid, l2cDataCback_t dataCback, l2cCtrlCback_t ctrlCback);
292 
293 
294 /*************************************************************************************************/
295 /*!
296  * \brief Send an L2CAP data packet on the given CID.
297  *
298  * \param cid The channel identifier.
299  * \param handle The connection handle. The client receives this handle from DM.
300  * \param len The length of the payload data in pPacket.
301  * \param pL2cPacket A buffer containing the packet.
302  *
303  * \return None.
304  */
305 /*************************************************************************************************/
306 void L2cDataReq(uint16_t cid, uint16_t handle, uint16_t len, uint8_t *pL2cPacket);
307 
308 /**@}*/
309 
310 /** \name L2CAP COC Functions
311  * Connection Oriented Channels Functions
312  */
313 /**@{*/
314 
315 /*************************************************************************************************/
316 /*!
317  * \brief Initialize L2C connection oriented channel subsystem.
318  *
319  * \return None.
320  */
321 /*************************************************************************************************/
322 void L2cCocInit(void);
323 
324 /*************************************************************************************************/
325 /*!
326  * \brief Register to use a connection oriented channel, as either a channel acceptor,
327  * initiator, or both. If registering as channel acceptor then the PSM is specified.
328  * After registering a connection can be established by the client using this
329  * registration instance.
330  *
331  * \param cback Client callback function.
332  * \param pReg Registration parameter structure.
333  *
334  * \return Registration instance ID or L2C_COC_REG_ID_NONE if registration failed.
335  */
336 /*************************************************************************************************/
337 l2cCocRegId_t L2cCocRegister(l2cCocCback_t cback, l2cCocReg_t *pReg);
338 
339 /*************************************************************************************************/
340 /*!
341  * \brief Deregister and deallocate a connection oriented channel registration instance.
342  * This function should only be called if there are no active channels using this
343  * registration instance.
344  *
345  * \param regId Registration instance ID.
346  *
347  * \return None.
348  */
349 /*************************************************************************************************/
350 void L2cCocDeregister(l2cCocRegId_t regId);
351 
352 /*************************************************************************************************/
353 /*!
354  * \brief Initiate a connection to the given peer PSM.
355  *
356  * \param connId DM connection ID.
357  * \param regId The associated registration instance.
358  * \param psm Peer PSM.
359  *
360  * \return Local CID or L2C_COC_CID_NONE none if failure.
361  */
362 /*************************************************************************************************/
363 uint16_t L2cCocConnectReq(dmConnId_t connId, l2cCocRegId_t regId, uint16_t psm);
364 
365 /*************************************************************************************************/
366 /*!
367  * \brief Disconnect the channel for the given CID.
368  *
369  * \param cid Channel ID.
370  *
371  * \return None.
372  */
373 /*************************************************************************************************/
374 void L2cCocDisconnectReq(uint16_t cid);
375 
376 /*************************************************************************************************/
377 /*!
378  * \brief Send an L2CAP data packet on the given connection oriented CID.
379  *
380  * \param cid The local channel identifier.
381  * \param len The length of the payload data in pPacket.
382  * \param pPayload Packet payload data.
383  *
384  * \return None.
385  */
386 /*************************************************************************************************/
387 void L2cCocDataReq(uint16_t cid, uint16_t len, uint8_t *pPayload);
388 
389 /*************************************************************************************************/
390 /*!
391  * \brief For testing purposes only.
392  *
393  * \param result Result code
394  *
395  * \return None.
396  */
397 /*************************************************************************************************/
398 void L2cCocErrorTest(uint16_t result);
399 
400 /*************************************************************************************************/
401 /*!
402  * \brief For testing purposes only.
403  *
404  * \param cid The local channel identifier.
405  * \param credits Credits to send.
406  *
407  * \return None.
408  */
409 /*************************************************************************************************/
410 void L2cCocCreditSendTest(uint16_t cid, uint16_t credits);
411 
412 /**@}*/
413 
414 /** \name L2CAP Connection Parameter Update Functions
415  *
416  */
417 /**@{*/
418 
419 /*************************************************************************************************/
420 /*!
421  * \brief For internal use only. This function is called by DM to send an L2CAP
422  * connection update request.
423  *
424  * \param handle The connection handle.
425  * \param pConnSpec Pointer to the connection specification structure.
426  *
427  * \return None.
428  */
429 /*************************************************************************************************/
430 void L2cDmConnUpdateReq(uint16_t handle, hciConnSpec_t *pConnSpec);
431 
432 /*************************************************************************************************/
433 /*!
434  * \brief For internal use only. This function is called by DM to send an L2CAP
435  * connection update response.
436  *
437  * \param identifier Identifier value previously passed from L2C to DM.
438  * \param handle The connection handle.
439  * \param result Connection update response result.
440  *
441  * \return None.
442  */
443 /*************************************************************************************************/
444 void L2cDmConnUpdateRsp(uint8_t identifier, uint16_t handle, uint16_t result);
445 
446 /**@}*/
447 
448 /*! \} */ /*! STACK_L2CAP_API */
449 
450 #ifdef __cplusplus
451 };
452 #endif
453 
454 #endif /* L2C_API_H */
void L2cDataReq(uint16_t cid, uint16_t handle, uint16_t len, uint8_t *pL2cPacket)
Send an L2CAP data packet on the given CID.
Connection oriented channel registration structure.
Definition: l2c_api.h:93
void L2cInit(void)
Initialize L2C subsystem.
uint16_t dataLen
packet data length
Definition: l2c_api.h:127
uint8_t dmConnId_t
Connection identifier.
Definition: dm_api.h:501
void(* l2cCocCback_t)(l2cCocEvt_t *pMsg)
This callback function sends data and other events to connection oriented channels clients...
Definition: l2c_api.h:222
void L2cCocDataReq(uint16_t cid, uint16_t len, uint8_t *pPayload)
Send an L2CAP data packet on the given connection oriented CID.
void L2cCocCreditSendTest(uint16_t cid, uint16_t credits)
For testing purposes only.
void L2cDmConnUpdateRsp(uint8_t identifier, uint16_t handle, uint16_t result)
For internal use only. This function is called by DM to send an L2CAP connection update response...
void L2cCocDisconnectReq(uint16_t cid)
Disconnect the channel for the given CID.
wsfMsgHdr_t hdr
Header structure.
Definition: l2c_api.h:107
void(* l2cDataCback_t)(uint16_t handle, uint16_t len, uint8_t *pPacket)
This callback function sends a received L2CAP packet to the client.
Definition: l2c_api.h:199
uint8_t bool_t
Boolean data type.
Definition: wsf_types.h:78
uint16_t L2cCocConnectReq(dmConnId_t connId, l2cCocRegId_t regId, uint16_t psm)
Initiate a connection to the given peer PSM.
uint16_t(* l2cCocAuthorCback_t)(dmConnId_t connId, l2cCocRegId_t regId, uint16_t psm)
This callback function is used for authoriztion of connection oriented channels.
Definition: l2c_api.h:235
uint8_t role
Channel initiator/acceptor role.
Definition: l2c_api.h:101
bool_t authoriz
TRUE if authorization is required.
Definition: l2c_api.h:99
l2cCocDisconnectInd_t disconnectInd
Channel disconnect indication.
Definition: l2c_api.h:150
uint16_t cid
Local channel ID.
Definition: l2c_api.h:125
Connection oriented channel disconnect indication structure.
Definition: l2c_api.h:114
Received data indication.
Definition: l2c_api.h:78
Connection oriented channel connect indication structure.
Definition: l2c_api.h:105
wsfMsgHdr_t hdr
Header structure.
Definition: l2c_api.h:124
l2cCocConnectInd_t connectInd
Channel connect indication.
Definition: l2c_api.h:149
Connection oriented channel event structure.
Definition: l2c_api.h:146
L2CAP constants and definitions from the Bluetooth specification.
void L2cCocInit(void)
Initialize L2C connection oriented channel subsystem.
Transmit data confirm.
Definition: l2c_api.h:79
uint8_t secLevel
Channel minimum security level requirements.
Definition: l2c_api.h:100
Configurable parameters.
Definition: l2c_api.h:156
l2cCocRegId_t L2cCocRegister(l2cCocCback_t cback, l2cCocReg_t *pReg)
Register to use a connection oriented channel, as either a channel acceptor, initiator, or both. If registering as channel acceptor then the PSM is specified. After registering a connection can be established by the client using this registration instance.
l2cCocDataInd_t dataInd
Received data indication.
Definition: l2c_api.h:151
void(* l2cCtrlCback_t)(wsfMsgHdr_t *pMsg)
This callback function sends control messages to the client.
Definition: l2c_api.h:210
Connection specification type.
Definition: hci_api.h:641
uint16_t l2cCocRegId_t
Connection oriented channel registration ID.
Definition: l2c_api.h:90
uint16_t credits
Data packet receive credits for this channel.
Definition: l2c_api.h:98
void L2cSlaveInit(void)
Initialize L2C for operation as a Bluetooth LE slave.
uint16_t mps
Maximum receive PDU fragment size.
Definition: l2c_api.h:96
Connection oriented channel data indication structure.
Definition: l2c_api.h:122
uint8_t * pData
Pointer to packet data.
Definition: l2c_api.h:126
l2cCocDataCnf_t dataCnf
Transmit data confirm.
Definition: l2c_api.h:152
void L2cCocErrorTest(uint16_t result)
For testing purposes only.
uint16_t cid
Local channel ID.
Definition: l2c_api.h:108
uint16_t reqTimeout
Request timeout in seconds.
Definition: l2c_api.h:158
Device Manager subsystem API.
void L2cRegister(uint16_t cid, l2cDataCback_t dataCback, l2cCtrlCback_t ctrlCback)
called by the L2C client, such as ATT or SMP, to register for the given CID.
Channel connect indication.
Definition: l2c_api.h:76
Connection oriented channel disconnect indication structure.
Definition: l2c_api.h:131
unsigned short uint16_t
Unsigned 16-bit value.
Definition: wsf_types.h:67
uint16_t psm
Connected PSM.
Definition: l2c_api.h:110
wsfMsgHdr_t hdr
Header structure.
Definition: l2c_api.h:116
void L2cDmConnUpdateReq(uint16_t handle, hciConnSpec_t *pConnSpec)
For internal use only. This function is called by DM to send an L2CAP connection update request...
uint16_t psm
Protocol service multiplexer.
Definition: l2c_api.h:95
uint16_t mtu
Maximum receive data packet size.
Definition: l2c_api.h:97
uint16_t cid
Local channel ID.
Definition: l2c_api.h:117
void L2cCocDeregister(l2cCocRegId_t regId)
Deregister and deallocate a connection oriented channel registration instance. This function should o...
wsfMsgHdr_t hdr
Header structure.
Definition: l2c_api.h:133
uint16_t peerMtu
Data packet MTU peer can receive.
Definition: l2c_api.h:109
uint16_t result
Connection failure result code.
Definition: l2c_api.h:118
wsfMsgHdr_t hdr
Header structure.
Definition: l2c_api.h:148
void L2cMasterInit(void)
Initialize L2C for operation as a Bluetooth LE master.
Common message structure passed to event handler.
Definition: wsf_os.h:97
#define L2C_COC_CBACK_START
L2C callback event starting value.
Definition: l2c_api.h:72
uint16_t cid
Local channel ID.
Definition: l2c_api.h:134
unsigned char uint8_t
Unsigned 8-bit value.
Definition: wsf_types.h:63
l2cCfg_t * pL2cCfg
Configuration pointer.
Channel disconnect indication.
Definition: l2c_api.h:77