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