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 "utils.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 /* API_START */ 91 92 /** 93 * @brief Enable/disable bonding. Default is enabled. 94 * @param enabled 95 */ 96 void gap_set_bondable_mode(int enabled); 97 98 /** 99 * @brief Get bondable mode. 100 * @return 1 if bondable 101 */ 102 int gap_get_bondable_mode(void); 103 104 /** 105 * @brief Start dedicated bonding with device. Disconnect after bonding. 106 * @param device 107 * @param request MITM protection 108 * @return error, if max num acl connections active 109 * @result GAP_DEDICATED_BONDING_COMPLETE 110 */ 111 int gap_dedicated_bonding(bd_addr_t device, int mitm_protection_required); 112 113 gap_security_level_t gap_security_level_for_link_key_type(link_key_type_t link_key_type); 114 gap_security_level_t gap_security_level(hci_con_handle_t con_handle); 115 116 void gap_request_security_level(hci_con_handle_t con_handle, gap_security_level_t level); 117 int gap_mitm_protection_required_for_security_level(gap_security_level_t level); 118 119 /** 120 * @brief Sets local name. 121 * @note has to be done before stack starts up 122 * @param name is not copied, make sure memory is accessible during stack startup 123 */ 124 void gap_set_local_name(const char * local_name); 125 /* API_END*/ 126 127 /** 128 * @brief Get connection type 129 * @param con_handle 130 * @result connection_type 131 */ 132 gap_connection_type_t gap_get_connection_type(hci_con_handle_t connection_handle); 133 134 typedef enum { 135 GAP_RANDOM_ADDRESS_TYPE_OFF = 0, 136 GAP_RANDOM_ADDRESS_NON_RESOLVABLE, 137 GAP_RANDOM_ADDRESS_RESOLVABLE, 138 } gap_random_address_type_t; 139 140 /** 141 * @brief Enable privacy by using random addresses 142 * @param random_address_type to use (incl. OFF) 143 */ 144 void gap_random_address_set_mode(gap_random_address_type_t random_address_type); 145 146 /** 147 * @brief Get privacy mode 148 */ 149 gap_random_address_type_t gap_random_address_get_mode(void); 150 151 /** 152 * @brief Sets update period for random address 153 * @param period_ms in ms 154 */ 155 void gap_random_address_set_update_period(int period_ms); 156 157 /** 158 * @brief Updates the connection parameters for a given LE connection 159 * @param handle 160 * @param conn_interval_min (unit: 1.25ms) 161 * @param conn_interval_max (unit: 1.25ms) 162 * @param conn_latency 163 * @param supervision_timeout (unit: 10ms) 164 * @returns 0 if ok 165 */ 166 int gap_update_connection_parameters(hci_con_handle_t con_handle, uint16_t conn_interval_min, 167 uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout); 168 169 /** 170 * @brief Request an update of the connection parameter for a given LE connection 171 * @param handle 172 * @param conn_interval_min (unit: 1.25ms) 173 * @param conn_interval_max (unit: 1.25ms) 174 * @param conn_latency 175 * @param supervision_timeout (unit: 10ms) 176 * @returns 0 if ok 177 */ 178 int gap_request_connection_parameter_update(hci_con_handle_t con_handle, uint16_t conn_interval_min, 179 uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout); 180 181 /** 182 * @brief Set Advertisement Data 183 * @param advertising_data_length 184 * @param advertising_data (max 31 octets) 185 * @note data is not copied, pointer has to stay valid 186 */ 187 void gap_advertisements_set_data(uint8_t advertising_data_length, uint8_t * advertising_data); 188 189 /** 190 * @brief Set Advertisement Paramters 191 * @param adv_int_min 192 * @param adv_int_max 193 * @param adv_type 194 * @param direct_address_type 195 * @param direct_address 196 * @param channel_map 197 * @param filter_policy 198 * @note own_address_type is used from gap_random_address_set_mode 199 */ 200 void gap_advertisements_set_params(uint16_t adv_int_min, uint16_t adv_int_max, uint8_t adv_type, 201 uint8_t direct_address_typ, bd_addr_t direct_address, uint8_t channel_map, uint8_t filter_policy); 202 203 /** 204 * @brief Enable/Disable Advertisements 205 * @param enabled 206 */ 207 void gap_advertisements_enable(int enabled); 208 209 /** 210 * @brief Auto Connection Establishment - Start Connecting to device 211 * @param address_typ 212 * @param address 213 * @returns 0 if ok 214 */ 215 int gap_auto_connection_start(bd_addr_type_t address_typ, bd_addr_t address); 216 217 /** 218 * @brief Auto Connection Establishment - Stop Connecting to device 219 * @param address_typ 220 * @param address 221 * @returns 0 if ok 222 */ 223 int gap_auto_connection_stop(bd_addr_type_t address_typ, bd_addr_t address); 224 225 /** 226 * @brief Auto Connection Establishment - Stop everything 227 * @note Convenience function to stop all active auto connection attempts 228 */ 229 void gap_auto_connection_stop_all(void); 230 231 #if defined __cplusplus 232 } 233 #endif 234 235 #endif // __GAP_H 236