1 /* 2 * Copyright (C) 2014 BlueKitchen GmbH 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions 6 * are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 3. Neither the name of the copyright holders nor the names of 14 * contributors may be used to endorse or promote products derived 15 * from this software without specific prior written permission. 16 * 4. Any redistribution, use, or modification is done solely for 17 * personal benefit and not for any commercial purpose or for 18 * monetary gain. 19 * 20 * THIS SOFTWARE IS PROVIDED BY BLUEKITCHEN GMBH AND CONTRIBUTORS 21 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL MATTHIAS 24 * RINGWALD OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 26 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 27 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 30 * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31 * SUCH DAMAGE. 32 * 33 * Please inquire about commercial licensing options at 34 * [email protected] 35 * 36 */ 37 38 #ifndef __GAP_H 39 #define __GAP_H 40 41 #if defined __cplusplus 42 extern "C" { 43 #endif 44 45 #include "btstack_defines.h" 46 #include "btstack_util.h" 47 48 typedef enum { 49 50 // MITM protection not required 51 // No encryption required 52 // No user interaction required 53 LEVEL_0 = 0, 54 55 // MITM protection not required 56 // No encryption required 57 // Minimal user interaction desired 58 LEVEL_1, 59 60 // MITM protection not required 61 // Encryption required 62 LEVEL_2, 63 64 // MITM protection required 65 // Encryption required 66 // User interaction acceptable 67 LEVEL_3, 68 69 // MITM protection required 70 // Encryption required 71 // 128-bit equivalent strength for link and encryption keys required (P-192 is not enough) 72 // User interaction acceptable 73 LEVEL_4, 74 } gap_security_level_t; 75 76 typedef enum { 77 GAP_SECURITY_NONE, 78 GAP_SECUIRTY_ENCRYPTED, // SSP: JUST WORKS 79 GAP_SECURITY_AUTHENTICATED, // SSP: numeric comparison, passkey, OOB 80 // GAP_SECURITY_AUTHORIZED 81 } gap_security_state; 82 83 typedef enum { 84 GAP_CONNECTION_INVALID, 85 GAP_CONNECTION_ACL, 86 GAP_CONNECTION_SCO, 87 GAP_CONNECTION_LE 88 } gap_connection_type_t; 89 90 typedef struct le_connection_parameter_range{ 91 uint16_t le_conn_interval_min; 92 uint16_t le_conn_interval_max; 93 uint16_t le_conn_latency_min; 94 uint16_t le_conn_latency_max; 95 uint16_t le_supervision_timeout_min; 96 uint16_t le_supervision_timeout_max; 97 } le_connection_parameter_range_t; 98 99 typedef enum { 100 GAP_RANDOM_ADDRESS_TYPE_OFF = 0, 101 GAP_RANDOM_ADDRESS_TYPE_STATIC, 102 GAP_RANDOM_ADDRESS_NON_RESOLVABLE, 103 GAP_RANDOM_ADDRESS_RESOLVABLE, 104 } gap_random_address_type_t; 105 106 /* API_START */ 107 108 // Classic + LE 109 110 /** 111 * @brief Disconnect connection with handle 112 * @param handle 113 */ 114 uint8_t gap_disconnect(hci_con_handle_t handle); 115 116 /** 117 * @brief Get connection type 118 * @param con_handle 119 * @result connection_type 120 */ 121 gap_connection_type_t gap_get_connection_type(hci_con_handle_t connection_handle); 122 123 // Classic 124 125 /** 126 * @brief Sets local name. 127 * @note has to be done before stack starts up 128 * @note Default name is 'BTstack 00:00:00:00:00:00' 129 * @note '00:00:00:00:00:00' in local_name will be replaced with actual bd addr 130 * @param name is not copied, make sure memory is accessible during stack startup 131 */ 132 void gap_set_local_name(const char * local_name); 133 134 /** 135 * @brief Set Extended Inquiry Response data 136 * @note has to be done before stack starts up 137 * @note If not set, local name will be used for EIR data (see gap_set_local_name) 138 * @note '00:00:00:00:00:00' in local_name will be replaced with actual bd addr 139 * @param eir_data size 240 bytes, is not copied make sure memory is accessible during stack startup 140 */ 141 void gap_set_extended_inquiry_response(const uint8_t * data); 142 143 /** 144 * @brief Set class of device that will be set during Bluetooth init. 145 * @note has to be done before stack starts up 146 */ 147 void gap_set_class_of_device(uint32_t class_of_device); 148 149 /** 150 * @brief Enable/disable bonding. Default is enabled. 151 * @param enabled 152 */ 153 void gap_set_bondable_mode(int enabled); 154 155 /** 156 * @brief Get bondable mode. 157 * @return 1 if bondable 158 */ 159 int gap_get_bondable_mode(void); 160 161 /* Configure Secure Simple Pairing */ 162 163 /** 164 * @brief Enable will enable SSP during init. 165 */ 166 void gap_ssp_set_enable(int enable); 167 168 /** 169 * @brief Set IO Capability. BTstack will return capability to SSP requests 170 */ 171 void gap_ssp_set_io_capability(int ssp_io_capability); 172 173 /** 174 * @brief Set Authentication Requirements using during SSP 175 */ 176 void gap_ssp_set_authentication_requirement(int authentication_requirement); 177 178 /** 179 * @brief If set, BTstack will confirm a numeric comparison and enter '000000' if requested. 180 */ 181 void gap_ssp_set_auto_accept(int auto_accept); 182 183 /** 184 * @brief Start dedicated bonding with device. Disconnect after bonding. 185 * @param device 186 * @param request MITM protection 187 * @return error, if max num acl connections active 188 * @result GAP_DEDICATED_BONDING_COMPLETE 189 */ 190 int gap_dedicated_bonding(bd_addr_t device, int mitm_protection_required); 191 192 gap_security_level_t gap_security_level_for_link_key_type(link_key_type_t link_key_type); 193 gap_security_level_t gap_security_level(hci_con_handle_t con_handle); 194 195 void gap_request_security_level(hci_con_handle_t con_handle, gap_security_level_t level); 196 197 int gap_mitm_protection_required_for_security_level(gap_security_level_t level); 198 199 // LE 200 201 /** 202 * @brief Set parameters for LE Scan 203 */ 204 void gap_set_scan_parameters(uint8_t scan_type, uint16_t scan_interval, uint16_t scan_window); 205 206 /** 207 * @brief Start LE Scan 208 */ 209 void gap_start_scan(void); 210 211 /** 212 * @brief Stop LE Scan 213 */ 214 void gap_stop_scan(void); 215 216 /** 217 * @brief Enable privacy by using random addresses 218 * @param random_address_type to use (incl. OFF) 219 */ 220 void gap_random_address_set_mode(gap_random_address_type_t random_address_type); 221 222 /** 223 * @brief Get privacy mode 224 */ 225 gap_random_address_type_t gap_random_address_get_mode(void); 226 227 /** 228 * @brief Sets update period for random address 229 * @param period_ms in ms 230 */ 231 void gap_random_address_set_update_period(int period_ms); 232 233 /** 234 * @brief Sets a fixed random address for advertising 235 * @param addr 236 * @note Sets random address mode to type off 237 */ 238 void gap_random_address_set(bd_addr_t addr); 239 240 /** 241 * @brief Set Advertisement Data 242 * @param advertising_data_length 243 * @param advertising_data (max 31 octets) 244 * @note data is not copied, pointer has to stay valid 245 * @note '00:00:00:00:00:00' in advertising_data will be replaced with actual bd addr 246 */ 247 void gap_advertisements_set_data(uint8_t advertising_data_length, uint8_t * advertising_data); 248 249 /** 250 * @brief Set Advertisement Paramters 251 * @param adv_int_min 252 * @param adv_int_max 253 * @param adv_type 254 * @param direct_address_type 255 * @param direct_address 256 * @param channel_map 257 * @param filter_policy 258 * @note own_address_type is used from gap_random_address_set_mode 259 */ 260 void gap_advertisements_set_params(uint16_t adv_int_min, uint16_t adv_int_max, uint8_t adv_type, 261 uint8_t direct_address_typ, bd_addr_t direct_address, uint8_t channel_map, uint8_t filter_policy); 262 263 /** 264 * @brief Enable/Disable Advertisements. OFF by default. 265 * @param enabled 266 */ 267 void gap_advertisements_enable(int enabled); 268 269 /** 270 * @brief Set Scan Response Data 271 * 272 * @note For scan response data, scannable undirected advertising (ADV_SCAN_IND) need to be used 273 * 274 * @param advertising_data_length 275 * @param advertising_data (max 31 octets) 276 * @note data is not copied, pointer has to stay valid 277 * @note '00:00:00:00:00:00' in scan_response_data will be replaced with actual bd addr 278 */ 279 void gap_scan_response_set_data(uint8_t scan_response_data_length, uint8_t * scan_response_data); 280 281 /** 282 * @brief Set connection parameters for outgoing connections 283 * @param conn_interval_min (unit: 1.25ms), default: 10 ms 284 * @param conn_interval_max (unit: 1.25ms), default: 30 ms 285 * @param conn_latency, default: 4 286 * @param supervision_timeout (unit: 10ms), default: 720 ms 287 * @param min_ce_length (unit: 0.625ms), default: 10 ms 288 * @param max_ce_length (unit: 0.625ms), default: 30 ms 289 */ 290 291 void gap_set_connection_parameters(uint16_t conn_interval_min, uint16_t conn_interval_max, 292 uint16_t conn_latency, uint16_t supervision_timeout, uint16_t min_ce_length, uint16_t max_ce_length); 293 294 /** 295 * @brief Request an update of the connection parameter for a given LE connection 296 * @param handle 297 * @param conn_interval_min (unit: 1.25ms) 298 * @param conn_interval_max (unit: 1.25ms) 299 * @param conn_latency 300 * @param supervision_timeout (unit: 10ms) 301 * @returns 0 if ok 302 */ 303 int gap_request_connection_parameter_update(hci_con_handle_t con_handle, uint16_t conn_interval_min, 304 uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout); 305 306 /** 307 * @brief Updates the connection parameters for a given LE connection 308 * @param handle 309 * @param conn_interval_min (unit: 1.25ms) 310 * @param conn_interval_max (unit: 1.25ms) 311 * @param conn_latency 312 * @param supervision_timeout (unit: 10ms) 313 * @returns 0 if ok 314 */ 315 int gap_update_connection_parameters(hci_con_handle_t con_handle, uint16_t conn_interval_min, 316 uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout); 317 318 /** 319 * @brief Set accepted connection parameter range 320 * @param range 321 */ 322 void gap_get_connection_parameter_range(le_connection_parameter_range_t * range); 323 324 /** 325 * @brief Get accepted connection parameter range 326 * @param range 327 */ 328 void gap_set_connection_parameter_range(le_connection_parameter_range_t * range); 329 330 /** 331 * @brief Connect to remote LE device 332 */ 333 uint8_t gap_connect(bd_addr_t addr, bd_addr_type_t addr_type); 334 335 /** 336 * @brief Cancel connection process initiated by gap_connect 337 */ 338 uint8_t gap_connect_cancel(void); 339 340 /** 341 * @brief Auto Connection Establishment - Start Connecting to device 342 * @param address_typ 343 * @param address 344 * @returns 0 if ok 345 */ 346 int gap_auto_connection_start(bd_addr_type_t address_typ, bd_addr_t address); 347 348 /** 349 * @brief Auto Connection Establishment - Stop Connecting to device 350 * @param address_typ 351 * @param address 352 * @returns 0 if ok 353 */ 354 int gap_auto_connection_stop(bd_addr_type_t address_typ, bd_addr_t address); 355 356 /** 357 * @brief Auto Connection Establishment - Stop everything 358 * @note Convenience function to stop all active auto connection attempts 359 */ 360 void gap_auto_connection_stop_all(void); 361 362 // Classic 363 364 /** 365 * @brief Override page scan mode. Page scan mode enabled by l2cap when services are registered 366 * @note Might be used to reduce power consumption while Bluetooth module stays powered but no (new) 367 * connections are expected 368 */ 369 void gap_connectable_control(uint8_t enable); 370 371 /** 372 * @brief Allows to control if device is discoverable. OFF by default. 373 */ 374 void gap_discoverable_control(uint8_t enable); 375 376 /** 377 * @brief Gets local address. 378 */ 379 void gap_local_bd_addr(bd_addr_t address_buffer); 380 381 /** 382 * @brief Deletes link key for remote device with baseband address. 383 * @param addr 384 */ 385 void gap_drop_link_key_for_bd_addr(bd_addr_t addr); 386 387 /** 388 * @brief Store link key for remote device with baseband address 389 * @param addr 390 * @param link_key 391 * @param link_key_type 392 */ 393 void gap_store_link_key_for_bd_addr(bd_addr_t addr, link_key_t link_key, link_key_type_t type); 394 395 /** 396 * @brief Start GAP Classic Inquiry 397 * @param duration in 1.28s units 398 * @return 0 if ok 399 * @events: GAP_EVENT_INQUIRY_RESULT, GAP_EVENT_INQUIRY_COMPLETE 400 */ 401 int gap_inquiry_start(uint8_t duration_in_1280ms_units); 402 403 /** 404 * @brief Stop GAP Classic Inquiry 405 * @brief Stop GAP Classic Inquiry 406 * @returns 0 if ok 407 * @events: GAP_EVENT_INQUIRY_COMPLETE 408 */ 409 int gap_inquiry_stop(void); 410 411 /** 412 * @brief Remote Name Request 413 * @param addr 414 * @param page_scan_repetition_mode 415 * @param clock_offset only used when bit 15 is set - pass 0 if not known 416 * @events: HCI_EVENT_REMOTE_NAME_REQUEST_COMPLETE 417 */ 418 int gap_remote_name_request(bd_addr_t addr, uint8_t page_scan_repetition_mode, uint16_t clock_offset); 419 420 /** 421 * @brief Legacy Pairing Pin Code Response 422 * @param addr 423 * @param pin 424 * @return 0 if ok 425 */ 426 int gap_pin_code_response(bd_addr_t addr, const char * pin); 427 428 /** 429 * @brief Abort Legacy Pairing 430 * @param addr 431 * @param pin 432 * @return 0 if ok 433 */ 434 int gap_pin_code_negative(bd_addr_t addr); 435 436 /** 437 * @brief SSP Passkey Response 438 * @param addr 439 * @param passkey [0..999999] 440 * @return 0 if ok 441 */ 442 int gap_ssp_passkey_response(bd_addr_t addr, uint32_t passkey); 443 444 /** 445 * @brief Abort SSP Passkey Entry/Pairing 446 * @param addr 447 * @param pin 448 * @return 0 if ok 449 */ 450 int gap_ssp_passkey_negative(bd_addr_t addr); 451 452 /** 453 * @brief Accept SSP Numeric Comparison 454 * @param addr 455 * @param passkey 456 * @return 0 if ok 457 */ 458 int gap_ssp_confirmation_response(bd_addr_t addr); 459 460 /** 461 * @brief Abort SSP Numeric Comparison/Pairing 462 * @param addr 463 * @param pin 464 * @return 0 if ok 465 */ 466 int gap_ssp_confirmation_negative(bd_addr_t addr); 467 468 469 470 // LE 471 472 /** 473 * @brief Get own addr type and address used for LE 474 */ 475 void gap_le_get_own_address(uint8_t * addr_type, bd_addr_t addr); 476 477 478 /* API_END*/ 479 480 #if defined __cplusplus 481 } 482 #endif 483 484 #endif // __GAP_H 485