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