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 /*** used in connection variables and functions ***/
87 #define GAP_INVALID_HANDLE 0xFFFF
88 
89 /* This is used to change the criteria for AMP */
90 #define GAP_PROTOCOL_ID (UUID_PROTOCOL_UDP)
91 
92 #ifndef GAP_PREFER_CONN_INT_MAX
93 #define GAP_PREFER_CONN_INT_MAX BTM_BLE_CONN_INT_MIN
94 #endif
95 
96 #ifndef GAP_PREFER_CONN_INT_MIN
97 #define GAP_PREFER_CONN_INT_MIN BTM_BLE_CONN_INT_MIN
98 #endif
99 
100 #ifndef GAP_PREFER_CONN_LATENCY
101 #define GAP_PREFER_CONN_LATENCY 0
102 #endif
103 
104 #ifndef GAP_PREFER_CONN_SP_TOUT
105 #define GAP_PREFER_CONN_SP_TOUT 2000
106 #endif
107 
108 struct tGAP_COC_CREDITS {
109   uint16_t gap_handle;
110   uint16_t credits_received;
111   uint16_t credit_count;
112 };
113 
114 union tGAP_CB_DATA {
115   tGAP_COC_CREDITS coc_credits;
116 };
117 
118 /*****************************************************************************
119  *  Type Definitions
120  ****************************************************************************/
121 /*
122  * Callback function for connection services
123 */
124 typedef void(tGAP_CONN_CALLBACK)(uint16_t gap_handle, uint16_t event,
125                                  tGAP_CB_DATA* data);
126 
127 /*
128  * Define the callback function prototypes.  Parameters are specific
129  * to each event and are described below
130 */
131 typedef void(tGAP_CALLBACK)(uint16_t event, void* p_data);
132 
133 /* Definition of the GAP_FindAddrByName results structure */
134 typedef struct {
135   uint16_t status;
136   RawAddress bd_addr;
137   tBTM_BD_NAME devname;
138 } tGAP_FINDADDR_RESULTS;
139 
140 typedef struct {
141   uint16_t int_min;
142   uint16_t int_max;
143   uint16_t latency;
144   uint16_t sp_tout;
145 } tGAP_BLE_PREF_PARAM;
146 
147 typedef union {
148   tGAP_BLE_PREF_PARAM conn_param;
149   RawAddress reconn_bda;
150   uint16_t icon;
151   uint8_t* p_dev_name;
152   uint8_t addr_resolution;
153 
154 } tGAP_BLE_ATTR_VALUE;
155 
156 typedef void(tGAP_BLE_CMPL_CBACK)(bool status, const RawAddress& addr,
157                                   uint16_t length, char* p_name);
158 
159 /*****************************************************************************
160  *  External Function Declarations
161  ****************************************************************************/
162 
163 /*** Functions for L2CAP connection interface ***/
164 
165 /*******************************************************************************
166  *
167  * Function         GAP_ConnOpen
168  *
169  * Description      This function is called to open a generic L2CAP connection.
170  *
171  * Returns          handle of the connection if successful, else
172  *                  GAP_INVALID_HANDLE
173  *
174  ******************************************************************************/
175 extern uint16_t GAP_ConnOpen(const char* p_serv_name, uint8_t service_id,
176                              bool is_server, const RawAddress* p_rem_bda,
177                              uint16_t psm, uint16_t le_mps,
178                              tL2CAP_CFG_INFO* p_cfg,
179                              tL2CAP_ERTM_INFO* ertm_info, uint16_t security,
180                              uint8_t chan_mode_mask, tGAP_CONN_CALLBACK* p_cb,
181                              tBT_TRANSPORT transport);
182 
183 /*******************************************************************************
184  *
185  * Function         GAP_ConnClose
186  *
187  * Description      This function is called to close a connection.
188  *
189  * Returns          BT_PASS             - closed OK
190  *                  GAP_ERR_BAD_HANDLE  - invalid handle
191  *
192  ******************************************************************************/
193 extern uint16_t GAP_ConnClose(uint16_t gap_handle);
194 
195 /*******************************************************************************
196  *
197  * Function         GAP_ConnReadData
198  *
199  * Description      GKI buffer unaware application will call this function
200  *                  after receiving GAP_EVT_RXDATA event. A data copy is made
201  *                  into the receive buffer parameter.
202  *
203  * Returns          BT_PASS             - data read
204  *                  GAP_ERR_BAD_HANDLE  - invalid handle
205  *                  GAP_NO_DATA_AVAIL   - no data available
206  *
207  ******************************************************************************/
208 extern uint16_t GAP_ConnReadData(uint16_t gap_handle, uint8_t* p_data,
209                                  uint16_t max_len, uint16_t* p_len);
210 
211 /*******************************************************************************
212  *
213  * Function         GAP_GetRxQueueCnt
214  *
215  * Description      This function return number of bytes on the rx queue.
216  *
217  * Parameters:      handle     - Handle returned in the GAP_ConnOpen
218  *                  p_rx_queue_count - Pointer to return queue count in.
219  *
220  *
221  ******************************************************************************/
222 extern int GAP_GetRxQueueCnt(uint16_t handle, uint32_t* p_rx_queue_count);
223 
224 /*******************************************************************************
225  *
226  * Function         GAP_ConnBTRead
227  *
228  * Description      GKI buffer aware applications will call this function after
229  *                  receiving an GAP_EVT_RXDATA event to process the incoming
230  *                  data buffer.
231  *
232  * Returns          BT_PASS             - data read
233  *                  GAP_ERR_BAD_HANDLE  - invalid handle
234  *                  GAP_NO_DATA_AVAIL   - no data available
235  *
236  ******************************************************************************/
237 extern uint16_t GAP_ConnBTRead(uint16_t gap_handle, BT_HDR** pp_buf);
238 
239 /*******************************************************************************
240  *
241  * Function         GAP_ConnWriteData
242  *
243  * Description      GKI buffer unaware application will call this function
244  *                  to send data to the connection. A data copy is made into a
245  *                  GKI buffer.
246  *
247  * Returns          BT_PASS                 - data read
248  *                  GAP_ERR_BAD_HANDLE      - invalid handle
249  *                  GAP_ERR_BAD_STATE       - connection not established
250  *                  GAP_CONGESTION          - system is congested
251  *
252  ******************************************************************************/
253 extern uint16_t GAP_ConnWriteData(uint16_t gap_handle, BT_HDR* msg);
254 
255 /*******************************************************************************
256  *
257  * Function         GAP_ConnReconfig
258  *
259  * Description      Applications can call this function to reconfigure the
260  *                  connection.
261  *
262  * Returns          BT_PASS                 - config process started
263  *                  GAP_ERR_BAD_HANDLE      - invalid handle
264  *
265  ******************************************************************************/
266 extern uint16_t GAP_ConnReconfig(uint16_t gap_handle, tL2CAP_CFG_INFO* p_cfg);
267 
268 /*******************************************************************************
269  *
270  * Function         GAP_ConnSetIdleTimeout
271  *
272  * Description      Higher layers call this function to set the idle timeout for
273  *                  a connection, or for all future connections. The "idle
274  *                  timeout" is the amount of time that a connection can remain
275  *                  up with no L2CAP channels on it. A timeout of zero means
276  *                  that the connection will be torn down immediately when the
277  *                  last channel is removed. A timeout of 0xFFFF means no
278  *                  timeout. Values are in seconds.
279  *
280  * Returns          BT_PASS                 - config process started
281  *                  GAP_ERR_BAD_HANDLE      - invalid handle
282  *
283  ******************************************************************************/
284 extern uint16_t GAP_ConnSetIdleTimeout(uint16_t gap_handle, uint16_t timeout);
285 
286 /*******************************************************************************
287  *
288  * Function         GAP_ConnGetRemoteAddr
289  *
290  * Description      This function is called to get the remote BD address
291  *                  of a connection.
292  *
293  * Returns          BT_PASS             - closed OK
294  *                  GAP_ERR_BAD_HANDLE  - invalid handle
295  *
296  ******************************************************************************/
297 extern const RawAddress* GAP_ConnGetRemoteAddr(uint16_t gap_handle);
298 
299 /*******************************************************************************
300  *
301  * Function         GAP_ConnGetRemMtuSize
302  *
303  * Description      Returns the remote device's MTU size.
304  *
305  * Returns          uint16_t - maximum size buffer that can be transmitted to
306  *                             the peer
307  *
308  ******************************************************************************/
309 extern uint16_t GAP_ConnGetRemMtuSize(uint16_t gap_handle);
310 
311 /*******************************************************************************
312  *
313  * Function         GAP_ConnGetL2CAPCid
314  *
315  * Description      Returns the L2CAP channel id
316  *
317  * Parameters:      handle      - Handle of the connection
318  *
319  * Returns          uint16_t    - The L2CAP channel id
320  *                  0, if error
321  *
322  ******************************************************************************/
323 extern uint16_t GAP_ConnGetL2CAPCid(uint16_t gap_handle);
324 
325 /*******************************************************************************
326  *
327  * Function         GAP_Init
328  *
329  * Description      Initializes the control blocks used by GAP.
330  *                  This routine should not be called except once per
331  *                      stack invocation.
332  *
333  * Returns          Nothing
334  *
335  ******************************************************************************/
336 extern void GAP_Init(void);
337 
338 /*******************************************************************************
339  *
340  * Function         GAP_BleAttrDBUpdate
341  *
342  * Description      update GAP local BLE attribute database.
343  *
344  * Returns          Nothing
345  *
346  ******************************************************************************/
347 extern void GAP_BleAttrDBUpdate(uint16_t attr_uuid,
348                                 tGAP_BLE_ATTR_VALUE* p_value);
349 
350 /*******************************************************************************
351  *
352  * Function         GAP_BleReadPeerPrefConnParams
353  *
354  * Description      Start a process to read a connected peripheral's preferred
355  *                  connection parameters
356  *
357  * Returns          true if read started, else false if GAP is busy
358  *
359  ******************************************************************************/
360 extern bool GAP_BleReadPeerPrefConnParams(const RawAddress& peer_bda);
361 
362 /*******************************************************************************
363  *
364  * Function         GAP_BleReadPeerDevName
365  *
366  * Description      Start a process to read a connected peripheral's device
367  *                  name.
368  *
369  * Returns          true if request accepted
370  *
371  ******************************************************************************/
372 extern bool GAP_BleReadPeerDevName(const RawAddress& peer_bda,
373                                    tGAP_BLE_CMPL_CBACK* p_cback);
374 
375 /*******************************************************************************
376  *
377  * Function         GAP_BleReadPeerAddressResolutionCap
378  *
379  * Description      Start a process to read peer address resolution capability
380  *
381  * Returns          true if request accepted
382  *
383  ******************************************************************************/
384 extern bool GAP_BleReadPeerAddressResolutionCap(const RawAddress& peer_bda,
385                                                 tGAP_BLE_CMPL_CBACK* p_cback);
386 
387 /*******************************************************************************
388  *
389  * Function         GAP_BleCancelReadPeerDevName
390  *
391  * Description      Cancel reading a peripheral's device name.
392  *
393  * Returns          true if request accepted
394  *
395  ******************************************************************************/
396 extern bool GAP_BleCancelReadPeerDevName(const RawAddress& peer_bda);
397 
398 #endif /* GAP_API_H */
399