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

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.