Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of nRF51822 by
ble_bondmngr.h
00001 /* Copyright (c) 2012 Nordic Semiconductor. All Rights Reserved. 00002 * 00003 * The information contained herein is property of Nordic Semiconductor ASA. 00004 * Terms and conditions of usage are described in detail in NORDIC 00005 * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT. 00006 * 00007 * Licensees are granted free, non-transferable use of the information. NO 00008 * WARRANTY of ANY KIND is provided. This heading must NOT be removed from 00009 * the file. 00010 * 00011 */ 00012 00013 /** @file 00014 * 00015 * @defgroup ble_sdk_lib_bond_manager Bonds and Persistent Data Manager 00016 * @{ 00017 * @ingroup ble_sdk_lib 00018 * @brief This module handles multiple bonds and persistent attributes. 00019 * 00020 * @details When using <i>Bluetooth</i> low energy, a central device and a peripheral device can 00021 * exchange identification information which they are capable of storing in memory (for 00022 * example, in non-volatile memory). This information can be used for identity verification 00023 * between the devices when they reconnect in the future. This relationship is known as a 00024 * 'bond'. 00025 * 00026 * <b>Bonding Information:</b> 00027 * 00028 * The S110 SoftDevice handles the BLE on-air transactions necessary to establish a new 00029 * bond or to use a previous bond when it reconnects to a bonded central. It is however up 00030 * to the application layer to memorize the <i>identification information</i> between 00031 * connections and to provide them back to the S110 stack when it detects a re-connection 00032 * from a previously bonded central. This identification information is referred to as 00033 * Bonding Information in code and the SDK. 00034 * 00035 * <b>System Attributes:</b> 00036 * 00037 * If the application is a GATT server, it stores a set of persistent attributes related 00038 * to a connection when bonding with a central. On reconnection with the known bonded 00039 * central, the application restores the related persistent attributes in the last known 00040 * state back to the S110 SoftDevice. These persistent attributes mainly include the Client 00041 * Characteristic Configuration Descriptor (or CCCD, see the <i><b>Bluetooth</b> 00042 * Core Specification</i> for more information) states and could include other attributes 00043 * in the future. Persistent attributes are referred to as System Attributes in code and 00044 * in the SDK documentation. 00045 * 00046 * An application can use the Bonds and Persistent Data Manager module (referred to as the 00047 * bond manager) included in the nRF51 SDK to handle most of the operations related to 00048 * the Bonding Information and System Attributes. The bond manager notifies the 00049 * application when it's connected to a new bonded central or to a previously bonded central. 00050 * The application can use the Bond Manager API to store or load (or restore) the 00051 * Bonding Information and System Attributes. The bond manager identifies all the centrals 00052 * the application is bonded to and restores their respective Bonding Information and 00053 * System Attributes to the S110 stack. 00054 * 00055 * In addition, you can use the bond manager to set up your application to advertise: 00056 * 00057 * - To a given bonded central using directed advertisement. 00058 * - To a list of bonded centrals - i.e. using whitelist. 00059 * 00060 * The bond manager automatically writes the Bonding Information to the flash memory when 00061 * the bonding procedure to a new central is finished. Upon disconnection, the application 00062 * should use the Bond Manager API @ref ble_bondmngr_bonded_centrals_store to write the 00063 * latest Bonding Information and System Attributes to flash. 00064 * 00065 * The bond manager provides the API @ref ble_bondmngr_sys_attr_store to allow the 00066 * application to write the System Attributes to flash while in a connection. Your 00067 * application should call this API when it considers that all CCCDs and other persistent 00068 * attributes are in a stable state. This API call will safely fail if System Attributes 00069 * data for the current connected central is already present in the flash. The API does so 00070 * because a flash write in such a situation would require an erase of flash, which takes a 00071 * long time (21 milliseconds) to complete. This may disrupt the radio. 00072 * 00073 * Applications using the Bond Manager must have a configuration file named 00074 * ble_bondmngr_cfg.h (see below for details). 00075 * 00076 * Refer to @ref ble_bond_mgr_msc to see the flow of events when connecting to a central 00077 * using the Bond Manager 00078 * 00079 * 00080 * @section ble_sdk_lib_bond_manager_cfg Configuration File 00081 * Applications using the Bond Manager must have a configuration file named ble_bondmngr_cfg.h. 00082 * Here is an example of this file: 00083 * 00084 * @code 00085 * #ifndef BLE_BONDMNGR_CFG_H__ 00086 * #define BLE_BONDMNGR_CFG_H__ 00087 * 00088 * #define BLE_BONDMNGR_CCCD_COUNT 1 00089 * #define BLE_BONDMNGR_MAX_BONDED_CENTRALS 4 00090 * 00091 * #endif // BLE_BONDMNGR_CFG_H__ 00092 * @endcode 00093 * 00094 * BLE_BONDMNGR_CCCD_COUNT is the number of CCCDs used in the application, and 00095 * BLE_BONDMNGR_MAX_BONDED_CENTRALS is the maximum number of bonded centrals to be supported by the 00096 * application. 00097 */ 00098 00099 #ifndef BLE_BONDMNGR_H__ 00100 #define BLE_BONDMNGR_H__ 00101 00102 #include <stdint.h> 00103 #include "nordic_global.h" 00104 #include "ble.h" 00105 #include "ble_srv_common.h " 00106 00107 00108 /** @defgroup ble_bond_mgr_msc Message Sequence Charts 00109 * @{ 00110 * @brief Bond Manager interaction with S110 Stack 00111 * @{ 00112 * @defgroup UNBONDED_CENTRAL Connecting to an unbonded central 00113 * @image html bond_manager_unbonded_master.jpg Connecting to an unbonded central 00114 * @defgroup BONDED_CENTRAL Connecting to a bonded central 00115 * @image html bond_manager_bonded_master.jpg Connecting to a bonded central 00116 * @} 00117 * @} 00118 */ 00119 00120 /** @defgroup DEFINES Defines 00121 * @brief Macros defined by this module. 00122 * @{ */ 00123 00124 #define INVALID_CENTRAL_HANDLE (-1) /**< Invalid handle, used to indicate that the central is not a known bonded central. */ 00125 00126 /** @} */ 00127 00128 /** @defgroup ENUMS Enumerations 00129 * @brief Enumerations defined by this module. 00130 * @{ */ 00131 00132 /**@brief Bond Manager Module event type. */ 00133 typedef enum 00134 { 00135 BLE_BONDMNGR_EVT_NEW_BOND, /**< New bond has been created. */ 00136 BLE_BONDMNGR_EVT_CONN_TO_BONDED_CENTRAL, /**< Connected to a previously bonded central. */ 00137 BLE_BONDMNGR_EVT_ENCRYPTED, /**< Current link is encrypted. */ 00138 BLE_BONDMNGR_EVT_AUTH_STATUS_UPDATED, /**< Authentication status updated for current central. */ 00139 BLE_BONDMNGR_EVT_BOND_FLASH_FULL /**< Flash block for storing Bonding Information is full. */ 00140 } ble_bondmngr_evt_type_t; 00141 00142 /** @} */ 00143 00144 00145 /** @defgroup DATA_STRUCTURES Data Structures 00146 * @brief Data Structures defined by this module. 00147 * @{ */ 00148 00149 /**@brief Bond Manager Module event. */ 00150 typedef struct 00151 { 00152 ble_bondmngr_evt_type_t evt_type; /**< Type of event. */ 00153 int8_t central_handle; /**< Handle to the current central. This is an index to the central list maintained internally by the bond manager. */ 00154 uint16_t central_id; /**< Identifier to the central. This will be the same as Encryption diversifier of the central (see @ref ble_gap_evt_sec_info_request_t). This value is constant for the duration of the bond. */ 00155 } ble_bondmngr_evt_t; 00156 00157 /** @} */ 00158 00159 /** @defgroup TYPEDEFS Typedefs 00160 * @brief Typedefs defined by this module. 00161 * @{ */ 00162 00163 /**@brief Bond Manager Module event handler type. */ 00164 typedef void (*ble_bondmngr_evt_handler_t) (ble_bondmngr_evt_t * p_evt); 00165 00166 /** @} */ 00167 00168 /** @addtogroup DATA_STRUCTURES 00169 * @{ */ 00170 00171 /**@brief Bond Manager Module init structure. This contains all options and data needed for 00172 * initialization of the Bond Manager module. */ 00173 typedef struct 00174 { 00175 uint8_t flash_page_num_bond; /**< Flash page number to use for storing Bonding Information. */ 00176 uint8_t flash_page_num_sys_attr; /**< Flash page number to use for storing System Attributes. */ 00177 bool bonds_delete; /**< TRUE if bonding and System Attributes for all centrals is to be deleted from flash during initialization, FALSE otherwise. */ 00178 ble_bondmngr_evt_handler_t evt_handler; /**< Event handler to be called for handling events in bond manager. */ 00179 ble_srv_error_handler_t error_handler; /**< Function to be called in case of an error. */ 00180 } ble_bondmngr_init_t; 00181 00182 /** @} */ 00183 00184 00185 /** @defgroup FUNCTIONS Functions 00186 * @brief Functions/APIs implemented and exposed by this module. 00187 * @{ */ 00188 00189 /**@brief Function for initializing the Bond Manager. 00190 * 00191 * @param[in] p_init This contains information needed to initialize this module. 00192 * 00193 * @return NRF_SUCCESS on successful initialization, otherwise an error code. 00194 */ 00195 uint32_t ble_bondmngr_init(ble_bondmngr_init_t * p_init); 00196 00197 /**@brief Function for handling all events from the BLE stack that relate to this module. 00198 * 00199 * @param[in] p_ble_evt The event received from the BLE stack. 00200 * 00201 * @return NRF_SUCCESS if all operations went successfully, 00202 * NRF_ERROR_NO_MEM if the maximum number of bonded centrals has been reached. 00203 * Other error codes in other situations. 00204 */ 00205 void ble_bondmngr_on_ble_evt(ble_evt_t * p_ble_evt); 00206 00207 /**@brief Function for storing the bonded centrals data including bonding info and System Attributes into 00208 * flash memory. 00209 * 00210 * @details If the data to be written is different from the existing data, this function erases the 00211 * flash pages before writing to flash. 00212 * 00213 * @warning This function could prevent the radio from running. Therefore it MUST be called ONLY 00214 * when the application knows that the <i>Bluetooth</i> radio is not active. An example of 00215 * such a state is when the application has received the Disconnected event and has not yet 00216 * started advertising. <b>If it is called in any other state, or if it is not called at 00217 * all, the behavior is undefined.</b> 00218 * 00219 * @return NRF_SUCCESS on success, an error_code otherwise. 00220 */ 00221 uint32_t ble_bondmngr_bonded_centrals_store(void); 00222 00223 /**@brief Function for deleting the bonded central database from flash. 00224 * 00225 * @details After calling this function you should call ble_bondmngr_init() to re-initialize the 00226 * RAM database. 00227 * 00228 * @return NRF_SUCCESS on success, an error_code otherwise. 00229 */ 00230 uint32_t ble_bondmngr_bonded_centrals_delete(void); 00231 00232 /**@brief Function for getting the whitelist containing all currently bonded centrals. 00233 * 00234 * @details This function populates the whitelist with either the IRKs or the public adresses 00235 * of all bonded centrals. 00236 * 00237 * @param[out] p_whitelist Whitelist structure with all bonded centrals. 00238 * 00239 * @return NRF_SUCCESS on success, an error_code otherwise. 00240 */ 00241 uint32_t ble_bondmngr_whitelist_get(ble_gap_whitelist_t * p_whitelist); 00242 00243 /**@brief Function for getting the central's address corresponding to a given central_handle. 00244 * 00245 * @note This function returns NRF_ERROR_INVALID_PARAM if the given central has a private 00246 * address. 00247 * 00248 * @param[in] central_handle Central's handle. 00249 * @param[out] p_central_addr Pointer to the central's address which can be used for 00250 * directed advertising. 00251 */ 00252 uint32_t ble_bondmngr_central_addr_get(int8_t central_handle, ble_gap_addr_t * p_central_addr); 00253 00254 /**@brief Function for storing the System Attributes of a newly connected central. 00255 * 00256 * @details This function fetches the System Attributes of the current central from the stack, adds 00257 * it to the database in memory, and also stores it in the flash (without erasing any 00258 * flash page). 00259 * This function is intended to facilitate the storage of System Attributes when connected 00260 * to new central (whose System Attributes are NOT yet stored in flash) even in connected 00261 * state without affecting radio link. This function can, for example, be called after the 00262 * CCCD is written by a central. The function will succeed if the central is a new central. 00263 * See @ref ble_sdk_app_hids_keyboard or @ref ble_sdk_app_hids_mouse for sample usage. 00264 * 00265 * @return NRF_SUCCESS on success, otherwise an error code. 00266 * NRF_ERROR_INVALID_STATE is returned if the System Attributes of the current central is 00267 * already present in the flash because it is a previously known central. 00268 */ 00269 uint32_t ble_bondmngr_sys_attr_store(void); 00270 00271 /**@brief Function for fetching the identifiers of known centrals. 00272 * 00273 * @details This function fetches the identifiers of the centrals that are currently in the 00274 * database, or in other words, known to the bond manager. 00275 * 00276 * @param[out] p_central_ids Pointer to the array of central identifiers. It is recommended 00277 * that the length of this array be equal to 00278 * MAX_NUMBER_OF_BONDED_CENTRALS * 2 bytes. If value of this pointer 00279 * is NULL, only the number of centrals in the database will be 00280 * filled in p_length. This can be used to find out the 00281 * required size of the array pointed to by p_central_ids in 00282 * a subsequent call. 00283 * @param[in, out] p_length Pointer to the length of p_central_ids array provided as 00284 * input. On return, this function will write the number of central 00285 * identifiers found to p_length 00286 * 00287 * @return NRF_SUCCESS on success. 00288 * NRF_ERROR_NULL if the input parameter p_length is NULL. 00289 * NRF_ERROR_INVALID_STATE is returned if the bond manager was not initialized. 00290 * NRF_ERROR_DATA_SIZE is returned if the length of the input parameter 00291 * p_central_ids provided is not enough to fit in all the central identifiers in the 00292 * database. 00293 */ 00294 uint32_t ble_bondmngr_central_ids_get(uint16_t * p_central_ids, uint16_t * p_length); 00295 00296 /**@brief Function for deleting a single central from the database. 00297 * @details This function deletes the Bonding Information and System Attributes of a single 00298 * central from the flash. 00299 * The application can use the @ref ble_bondmngr_central_ids_get function to fetch the 00300 * identifiers of centrals present in the database and then call this function. 00301 * 00302 * @warning This function could prevent the radio from running. Therefore it MUST be called ONLY 00303 * when the application knows that the <i>Bluetooth</i> radio is not active. An example 00304 * of such a state could be when the application is not in a connected state AND is 00305 * also not advertising. <b>If it is called in any other state, the behavior is 00306 * undefined.</b> 00307 * 00308 * @param[in] central_id Identifier of the central to be deleted. 00309 * 00310 * @return NRF_SUCCESS on success. 00311 * NRF_ERROR_INVALID_STATE is returned if the bond manager was not initialized. 00312 * NRF_ERROR_NOT_FOUND if the central with the given identifier is not found in the 00313 * database. 00314 */ 00315 uint32_t ble_bondmngr_bonded_central_delete(uint16_t central_id); 00316 00317 /**@brief Function to verify encryption status link with bonded central is encrypted or not. 00318 * @details This function provides status of encrption of the link with a bonded central. 00319 * Its is recommended that the application can use the 00320 * @ref ble_bondmngr_central_ids_get function to verify if the central is in the 00321 * database and then call this function. 00322 * 00323 * @warning Currently the central id paramater is unused and is added only for future extension. 00324 * As, today only one link is permitted for the peripheral device, status of current 00325 * link is provided. In future, with more possibilities in the topology, central_id 00326 * will be needed to identify the central. 00327 * 00328 * @param[out] status Status of encryption, true implies link encrypted. 00329 * 00330 * @return NRF_SUCCESS on success. 00331 * NRF_ERROR_INVALID_STATE is returned if the bond manager was not initialized. 00332 */ 00333 uint32_t ble_bondmngr_is_link_encrypted(bool * status); 00334 00335 /** @} */ 00336 00337 #endif // BLE_BONDMNGR_H__ 00338 00339 /** @} */
Generated on Tue Jul 12 2022 19:00:52 by
