peer_manager_types.h

00001 /*
00002  * Copyright (c) Nordic Semiconductor ASA
00003  * All rights reserved.
00004  *
00005  * Redistribution and use in source and binary forms, with or without modification,
00006  * are permitted provided that the following conditions are met:
00007  *
00008  *   1. Redistributions of source code must retain the above copyright notice, this
00009  *   list of conditions and the following disclaimer.
00010  *
00011  *   2. Redistributions in binary form must reproduce the above copyright notice, this
00012  *   list of conditions and the following disclaimer in the documentation and/or
00013  *   other materials provided with the distribution.
00014  *
00015  *   3. Neither the name of Nordic Semiconductor ASA nor the names of other
00016  *   contributors to this software may be used to endorse or promote products
00017  *   derived from this software without specific prior written permission.
00018  *
00019  *
00020  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
00021  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00022  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00023  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
00024  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00025  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00026  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
00027  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00028  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00029  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00030  *
00031  */
00032 
00033 
00034 
00035 #ifndef PEER_MANAGER_TYPES_H__
00036 #define PEER_MANAGER_TYPES_H__
00037 
00038 #include <stdint.h>
00039 #include <stdbool.h>
00040 
00041 
00042 /**
00043  * @file peer_manager_types.h
00044  *
00045  * @addtogroup peer_manager
00046  * @{
00047  */
00048 
00049 
00050 #include <stdint.h>
00051 #include <stddef.h>
00052 #include "ble_gap.h"
00053 #include "ble_hci.h"
00054 #include "ble_gatt_db.h"
00055 #include "compiler_abstraction.h"
00056 
00057 
00058 /**@brief Handle to uniquely identify a peer for which we have persistently stored data.
00059  */
00060 typedef uint16_t pm_peer_id_t;
00061 
00062 #define PM_PEER_ID_INVALID              0xFFFF /**< Invalid value for @ref pm_peer_id_t. */
00063 #define PM_PEER_ID_N_AVAILABLE_IDS      256    /**< The number of available peer IDs. */
00064 #define PM_LOCAL_DB_LEN_OVERHEAD_BYTES  offsetof(pm_peer_data_local_gatt_db_flash_t, p_data)
00065 #define PM_REMOTE_DB_LEN_OVERHEAD_BYTES offsetof(pm_peer_data_remote_gatt_db_flash_t, p_data)
00066 
00067 static __INLINE uint16_t PM_N_WORDS(uint16_t n_bytes)
00068 {
00069     return ((n_bytes + 3) >> 2);
00070 }
00071 
00072 /**@brief Errors originating from the Peer Manager module.
00073  */
00074 typedef enum
00075 {
00076     PM_SEC_ERROR_CODE_PIN_OR_KEY_MISSING = BLE_HCI_STATUS_CODE_PIN_OR_KEY_MISSING,  /**< Encryption failed because the peripheral has lost the LTK for this bond. */
00077     PM_SEC_ERROR_CODE_MIC_FAILURE = BLE_HCI_CONN_TERMINATED_DUE_TO_MIC_FAILURE,     /**< Pairing ended with disconnection because of mismatching keys. */
00078     PM_SEC_ERROR_SMP_TIMEOUT,                                                       /**< Pairing/bonding could not start because an SMP timeout has already happened on this link. This means that no more pairing or bonding can happen on this link. To be able to pair or bond, the link must be disconnected and then reconnected. See Bluetooth specification 4.2 section 3.H.3.4 */
00079 } pm_sec_error_code_t;
00080 
00081 
00082 /**@brief Enumeration describing the different procedures that can lead to an encrypted link.
00083  */
00084 typedef enum
00085 {
00086     PM_LINK_SECURED_PROCEDURE_ENCRYPTION, /**< Using an LTK shared during a previous bonding procedure to encrypt the link. */
00087     PM_LINK_SECURED_PROCEDURE_BONDING,    /**< A pairing procedure, followed by a bonding procedure. */
00088     PM_LINK_SECURED_PROCEDURE_PAIRING,    /**< A pairing procedure with no bonding. */
00089 } pm_sec_procedure_t;
00090 
00091 
00092 /**@brief Data associated with a bond to a peer.
00093  */
00094 typedef struct
00095 {
00096     uint8_t           own_role; /**< The role of the local device during bonding. */
00097     ble_gap_id_key_t  peer_id;  /**< The peer's peer address and identity resolution key. */
00098     ble_gap_enc_key_t peer_ltk; /**< The peer's long term encryption key. */
00099     ble_gap_enc_key_t own_ltk;  /**< Locally generated long term encryption key, distributed to the peer. */
00100 } pm_peer_data_bonding_t;
00101 
00102 
00103 /**@brief Function for calculating the flash size of bonding data.
00104  *
00105  * @return The number of words the data will take in flash.
00106  */
00107 static __INLINE uint16_t PM_BONDING_DATA_N_WORDS(void)
00108 {
00109     return PM_N_WORDS(sizeof(pm_peer_data_bonding_t));
00110 }
00111 
00112 
00113 /**@brief Function for calculating the flash size of service changed pending state.
00114  *
00115  * @return The number of words the data will take in flash.
00116  */
00117 static __INLINE uint16_t PM_SC_STATE_N_WORDS(void)
00118 {
00119     return PM_N_WORDS(sizeof(bool));
00120 }
00121 
00122 
00123 /**@brief Data on a local GATT database.
00124  */
00125 typedef struct
00126 {
00127     uint32_t  flags;   /**< Flags describing the database attributes. */
00128     uint16_t  len;     /**< Size of attribute array. */
00129     uint8_t * p_data;  /**< Array to hold the database attributes. */
00130 } pm_peer_data_local_gatt_db_t;
00131 
00132 
00133 /**@brief Data on a local GATT database, as formatted in flash.
00134  */
00135 typedef struct
00136 {
00137     uint32_t flags;
00138     uint16_t len;
00139     uint16_t _padding;
00140     uint8_t  p_data[];
00141 } pm_peer_data_local_gatt_db_flash_t;
00142 
00143 
00144 /**@brief Function for calculating the flash size of local GATT database data.
00145  *
00146  * @param[in]  local_db_len  The length of the database as reported by the SoftDevice.
00147  *
00148  * @return The number of words the data will take in flash.
00149  */
00150 static __INLINE uint16_t PM_LOCAL_DB_N_WORDS(uint16_t local_db_len)
00151 {
00152     return PM_N_WORDS(local_db_len + PM_LOCAL_DB_LEN_OVERHEAD_BYTES);
00153 }
00154 
00155 
00156 /**@brief Function for calculating the length of a local GATT database attribute array.
00157  *
00158  * @param[in]  n_words  The number of words the data takes in flash.
00159  *
00160  * @return The length of the database attribute array.
00161  */
00162 static __INLINE uint16_t PM_LOCAL_DB_LEN(uint16_t n_words)
00163 {
00164     return ((n_words * 4) - PM_LOCAL_DB_LEN_OVERHEAD_BYTES);
00165 }
00166 
00167 
00168 /**@brief Data on a remote GATT database.
00169  */
00170 typedef struct
00171 {
00172     uint32_t            service_count; /**< Number of stored services. */
00173     ble_gatt_db_srv_t * p_data;        /**< Array to hold the database attributes. */
00174 } pm_peer_data_remote_gatt_db_t;
00175 
00176 
00177 /**@brief Data on a remote GATT database, as formatted in flash.
00178  */
00179 typedef struct
00180 {
00181     uint32_t          service_count;
00182     ble_gatt_db_srv_t p_data[];
00183 } pm_peer_data_remote_gatt_db_flash_t;
00184 
00185 
00186 
00187 /**@brief Function for calculating the flash size of remote GATT database data.
00188  *
00189  * @param[in]  service_count  The number of services in the service array.
00190  *
00191  * @return The number of words the data will take in flash.
00192  */
00193 static __INLINE uint16_t PM_REMOTE_DB_N_WORDS(uint16_t service_count)
00194 {
00195     return PM_N_WORDS((sizeof(ble_gatt_db_srv_t) * service_count) + PM_REMOTE_DB_LEN_OVERHEAD_BYTES);
00196 }
00197 
00198 
00199 /**@brief Union of all data associated with one peer.
00200  */
00201 typedef union
00202 {
00203     pm_peer_data_bonding_t        * p_bonding_data;            /**< The exchanged bond information in addition to metadata of the bonding. */
00204     bool                          * p_service_changed_pending; /**< Whether a service changed indication should be sent to the peer. */
00205     pm_peer_data_local_gatt_db_t  * p_local_gatt_db;           /**< Persistent information pertaining to a peer GATT client. */
00206     pm_peer_data_remote_gatt_db_t * p_remote_gatt_db;          /**< Persistent information pertaining to a peer GATT server. */
00207     uint8_t                       * p_application_data;        /**< Arbitrary data to associate with the peer. This data can be freely used by the application. */
00208 } pm_peer_data_unit_t;
00209 
00210 
00211 /**@brief Immutable version of @ref pm_peer_data_unit_t.
00212  */
00213 typedef union
00214 {
00215     pm_peer_data_bonding_t        const * p_bonding_data;
00216     bool                          const * p_service_changed_pending;
00217     pm_peer_data_local_gatt_db_t  const * p_local_gatt_db;
00218     pm_peer_data_remote_gatt_db_t const * p_remote_gatt_db;
00219     uint8_t                       const * p_application_data;
00220 } pm_peer_data_unit_const_t;
00221 
00222 
00223 /**@brief Data from @ref pm_peer_data_unit_t, as mapped in flash.
00224  */
00225 typedef union
00226 {
00227     pm_peer_data_bonding_t              const * p_bonding_data;
00228     bool                                const * p_service_changed_pending;
00229     pm_peer_data_local_gatt_db_flash_t  const * p_local_gatt_db;
00230     pm_peer_data_remote_gatt_db_flash_t const * p_remote_gatt_db;
00231     uint8_t                             const * p_application_data;
00232 } pm_peer_data_unit_flash_t;
00233 
00234 
00235 /**@brief The different types of data associated with a peer.
00236  */
00237 typedef enum
00238 {
00239     PM_PEER_DATA_ID_BONDING,
00240     PM_PEER_DATA_ID_SERVICE_CHANGED_PENDING,
00241     PM_PEER_DATA_ID_GATT_LOCAL,
00242     PM_PEER_DATA_ID_GATT_REMOTE,
00243     PM_PEER_DATA_ID_APPLICATION,
00244     PM_PEER_DATA_ID_INVALID,
00245 } pm_peer_data_id_t;
00246 
00247 
00248 //STATIC_ASSERT_MSG(sizeof(pm_peer_data_t) == sizeof(pm_peer_data_const_t), "Size of pm_peer_data_t different from immutable version.");
00249 
00250 
00251 /**@brief Macro saying whether a data_id is valid, i.e. one of the valid enum values.
00252  *
00253  * @param[in] data_id  The data_id to check.
00254  */
00255 static __INLINE bool PM_PEER_DATA_ID_IS_VALID(pm_peer_data_id_t data_id)
00256 {
00257     return ((data_id - PM_PEER_DATA_ID_BONDING) < (PM_PEER_DATA_ID_INVALID - PM_PEER_DATA_ID_BONDING));
00258 }
00259 
00260 
00261 /**@brief One piece of data associated with a peer, together with the type.
00262  */
00263 typedef struct
00264 {
00265     uint16_t            length_words;
00266     pm_peer_data_id_t   data_type;
00267     pm_peer_data_unit_t data;
00268 } pm_peer_data_t;
00269 
00270 /**@brief Immutable version of @ref pm_peer_data_t.
00271  */
00272 typedef struct
00273 {
00274     uint16_t                    length_words;
00275     pm_peer_data_id_t           data_type;
00276     pm_peer_data_unit_const_t   data;
00277 } pm_peer_data_const_t;
00278 
00279 /**@brief Data from @ref pm_peer_data_t, as mapped in flash.
00280  */
00281 typedef struct
00282 {
00283     uint16_t                  length_words;
00284     pm_peer_data_id_t         data_type;
00285     pm_peer_data_unit_flash_t data;
00286 } pm_peer_data_flash_t;
00287 
00288 
00289 /**@brief Typedef for type used for write prepares. Used to reserve space in flash
00290  */
00291 typedef uint32_t pm_prepare_token_t;
00292 
00293 
00294 /**@brief Typedef for type used to hold reference to stored item in flash.
00295  *        this token can be used for locking and validity check
00296  */
00297 typedef uint32_t pm_store_token_t;
00298 
00299  /** @} */
00300 
00301 #endif /* PEER_MANAGER_TYPES_H__ */