Jinu Andrews / nRF51

lib/ble/inc/ble_bondmngr.h@0:6ba9b94b8997, 2017-02-09 (annotated)

Committer:
jinu
Date:
Thu Feb 09 06:08:17 2017 +0000
Revision:
0:6ba9b94b8997
NRF51 serialization libraries for mDot

Who changed what in which revision?

UserRevisionLine numberNew contents of line
jinu 0:6ba9b94b8997 1 /* Copyright (c) Nordic Semiconductor ASA
jinu 0:6ba9b94b8997 2 * All rights reserved.
jinu 0:6ba9b94b8997 3 *
jinu 0:6ba9b94b8997 4 * Redistribution and use in source and binary forms, with or without modification,
jinu 0:6ba9b94b8997 5 * are permitted provided that the following conditions are met:
jinu 0:6ba9b94b8997 6 *
jinu 0:6ba9b94b8997 7 * 1. Redistributions of source code must retain the above copyright notice, this
jinu 0:6ba9b94b8997 8 * list of conditions and the following disclaimer.
jinu 0:6ba9b94b8997 9 *
jinu 0:6ba9b94b8997 10 * 2. Redistributions in binary form must reproduce the above copyright notice, this
jinu 0:6ba9b94b8997 11 * list of conditions and the following disclaimer in the documentation and/or
jinu 0:6ba9b94b8997 12 * other materials provided with the distribution.
jinu 0:6ba9b94b8997 13 *
jinu 0:6ba9b94b8997 14 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other
jinu 0:6ba9b94b8997 15 * contributors to this software may be used to endorse or promote products
jinu 0:6ba9b94b8997 16 * derived from this software without specific prior written permission.
jinu 0:6ba9b94b8997 17 *
jinu 0:6ba9b94b8997 18 * 4. This software must only be used in a processor manufactured by Nordic
jinu 0:6ba9b94b8997 19 * Semiconductor ASA, or in a processor manufactured by a third party that
jinu 0:6ba9b94b8997 20 * is used in combination with a processor manufactured by Nordic Semiconductor.
jinu 0:6ba9b94b8997 21 *
jinu 0:6ba9b94b8997 22 *
jinu 0:6ba9b94b8997 23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
jinu 0:6ba9b94b8997 24 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
jinu 0:6ba9b94b8997 25 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
jinu 0:6ba9b94b8997 26 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
jinu 0:6ba9b94b8997 27 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
jinu 0:6ba9b94b8997 28 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
jinu 0:6ba9b94b8997 29 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
jinu 0:6ba9b94b8997 30 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
jinu 0:6ba9b94b8997 31 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
jinu 0:6ba9b94b8997 32 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
jinu 0:6ba9b94b8997 33 */
jinu 0:6ba9b94b8997 34
jinu 0:6ba9b94b8997 35 /** @file
jinu 0:6ba9b94b8997 36 *
jinu 0:6ba9b94b8997 37 * @defgroup ble_sdk_lib_bond_manager Bonds and Persistent Data Manager
jinu 0:6ba9b94b8997 38 * @{
jinu 0:6ba9b94b8997 39 * @ingroup ble_sdk_lib
jinu 0:6ba9b94b8997 40 * @brief This module handles multiple bonds and persistent attributes.
jinu 0:6ba9b94b8997 41 *
jinu 0:6ba9b94b8997 42 * @details When using <i>Bluetooth</i> low energy, a central device and a peripheral device can
jinu 0:6ba9b94b8997 43 * exchange identification information which they are capable of storing in memory (for
jinu 0:6ba9b94b8997 44 * example, in non-volatile memory). This information can be used for identity verification
jinu 0:6ba9b94b8997 45 * between the devices when they reconnect in the future. This relationship is known as a
jinu 0:6ba9b94b8997 46 * 'bond'.
jinu 0:6ba9b94b8997 47 *
jinu 0:6ba9b94b8997 48 * <b>Bonding Information:</b>
jinu 0:6ba9b94b8997 49 *
jinu 0:6ba9b94b8997 50 * The S110 SoftDevice handles the BLE on-air transactions necessary to establish a new
jinu 0:6ba9b94b8997 51 * bond or to use a previous bond when it reconnects to a bonded central. It is however up
jinu 0:6ba9b94b8997 52 * to the application layer to memorize the <i>identification information</i> between
jinu 0:6ba9b94b8997 53 * connections and to provide them back to the S110 stack when it detects a re-connection
jinu 0:6ba9b94b8997 54 * from a previously bonded central. This identification information is referred to as
jinu 0:6ba9b94b8997 55 * Bonding Information in code and the SDK.
jinu 0:6ba9b94b8997 56 *
jinu 0:6ba9b94b8997 57 * <b>System Attributes:</b>
jinu 0:6ba9b94b8997 58 *
jinu 0:6ba9b94b8997 59 * If the application is a GATT server, it stores a set of persistent attributes related
jinu 0:6ba9b94b8997 60 * to a connection when bonding with a central. On reconnection with the known bonded
jinu 0:6ba9b94b8997 61 * central, the application restores the related persistent attributes in the last known
jinu 0:6ba9b94b8997 62 * state back to the S110 SoftDevice. These persistent attributes mainly include the Client
jinu 0:6ba9b94b8997 63 * Characteristic Configuration Descriptor (or CCCD, see the <i><b>Bluetooth</b>
jinu 0:6ba9b94b8997 64 * Core Specification</i> for more information) states and could include other attributes
jinu 0:6ba9b94b8997 65 * in the future. Persistent attributes are referred to as System Attributes in code and
jinu 0:6ba9b94b8997 66 * in the SDK documentation.
jinu 0:6ba9b94b8997 67 *
jinu 0:6ba9b94b8997 68 * An application can use the Bonds and Persistent Data Manager module (referred to as the
jinu 0:6ba9b94b8997 69 * bond manager) included in the nRF51 SDK to handle most of the operations related to
jinu 0:6ba9b94b8997 70 * the Bonding Information and System Attributes. The bond manager notifies the
jinu 0:6ba9b94b8997 71 * application when it's connected to a new bonded central or to a previously bonded central.
jinu 0:6ba9b94b8997 72 * The application can use the Bond Manager API to store or load (or restore) the
jinu 0:6ba9b94b8997 73 * Bonding Information and System Attributes. The bond manager identifies all the centrals
jinu 0:6ba9b94b8997 74 * the application is bonded to and restores their respective Bonding Information and
jinu 0:6ba9b94b8997 75 * System Attributes to the S110 stack.
jinu 0:6ba9b94b8997 76 *
jinu 0:6ba9b94b8997 77 * In addition, you can use the bond manager to set up your application to advertise:
jinu 0:6ba9b94b8997 78 *
jinu 0:6ba9b94b8997 79 * - To a given bonded central using directed advertisement.
jinu 0:6ba9b94b8997 80 * - To a list of bonded centrals - i.e. using whitelist.
jinu 0:6ba9b94b8997 81 *
jinu 0:6ba9b94b8997 82 * The bond manager automatically writes the Bonding Information to the flash memory when
jinu 0:6ba9b94b8997 83 * the bonding procedure to a new central is finished. Upon disconnection, the application
jinu 0:6ba9b94b8997 84 * should use the Bond Manager API @ref ble_bondmngr_bonded_centrals_store to write the
jinu 0:6ba9b94b8997 85 * latest Bonding Information and System Attributes to flash.
jinu 0:6ba9b94b8997 86 *
jinu 0:6ba9b94b8997 87 * The bond manager provides the API @ref ble_bondmngr_sys_attr_store to allow the
jinu 0:6ba9b94b8997 88 * application to write the System Attributes to flash while in a connection. Your
jinu 0:6ba9b94b8997 89 * application should call this API when it considers that all CCCDs and other persistent
jinu 0:6ba9b94b8997 90 * attributes are in a stable state. This API call will safely fail if System Attributes
jinu 0:6ba9b94b8997 91 * data for the current connected central is already present in the flash. The API does so
jinu 0:6ba9b94b8997 92 * because a flash write in such a situation would require an erase of flash, which takes a
jinu 0:6ba9b94b8997 93 * long time (21 milliseconds) to complete. This may disrupt the radio.
jinu 0:6ba9b94b8997 94 *
jinu 0:6ba9b94b8997 95 * Applications using the Bond Manager must have a configuration file named
jinu 0:6ba9b94b8997 96 * ble_bondmngr_cfg.h (see below for details).
jinu 0:6ba9b94b8997 97 *
jinu 0:6ba9b94b8997 98 * Refer to @ref ble_bond_mgr_msc to see the flow of events when connecting to a central
jinu 0:6ba9b94b8997 99 * using the Bond Manager
jinu 0:6ba9b94b8997 100 *
jinu 0:6ba9b94b8997 101 *
jinu 0:6ba9b94b8997 102 * @section ble_sdk_lib_bond_manager_cfg Configuration File
jinu 0:6ba9b94b8997 103 * Applications using the Bond Manager must have a configuration file named ble_bondmngr_cfg.h.
jinu 0:6ba9b94b8997 104 * Here is an example of this file:
jinu 0:6ba9b94b8997 105 *
jinu 0:6ba9b94b8997 106 * @code
jinu 0:6ba9b94b8997 107 * #ifndef BLE_BONDMNGR_CFG_H__
jinu 0:6ba9b94b8997 108 * #define BLE_BONDMNGR_CFG_H__
jinu 0:6ba9b94b8997 109 *
jinu 0:6ba9b94b8997 110 * #define BLE_BONDMNGR_CCCD_COUNT 1
jinu 0:6ba9b94b8997 111 * #define BLE_BONDMNGR_MAX_BONDED_CENTRALS 4
jinu 0:6ba9b94b8997 112 *
jinu 0:6ba9b94b8997 113 * #endif // BLE_BONDMNGR_CFG_H__
jinu 0:6ba9b94b8997 114 * @endcode
jinu 0:6ba9b94b8997 115 *
jinu 0:6ba9b94b8997 116 * BLE_BONDMNGR_CCCD_COUNT is the number of CCCDs used in the application, and
jinu 0:6ba9b94b8997 117 * BLE_BONDMNGR_MAX_BONDED_CENTRALS is the maximum number of bonded centrals to be supported by the
jinu 0:6ba9b94b8997 118 * application.
jinu 0:6ba9b94b8997 119 */
jinu 0:6ba9b94b8997 120
jinu 0:6ba9b94b8997 121 #ifndef BLE_BONDMNGR_H__
jinu 0:6ba9b94b8997 122 #define BLE_BONDMNGR_H__
jinu 0:6ba9b94b8997 123
jinu 0:6ba9b94b8997 124 #include <stdint.h>
jinu 0:6ba9b94b8997 125 #include "ble.h"
jinu 0:6ba9b94b8997 126 #include "ble_srv_common.h"
jinu 0:6ba9b94b8997 127
jinu 0:6ba9b94b8997 128
jinu 0:6ba9b94b8997 129 /** @defgroup ble_bond_mgr_msc Message Sequence Charts
jinu 0:6ba9b94b8997 130 * @{
jinu 0:6ba9b94b8997 131 * @brief Bond Manager interaction with S110 Stack
jinu 0:6ba9b94b8997 132 * @{
jinu 0:6ba9b94b8997 133 * @defgroup UNBONDED_CENTRAL Connecting to an unbonded central
jinu 0:6ba9b94b8997 134 * @image html bond_manager_unbonded_master.jpg Connecting to an unbonded central
jinu 0:6ba9b94b8997 135 * @defgroup BONDED_CENTRAL Connecting to a bonded central
jinu 0:6ba9b94b8997 136 * @image html bond_manager_bonded_master.jpg Connecting to a bonded central
jinu 0:6ba9b94b8997 137 * @}
jinu 0:6ba9b94b8997 138 * @}
jinu 0:6ba9b94b8997 139 */
jinu 0:6ba9b94b8997 140
jinu 0:6ba9b94b8997 141 /** @defgroup DEFINES Defines
jinu 0:6ba9b94b8997 142 * @brief Macros defined by this module.
jinu 0:6ba9b94b8997 143 * @{ */
jinu 0:6ba9b94b8997 144
jinu 0:6ba9b94b8997 145 #define INVALID_CENTRAL_HANDLE (-1) /**< Invalid handle, used to indicate that the central is not a known bonded central. */
jinu 0:6ba9b94b8997 146
jinu 0:6ba9b94b8997 147 /** @} */
jinu 0:6ba9b94b8997 148
jinu 0:6ba9b94b8997 149 /** @defgroup ENUMS Enumerations
jinu 0:6ba9b94b8997 150 * @brief Enumerations defined by this module.
jinu 0:6ba9b94b8997 151 * @{ */
jinu 0:6ba9b94b8997 152
jinu 0:6ba9b94b8997 153 /**@brief Bond Manager Module event type. */
jinu 0:6ba9b94b8997 154 typedef enum
jinu 0:6ba9b94b8997 155 {
jinu 0:6ba9b94b8997 156 BLE_BONDMNGR_EVT_NEW_BOND, /**< New bond has been created. */
jinu 0:6ba9b94b8997 157 BLE_BONDMNGR_EVT_CONN_TO_BONDED_CENTRAL, /**< Connected to a previously bonded central. */
jinu 0:6ba9b94b8997 158 BLE_BONDMNGR_EVT_ENCRYPTED, /**< Current link is encrypted. */
jinu 0:6ba9b94b8997 159 BLE_BONDMNGR_EVT_AUTH_STATUS_UPDATED, /**< Authentication status updated for current central. */
jinu 0:6ba9b94b8997 160 BLE_BONDMNGR_EVT_BOND_FLASH_FULL /**< Flash block for storing Bonding Information is full. */
jinu 0:6ba9b94b8997 161 } ble_bondmngr_evt_type_t;
jinu 0:6ba9b94b8997 162
jinu 0:6ba9b94b8997 163 /** @} */
jinu 0:6ba9b94b8997 164
jinu 0:6ba9b94b8997 165
jinu 0:6ba9b94b8997 166 /** @defgroup DATA_STRUCTURES Data Structures
jinu 0:6ba9b94b8997 167 * @brief Data Structures defined by this module.
jinu 0:6ba9b94b8997 168 * @{ */
jinu 0:6ba9b94b8997 169
jinu 0:6ba9b94b8997 170 /**@brief Bond Manager Module event. */
jinu 0:6ba9b94b8997 171 typedef struct
jinu 0:6ba9b94b8997 172 {
jinu 0:6ba9b94b8997 173 ble_bondmngr_evt_type_t evt_type; /**< Type of event. */
jinu 0:6ba9b94b8997 174 int8_t central_handle; /**< Handle to the current central. This is an index to the central list maintained internally by the bond manager. */
jinu 0:6ba9b94b8997 175 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. */
jinu 0:6ba9b94b8997 176 } ble_bondmngr_evt_t;
jinu 0:6ba9b94b8997 177
jinu 0:6ba9b94b8997 178 /** @} */
jinu 0:6ba9b94b8997 179
jinu 0:6ba9b94b8997 180 /** @defgroup TYPEDEFS Typedefs
jinu 0:6ba9b94b8997 181 * @brief Typedefs defined by this module.
jinu 0:6ba9b94b8997 182 * @{ */
jinu 0:6ba9b94b8997 183
jinu 0:6ba9b94b8997 184 /**@brief Bond Manager Module event handler type. */
jinu 0:6ba9b94b8997 185 typedef void (*ble_bondmngr_evt_handler_t) (ble_bondmngr_evt_t * p_evt);
jinu 0:6ba9b94b8997 186
jinu 0:6ba9b94b8997 187 /** @} */
jinu 0:6ba9b94b8997 188
jinu 0:6ba9b94b8997 189 /** @addtogroup DATA_STRUCTURES
jinu 0:6ba9b94b8997 190 * @{ */
jinu 0:6ba9b94b8997 191
jinu 0:6ba9b94b8997 192 /**@brief Bond Manager Module init structure. This contains all options and data needed for
jinu 0:6ba9b94b8997 193 * initialization of the Bond Manager module. */
jinu 0:6ba9b94b8997 194 typedef struct
jinu 0:6ba9b94b8997 195 {
jinu 0:6ba9b94b8997 196 uint8_t flash_page_num_bond; /**< Deprecated: Flash page number to use for storing Bonding Information. */
jinu 0:6ba9b94b8997 197 uint8_t flash_page_num_sys_attr; /**< Deprecated: Flash page number to use for storing System Attributes. */
jinu 0:6ba9b94b8997 198 bool bonds_delete; /**< TRUE if bonding and System Attributes for all centrals is to be deleted from flash during initialization, FALSE otherwise. */
jinu 0:6ba9b94b8997 199 ble_bondmngr_evt_handler_t evt_handler; /**< Event handler to be called for handling events in bond manager. */
jinu 0:6ba9b94b8997 200 ble_srv_error_handler_t error_handler; /**< Function to be called in case of an error. */
jinu 0:6ba9b94b8997 201 } ble_bondmngr_init_t;
jinu 0:6ba9b94b8997 202
jinu 0:6ba9b94b8997 203 /** @} */
jinu 0:6ba9b94b8997 204
jinu 0:6ba9b94b8997 205
jinu 0:6ba9b94b8997 206 /** @defgroup FUNCTIONS Functions
jinu 0:6ba9b94b8997 207 * @brief Functions/APIs implemented and exposed by this module.
jinu 0:6ba9b94b8997 208 * @{ */
jinu 0:6ba9b94b8997 209
jinu 0:6ba9b94b8997 210 /**@brief Function for initializing the Bond Manager.
jinu 0:6ba9b94b8997 211 *
jinu 0:6ba9b94b8997 212 * @param[in] p_init This contains information needed to initialize this module.
jinu 0:6ba9b94b8997 213 *
jinu 0:6ba9b94b8997 214 * @return NRF_SUCCESS on successful initialization, otherwise an error code.
jinu 0:6ba9b94b8997 215 */
jinu 0:6ba9b94b8997 216 uint32_t ble_bondmngr_init(ble_bondmngr_init_t * p_init);
jinu 0:6ba9b94b8997 217
jinu 0:6ba9b94b8997 218 /**@brief Function for handling all events from the BLE stack that relate to this module.
jinu 0:6ba9b94b8997 219 *
jinu 0:6ba9b94b8997 220 * @param[in] p_ble_evt The event received from the BLE stack.
jinu 0:6ba9b94b8997 221 *
jinu 0:6ba9b94b8997 222 * @return NRF_SUCCESS if all operations went successfully,
jinu 0:6ba9b94b8997 223 * NRF_ERROR_NO_MEM if the maximum number of bonded centrals has been reached.
jinu 0:6ba9b94b8997 224 * Other error codes in other situations.
jinu 0:6ba9b94b8997 225 */
jinu 0:6ba9b94b8997 226 void ble_bondmngr_on_ble_evt(ble_evt_t * p_ble_evt);
jinu 0:6ba9b94b8997 227
jinu 0:6ba9b94b8997 228 /**@brief Function for storing the bonded centrals data including bonding info and System Attributes into
jinu 0:6ba9b94b8997 229 * flash memory.
jinu 0:6ba9b94b8997 230 *
jinu 0:6ba9b94b8997 231 * @details If the data to be written is different from the existing data, this function erases the
jinu 0:6ba9b94b8997 232 * flash pages before writing to flash.
jinu 0:6ba9b94b8997 233 *
jinu 0:6ba9b94b8997 234 * @warning This function could prevent the radio from running. Therefore it MUST be called ONLY
jinu 0:6ba9b94b8997 235 * when the application knows that the <i>Bluetooth</i> radio is not active. An example of
jinu 0:6ba9b94b8997 236 * such a state is when the application has received the Disconnected event and has not yet
jinu 0:6ba9b94b8997 237 * started advertising. <b>If it is called in any other state, or if it is not called at
jinu 0:6ba9b94b8997 238 * all, the behavior is undefined.</b>
jinu 0:6ba9b94b8997 239 *
jinu 0:6ba9b94b8997 240 * @return NRF_SUCCESS on success, an error_code otherwise.
jinu 0:6ba9b94b8997 241 */
jinu 0:6ba9b94b8997 242 uint32_t ble_bondmngr_bonded_centrals_store(void);
jinu 0:6ba9b94b8997 243
jinu 0:6ba9b94b8997 244 /**@brief Function for deleting the bonded central database from flash.
jinu 0:6ba9b94b8997 245 *
jinu 0:6ba9b94b8997 246 * @details After calling this function you should call ble_bondmngr_init() to re-initialize the
jinu 0:6ba9b94b8997 247 * RAM database.
jinu 0:6ba9b94b8997 248 *
jinu 0:6ba9b94b8997 249 * @return NRF_SUCCESS on success, an error_code otherwise.
jinu 0:6ba9b94b8997 250 */
jinu 0:6ba9b94b8997 251 uint32_t ble_bondmngr_bonded_centrals_delete(void);
jinu 0:6ba9b94b8997 252
jinu 0:6ba9b94b8997 253 /**@brief Function for getting the whitelist containing all currently bonded centrals.
jinu 0:6ba9b94b8997 254 *
jinu 0:6ba9b94b8997 255 * @details This function populates the whitelist with either the IRKs or the public adresses
jinu 0:6ba9b94b8997 256 * of all bonded centrals.
jinu 0:6ba9b94b8997 257 *
jinu 0:6ba9b94b8997 258 * @param[out] p_whitelist Whitelist structure with all bonded centrals.
jinu 0:6ba9b94b8997 259 *
jinu 0:6ba9b94b8997 260 * @return NRF_SUCCESS on success, an error_code otherwise.
jinu 0:6ba9b94b8997 261 */
jinu 0:6ba9b94b8997 262 uint32_t ble_bondmngr_whitelist_get(ble_gap_whitelist_t * p_whitelist);
jinu 0:6ba9b94b8997 263
jinu 0:6ba9b94b8997 264 /**@brief Function for getting the central's address corresponding to a given central_handle.
jinu 0:6ba9b94b8997 265 *
jinu 0:6ba9b94b8997 266 * @note This function returns NRF_ERROR_INVALID_PARAM if the given central has a private
jinu 0:6ba9b94b8997 267 * address.
jinu 0:6ba9b94b8997 268 *
jinu 0:6ba9b94b8997 269 * @param[in] central_handle Central's handle.
jinu 0:6ba9b94b8997 270 * @param[out] p_central_addr Pointer to the central's address which can be used for
jinu 0:6ba9b94b8997 271 * directed advertising.
jinu 0:6ba9b94b8997 272 */
jinu 0:6ba9b94b8997 273 uint32_t ble_bondmngr_central_addr_get(int8_t central_handle, ble_gap_addr_t * p_central_addr);
jinu 0:6ba9b94b8997 274
jinu 0:6ba9b94b8997 275 /**@brief Function for storing the System Attributes of a newly connected central.
jinu 0:6ba9b94b8997 276 *
jinu 0:6ba9b94b8997 277 * @details This function fetches the System Attributes of the current central from the stack, adds
jinu 0:6ba9b94b8997 278 * it to the database in memory, and also stores it in the flash (without erasing any
jinu 0:6ba9b94b8997 279 * flash page).
jinu 0:6ba9b94b8997 280 * This function is intended to facilitate the storage of System Attributes when connected
jinu 0:6ba9b94b8997 281 * to new central (whose System Attributes are NOT yet stored in flash) even in connected
jinu 0:6ba9b94b8997 282 * state without affecting radio link. This function can, for example, be called after the
jinu 0:6ba9b94b8997 283 * CCCD is written by a central. The function will succeed if the central is a new central.
jinu 0:6ba9b94b8997 284 * See @ref ble_sdk_app_hids_keyboard or @ref ble_sdk_app_hids_mouse for sample usage.
jinu 0:6ba9b94b8997 285 *
jinu 0:6ba9b94b8997 286 * @return NRF_SUCCESS on success, otherwise an error code.
jinu 0:6ba9b94b8997 287 * NRF_ERROR_INVALID_STATE is returned if the System Attributes of the current central is
jinu 0:6ba9b94b8997 288 * already present in the flash because it is a previously known central.
jinu 0:6ba9b94b8997 289 */
jinu 0:6ba9b94b8997 290 uint32_t ble_bondmngr_sys_attr_store(void);
jinu 0:6ba9b94b8997 291
jinu 0:6ba9b94b8997 292 /**@brief Function for fetching the identifiers of known centrals.
jinu 0:6ba9b94b8997 293 *
jinu 0:6ba9b94b8997 294 * @details This function fetches the identifiers of the centrals that are currently in the
jinu 0:6ba9b94b8997 295 * database, or in other words, known to the bond manager.
jinu 0:6ba9b94b8997 296 *
jinu 0:6ba9b94b8997 297 * @param[out] p_central_ids Pointer to the array of central identifiers. It is recommended
jinu 0:6ba9b94b8997 298 * that the length of this array be equal to
jinu 0:6ba9b94b8997 299 * MAX_NUMBER_OF_BONDED_CENTRALS * 2 bytes. If value of this pointer
jinu 0:6ba9b94b8997 300 * is NULL, only the number of centrals in the database will be
jinu 0:6ba9b94b8997 301 * filled in p_length. This can be used to find out the
jinu 0:6ba9b94b8997 302 * required size of the array pointed to by p_central_ids in
jinu 0:6ba9b94b8997 303 * a subsequent call.
jinu 0:6ba9b94b8997 304 * @param[in, out] p_length Pointer to the length of p_central_ids array provided as
jinu 0:6ba9b94b8997 305 * input. On return, this function will write the number of central
jinu 0:6ba9b94b8997 306 * identifiers found to p_length
jinu 0:6ba9b94b8997 307 *
jinu 0:6ba9b94b8997 308 * @return NRF_SUCCESS on success.
jinu 0:6ba9b94b8997 309 * NRF_ERROR_NULL if the input parameter p_length is NULL.
jinu 0:6ba9b94b8997 310 * NRF_ERROR_INVALID_STATE is returned if the bond manager was not initialized.
jinu 0:6ba9b94b8997 311 * NRF_ERROR_DATA_SIZE is returned if the length of the input parameter
jinu 0:6ba9b94b8997 312 * p_central_ids provided is not enough to fit in all the central identifiers in the
jinu 0:6ba9b94b8997 313 * database.
jinu 0:6ba9b94b8997 314 */
jinu 0:6ba9b94b8997 315 uint32_t ble_bondmngr_central_ids_get(uint16_t * p_central_ids, uint16_t * p_length);
jinu 0:6ba9b94b8997 316
jinu 0:6ba9b94b8997 317 /**@brief Function for deleting a single central from the database.
jinu 0:6ba9b94b8997 318 * @details This function deletes the Bonding Information and System Attributes of a single
jinu 0:6ba9b94b8997 319 * central from the flash.
jinu 0:6ba9b94b8997 320 * The application can use the @ref ble_bondmngr_central_ids_get function to fetch the
jinu 0:6ba9b94b8997 321 * identifiers of centrals present in the database and then call this function.
jinu 0:6ba9b94b8997 322 *
jinu 0:6ba9b94b8997 323 * @warning This function could prevent the radio from running. Therefore it MUST be called ONLY
jinu 0:6ba9b94b8997 324 * when the application knows that the <i>Bluetooth</i> radio is not active. An example
jinu 0:6ba9b94b8997 325 * of such a state could be when the application is not in a connected state AND is
jinu 0:6ba9b94b8997 326 * also not advertising. <b>If it is called in any other state, the behavior is
jinu 0:6ba9b94b8997 327 * undefined.</b>
jinu 0:6ba9b94b8997 328 *
jinu 0:6ba9b94b8997 329 * @param[in] central_id Identifier of the central to be deleted.
jinu 0:6ba9b94b8997 330 *
jinu 0:6ba9b94b8997 331 * @return NRF_SUCCESS on success.
jinu 0:6ba9b94b8997 332 * NRF_ERROR_INVALID_STATE is returned if the bond manager was not initialized.
jinu 0:6ba9b94b8997 333 * NRF_ERROR_NOT_FOUND if the central with the given identifier is not found in the
jinu 0:6ba9b94b8997 334 * database.
jinu 0:6ba9b94b8997 335 */
jinu 0:6ba9b94b8997 336 uint32_t ble_bondmngr_bonded_central_delete(uint16_t central_id);
jinu 0:6ba9b94b8997 337
jinu 0:6ba9b94b8997 338 /**@brief Function to verify encryption status link with bonded central is encrypted or not.
jinu 0:6ba9b94b8997 339 * @details This function provides status of encrption of the link with a bonded central.
jinu 0:6ba9b94b8997 340 * Its is recommended that the application can use the
jinu 0:6ba9b94b8997 341 * @ref ble_bondmngr_central_ids_get function to verify if the central is in the
jinu 0:6ba9b94b8997 342 * database and then call this function.
jinu 0:6ba9b94b8997 343 *
jinu 0:6ba9b94b8997 344 * @warning Currently the central id paramater is unused and is added only for future extension.
jinu 0:6ba9b94b8997 345 * As of today, only one link is permitted for the peripheral device, status of current
jinu 0:6ba9b94b8997 346 * link is provided. In future, with more possibilities in the topology, central_id
jinu 0:6ba9b94b8997 347 * will be needed to identify the central.
jinu 0:6ba9b94b8997 348 *
jinu 0:6ba9b94b8997 349 * @param[out] status Status of encryption, true implies link encrypted.
jinu 0:6ba9b94b8997 350 *
jinu 0:6ba9b94b8997 351 * @return NRF_SUCCESS on success.
jinu 0:6ba9b94b8997 352 * NRF_ERROR_INVALID_STATE is returned if the bond manager was not initialized.
jinu 0:6ba9b94b8997 353 */
jinu 0:6ba9b94b8997 354 uint32_t ble_bondmngr_is_link_encrypted(bool * status);
jinu 0:6ba9b94b8997 355
jinu 0:6ba9b94b8997 356 /** @} */
jinu 0:6ba9b94b8997 357
jinu 0:6ba9b94b8997 358 #endif // BLE_BONDMNGR_H__
jinu 0:6ba9b94b8997 359
jinu 0:6ba9b94b8997 360 /** @} */
jinu 0:6ba9b94b8997 361