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