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