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 /** @} */