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