test
Fork of nrf51-sdk by
Embed:
(wiki syntax)
Show/hide line numbers
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
Generated on Tue Jul 12 2022 15:51:28 by 1.7.2