peer_database.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_DATABASE_H__
00035 #define PEER_DATABASE_H__
00036 
00037 #include <stdint.h>
00038 #include "peer_manager_types.h "
00039 #include "sdk_errors.h "
00040 
00041 /**
00042  * @defgroup peer_database Peer Database
00043  * @ingroup peer_manager
00044  * @{
00045  * @brief An internal module of @ref peer_manager. A module for simple management of reading and
00046  *        writing of peer data into persistent storage.
00047  *
00048  */
00049 
00050 #define PDB_WRITE_BUF_SIZE (sizeof(pm_peer_data_bonding_t))
00051 
00052 /**@brief Events that can come from the peer_database module.
00053  */
00054 typedef enum
00055 {
00056     PDB_EVT_WRITE_BUF_STORED,   /**< A pdb_write_buf_store operation has completed successfully. */
00057     PDB_EVT_RAW_STORED,         /**< A pdb_raw_store operation has completed successfully. */
00058     PDB_EVT_RAW_STORE_FAILED,   /**< A pdb_raw_store operation has failed. */
00059     PDB_EVT_CLEARED,            /**< A pdb_clear operation has completed successfully. */
00060     PDB_EVT_CLEAR_FAILED,       /**< A pdb_clear operation has failed. */
00061     PDB_EVT_COMPRESSED,         /**< A compress procedure has completed. */
00062     PDB_EVT_ERROR_NO_MEM,       /**< An operation is blocked because the flash is full. It will be reattempted automatically after the next compress procedure. */
00063     PDB_EVT_ERROR_UNEXPECTED,   /**< An unexpected error occurred. This is a fatal error. */
00064 } pdb_evt_id_t;
00065 
00066 /**@brief Events that can come from the peer_database module.
00067  */
00068 typedef struct
00069 {
00070     pdb_evt_id_t      evt_id;  /**< The event that has happened. */
00071     pm_peer_id_t      peer_id; /**< The id of the peer the event pertains to. */
00072     pm_peer_data_id_t data_id; /**< The data the event pertains to. */
00073     union
00074     {
00075         struct
00076         {
00077             pm_store_token_t store_token;  /**< A token identifying the store operation this event pertains to. */
00078         } raw_stored_evt;
00079         struct
00080         {
00081             pm_store_token_t store_token;  /**< A token identifying the store operation this event pertains to. */
00082         } error_raw_store_evt;
00083     } params;
00084 } pdb_evt_t;
00085 
00086 /**@brief Event handler for events from the peer_data_storage module.
00087  *
00088  * @param[in]  p_event   The event that has happened.
00089  */
00090 typedef void (*pdb_evt_handler_t)(pdb_evt_t const * p_event);
00091 
00092 
00093 /**@brief Function for registering for events from the peer database.
00094  *
00095  * @note This function will initialize the module if it is not already initialized.
00096  *
00097  * @param[in]  evt_handler  Event handler to register.
00098  *
00099  * @retval NRF_SUCCESS              Registration successful.
00100  * @retval NRF_ERROR_NO_MEM         No more event handlers can be registered.
00101  * @retval NRF_ERROR_NULL           evt_handler was NULL.
00102  * @retval NRF_ERROR_INVALID_PARAM  Unexpected return code from @ref pm_buffer_init.
00103  * @retval NRF_ERROR_INVALID_STATE  FDS has not been initalized.
00104  */
00105 ret_code_t pdb_register(pdb_evt_handler_t evt_handler);
00106 
00107 
00108 /**@brief Function for allocating persistent bond storage for a peer.
00109  *
00110  * @return  The ID of the newly allocated storage.
00111  * @retval  PM_PEER_ID_INVALID  If no peer ID is available.
00112  */
00113 pm_peer_id_t pdb_peer_allocate(void);
00114 
00115 
00116 /**@brief Function for freeing a peer's persistent bond storage.
00117  *
00118  * @note This function will call @ref pdb_write_buf_release on the data for this peer.
00119  *
00120  * @param[in] peer_id  ID to be freed.
00121  *
00122  * @retval NRF_SUCCESS              Peer ID was released and clear operation was initiated successfully.
00123  * @retval NRF_ERROR_BUSY           Another peer_id clear was already requested or could not be started.
00124  * @retval NRF_ERROR_INVALID_STATE  Module is not initialized.
00125  */
00126 ret_code_t pdb_peer_free(pm_peer_id_t peer_id);
00127 
00128 
00129 /**@brief Function for retrieving pointers to read-only peer data.
00130  *
00131  * @note  Reading this pointer is not safe in the strictest sense. If a safe read is required:
00132  *          - Disable interrupts
00133  *          - Call this function. If the return code is @ref NRF_SUCCESS, the following read is safe.
00134  *          - Read memory.
00135  *          - Enable interrupts.
00136  * @note  This buffer does not need to be released. It is a pointer directly to flash.
00137  *
00138  * @param[in]  peer_id      ID of peer to retrieve data for.
00139  * @param[in]  data_id      Which piece of data to get.
00140  * @param[out] p_peer_data  Pointer to immutable peer data.
00141  * @param[out] p_token      Token that can be used to lock data in flash and check data validity.
00142  *
00143  * @retval NRF_SUCCESS              Data retrieved successfully.
00144  * @retval NRF_ERROR_INVALID_PARAM  Data ID or Peer ID was invalid or unallocated.
00145  * @retval NRF_ERROR_NULL           p_peer_data was NULL.
00146  * @retval NRF_ERROR_NOT_FOUND      This data was not found for this peer ID.
00147  * @retval NRF_ERROR_INVALID_STATE  Module is not initialized.
00148  */
00149 ret_code_t pdb_read_buf_get(pm_peer_id_t           peer_id,
00150                             pm_peer_data_id_t      data_id,
00151                             pm_peer_data_flash_t * p_peer_data,
00152                             pm_store_token_t     * p_token);
00153 
00154 
00155 /**@brief Function for retrieving pointers to a write buffer for peer data.
00156  *
00157  * @details This function will provide pointers to a buffer of the data. The data buffer will not be
00158  *          written to persistent storage until @ref pdb_write_buf_store is called. The buffer is
00159  *          released by calling either @ref pdb_write_buf_release, @ref pdb_write_buf_store, or
00160  *          @ref pdb_peer_free.
00161  *
00162  *          When the data_id refers to a variable length data type, the available size is written
00163  *          to the data, both the top-level, and any internal length fields.
00164  *
00165  * @note Calling this function on a peer_id/data_id pair that already has a buffer created will
00166  *       give the same buffer, not create a new one. If n_bufs was increased since last time, the
00167  *       buffer might be relocated to be able to provide additional room. In this case, the data
00168  *       will be copied. If n_bufs was increased since last time, this function might return @ref
00169  *       NRF_ERROR_BUSY. In that case, the buffer is automatically released.
00170  *
00171  * @param[in]  peer_id      ID of peer to get a write buffer for.
00172  * @param[in]  data_id      Which piece of data to get.
00173  * @param[in]  n_bufs       The number of contiguous buffers needed.
00174  * @param[out] p_peer_data  Pointers to mutable peer data.
00175  *
00176  * @retval NRF_SUCCESS              Data retrieved successfully.
00177  * @retval NRF_ERROR_INVALID_PARAM  Data ID or Peer ID was invalid or unallocated, or n_bufs was 0
00178  *                                  or more than the total available buffers.
00179  * @retval NRF_ERROR_NULL           p_peer_data was NULL.
00180  * @retval NRF_ERROR_BUSY           Not enough buffer(s) available.
00181  * @retval NRF_ERROR_INTERNAL       Unexpected internal error.
00182  * @retval NRF_ERROR_INVALID_STATE  Module is not initialized.
00183  */
00184 ret_code_t pdb_write_buf_get(pm_peer_id_t      peer_id,
00185                              pm_peer_data_id_t data_id,
00186                              uint32_t          n_bufs,
00187                              pm_peer_data_t  * p_peer_data);
00188 
00189 
00190 /**@brief Function for freeing a write buffer allocated with @ref pdb_write_buf_get.
00191  *
00192  * @note This function will not write peer data to persistent memory. Data in released buffer will
00193  *       be lost.
00194  *
00195  * @note This function will undo any previous call to @ref pdb_write_buf_store_prepare for this
00196  *       piece of data.
00197  *
00198  * @param[in]  peer_id  ID of peer to release buffer for.
00199  * @param[in]  data_id  Which piece of data to release buffer for.
00200  *
00201  * @retval NRF_SUCCESS              Successfully released buffer.
00202  * @retval NRF_ERROR_NOT_FOUND      No buffer was allocated for this peer ID/data ID pair.
00203  * @retval NRF_ERROR_INVALID_STATE  Module is not initialized.
00204  * @retval NRF_ERROR_INTERNAL       Unexpected internal error.
00205  */
00206 ret_code_t pdb_write_buf_release(pm_peer_id_t peer_id, pm_peer_data_id_t data_id);
00207 
00208 
00209 /**@brief Function for reserving space in persistent storage for data in a buffer.
00210  *
00211  * @note This function only works for data which has a write buffer allocated. If the write buffer
00212  *       is released, this prepare is undone.
00213  *
00214  * @note If space has already been reserved for this data, nothing is done.
00215  *
00216  * @param[in]  peer_id  The peer whose data to reserve space for.
00217  * @param[in]  data_id  The type of data to reserve space for.
00218  *
00219  * @retval NRF_SUCCESS              Successfully reserved space in persistent storage.
00220  * @retval NRF_ERROR_NO_MEM         Not enough room in persistent storage.
00221  * @retval NRF_ERROR_BUSY           Could not process request at this time. Reattempt later.
00222  * @retval NRF_ERROR_NOT_FOUND      No buffer has been allocated for this peer ID/data ID pair.
00223  * @retval NRF_ERROR_INVALID_PARAM  Data ID or Peer ID was invalid or unallocated.
00224  * @retval NRF_ERROR_INVALID_STATE  Module is not initialized.
00225  */
00226 ret_code_t pdb_write_buf_store_prepare(pm_peer_id_t peer_id, pm_peer_data_id_t data_id);
00227 
00228 
00229 /**@brief Function for writing data into persistent storage. Writing happens asynchronously.
00230  *
00231  * @note This will unlock the data after it has been written.
00232  *
00233  * @param[in]  peer_id      ID of peer to store data for.
00234  * @param[in]  data_id      Which piece of data to store.
00235  *
00236  * @retval NRF_SUCCESS              Data storing was successfully started.
00237  * @retval NRF_ERROR_NO_MEM         No space available in persistent storage. Please clear some
00238  *                                  space, the operation will be reattempted after the next compress
00239  *                                  procedure. This error will not happen if
00240  *                                  @ref pdb_write_buf_store_prepare is called beforehand.
00241  * @retval NRF_ERROR_INVALID_PARAM  Data ID was invalid.
00242  * @retval NRF_ERROR_NOT_FOUND      No buffer has been allocated for this peer ID/data ID pair.
00243  * @retval NRF_ERROR_INVALID_STATE  Module is not initialized.
00244  * @retval NRF_ERROR_INTERNAL       Unexpected internal error.
00245  */
00246 ret_code_t pdb_write_buf_store(pm_peer_id_t      peer_id,
00247                                pm_peer_data_id_t data_id);
00248 
00249 
00250 /**@brief Function for clearing data from persistent storage.
00251  *
00252  * @param[in]  peer_id  ID of peer to clear data for.
00253  * @param[in]  data_id  Which piece of data to clear.
00254  *
00255  * @retval NRF_SUCCESS              Data clear was successfully started.
00256  * @retval NRF_ERROR_INVALID_PARAM  Data ID was invalid.
00257  * @retval NRF_ERROR_NOT_FOUND      Nothing to clear for this data for this peer ID.
00258  * @retval NRF_ERROR_BUSY           Could not process request at this time. Reattempt later.
00259  * @retval NRF_ERROR_INVALID_STATE  Module is not initialized.
00260  */
00261 ret_code_t pdb_clear(pm_peer_id_t peer_id, pm_peer_data_id_t data_id);
00262 
00263 
00264 /**@brief Function for querying the number of valid peer IDs available. I.E the number of peers
00265  *        in persistent storage.
00266  *
00267  * @return  The number of valid peer IDs.
00268  */
00269 uint32_t pdb_n_peers(void);
00270 
00271 
00272 /**@brief Function for getting the next peer ID in the sequence of all used peer IDs. Can be
00273  *        used to loop through all used peer IDs.
00274  *
00275  * @note @ref PM_PEER_ID_INVALID is considered to be before the first and after the last ordinary
00276  *       peer ID.
00277  *
00278  * @param[in]  prev_peer_id  The previous peer ID.
00279  *
00280  * @return  The next peer ID.
00281  * @return  The first ordinary peer ID  if prev_peer_id was @ref PM_PEER_ID_INVALID.
00282  * @retval  PM_PEER_ID_INVALID          if prev_peer_id was the last ordinary peer ID.
00283  */
00284 pm_peer_id_t pdb_next_peer_id_get(pm_peer_id_t prev_peer_id);
00285 
00286 
00287 /**@brief Function for updating currently stored peer data to a new version
00288  *
00289  * @details Updating happens asynchronously. 
00290  *          Expect a @ref PDS_EVT_STORED or @ref PDS_EVT_ERROR_STORE for the store token
00291  *          and a @ref PDS_EVT_ERROR_CLEAR or @ref PDS_EVT_ERROR_CLEAR for the old token 
00292  *      
00293  * @param[in]   peer_data           New data
00294  * @param[in]   old_token           Store token for the old data
00295  * @param[out]  p_store_token       Store token for the new data
00296  *
00297  * @retval NRF_SUCESS               The update was initiated successfully
00298  * @retval NRF_ERROR_NOT_FOUND      The old store token was invalid.
00299  * @retval NRF_ERROR_NULL           Data contained a NULL pointer.
00300  * @retval NRF_ERROR_NO_MEM         No space available in persistent storage.
00301  * @retval NRF_ERROR_BUSY           FDS or underlying modules are busy and can't take any 
00302  *                                  more requests
00303  * @retval NRF_ERROR_INVALID_STATE  Module is not initialized.
00304  */
00305 ret_code_t pdb_peer_data_update(pm_peer_data_const_t        peer_data,
00306                                 pm_store_token_t            old_token,
00307                                 pm_store_token_t          * p_store_token);
00308 
00309 
00310 /**@brief Function for reading data directly from persistent storage to external memory.
00311  *
00312  * @param[in]    peer_id      ID of peer to read data for.
00313  * @param[in]    data_id      Which piece of data to read.
00314  * @param[inout] p_peer_data  Where to store the data. If the data to be read has variable length,
00315  *                            the appropriate length field needs to reflect the available buffer
00316  *                            space. On a successful read, the length field is updated to match the
00317  *                            length of the read data.
00318  *
00319  * @retval NRF_SUCCESS              Data successfully read.
00320  * @retval NRF_ERROR_INVALID_PARAM  Data ID or Peer ID was invalid or unallocated.
00321  * @retval NRF_ERROR_NULL           p_peer_data contained a NULL pointer.
00322  * @retval NRF_ERROR_NOT_FOUND      This data was not found for this peer ID.
00323  * @retval NRF_ERROR_DATA_SIZE      The provided buffer was not large enough.
00324  * @retval NRF_ERROR_INVALID_STATE  Module is not initialized.
00325  */
00326 ret_code_t pdb_raw_read(pm_peer_id_t      peer_id,
00327                         pm_peer_data_id_t data_id,
00328                         pm_peer_data_t  * p_peer_data);
00329 
00330 
00331 /**@brief Function for writing data directly to persistent storage from external memory.
00332  *
00333  * @param[in]  peer_id        ID of peer to write data for.
00334  * @param[in]  p_peer_data    Data to store.
00335  * @param[out] p_store_token  A token identifying this particular store operation. The token can be
00336  *                            used to identify events pertaining to this operation.
00337  *
00338  * @retval NRF_SUCCESS               Data successfully written.
00339  * @retval NRF_ERROR_INVALID_PARAM   Data ID or Peer ID was invalid or unallocated.
00340  * @retval NRF_ERROR_NULL            p_peer_data contained a NULL pointer.
00341  * @retval NRF_ERROR_NO_MEM          No space available in persistent storage.
00342  * @retval NRF_ERROR_INVALID_LENGTH  Data length above the maximum allowed.
00343  * @retval NRF_ERROR_INVALID_STATE   Module is not initialized.
00344  */
00345 ret_code_t pdb_raw_store(pm_peer_id_t           peer_id,
00346                          pm_peer_data_const_t * p_peer_data,
00347                          pm_store_token_t     * p_store_token);
00348 
00349 
00350 /** @} */
00351 
00352 #endif /* PEER_DATABASE_H__ */
00353 
00354