Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of nrf51-sdk by
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__ */
Generated on Tue Jul 12 2022 14:11:20 by
