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