Permalink
Fetching contributors…
Cannot retrieve contributors at this time
574 lines (483 sloc) 16 KB
/*
* Copyright (C) 2014 BlueKitchen GmbH
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. Neither the name of the copyright holders nor the names of
* contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
* 4. Any redistribution, use, or modification is done solely for
* personal benefit and not for any commercial purpose or for
* monetary gain.
*
* THIS SOFTWARE IS PROVIDED BY BLUEKITCHEN GMBH AND CONTRIBUTORS
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL MATTHIAS
* RINGWALD OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
* OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
* AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
* THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* Please inquire about commercial licensing options at
* contact@bluekitchen-gmbh.com
*
*/
#ifndef __GAP_H
#define __GAP_H
#if defined __cplusplus
extern "C" {
#endif
#include "btstack_defines.h"
#include "btstack_util.h"
#include "classic/btstack_link_key_db.h"
typedef enum {
// MITM protection not required
// No encryption required
// No user interaction required
LEVEL_0 = 0,
// MITM protection not required
// No encryption required
// Minimal user interaction desired
LEVEL_1,
// MITM protection not required
// Encryption required
LEVEL_2,
// MITM protection required
// Encryption required
// User interaction acceptable
LEVEL_3,
// MITM protection required
// Encryption required
// 128-bit equivalent strength for link and encryption keys required (P-192 is not enough)
// User interaction acceptable
LEVEL_4,
} gap_security_level_t;
typedef enum {
GAP_SECURITY_NONE,
GAP_SECUIRTY_ENCRYPTED, // SSP: JUST WORKS
GAP_SECURITY_AUTHENTICATED, // SSP: numeric comparison, passkey, OOB
// GAP_SECURITY_AUTHORIZED
} gap_security_state;
typedef enum {
GAP_CONNECTION_INVALID,
GAP_CONNECTION_ACL,
GAP_CONNECTION_SCO,
GAP_CONNECTION_LE
} gap_connection_type_t;
typedef struct le_connection_parameter_range{
uint16_t le_conn_interval_min;
uint16_t le_conn_interval_max;
uint16_t le_conn_latency_min;
uint16_t le_conn_latency_max;
uint16_t le_supervision_timeout_min;
uint16_t le_supervision_timeout_max;
} le_connection_parameter_range_t;
typedef enum {
GAP_RANDOM_ADDRESS_TYPE_OFF = 0,
GAP_RANDOM_ADDRESS_TYPE_STATIC,
GAP_RANDOM_ADDRESS_NON_RESOLVABLE,
GAP_RANDOM_ADDRESS_RESOLVABLE,
} gap_random_address_type_t;
// Authorization state
typedef enum {
AUTHORIZATION_UNKNOWN,
AUTHORIZATION_PENDING,
AUTHORIZATION_DECLINED,
AUTHORIZATION_GRANTED
} authorization_state_t;
/* API_START */
// Classic + LE
/**
* @brief Disconnect connection with handle
* @param handle
*/
uint8_t gap_disconnect(hci_con_handle_t handle);
/**
* @brief Get connection type
* @param con_handle
* @result connection_type
*/
gap_connection_type_t gap_get_connection_type(hci_con_handle_t connection_handle);
// Classic
/**
* @brief Sets local name.
* @note has to be done before stack starts up
* @note Default name is 'BTstack 00:00:00:00:00:00'
* @note '00:00:00:00:00:00' in local_name will be replaced with actual bd addr
* @param name is not copied, make sure memory is accessible during stack startup
*/
void gap_set_local_name(const char * local_name);
/**
* @brief Set Extended Inquiry Response data
* @note has to be done before stack starts up
* @note If not set, local name will be used for EIR data (see gap_set_local_name)
* @note '00:00:00:00:00:00' in local_name will be replaced with actual bd addr
* @param eir_data size 240 bytes, is not copied make sure memory is accessible during stack startup
*/
void gap_set_extended_inquiry_response(const uint8_t * data);
/**
* @brief Set class of device that will be set during Bluetooth init.
* @note has to be done before stack starts up
*/
void gap_set_class_of_device(uint32_t class_of_device);
/**
* @brief Enable/disable bonding. Default is enabled.
* @param enabled
*/
void gap_set_bondable_mode(int enabled);
/**
* @brief Get bondable mode.
* @return 1 if bondable
*/
int gap_get_bondable_mode(void);
/* Configure Secure Simple Pairing */
/**
* @brief Enable will enable SSP during init.
*/
void gap_ssp_set_enable(int enable);
/**
* @brief Set IO Capability. BTstack will return capability to SSP requests
*/
void gap_ssp_set_io_capability(int ssp_io_capability);
/**
* @brief Set Authentication Requirements using during SSP
*/
void gap_ssp_set_authentication_requirement(int authentication_requirement);
/**
* @brief If set, BTstack will confirm a numeric comparison and enter '000000' if requested.
*/
void gap_ssp_set_auto_accept(int auto_accept);
/**
* @brief Start dedicated bonding with device. Disconnect after bonding.
* @param device
* @param request MITM protection
* @return error, if max num acl connections active
* @result GAP_DEDICATED_BONDING_COMPLETE
*/
int gap_dedicated_bonding(bd_addr_t device, int mitm_protection_required);
gap_security_level_t gap_security_level_for_link_key_type(link_key_type_t link_key_type);
gap_security_level_t gap_security_level(hci_con_handle_t con_handle);
void gap_request_security_level(hci_con_handle_t con_handle, gap_security_level_t level);
int gap_mitm_protection_required_for_security_level(gap_security_level_t level);
// LE
/**
* @brief Set parameters for LE Scan
*/
void gap_set_scan_parameters(uint8_t scan_type, uint16_t scan_interval, uint16_t scan_window);
/**
* @brief Start LE Scan
*/
void gap_start_scan(void);
/**
* @brief Stop LE Scan
*/
void gap_stop_scan(void);
/**
* @brief Enable privacy by using random addresses
* @param random_address_type to use (incl. OFF)
*/
void gap_random_address_set_mode(gap_random_address_type_t random_address_type);
/**
* @brief Get privacy mode
*/
gap_random_address_type_t gap_random_address_get_mode(void);
/**
* @brief Sets update period for random address
* @param period_ms in ms
*/
void gap_random_address_set_update_period(int period_ms);
/**
* @brief Sets a fixed random address for advertising
* @param addr
* @note Sets random address mode to type off
*/
void gap_random_address_set(bd_addr_t addr);
/**
* @brief Set Advertisement Data
* @param advertising_data_length
* @param advertising_data (max 31 octets)
* @note data is not copied, pointer has to stay valid
* @note '00:00:00:00:00:00' in advertising_data will be replaced with actual bd addr
*/
void gap_advertisements_set_data(uint8_t advertising_data_length, uint8_t * advertising_data);
/**
* @brief Set Advertisement Paramters
* @param adv_int_min
* @param adv_int_max
* @param adv_type
* @param direct_address_type
* @param direct_address
* @param channel_map
* @param filter_policy
* @note own_address_type is used from gap_random_address_set_mode
*/
void gap_advertisements_set_params(uint16_t adv_int_min, uint16_t adv_int_max, uint8_t adv_type,
uint8_t direct_address_typ, bd_addr_t direct_address, uint8_t channel_map, uint8_t filter_policy);
/**
* @brief Enable/Disable Advertisements. OFF by default.
* @param enabled
*/
void gap_advertisements_enable(int enabled);
/**
* @brief Set Scan Response Data
*
* @note For scan response data, scannable undirected advertising (ADV_SCAN_IND) need to be used
*
* @param advertising_data_length
* @param advertising_data (max 31 octets)
* @note data is not copied, pointer has to stay valid
* @note '00:00:00:00:00:00' in scan_response_data will be replaced with actual bd addr
*/
void gap_scan_response_set_data(uint8_t scan_response_data_length, uint8_t * scan_response_data);
/**
* @brief Set connection parameters for outgoing connections
* @param conn_scan_interval (unit: 0.625 msec), default: 60 ms
* @param conn_scan_window (unit: 0.625 msec), default: 30 ms
* @param conn_interval_min (unit: 1.25ms), default: 10 ms
* @param conn_interval_max (unit: 1.25ms), default: 30 ms
* @param conn_latency, default: 4
* @param supervision_timeout (unit: 10ms), default: 720 ms
* @param min_ce_length (unit: 0.625ms), default: 10 ms
* @param max_ce_length (unit: 0.625ms), default: 30 ms
*/
void gap_set_connection_parameters(uint16_t conn_scan_interval, uint16_t conn_scan_window,
uint16_t conn_interval_min, uint16_t conn_interval_max, uint16_t conn_latency,
uint16_t supervision_timeout, uint16_t min_ce_length, uint16_t max_ce_length);
/**
* @brief Request an update of the connection parameter for a given LE connection
* @param handle
* @param conn_interval_min (unit: 1.25ms)
* @param conn_interval_max (unit: 1.25ms)
* @param conn_latency
* @param supervision_timeout (unit: 10ms)
* @returns 0 if ok
*/
int gap_request_connection_parameter_update(hci_con_handle_t con_handle, uint16_t conn_interval_min,
uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout);
/**
* @brief Updates the connection parameters for a given LE connection
* @param handle
* @param conn_interval_min (unit: 1.25ms)
* @param conn_interval_max (unit: 1.25ms)
* @param conn_latency
* @param supervision_timeout (unit: 10ms)
* @returns 0 if ok
*/
int gap_update_connection_parameters(hci_con_handle_t con_handle, uint16_t conn_interval_min,
uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout);
/**
* @brief Set accepted connection parameter range
* @param range
*/
void gap_get_connection_parameter_range(le_connection_parameter_range_t * range);
/**
* @brief Get accepted connection parameter range
* @param range
*/
void gap_set_connection_parameter_range(le_connection_parameter_range_t * range);
/**
* @brief Test if connection parameters are inside in existing rage
* @param conn_interval_min (unit: 1.25ms)
* @param conn_interval_max (unit: 1.25ms)
* @param conn_latency
* @param supervision_timeout (unit: 10ms)
* @returns 1 if included
*/
int gap_connection_parameter_range_included(le_connection_parameter_range_t * existing_range, uint16_t le_conn_interval_min, uint16_t le_conn_interval_max, uint16_t le_conn_latency, uint16_t le_supervision_timeout);
/**
* @brief Set max number of connections in LE Peripheral role (if Bluetooth Controller supports it)
* @note: default: 1
* @param max_peripheral_connections
*/
void gap_set_max_number_peripheral_connections(int max_peripheral_connections);
/**
* @brief Connect to remote LE device
*/
uint8_t gap_connect(bd_addr_t addr, bd_addr_type_t addr_type);
/**
* @brief Cancel connection process initiated by gap_connect
*/
uint8_t gap_connect_cancel(void);
/**
* @brief Auto Connection Establishment - Start Connecting to device
* @param address_typ
* @param address
* @returns 0 if ok
*/
int gap_auto_connection_start(bd_addr_type_t address_typ, bd_addr_t address);
/**
* @brief Auto Connection Establishment - Stop Connecting to device
* @param address_typ
* @param address
* @returns 0 if ok
*/
int gap_auto_connection_stop(bd_addr_type_t address_typ, bd_addr_t address);
/**
* @brief Auto Connection Establishment - Stop everything
* @note Convenience function to stop all active auto connection attempts
*/
void gap_auto_connection_stop_all(void);
/**
*
* @brief Get encryption key size.
* @param con_handle
* @return 0 if not encrypted, 7-16 otherwise
*/
int gap_encryption_key_size(hci_con_handle_t con_handle);
/**
* @brief Get authentication property.
* @param con_handle
* @return 1 if bonded with OOB/Passkey (AND MITM protection)
*/
int gap_authenticated(hci_con_handle_t con_handle);
/**
* @brief Queries authorization state.
* @param con_handle
* @return authorization_state for the current session
*/
authorization_state_t gap_authorization_state(hci_con_handle_t con_handle);
// Classic
/**
* @brief Override page scan mode. Page scan mode enabled by l2cap when services are registered
* @note Might be used to reduce power consumption while Bluetooth module stays powered but no (new)
* connections are expected
*/
void gap_connectable_control(uint8_t enable);
/**
* @brief Allows to control if device is discoverable. OFF by default.
*/
void gap_discoverable_control(uint8_t enable);
/**
* @brief Gets local address.
*/
void gap_local_bd_addr(bd_addr_t address_buffer);
/**
* @brief Deletes link key for remote device with baseband address.
* @param addr
*/
void gap_drop_link_key_for_bd_addr(bd_addr_t addr);
/**
* @brief Delete all stored link keys
*/
void gap_delete_all_link_keys(void);
/**
* @brief Store link key for remote device with baseband address
* @param addr
* @param link_key
* @param link_key_type
*/
void gap_store_link_key_for_bd_addr(bd_addr_t addr, link_key_t link_key, link_key_type_t type);
/**
* @brief Setup Link Key iterator
* @param it
* @returns 1 on success
*/
int gap_link_key_iterator_init(btstack_link_key_iterator_t * it);
/**
* @brief Get next Link Key
* @param it
* @brief addr
* @brief link_key
* @brief type of link key
* @returns 1, if valid link key found
*/
int gap_link_key_iterator_get_next(btstack_link_key_iterator_t * it, bd_addr_t bd_addr, link_key_t link_key, link_key_type_t * type);
/**
* @brief Frees resources allocated by iterator_init
* @note Must be called after iteration to free resources
* @param it
*/
void gap_link_key_iterator_done(btstack_link_key_iterator_t * it);
/**
* @brief Start GAP Classic Inquiry
* @param duration in 1.28s units
* @return 0 if ok
* @events: GAP_EVENT_INQUIRY_RESULT, GAP_EVENT_INQUIRY_COMPLETE
*/
int gap_inquiry_start(uint8_t duration_in_1280ms_units);
/**
* @brief Stop GAP Classic Inquiry
* @brief Stop GAP Classic Inquiry
* @returns 0 if ok
* @events: GAP_EVENT_INQUIRY_COMPLETE
*/
int gap_inquiry_stop(void);
/**
* @brief Remote Name Request
* @param addr
* @param page_scan_repetition_mode
* @param clock_offset only used when bit 15 is set - pass 0 if not known
* @events: HCI_EVENT_REMOTE_NAME_REQUEST_COMPLETE
*/
int gap_remote_name_request(bd_addr_t addr, uint8_t page_scan_repetition_mode, uint16_t clock_offset);
/**
* @brief Legacy Pairing Pin Code Response
* @param addr
* @param pin
* @return 0 if ok
*/
int gap_pin_code_response(bd_addr_t addr, const char * pin);
/**
* @brief Abort Legacy Pairing
* @param addr
* @param pin
* @return 0 if ok
*/
int gap_pin_code_negative(bd_addr_t addr);
/**
* @brief SSP Passkey Response
* @param addr
* @param passkey [0..999999]
* @return 0 if ok
*/
int gap_ssp_passkey_response(bd_addr_t addr, uint32_t passkey);
/**
* @brief Abort SSP Passkey Entry/Pairing
* @param addr
* @param pin
* @return 0 if ok
*/
int gap_ssp_passkey_negative(bd_addr_t addr);
/**
* @brief Accept SSP Numeric Comparison
* @param addr
* @param passkey
* @return 0 if ok
*/
int gap_ssp_confirmation_response(bd_addr_t addr);
/**
* @brief Abort SSP Numeric Comparison/Pairing
* @param addr
* @param pin
* @return 0 if ok
*/
int gap_ssp_confirmation_negative(bd_addr_t addr);
// LE
/**
* @brief Get own addr type and address used for LE
*/
void gap_le_get_own_address(uint8_t * addr_type, bd_addr_t addr);
/**
* @brief Get state of connection re-encryptiong for bonded devices when in central role
* @note used by gatt_client and att_server to wait for re-encryption
* @param con_handle
* @return 1 if security setup is active
*/
int gap_reconnect_security_setup_active(hci_con_handle_t con_handle);
/* API_END*/
#if defined __cplusplus
}
#endif
#endif // __GAP_H