Thomas Butler
cvb
Fork of
nrf51-sdk
by 
Lancaster University
source/nordic_sdk/components/ble/peer_manager/peer_data_storage.h@9:d3dd910b0f4b, 2018-08-14 (annotated)
- Committer:
- tb942
- Date:
- Tue Aug 14 18:27:20 2018 +0000
- Revision:
- 9:d3dd910b0f4b
- Parent:
- 0:bc2961fa1ef0
Who changed what in which revision?
| User | Revision | Line number | New contents of line |
|---|---|---|---|
| Jonathan Austin |
0:bc2961fa1ef0 | 1 | /* |
| Jonathan Austin |
0:bc2961fa1ef0 | 2 | * Copyright (c) Nordic Semiconductor ASA |
| Jonathan Austin |
0:bc2961fa1ef0 | 3 | * All rights reserved. |
| Jonathan Austin |
0:bc2961fa1ef0 | 4 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 5 | * Redistribution and use in source and binary forms, with or without modification, |
| Jonathan Austin |
0:bc2961fa1ef0 | 6 | * are permitted provided that the following conditions are met: |
| Jonathan Austin |
0:bc2961fa1ef0 | 7 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 8 | * 1. Redistributions of source code must retain the above copyright notice, this |
| Jonathan Austin |
0:bc2961fa1ef0 | 9 | * list of conditions and the following disclaimer. |
| Jonathan Austin |
0:bc2961fa1ef0 | 10 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 11 | * 2. Redistributions in binary form must reproduce the above copyright notice, this |
| Jonathan Austin |
0:bc2961fa1ef0 | 12 | * list of conditions and the following disclaimer in the documentation and/or |
| Jonathan Austin |
0:bc2961fa1ef0 | 13 | * other materials provided with the distribution. |
| Jonathan Austin |
0:bc2961fa1ef0 | 14 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 15 | * 3. Neither the name of Nordic Semiconductor ASA nor the names of other |
| Jonathan Austin |
0:bc2961fa1ef0 | 16 | * contributors to this software may be used to endorse or promote products |
| Jonathan Austin |
0:bc2961fa1ef0 | 17 | * derived from this software without specific prior written permission. |
| Jonathan Austin |
0:bc2961fa1ef0 | 18 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 19 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 20 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND |
| Jonathan Austin |
0:bc2961fa1ef0 | 21 | * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED |
| Jonathan Austin |
0:bc2961fa1ef0 | 22 | * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE |
| Jonathan Austin |
0:bc2961fa1ef0 | 23 | * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR |
| Jonathan Austin |
0:bc2961fa1ef0 | 24 | * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES |
| Jonathan Austin |
0:bc2961fa1ef0 | 25 | * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; |
| Jonathan Austin |
0:bc2961fa1ef0 | 26 | * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON |
| Jonathan Austin |
0:bc2961fa1ef0 | 27 | * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| Jonathan Austin |
0:bc2961fa1ef0 | 28 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS |
| Jonathan Austin |
0:bc2961fa1ef0 | 29 | * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| Jonathan Austin |
0:bc2961fa1ef0 | 30 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 31 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 32 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 33 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 34 | #ifndef PEER_DATA_STORAGE_H__ |
| Jonathan Austin |
0:bc2961fa1ef0 | 35 | #define PEER_DATA_STORAGE_H__ |
| Jonathan Austin |
0:bc2961fa1ef0 | 36 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 37 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 38 | #include "stdint.h" |
| Jonathan Austin |
0:bc2961fa1ef0 | 39 | #include "sdk_errors.h" |
| Jonathan Austin |
0:bc2961fa1ef0 | 40 | #include "ble_gap.h" |
| Jonathan Austin |
0:bc2961fa1ef0 | 41 | #include "peer_manager_types.h" |
| Jonathan Austin |
0:bc2961fa1ef0 | 42 | #include "fds.h" |
| Jonathan Austin |
0:bc2961fa1ef0 | 43 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 44 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 45 | /** |
| Jonathan Austin |
0:bc2961fa1ef0 | 46 | * @defgroup peer_data_storage Peer Data Storage |
| Jonathan Austin |
0:bc2961fa1ef0 | 47 | * @ingroup peer_manager |
| Jonathan Austin |
0:bc2961fa1ef0 | 48 | * @{ |
| Jonathan Austin |
0:bc2961fa1ef0 | 49 | * @brief An internal module of @ref peer_manager. This module provides a Peer Manager-specific API |
| Jonathan Austin |
0:bc2961fa1ef0 | 50 | * to the persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 51 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 52 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 53 | #define PDS_PREPARE_TOKEN_INVALID 0 |
| Jonathan Austin |
0:bc2961fa1ef0 | 54 | #define PDS_STORE_TOKEN_INVALID 0 |
| Jonathan Austin |
0:bc2961fa1ef0 | 55 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 56 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 57 | typedef enum |
| Jonathan Austin |
0:bc2961fa1ef0 | 58 | { |
| Jonathan Austin |
0:bc2961fa1ef0 | 59 | peer_id_to_instance_id = 16384, |
| Jonathan Austin |
0:bc2961fa1ef0 | 60 | instance_id_to_peer_id = -peer_id_to_instance_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 61 | peer_data_id_to_type_id = 32768, |
| Jonathan Austin |
0:bc2961fa1ef0 | 62 | type_id_to_peer_data_id = -peer_data_id_to_type_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 63 | } pds_convert_t; |
| Jonathan Austin |
0:bc2961fa1ef0 | 64 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 65 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 66 | /**@brief The types of events that can come from the peer_data_storage module. |
| Jonathan Austin |
0:bc2961fa1ef0 | 67 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 68 | typedef enum |
| Jonathan Austin |
0:bc2961fa1ef0 | 69 | { |
| Jonathan Austin |
0:bc2961fa1ef0 | 70 | PDS_EVT_STORED, /**< The specified data has been successfully stored. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 71 | PDS_EVT_CLEARED, /**< The specified data has been successfully cleared. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 72 | PDS_EVT_PEER_ID_CLEAR, /**< The peer id has been successfully cleared. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 73 | PDS_EVT_ERROR_STORE, /**< The specified data could not be stored. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 74 | PDS_EVT_ERROR_CLEAR, /**< The specified data could not be cleared. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 75 | PDS_EVT_ERROR_PEER_ID_CLEAR, /**< The peer id has been successfully cleared. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 76 | PDS_EVT_COMPRESSED, /**< A compress procedure has finished successfully. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 77 | } pds_evt_id_t; |
| Jonathan Austin |
0:bc2961fa1ef0 | 78 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 79 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 80 | /**@brief Events that can come from the peer_data_storage module. |
| Jonathan Austin |
0:bc2961fa1ef0 | 81 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 82 | typedef struct |
| Jonathan Austin |
0:bc2961fa1ef0 | 83 | { |
| Jonathan Austin |
0:bc2961fa1ef0 | 84 | pds_evt_id_t evt_id; /**< The type of event. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 85 | pm_peer_id_t peer_id; /**< The peer the event pertains to. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 86 | pm_peer_data_id_t data_id; /**< The data the event pertains to. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 87 | pm_store_token_t store_token; |
| Jonathan Austin |
0:bc2961fa1ef0 | 88 | } pds_evt_t; |
| Jonathan Austin |
0:bc2961fa1ef0 | 89 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 90 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 91 | /**@brief Event handler for events from the peer_data_storage module. |
| Jonathan Austin |
0:bc2961fa1ef0 | 92 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 93 | * @param[in] event The event that has happened. |
| Jonathan Austin |
0:bc2961fa1ef0 | 94 | * @param[in] peer_id The id of the peer the event pertains to. |
| Jonathan Austin |
0:bc2961fa1ef0 | 95 | * @param[in] flags The data the event pertains to. |
| Jonathan Austin |
0:bc2961fa1ef0 | 96 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 97 | typedef void (*pds_evt_handler_t)(pds_evt_t const * p_event); |
| Jonathan Austin |
0:bc2961fa1ef0 | 98 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 99 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 100 | /**@brief Function for registering for events from the peer database. |
| Jonathan Austin |
0:bc2961fa1ef0 | 101 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 102 | * @note This function will initialize the module if it is not already initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 103 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 104 | * @param[in] evt_handler Event handler to register. |
| Jonathan Austin |
0:bc2961fa1ef0 | 105 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 106 | * @retval NRF_SUCCESS Registration successful. |
| Jonathan Austin |
0:bc2961fa1ef0 | 107 | * @retval NRF_ERROR_NO_MEM No more event handlers can be registered. |
| Jonathan Austin |
0:bc2961fa1ef0 | 108 | * @retval NRF_ERROR_NULL evt_handler was NULL. |
| Jonathan Austin |
0:bc2961fa1ef0 | 109 | * @retval NRF_ERROR_INVALID_PARAM Unexpected return code from @ref pm_buffer_init. |
| Jonathan Austin |
0:bc2961fa1ef0 | 110 | * @retval NRF_ERROR_INVALID_STATE FDS has not been initalized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 111 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 112 | ret_code_t pds_register(pds_evt_handler_t evt_handler); |
| Jonathan Austin |
0:bc2961fa1ef0 | 113 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 114 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 115 | #if 0 |
| Jonathan Austin |
0:bc2961fa1ef0 | 116 | /**@brief Function for initializing Peer Data storage and registering a |
| Jonathan Austin |
0:bc2961fa1ef0 | 117 | * callback for its events. |
| Jonathan Austin |
0:bc2961fa1ef0 | 118 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 119 | * @param[in] evt_handler Event handler to register. |
| Jonathan Austin |
0:bc2961fa1ef0 | 120 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 121 | * @retval NRF_SUCCESS Registration successful. |
| Jonathan Austin |
0:bc2961fa1ef0 | 122 | * @retval NRF_ERROR_NO_MEM No more event handlers can be registered. |
| Jonathan Austin |
0:bc2961fa1ef0 | 123 | * @retval NRF_ERROR_NULL evt_handler was NULL. |
| Jonathan Austin |
0:bc2961fa1ef0 | 124 | * @retval NRF_ERROR_INVALID_STATE FDS has not completed initialization. |
| Jonathan Austin |
0:bc2961fa1ef0 | 125 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 126 | ret_code_t pds_init(pds_evt_handler_t evt_handler); |
| Jonathan Austin |
0:bc2961fa1ef0 | 127 | #endif |
| Jonathan Austin |
0:bc2961fa1ef0 | 128 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 129 | /**@brief Function for retrieving a direct pointer to peer data in persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 130 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 131 | * @param[in] peer_id The id of the peer whose data to read. |
| Jonathan Austin |
0:bc2961fa1ef0 | 132 | * @param[in] data_id Which data to get. |
| Jonathan Austin |
0:bc2961fa1ef0 | 133 | * @param[out] p_data The peer data pointer. |
| Jonathan Austin |
0:bc2961fa1ef0 | 134 | * @param[out] p_token Token that can be used to lock data in flash and check data validity. |
| Jonathan Austin |
0:bc2961fa1ef0 | 135 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 136 | * @retval NRF_SUCCESS The pointer was successfully retrieved. |
| Jonathan Austin |
0:bc2961fa1ef0 | 137 | * @retval NRF_ERROR_INVALID_PARAM Invalid data_id. |
| Jonathan Austin |
0:bc2961fa1ef0 | 138 | * @retval NRF_ERROR_NULL p_data was NULL. |
| Jonathan Austin |
0:bc2961fa1ef0 | 139 | * @retval NRF_ERROR_NOT_FOUND The requested data was not found in persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 140 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 141 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 142 | ret_code_t pds_peer_data_read_ptr_get(pm_peer_id_t peer_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 143 | pm_peer_data_id_t data_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 144 | pm_peer_data_flash_t * p_data, |
| Jonathan Austin |
0:bc2961fa1ef0 | 145 | pm_store_token_t * p_token); |
| Jonathan Austin |
0:bc2961fa1ef0 | 146 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 147 | /**@brief Function to lock the flash data (to defer compression from invalidating data) |
| Jonathan Austin |
0:bc2961fa1ef0 | 148 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 149 | * @param[in] store_token The token representing the item to lock |
| Jonathan Austin |
0:bc2961fa1ef0 | 150 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 151 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 152 | ret_code_t pds_peer_data_lock(pm_store_token_t store_token); |
| Jonathan Austin |
0:bc2961fa1ef0 | 153 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 154 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 155 | /**@brief Function to verify flash data integrity |
| Jonathan Austin |
0:bc2961fa1ef0 | 156 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 157 | * @param[in] store_token The token representing the item to lock |
| Jonathan Austin |
0:bc2961fa1ef0 | 158 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 159 | * @retval NRF_SUCCESS The data integrity is valid. |
| Jonathan Austin |
0:bc2961fa1ef0 | 160 | * @retval NRF_ERROR_NULL The token is invalid. |
| Jonathan Austin |
0:bc2961fa1ef0 | 161 | * @retval NRF_ERROR_INVALID_DATA The data integrity is not valid. |
| Jonathan Austin |
0:bc2961fa1ef0 | 162 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 163 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 164 | ret_code_t pds_peer_data_verify(pm_store_token_t store_token); |
| Jonathan Austin |
0:bc2961fa1ef0 | 165 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 166 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 167 | /**@brief Function for retrieving peer data from persistent storage by making a copy |
| Jonathan Austin |
0:bc2961fa1ef0 | 168 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 169 | * @param[in] peer_id The id of the peer whose data to read. |
| Jonathan Austin |
0:bc2961fa1ef0 | 170 | * @param[in] data_id Which piece of data to read. |
| Jonathan Austin |
0:bc2961fa1ef0 | 171 | * @param[out] p_data Pointer to the peer data. |
| Jonathan Austin |
0:bc2961fa1ef0 | 172 | * @param[in,out] p_len_words Length available to copy to (in words). |
| Jonathan Austin |
0:bc2961fa1ef0 | 173 | * If set to NULL, then no copy will be made and the |
| Jonathan Austin |
0:bc2961fa1ef0 | 174 | * length will be reflected in p_len_words after the call returns. |
| Jonathan Austin |
0:bc2961fa1ef0 | 175 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 176 | * @retval NRF_SUCCESS The read was successful. |
| Jonathan Austin |
0:bc2961fa1ef0 | 177 | * @retval NRF_ERROR_INVALID_PARAM Invalid data_id. |
| Jonathan Austin |
0:bc2961fa1ef0 | 178 | * @retval NRF_ERROR_NULL data contained a NULL pointer. |
| Jonathan Austin |
0:bc2961fa1ef0 | 179 | * @retval NRF_ERROR_NOT_FOUND The requested data was not found in persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 180 | * @retval NRF_ERROR_NO_MEM The length of stored data too large to copy out |
| Jonathan Austin |
0:bc2961fa1ef0 | 181 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 182 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 183 | ret_code_t pds_peer_data_read(pm_peer_id_t peer_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 184 | pm_peer_data_id_t data_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 185 | pm_peer_data_t * p_data, |
| Jonathan Austin |
0:bc2961fa1ef0 | 186 | fds_length_t * p_len_words); |
| Jonathan Austin |
0:bc2961fa1ef0 | 187 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 188 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 189 | /**@brief Function for preparing persistent storage for a write. |
| Jonathan Austin |
0:bc2961fa1ef0 | 190 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 191 | * @details If this call succeeds, space is reserved in persistent storage, so the write will fit. |
| Jonathan Austin |
0:bc2961fa1ef0 | 192 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 193 | * @note If space has already been prepared for this peer_id/data_id pair, no new space will be |
| Jonathan Austin |
0:bc2961fa1ef0 | 194 | * reserved, unless the previous reservation had too small size. |
| Jonathan Austin |
0:bc2961fa1ef0 | 195 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 196 | * @param[in] p_peer_data Data to prepare for. The data needs not be ready, but length and type |
| Jonathan Austin |
0:bc2961fa1ef0 | 197 | * values must. |
| Jonathan Austin |
0:bc2961fa1ef0 | 198 | * @param[out] p_prepare_token A token identifying the prepared memory area. |
| Jonathan Austin |
0:bc2961fa1ef0 | 199 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 200 | * @retval NRF_SUCCESS The call was successful. |
| Jonathan Austin |
0:bc2961fa1ef0 | 201 | * @retval NRF_ERROR_INVALID_PARAM Invalid data ID. |
| Jonathan Austin |
0:bc2961fa1ef0 | 202 | * @retval NRF_ERROR_INVALID_LENGTH Data length above the maximum allowed. |
| Jonathan Austin |
0:bc2961fa1ef0 | 203 | * @retval NRF_ERROR_NO_MEM No space available in persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 204 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 205 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 206 | ret_code_t pds_peer_data_write_prepare(pm_peer_data_const_t const * p_peer_data, |
| Jonathan Austin |
0:bc2961fa1ef0 | 207 | pm_prepare_token_t * p_prepare_token); |
| Jonathan Austin |
0:bc2961fa1ef0 | 208 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 209 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 210 | /**@brief Function for undoing a previous call to @ref pds_peer_data_write_prepare. |
| Jonathan Austin |
0:bc2961fa1ef0 | 211 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 212 | * @param[in] prepare_token A token identifying the prepared memory area to cancel. |
| Jonathan Austin |
0:bc2961fa1ef0 | 213 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 214 | * @retval NRF_SUCCESS The call was successful. |
| Jonathan Austin |
0:bc2961fa1ef0 | 215 | * @retval NRF_ERROR_NOT_FOUND Invalid peer ID and/or prepare token. |
| Jonathan Austin |
0:bc2961fa1ef0 | 216 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 217 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 218 | ret_code_t pds_peer_data_write_prepare_cancel(pm_prepare_token_t prepare_token); |
| Jonathan Austin |
0:bc2961fa1ef0 | 219 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 220 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 221 | /**@brief Function for writing prepared (reserved) peer data to persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 222 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 223 | * @details Writing happens asynchronously. Expect a @ref PDS_EVT_STORED or @ref PDS_EVT_ERROR_STORE |
| Jonathan Austin |
0:bc2961fa1ef0 | 224 | * event. |
| Jonathan Austin |
0:bc2961fa1ef0 | 225 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 226 | * @param[in] peer_id The id of the peer the data pertains to. |
| Jonathan Austin |
0:bc2961fa1ef0 | 227 | * @param[in] p_peer_data The peer data. |
| Jonathan Austin |
0:bc2961fa1ef0 | 228 | * @param[in] prepare_token A token identifying the prepared memory area to write into. If |
| Jonathan Austin |
0:bc2961fa1ef0 | 229 | * the prepare token is invalid, e.g. PDS_PREPARE_TOKEN_INVALID, the |
| Jonathan Austin |
0:bc2961fa1ef0 | 230 | * prepare/write sequence will happen atomically. |
| Jonathan Austin |
0:bc2961fa1ef0 | 231 | * @param[out] p_store_token A token identifying this particular store operation. The token can be |
| Jonathan Austin |
0:bc2961fa1ef0 | 232 | * used to identify events pertaining to this operation. |
| Jonathan Austin |
0:bc2961fa1ef0 | 233 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 234 | * @retval NRF_SUCCESS The write was initiated successfully. |
| Jonathan Austin |
0:bc2961fa1ef0 | 235 | * @retval NRF_ERROR_INVALID_PARAM Invalid data ID or store_flags. |
| Jonathan Austin |
0:bc2961fa1ef0 | 236 | * @retval NRF_ERROR_INVALID_LENGTH Length of data longer than in prepare call. |
| Jonathan Austin |
0:bc2961fa1ef0 | 237 | * @retval NRF_ERROR_NULL data contained a NULL pointer. |
| Jonathan Austin |
0:bc2961fa1ef0 | 238 | * @retval NRF_ERROR_NO_MEM No space available in persistent storage. This can only happen |
| Jonathan Austin |
0:bc2961fa1ef0 | 239 | * if p_prepare_token is NULL. |
| Jonathan Austin |
0:bc2961fa1ef0 | 240 | * @retval NRF_ERROR_BUSY FDS or underlying modules are busy and can't take any |
| Jonathan Austin |
0:bc2961fa1ef0 | 241 | * more requests |
| Jonathan Austin |
0:bc2961fa1ef0 | 242 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 243 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 244 | ret_code_t pds_peer_data_write_prepared(pm_peer_id_t peer_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 245 | pm_peer_data_const_t const * p_peer_data, |
| Jonathan Austin |
0:bc2961fa1ef0 | 246 | pm_prepare_token_t prepare_token, |
| Jonathan Austin |
0:bc2961fa1ef0 | 247 | pm_store_token_t * p_store_token); |
| Jonathan Austin |
0:bc2961fa1ef0 | 248 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 249 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 250 | /**@brief Function for writing peer data to persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 251 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 252 | * @details Writing happens asynchronously. Expect a @ref PDS_EVT_STORED or @ref PDS_EVT_ERROR_STORE |
| Jonathan Austin |
0:bc2961fa1ef0 | 253 | * event. |
| Jonathan Austin |
0:bc2961fa1ef0 | 254 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 255 | * @param[in] peer_id The id of the peer the data pertains to. |
| Jonathan Austin |
0:bc2961fa1ef0 | 256 | * @param[in] p_peer_data The peer data. |
| Jonathan Austin |
0:bc2961fa1ef0 | 257 | * @param[out] p_store_token A token identifying this particular store operation. The token can be |
| Jonathan Austin |
0:bc2961fa1ef0 | 258 | * used to identify events pertaining to this operation. |
| Jonathan Austin |
0:bc2961fa1ef0 | 259 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 260 | * @retval NRF_SUCCESS The write was initiated successfully. |
| Jonathan Austin |
0:bc2961fa1ef0 | 261 | * @retval NRF_ERROR_INVALID_PARAM Invalid data ID or store_flags. |
| Jonathan Austin |
0:bc2961fa1ef0 | 262 | * @retval NRF_ERROR_NULL Data contained a NULL pointer. |
| Jonathan Austin |
0:bc2961fa1ef0 | 263 | * @retval NRF_ERROR_NO_MEM No space available in persistent storage. This can only happen |
| Jonathan Austin |
0:bc2961fa1ef0 | 264 | * if p_prepare_token is NULL. |
| Jonathan Austin |
0:bc2961fa1ef0 | 265 | * @retval NRF_ERROR_BUSY FDS or underlying modules are busy and can't take any |
| Jonathan Austin |
0:bc2961fa1ef0 | 266 | * more requests |
| Jonathan Austin |
0:bc2961fa1ef0 | 267 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 268 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 269 | ret_code_t pds_peer_data_write(pm_peer_id_t peer_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 270 | pm_peer_data_const_t const * p_peer_data, |
| Jonathan Austin |
0:bc2961fa1ef0 | 271 | pm_store_token_t * p_store_token); |
| Jonathan Austin |
0:bc2961fa1ef0 | 272 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 273 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 274 | /**@brief Function for updating currently stored peer data to a new version |
| Jonathan Austin |
0:bc2961fa1ef0 | 275 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 276 | * @details Updating happens asynchronously. |
| Jonathan Austin |
0:bc2961fa1ef0 | 277 | * Expect a @ref PDS_EVT_STORED or @ref PDS_EVT_ERROR_STORE for the store token |
| Jonathan Austin |
0:bc2961fa1ef0 | 278 | * and a @ref PDS_EVT_ERROR_CLEAR or @ref PDS_EVT_ERROR_CLEAR for the old token |
| Jonathan Austin |
0:bc2961fa1ef0 | 279 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 280 | * @param[in] peer_id The peer which the data is associated to. |
| Jonathan Austin |
0:bc2961fa1ef0 | 281 | * @param[in] peer_data New data. |
| Jonathan Austin |
0:bc2961fa1ef0 | 282 | * @param[in] old_token Store token for the old data. |
| Jonathan Austin |
0:bc2961fa1ef0 | 283 | * @param[out] p_store_token Store token for the new data. |
| Jonathan Austin |
0:bc2961fa1ef0 | 284 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 285 | * @retval NRF_SUCESS The update was initiated successfully |
| Jonathan Austin |
0:bc2961fa1ef0 | 286 | * @retval NRF_ERROR_NOT_FOUND The old store token was invalid. |
| Jonathan Austin |
0:bc2961fa1ef0 | 287 | * @retval NRF_ERROR_NULL Data contained a NULL pointer. |
| Jonathan Austin |
0:bc2961fa1ef0 | 288 | * @retval NRF_ERROR_NO_MEM No space available in persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 289 | * @retval NRF_ERROR_BUSY FDS or underlying modules are busy and can't take any |
| Jonathan Austin |
0:bc2961fa1ef0 | 290 | * more requests |
| Jonathan Austin |
0:bc2961fa1ef0 | 291 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 292 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 293 | ret_code_t pds_peer_data_update(pm_peer_id_t peer_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 294 | pm_peer_data_const_t const * peer_data, |
| Jonathan Austin |
0:bc2961fa1ef0 | 295 | pm_store_token_t old_token, |
| Jonathan Austin |
0:bc2961fa1ef0 | 296 | pm_store_token_t * p_store_token); |
| Jonathan Austin |
0:bc2961fa1ef0 | 297 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 298 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 299 | /**@brief Function for clearing peer data from persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 300 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 301 | * @details Clearing happens asynchronously. Expect a @ref PDS_EVT_CLEARED or @ref PDS_EVT_ERROR_CLEAR |
| Jonathan Austin |
0:bc2961fa1ef0 | 302 | * event. |
| Jonathan Austin |
0:bc2961fa1ef0 | 303 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 304 | * @param[in] peer_id The id of the peer the data pertains to. |
| Jonathan Austin |
0:bc2961fa1ef0 | 305 | * @param[in] data_id Which data to clear. |
| Jonathan Austin |
0:bc2961fa1ef0 | 306 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 307 | * @retval NRF_SUCCESS The clear was initiated successfully. |
| Jonathan Austin |
0:bc2961fa1ef0 | 308 | * @retval NRF_ERROR_INVALID_PARAM Data ID or was invalid. |
| Jonathan Austin |
0:bc2961fa1ef0 | 309 | * @retval NRF_ERROR_NOT_FOUND Nothing to clear for this peer ID. |
| Jonathan Austin |
0:bc2961fa1ef0 | 310 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 311 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 312 | ret_code_t pds_peer_data_clear(pm_peer_id_t peer_id, pm_peer_data_id_t data_id); |
| Jonathan Austin |
0:bc2961fa1ef0 | 313 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 314 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 315 | /**@brief Function for claiming an unused peer ID. |
| Jonathan Austin |
0:bc2961fa1ef0 | 316 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 317 | * @return The first unused peer ID. |
| Jonathan Austin |
0:bc2961fa1ef0 | 318 | * @retval PM_PEER_ID_INVALID If no peer ID is available or module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 319 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 320 | pm_peer_id_t pds_peer_id_allocate(void); |
| Jonathan Austin |
0:bc2961fa1ef0 | 321 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 322 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 323 | /**@brief Function for freeing a peer ID and clearing all data associated with it in persistent |
| Jonathan Austin |
0:bc2961fa1ef0 | 324 | * storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 325 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 326 | * @param[in] peer_id Peer ID to free. |
| Jonathan Austin |
0:bc2961fa1ef0 | 327 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 328 | * @retval NRF_SUCCESS The clear was initiated successfully |
| Jonathan Austin |
0:bc2961fa1ef0 | 329 | * @retval NRF_ERROR_BUSY Another peer_id clear was already requested or fds queue full |
| Jonathan Austin |
0:bc2961fa1ef0 | 330 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 331 | ret_code_t pds_peer_id_free(pm_peer_id_t peer_id); |
| Jonathan Austin |
0:bc2961fa1ef0 | 332 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 333 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 334 | /**@brief Function for finding out whether a peer ID is in use. |
| Jonathan Austin |
0:bc2961fa1ef0 | 335 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 336 | * @param[in] peer_id The peer ID to inquire about. |
| Jonathan Austin |
0:bc2961fa1ef0 | 337 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 338 | * @retval true peer_id is in use. |
| Jonathan Austin |
0:bc2961fa1ef0 | 339 | * @retval false peer_id is free, or the module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 340 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 341 | bool pds_peer_id_is_allocated(pm_peer_id_t peer_id); |
| Jonathan Austin |
0:bc2961fa1ef0 | 342 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 343 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 344 | /**@brief Function for getting the next peer ID in the sequence of all used peer IDs. Can be |
| Jonathan Austin |
0:bc2961fa1ef0 | 345 | * used to loop through all used peer IDs. |
| Jonathan Austin |
0:bc2961fa1ef0 | 346 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 347 | * @note @ref PM_PEER_ID_INVALID is considered to be before the first and after the last ordinary |
| Jonathan Austin |
0:bc2961fa1ef0 | 348 | * peer ID. |
| Jonathan Austin |
0:bc2961fa1ef0 | 349 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 350 | * @param[in] prev_peer_id The previous peer ID. |
| Jonathan Austin |
0:bc2961fa1ef0 | 351 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 352 | * @return The next peer ID. |
| Jonathan Austin |
0:bc2961fa1ef0 | 353 | * @return The first ordinary peer ID if prev_peer_id was @ref PM_PEER_ID_INVALID. |
| Jonathan Austin |
0:bc2961fa1ef0 | 354 | * @retval PM_PEER_ID_INVALID if prev_peer_id was the last ordinary peer ID or the module |
| Jonathan Austin |
0:bc2961fa1ef0 | 355 | * is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 356 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 357 | pm_peer_id_t pds_next_peer_id_get(pm_peer_id_t prev_peer_id); |
| Jonathan Austin |
0:bc2961fa1ef0 | 358 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 359 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 360 | /**@brief Function for querying the number of valid peer IDs available. I.E the number of peers |
| Jonathan Austin |
0:bc2961fa1ef0 | 361 | * in persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 362 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 363 | * @return The number of valid peer IDs, or 0 if module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 364 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 365 | uint32_t pds_n_peers(void); |
| Jonathan Austin |
0:bc2961fa1ef0 | 366 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 367 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 368 | /** @} */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 369 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 370 | #endif /* PEER_DATA_STORAGE_H__ */ |