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