peer_data_storage.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 #ifndef PEER_DATA_STORAGE_H__
00035 #define PEER_DATA_STORAGE_H__
00036 
00037 
00038 #include "stdint.h"
00039 #include "sdk_errors.h "
00040 #include "ble_gap.h"
00041 #include "peer_manager_types.h "
00042 #include "fds.h"
00043 
00044 
00045 /**
00046  * @defgroup peer_data_storage Peer Data Storage
00047  * @ingroup peer_manager
00048  * @{
00049  * @brief An internal module of @ref peer_manager. This module provides a Peer Manager-specific API
00050  *        to the persistent storage.
00051  */
00052 
00053 #define PDS_PREPARE_TOKEN_INVALID 0
00054 #define PDS_STORE_TOKEN_INVALID   0
00055 
00056 
00057 typedef enum
00058 {
00059     peer_id_to_instance_id  = 16384,
00060     instance_id_to_peer_id  = -peer_id_to_instance_id,
00061     peer_data_id_to_type_id = 32768,
00062     type_id_to_peer_data_id = -peer_data_id_to_type_id,
00063 } pds_convert_t;
00064 
00065 
00066 /**@brief The types of events that can come from the peer_data_storage module.
00067  */
00068 typedef enum
00069 {
00070     PDS_EVT_STORED,                 /**< The specified data has been successfully stored. */
00071     PDS_EVT_CLEARED,                /**< The specified data has been successfully cleared. */
00072     PDS_EVT_PEER_ID_CLEAR,          /**< The peer id has been successfully cleared. */
00073     PDS_EVT_ERROR_STORE,            /**< The specified data could not be stored. */
00074     PDS_EVT_ERROR_CLEAR,            /**< The specified data could not be cleared. */
00075     PDS_EVT_ERROR_PEER_ID_CLEAR,    /**< The peer id has been successfully cleared. */
00076     PDS_EVT_COMPRESSED,             /**< A compress procedure has finished successfully. */
00077 } pds_evt_id_t;
00078 
00079 
00080 /**@brief Events that can come from the peer_data_storage module.
00081  */
00082 typedef struct
00083 {
00084     pds_evt_id_t      evt_id;       /**< The type of event. */
00085     pm_peer_id_t      peer_id;      /**< The peer the event pertains to. */
00086     pm_peer_data_id_t data_id;      /**< The data the event pertains to. */
00087     pm_store_token_t  store_token;
00088 } pds_evt_t;
00089 
00090 
00091 /**@brief Event handler for events from the peer_data_storage module.
00092  *
00093  * @param[in]  event    The event that has happened.
00094  * @param[in]  peer_id  The id of the peer the event pertains to.
00095  * @param[in]  flags    The data the event pertains to.
00096  */
00097 typedef void (*pds_evt_handler_t)(pds_evt_t const * p_event);
00098 
00099 
00100 /**@brief Function for registering for events from the peer database.
00101  *
00102  * @note This function will initialize the module if it is not already initialized.
00103  *
00104  * @param[in]  evt_handler  Event handler to register.
00105  *
00106  * @retval NRF_SUCCESS              Registration successful.
00107  * @retval NRF_ERROR_NO_MEM         No more event handlers can be registered.
00108  * @retval NRF_ERROR_NULL           evt_handler was NULL.
00109  * @retval NRF_ERROR_INVALID_PARAM  Unexpected return code from @ref pm_buffer_init.
00110  * @retval NRF_ERROR_INVALID_STATE  FDS has not been initalized.
00111  */
00112 ret_code_t pds_register(pds_evt_handler_t evt_handler);
00113 
00114 
00115 #if 0
00116 /**@brief Function for initializing Peer Data storage and registering a
00117  * callback for its events.
00118  *
00119  * @param[in] evt_handler  Event handler to register.
00120  *
00121  * @retval NRF_SUCCESS              Registration successful.
00122  * @retval NRF_ERROR_NO_MEM         No more event handlers can be registered.
00123  * @retval NRF_ERROR_NULL           evt_handler was NULL.
00124  * @retval NRF_ERROR_INVALID_STATE  FDS has not completed initialization.
00125  */
00126 ret_code_t pds_init(pds_evt_handler_t evt_handler);
00127 #endif
00128 
00129 /**@brief Function for retrieving a direct pointer to peer data in persistent storage.
00130  *
00131  * @param[in]  peer_id      The id of the peer whose data to read.
00132  * @param[in]  data_id      Which data to get.
00133  * @param[out] p_data       The peer data pointer.
00134  * @param[out] p_token      Token that can be used to lock data in flash and check data validity.
00135  *
00136  * @retval NRF_SUCCESS              The pointer was successfully retrieved.
00137  * @retval NRF_ERROR_INVALID_PARAM  Invalid data_id.
00138  * @retval NRF_ERROR_NULL           p_data was NULL.
00139  * @retval NRF_ERROR_NOT_FOUND      The requested data was not found in persistent storage.
00140  * @retval NRF_ERROR_INVALID_STATE  Module is not initialized.
00141  */
00142 ret_code_t pds_peer_data_read_ptr_get(pm_peer_id_t            peer_id,
00143                                       pm_peer_data_id_t       data_id,
00144                                       pm_peer_data_flash_t  * p_data,
00145                                       pm_store_token_t      * p_token);
00146 
00147 /**@brief Function to lock the flash data (to defer compression from invalidating data)
00148  *
00149  * @param[in]   store_token     The token representing the item to lock
00150  *
00151  */
00152 ret_code_t pds_peer_data_lock(pm_store_token_t store_token);
00153 
00154 
00155 /**@brief Function to verify flash data integrity
00156  *
00157  * @param[in]   store_token     The token representing the item to lock
00158  *
00159  * @retval NRF_SUCCESS              The data integrity is valid.
00160  * @retval NRF_ERROR_NULL           The token is invalid.
00161  * @retval NRF_ERROR_INVALID_DATA   The data integrity is not valid.
00162  * @retval NRF_ERROR_INVALID_STATE  Module is not initialized.
00163  */
00164 ret_code_t  pds_peer_data_verify(pm_store_token_t store_token);
00165 
00166 
00167 /**@brief Function for retrieving peer data from persistent storage by making a copy
00168  *
00169  * @param[in]       peer_id     The id of the peer whose data to read.
00170  * @param[in]       data_id     Which piece of data to read.
00171  * @param[out]      p_data      Pointer to the peer data.
00172  * @param[in,out]   p_len_words Length available to copy to (in words).
00173  *                              If set to NULL, then no copy will be made and the
00174  *                              length will be reflected in p_len_words after the call returns.
00175  *
00176  * @retval NRF_SUCCESS              The read was successful.
00177  * @retval NRF_ERROR_INVALID_PARAM  Invalid data_id.
00178  * @retval NRF_ERROR_NULL           data contained a NULL pointer.
00179  * @retval NRF_ERROR_NOT_FOUND      The requested data was not found in persistent storage.
00180  * @retval NRF_ERROR_NO_MEM         The length of stored data too large to copy out
00181  * @retval NRF_ERROR_INVALID_STATE  Module is not initialized.
00182  */
00183 ret_code_t pds_peer_data_read(pm_peer_id_t          peer_id,
00184                               pm_peer_data_id_t     data_id,
00185                               pm_peer_data_t      * p_data,
00186                               fds_length_t        * p_len_words);
00187 
00188 
00189 /**@brief Function for preparing persistent storage for a write.
00190  *
00191  * @details If this call succeeds, space is reserved in persistent storage, so the write will fit.
00192  *
00193  * @note If space has already been prepared for this peer_id/data_id pair, no new space will be
00194  *       reserved, unless the previous reservation had too small size.
00195  *
00196  * @param[in]  p_peer_data      Data to prepare for. The data needs not be ready, but length and type
00197  *                              values must.
00198  * @param[out] p_prepare_token  A token identifying the prepared memory area.
00199  *
00200  * @retval NRF_SUCCESS               The call was successful.
00201  * @retval NRF_ERROR_INVALID_PARAM   Invalid data ID.
00202  * @retval NRF_ERROR_INVALID_LENGTH  Data length above the maximum allowed.
00203  * @retval NRF_ERROR_NO_MEM          No space available in persistent storage.
00204  * @retval NRF_ERROR_INVALID_STATE   Module is not initialized.
00205  */
00206 ret_code_t pds_peer_data_write_prepare(pm_peer_data_const_t const * p_peer_data,
00207                                        pm_prepare_token_t         * p_prepare_token);
00208 
00209 
00210 /**@brief Function for undoing a previous call to @ref pds_peer_data_write_prepare.
00211  *
00212  * @param[in]  prepare_token  A token identifying the prepared memory area to cancel.
00213  *
00214  * @retval NRF_SUCCESS               The call was successful.
00215  * @retval NRF_ERROR_NOT_FOUND       Invalid peer ID and/or prepare token.
00216  * @retval NRF_ERROR_INVALID_STATE   Module is not initialized.
00217  */
00218 ret_code_t pds_peer_data_write_prepare_cancel(pm_prepare_token_t prepare_token);
00219 
00220 
00221 /**@brief Function for writing prepared (reserved) peer data to persistent storage.
00222  *
00223  * @details Writing happens asynchronously. Expect a @ref PDS_EVT_STORED or @ref PDS_EVT_ERROR_STORE
00224  *          event.
00225  *
00226  * @param[in]  peer_id        The id of the peer the data pertains to.
00227  * @param[in]  p_peer_data    The peer data.
00228  * @param[in]  prepare_token  A token identifying the prepared memory area to write into. If
00229  *                            the prepare token is invalid, e.g. PDS_PREPARE_TOKEN_INVALID, the
00230  *                            prepare/write sequence will happen atomically.
00231  * @param[out] p_store_token  A token identifying this particular store operation. The token can be
00232  *                            used to identify events pertaining to this operation.
00233  *
00234  * @retval NRF_SUCCESS               The write was initiated successfully.
00235  * @retval NRF_ERROR_INVALID_PARAM   Invalid data ID or store_flags.
00236  * @retval NRF_ERROR_INVALID_LENGTH  Length of data longer than in prepare call.
00237  * @retval NRF_ERROR_NULL            data contained a NULL pointer.
00238  * @retval NRF_ERROR_NO_MEM          No space available in persistent storage. This can only happen
00239  *                                   if p_prepare_token is NULL.
00240  * @retval NRF_ERROR_BUSY            FDS or underlying modules are busy and can't take any
00241  *                                   more requests
00242  * @retval NRF_ERROR_INVALID_STATE   Module is not initialized.
00243  */
00244 ret_code_t pds_peer_data_write_prepared(pm_peer_id_t                    peer_id,
00245                                         pm_peer_data_const_t    const * p_peer_data,
00246                                         pm_prepare_token_t              prepare_token,
00247                                         pm_store_token_t              * p_store_token);
00248 
00249 
00250 /**@brief Function for writing peer data to persistent storage.
00251  *
00252  * @details Writing happens asynchronously. Expect a @ref PDS_EVT_STORED or @ref PDS_EVT_ERROR_STORE
00253  *          event.
00254  *
00255  * @param[in]  peer_id        The id of the peer the data pertains to.
00256  * @param[in]  p_peer_data    The peer data.
00257  * @param[out] p_store_token  A token identifying this particular store operation. The token can be
00258  *                            used to identify events pertaining to this operation.
00259  *
00260  * @retval NRF_SUCCESS               The write was initiated successfully.
00261  * @retval NRF_ERROR_INVALID_PARAM   Invalid data ID or store_flags.
00262  * @retval NRF_ERROR_NULL            Data contained a NULL pointer.
00263  * @retval NRF_ERROR_NO_MEM          No space available in persistent storage. This can only happen
00264  *                                   if p_prepare_token is NULL.
00265  * @retval NRF_ERROR_BUSY            FDS or underlying modules are busy and can't take any
00266  *                                   more requests
00267  * @retval NRF_ERROR_INVALID_STATE   Module is not initialized.
00268  */
00269 ret_code_t pds_peer_data_write(pm_peer_id_t                 peer_id,
00270                                pm_peer_data_const_t const * p_peer_data,
00271                                pm_store_token_t           * p_store_token);
00272 
00273 
00274 /**@brief Function for updating currently stored peer data to a new version
00275  *
00276  * @details Updating happens asynchronously.
00277  *          Expect a @ref PDS_EVT_STORED or @ref PDS_EVT_ERROR_STORE for the store token
00278  *          and a @ref PDS_EVT_ERROR_CLEAR or @ref PDS_EVT_ERROR_CLEAR for the old token
00279  *
00280  * @param[in]   peer_id             The peer which the data is associated to.
00281  * @param[in]   peer_data           New data.
00282  * @param[in]   old_token           Store token for the old data.
00283  * @param[out]  p_store_token       Store token for the new data.
00284  *
00285  * @retval NRF_SUCESS               The update was initiated successfully
00286  * @retval NRF_ERROR_NOT_FOUND      The old store token was invalid.
00287  * @retval NRF_ERROR_NULL           Data contained a NULL pointer.
00288  * @retval NRF_ERROR_NO_MEM         No space available in persistent storage.
00289  * @retval NRF_ERROR_BUSY           FDS or underlying modules are busy and can't take any
00290  *                                  more requests
00291  * @retval NRF_ERROR_INVALID_STATE  Module is not initialized.
00292  */
00293 ret_code_t pds_peer_data_update(pm_peer_id_t                 peer_id,
00294                                 pm_peer_data_const_t const * peer_data,
00295                                 pm_store_token_t             old_token,
00296                                 pm_store_token_t           * p_store_token);
00297 
00298 
00299 /**@brief Function for clearing peer data from persistent storage.
00300  *
00301  * @details Clearing happens asynchronously. Expect a @ref PDS_EVT_CLEARED or @ref PDS_EVT_ERROR_CLEAR
00302  *          event.
00303  *
00304  * @param[in]  peer_id  The id of the peer the data pertains to.
00305  * @param[in]  data_id  Which data to clear.
00306  *
00307  * @retval NRF_SUCCESS              The clear was initiated successfully.
00308  * @retval NRF_ERROR_INVALID_PARAM  Data ID or was invalid.
00309  * @retval NRF_ERROR_NOT_FOUND      Nothing to clear for this peer ID.
00310  * @retval NRF_ERROR_INVALID_STATE  Module is not initialized.
00311  */
00312 ret_code_t pds_peer_data_clear(pm_peer_id_t peer_id, pm_peer_data_id_t data_id);
00313 
00314 
00315 /**@brief Function for claiming an unused peer ID.
00316  *
00317  * @return  The first unused peer ID.
00318  * @retval  PM_PEER_ID_INVALID  If no peer ID is available or module is not initialized.
00319  */
00320 pm_peer_id_t pds_peer_id_allocate(void);
00321 
00322 
00323 /**@brief Function for freeing a peer ID and clearing all data associated with it in persistent
00324  *        storage.
00325  *
00326  * @param[in]  peer_id  Peer ID to free.
00327  *
00328  * @retval NRF_SUCCESS          The clear was initiated successfully
00329  * @retval NRF_ERROR_BUSY       Another peer_id clear was already requested or fds queue full
00330  */
00331 ret_code_t pds_peer_id_free(pm_peer_id_t peer_id);
00332 
00333 
00334 /**@brief Function for finding out whether a peer ID is in use.
00335  *
00336  * @param[in]  peer_id  The peer ID to inquire about.
00337  *
00338  * @retval  true   peer_id is in use.
00339  * @retval  false  peer_id is free, or the module is not initialized.
00340  */
00341 bool pds_peer_id_is_allocated(pm_peer_id_t peer_id);
00342 
00343 
00344 /**@brief Function for getting the next peer ID in the sequence of all used peer IDs. Can be
00345  *        used to loop through all used peer IDs.
00346  *
00347  * @note @ref PM_PEER_ID_INVALID is considered to be before the first and after the last ordinary
00348  *       peer ID.
00349  *
00350  * @param[in]  prev_peer_id  The previous peer ID.
00351  *
00352  * @return  The next peer ID.
00353  * @return  The first ordinary peer ID  if prev_peer_id was @ref PM_PEER_ID_INVALID.
00354  * @retval  PM_PEER_ID_INVALID          if prev_peer_id was the last ordinary peer ID or the module
00355  *                                      is not initialized.
00356  */
00357 pm_peer_id_t pds_next_peer_id_get(pm_peer_id_t prev_peer_id);
00358 
00359 
00360 /**@brief Function for querying the number of valid peer IDs available. I.E the number of peers
00361  *        in persistent storage.
00362  *
00363  * @return  The number of valid peer IDs, or 0 if module is not initialized.
00364  */
00365 uint32_t pds_n_peers(void);
00366 
00367 
00368 /** @} */
00369 
00370 #endif /* PEER_DATA_STORAGE_H__ */