• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /******************************************************************************
2  *
3  *  Copyright 2009-2013 Broadcom Corporation
4  *
5  *  Licensed under the Apache License, Version 2.0 (the "License");
6  *  you may not use this file except in compliance with the License.
7  *  You may obtain a copy of the License at:
8  *
9  *  http://www.apache.org/licenses/LICENSE-2.0
10  *
11  *  Unless required by applicable law or agreed to in writing, software
12  *  distributed under the License is distributed on an "AS IS" BASIS,
13  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  *  See the License for the specific language governing permissions and
15  *  limitations under the License.
16  *
17  ******************************************************************************/
18 
19 #ifndef GAP_API_H
20 #define GAP_API_H
21 
22 #include "btm_api.h"
23 #include "l2c_api.h"
24 #include "profiles_api.h"
25 
26 /*****************************************************************************
27  *  Constants
28  ****************************************************************************/
29 /*** GAP Error and Status Codes ***/
30 /* Unsupported call */
31 #define GAP_UNSUPPORTED (GAP_ERR_GRP + 0x01)
32 /* End of inquiry database marker */
33 #define GAP_EOINQDB (GAP_ERR_GRP + 0x02)
34 /* The requested function was busy */
35 #define GAP_ERR_BUSY (GAP_ERR_GRP + 0x03)
36 /* No control blocks available */
37 #define GAP_ERR_NO_CTRL_BLK (GAP_ERR_GRP + 0x04)
38 /* Error occurred while initiating the command */
39 #define GAP_ERR_STARTING_CMD (GAP_ERR_GRP + 0x05)
40 /* No Inquiry DB record for BD_ADDR */
41 #define GAP_NO_BDADDR_REC (GAP_ERR_GRP + 0x06)
42 /* An illegal mode parameter was detected */
43 #define GAP_ERR_ILL_MODE (GAP_ERR_GRP + 0x07)
44 /* An illegal time parameter was detected */
45 #define GAP_ERR_ILL_INQ_TIME (GAP_ERR_GRP + 0x08)
46 /* An illegal parameter was detected */
47 #define GAP_ERR_ILL_PARM (GAP_ERR_GRP + 0x09)
48 /* Error starting the remote device name request */
49 #define GAP_ERR_REM_NAME (GAP_ERR_GRP + 0x0a)
50 /* The GAP command was started (result pending) */
51 #define GAP_CMD_INITIATED (GAP_ERR_GRP + 0x0b)
52 /* The device was not up; the request was not executed */
53 #define GAP_DEVICE_NOT_UP (GAP_ERR_GRP + 0x0c)
54 /* The bd addr passed in was not found or invalid */
55 #define GAP_BAD_BD_ADDR (GAP_ERR_GRP + 0x0d)
56 
57 /* Bad GAP handle */
58 #define GAP_ERR_BAD_HANDLE (GAP_ERR_GRP + 0x0e)
59 /* Buffer offset invalid */
60 #define GAP_ERR_BUF_OFFSET (GAP_ERR_GRP + 0x0f)
61 /* Connection is in invalid state */
62 #define GAP_ERR_BAD_STATE (GAP_ERR_GRP + 0x10)
63 /* No data available */
64 #define GAP_NO_DATA_AVAIL (GAP_ERR_GRP + 0x11)
65 /* BT stack is congested */
66 #define GAP_ERR_CONGESTED (GAP_ERR_GRP + 0x12)
67 /* Security failed */
68 #define GAP_ERR_SECURITY (GAP_ERR_GRP + 0x13)
69 
70 /* General error processing BTM request */
71 #define GAP_ERR_PROCESSING (GAP_ERR_GRP + 0x14)
72 /* Timeout occurred while processing cmd */
73 #define GAP_ERR_TIMEOUT (GAP_ERR_GRP + 0x15)
74 #define GAP_EVT_CONN_OPENED 0x0100
75 #define GAP_EVT_CONN_CLOSED 0x0101
76 #define GAP_EVT_CONN_DATA_AVAIL 0x0102
77 #define GAP_EVT_CONN_CONGESTED 0x0103
78 #define GAP_EVT_CONN_UNCONGESTED 0x0104
79 #define GAP_EVT_TX_EMPTY 0x0105
80 #define GAP_EVT_LE_COC_CREDITS 0x0106
81 
82 /* Values for 'chan_mode_mask' field */
83 /* GAP_ConnOpen() - optional channels to negotiate */
84 #define GAP_FCR_CHAN_OPT_BASIC L2CAP_FCR_CHAN_OPT_BASIC
85 #define GAP_FCR_CHAN_OPT_ERTM L2CAP_FCR_CHAN_OPT_ERTM
86 #define GAP_FCR_CHAN_OPT_STREAM L2CAP_FCR_CHAN_OPT_STREAM
87 /*** used in connection variables and functions ***/
88 #define GAP_INVALID_HANDLE 0xFFFF
89 
90 /* This is used to change the criteria for AMP */
91 #define GAP_PROTOCOL_ID (UUID_PROTOCOL_UDP)
92 
93 #ifndef GAP_PREFER_CONN_INT_MAX
94 #define GAP_PREFER_CONN_INT_MAX BTM_BLE_CONN_INT_MIN
95 #endif
96 
97 #ifndef GAP_PREFER_CONN_INT_MIN
98 #define GAP_PREFER_CONN_INT_MIN BTM_BLE_CONN_INT_MIN
99 #endif
100 
101 #ifndef GAP_PREFER_CONN_LATENCY
102 #define GAP_PREFER_CONN_LATENCY 0
103 #endif
104 
105 #ifndef GAP_PREFER_CONN_SP_TOUT
106 #define GAP_PREFER_CONN_SP_TOUT 2000
107 #endif
108 
109 struct tGAP_COC_CREDITS {
110   uint16_t gap_handle;
111   uint16_t credits_received;
112   uint16_t credit_count;
113 };
114 
115 union tGAP_CB_DATA {
116   tGAP_COC_CREDITS coc_credits;
117 };
118 
119 /*****************************************************************************
120  *  Type Definitions
121  ****************************************************************************/
122 /*
123  * Callback function for connection services
124 */
125 typedef void(tGAP_CONN_CALLBACK)(uint16_t gap_handle, uint16_t event,
126                                  tGAP_CB_DATA* data);
127 
128 /*
129  * Define the callback function prototypes.  Parameters are specific
130  * to each event and are described below
131 */
132 typedef void(tGAP_CALLBACK)(uint16_t event, void* p_data);
133 
134 /* Definition of the GAP_FindAddrByName results structure */
135 typedef struct {
136   uint16_t status;
137   RawAddress bd_addr;
138   tBTM_BD_NAME devname;
139 } tGAP_FINDADDR_RESULTS;
140 
141 typedef struct {
142   uint16_t int_min;
143   uint16_t int_max;
144   uint16_t latency;
145   uint16_t sp_tout;
146 } tGAP_BLE_PREF_PARAM;
147 
148 typedef union {
149   tGAP_BLE_PREF_PARAM conn_param;
150   RawAddress reconn_bda;
151   uint16_t icon;
152   uint8_t* p_dev_name;
153   uint8_t addr_resolution;
154 
155 } tGAP_BLE_ATTR_VALUE;
156 
157 typedef void(tGAP_BLE_CMPL_CBACK)(bool status, const RawAddress& addr,
158                                   uint16_t length, char* p_name);
159 
160 /*****************************************************************************
161  *  External Function Declarations
162  ****************************************************************************/
163 
164 /*** Functions for L2CAP connection interface ***/
165 
166 /*******************************************************************************
167  *
168  * Function         GAP_ConnOpen
169  *
170  * Description      This function is called to open a generic L2CAP connection.
171  *
172  * Returns          handle of the connection if successful, else
173  *                  GAP_INVALID_HANDLE
174  *
175  ******************************************************************************/
176 extern uint16_t GAP_ConnOpen(const char* p_serv_name, uint8_t service_id,
177                              bool is_server, const RawAddress* p_rem_bda,
178                              uint16_t psm, uint16_t le_mps,
179                              tL2CAP_CFG_INFO* p_cfg,
180                              tL2CAP_ERTM_INFO* ertm_info, uint16_t security,
181                              uint8_t chan_mode_mask, tGAP_CONN_CALLBACK* p_cb,
182                              tBT_TRANSPORT transport);
183 
184 /*******************************************************************************
185  *
186  * Function         GAP_ConnClose
187  *
188  * Description      This function is called to close a connection.
189  *
190  * Returns          BT_PASS             - closed OK
191  *                  GAP_ERR_BAD_HANDLE  - invalid handle
192  *
193  ******************************************************************************/
194 extern uint16_t GAP_ConnClose(uint16_t gap_handle);
195 
196 /*******************************************************************************
197  *
198  * Function         GAP_ConnReadData
199  *
200  * Description      GKI buffer unaware application will call this function
201  *                  after receiving GAP_EVT_RXDATA event. A data copy is made
202  *                  into the receive buffer parameter.
203  *
204  * Returns          BT_PASS             - data read
205  *                  GAP_ERR_BAD_HANDLE  - invalid handle
206  *                  GAP_NO_DATA_AVAIL   - no data available
207  *
208  ******************************************************************************/
209 extern uint16_t GAP_ConnReadData(uint16_t gap_handle, uint8_t* p_data,
210                                  uint16_t max_len, uint16_t* p_len);
211 
212 /*******************************************************************************
213  *
214  * Function         GAP_GetRxQueueCnt
215  *
216  * Description      This function return number of bytes on the rx queue.
217  *
218  * Parameters:      handle     - Handle returned in the GAP_ConnOpen
219  *                  p_rx_queue_count - Pointer to return queue count in.
220  *
221  *
222  ******************************************************************************/
223 extern int GAP_GetRxQueueCnt(uint16_t handle, uint32_t* p_rx_queue_count);
224 
225 /*******************************************************************************
226  *
227  * Function         GAP_ConnBTRead
228  *
229  * Description      GKI buffer aware applications will call this function after
230  *                  receiving an GAP_EVT_RXDATA event to process the incoming
231  *                  data buffer.
232  *
233  * Returns          BT_PASS             - data read
234  *                  GAP_ERR_BAD_HANDLE  - invalid handle
235  *                  GAP_NO_DATA_AVAIL   - no data available
236  *
237  ******************************************************************************/
238 extern uint16_t GAP_ConnBTRead(uint16_t gap_handle, BT_HDR** pp_buf);
239 
240 /*******************************************************************************
241  *
242  * Function         GAP_ConnWriteData
243  *
244  * Description      GKI buffer unaware application will call this function
245  *                  to send data to the connection. A data copy is made into a
246  *                  GKI buffer.
247  *
248  * Returns          BT_PASS                 - data read
249  *                  GAP_ERR_BAD_HANDLE      - invalid handle
250  *                  GAP_ERR_BAD_STATE       - connection not established
251  *                  GAP_CONGESTION          - system is congested
252  *
253  ******************************************************************************/
254 extern uint16_t GAP_ConnWriteData(uint16_t gap_handle, BT_HDR* msg);
255 
256 /*******************************************************************************
257  *
258  * Function         GAP_ConnReconfig
259  *
260  * Description      Applications can call this function to reconfigure the
261  *                  connection.
262  *
263  * Returns          BT_PASS                 - config process started
264  *                  GAP_ERR_BAD_HANDLE      - invalid handle
265  *
266  ******************************************************************************/
267 extern uint16_t GAP_ConnReconfig(uint16_t gap_handle, tL2CAP_CFG_INFO* p_cfg);
268 
269 /*******************************************************************************
270  *
271  * Function         GAP_ConnSetIdleTimeout
272  *
273  * Description      Higher layers call this function to set the idle timeout for
274  *                  a connection, or for all future connections. The "idle
275  *                  timeout" is the amount of time that a connection can remain
276  *                  up with no L2CAP channels on it. A timeout of zero means
277  *                  that the connection will be torn down immediately when the
278  *                  last channel is removed. A timeout of 0xFFFF means no
279  *                  timeout. Values are in seconds.
280  *
281  * Returns          BT_PASS                 - config process started
282  *                  GAP_ERR_BAD_HANDLE      - invalid handle
283  *
284  ******************************************************************************/
285 extern uint16_t GAP_ConnSetIdleTimeout(uint16_t gap_handle, uint16_t timeout);
286 
287 /*******************************************************************************
288  *
289  * Function         GAP_ConnGetRemoteAddr
290  *
291  * Description      This function is called to get the remote BD address
292  *                  of a connection.
293  *
294  * Returns          BT_PASS             - closed OK
295  *                  GAP_ERR_BAD_HANDLE  - invalid handle
296  *
297  ******************************************************************************/
298 extern const RawAddress* GAP_ConnGetRemoteAddr(uint16_t gap_handle);
299 
300 /*******************************************************************************
301  *
302  * Function         GAP_ConnGetRemMtuSize
303  *
304  * Description      Returns the remote device's MTU size.
305  *
306  * Returns          uint16_t - maximum size buffer that can be transmitted to
307  *                             the peer
308  *
309  ******************************************************************************/
310 extern uint16_t GAP_ConnGetRemMtuSize(uint16_t gap_handle);
311 
312 /*******************************************************************************
313  *
314  * Function         GAP_ConnGetL2CAPCid
315  *
316  * Description      Returns the L2CAP channel id
317  *
318  * Parameters:      handle      - Handle of the connection
319  *
320  * Returns          uint16_t    - The L2CAP channel id
321  *                  0, if error
322  *
323  ******************************************************************************/
324 extern uint16_t GAP_ConnGetL2CAPCid(uint16_t gap_handle);
325 
326 /*******************************************************************************
327  *
328  * Function         GAP_Init
329  *
330  * Description      Initializes the control blocks used by GAP.
331  *                  This routine should not be called except once per
332  *                      stack invocation.
333  *
334  * Returns          Nothing
335  *
336  ******************************************************************************/
337 extern void GAP_Init(void);
338 
339 /*******************************************************************************
340  *
341  * Function         GAP_BleAttrDBUpdate
342  *
343  * Description      update GAP local BLE attribute database.
344  *
345  * Returns          Nothing
346  *
347  ******************************************************************************/
348 extern void GAP_BleAttrDBUpdate(uint16_t attr_uuid,
349                                 tGAP_BLE_ATTR_VALUE* p_value);
350 
351 /*******************************************************************************
352  *
353  * Function         GAP_BleReadPeerPrefConnParams
354  *
355  * Description      Start a process to read a connected peripheral's preferred
356  *                  connection parameters
357  *
358  * Returns          true if read started, else false if GAP is busy
359  *
360  ******************************************************************************/
361 extern bool GAP_BleReadPeerPrefConnParams(const RawAddress& peer_bda);
362 
363 /*******************************************************************************
364  *
365  * Function         GAP_BleReadPeerDevName
366  *
367  * Description      Start a process to read a connected peripheral's device
368  *                  name.
369  *
370  * Returns          true if request accepted
371  *
372  ******************************************************************************/
373 extern bool GAP_BleReadPeerDevName(const RawAddress& peer_bda,
374                                    tGAP_BLE_CMPL_CBACK* p_cback);
375 
376 /*******************************************************************************
377  *
378  * Function         GAP_BleReadPeerAddressResolutionCap
379  *
380  * Description      Start a process to read peer address resolution capability
381  *
382  * Returns          true if request accepted
383  *
384  ******************************************************************************/
385 extern bool GAP_BleReadPeerAddressResolutionCap(const RawAddress& peer_bda,
386                                                 tGAP_BLE_CMPL_CBACK* p_cback);
387 
388 /*******************************************************************************
389  *
390  * Function         GAP_BleCancelReadPeerDevName
391  *
392  * Description      Cancel reading a peripheral's device name.
393  *
394  * Returns          true if request accepted
395  *
396  ******************************************************************************/
397 extern bool GAP_BleCancelReadPeerDevName(const RawAddress& peer_bda);
398 
399 #endif /* GAP_API_H */
400