Thomas Butler
cvb
Fork of
nrf51-sdk
by 
Lancaster University
source/nordic_sdk/components/ble/peer_manager/peer_database.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_DATABASE_H__ |
| Jonathan Austin |
0:bc2961fa1ef0 | 35 | #define PEER_DATABASE_H__ |
| Jonathan Austin |
0:bc2961fa1ef0 | 36 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 37 | #include <stdint.h> |
| Jonathan Austin |
0:bc2961fa1ef0 | 38 | #include "peer_manager_types.h" |
| Jonathan Austin |
0:bc2961fa1ef0 | 39 | #include "sdk_errors.h" |
| Jonathan Austin |
0:bc2961fa1ef0 | 40 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 41 | /** |
| Jonathan Austin |
0:bc2961fa1ef0 | 42 | * @defgroup peer_database Peer Database |
| Jonathan Austin |
0:bc2961fa1ef0 | 43 | * @ingroup peer_manager |
| Jonathan Austin |
0:bc2961fa1ef0 | 44 | * @{ |
| Jonathan Austin |
0:bc2961fa1ef0 | 45 | * @brief An internal module of @ref peer_manager. A module for simple management of reading and |
| Jonathan Austin |
0:bc2961fa1ef0 | 46 | * writing of peer data into persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 47 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 48 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 49 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 50 | #define PDB_WRITE_BUF_SIZE (sizeof(pm_peer_data_bonding_t)) |
| Jonathan Austin |
0:bc2961fa1ef0 | 51 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 52 | /**@brief Events that can come from the peer_database module. |
| Jonathan Austin |
0:bc2961fa1ef0 | 53 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 54 | typedef enum |
| Jonathan Austin |
0:bc2961fa1ef0 | 55 | { |
| Jonathan Austin |
0:bc2961fa1ef0 | 56 | PDB_EVT_WRITE_BUF_STORED, /**< A pdb_write_buf_store operation has completed successfully. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 57 | PDB_EVT_RAW_STORED, /**< A pdb_raw_store operation has completed successfully. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 58 | PDB_EVT_RAW_STORE_FAILED, /**< A pdb_raw_store operation has failed. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 59 | PDB_EVT_CLEARED, /**< A pdb_clear operation has completed successfully. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 60 | PDB_EVT_CLEAR_FAILED, /**< A pdb_clear operation has failed. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 61 | PDB_EVT_COMPRESSED, /**< A compress procedure has completed. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 62 | PDB_EVT_ERROR_NO_MEM, /**< An operation is blocked because the flash is full. It will be reattempted automatically after the next compress procedure. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 63 | PDB_EVT_ERROR_UNEXPECTED, /**< An unexpected error occurred. This is a fatal error. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 64 | } pdb_evt_id_t; |
| Jonathan Austin |
0:bc2961fa1ef0 | 65 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 66 | /**@brief Events that can come from the peer_database module. |
| Jonathan Austin |
0:bc2961fa1ef0 | 67 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 68 | typedef struct |
| Jonathan Austin |
0:bc2961fa1ef0 | 69 | { |
| Jonathan Austin |
0:bc2961fa1ef0 | 70 | pdb_evt_id_t evt_id; /**< The event that has happened. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 71 | pm_peer_id_t peer_id; /**< The id of the peer the event pertains to. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 72 | pm_peer_data_id_t data_id; /**< The data the event pertains to. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 73 | union |
| Jonathan Austin |
0:bc2961fa1ef0 | 74 | { |
| Jonathan Austin |
0:bc2961fa1ef0 | 75 | struct |
| Jonathan Austin |
0:bc2961fa1ef0 | 76 | { |
| Jonathan Austin |
0:bc2961fa1ef0 | 77 | pm_store_token_t store_token; /**< A token identifying the store operation this event pertains to. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 78 | } raw_stored_evt; |
| Jonathan Austin |
0:bc2961fa1ef0 | 79 | struct |
| Jonathan Austin |
0:bc2961fa1ef0 | 80 | { |
| Jonathan Austin |
0:bc2961fa1ef0 | 81 | pm_store_token_t store_token; /**< A token identifying the store operation this event pertains to. */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 82 | } error_raw_store_evt; |
| Jonathan Austin |
0:bc2961fa1ef0 | 83 | } params; |
| Jonathan Austin |
0:bc2961fa1ef0 | 84 | } pdb_evt_t; |
| Jonathan Austin |
0:bc2961fa1ef0 | 85 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 86 | /**@brief Event handler for events from the peer_data_storage module. |
| Jonathan Austin |
0:bc2961fa1ef0 | 87 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 88 | * @param[in] p_event The event that has happened. |
| Jonathan Austin |
0:bc2961fa1ef0 | 89 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 90 | typedef void (*pdb_evt_handler_t)(pdb_evt_t const * p_event); |
| Jonathan Austin |
0:bc2961fa1ef0 | 91 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 92 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 93 | /**@brief Function for registering for events from the peer database. |
| Jonathan Austin |
0:bc2961fa1ef0 | 94 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 95 | * @note This function will initialize the module if it is not already initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 96 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 97 | * @param[in] evt_handler Event handler to register. |
| Jonathan Austin |
0:bc2961fa1ef0 | 98 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 99 | * @retval NRF_SUCCESS Registration successful. |
| Jonathan Austin |
0:bc2961fa1ef0 | 100 | * @retval NRF_ERROR_NO_MEM No more event handlers can be registered. |
| Jonathan Austin |
0:bc2961fa1ef0 | 101 | * @retval NRF_ERROR_NULL evt_handler was NULL. |
| Jonathan Austin |
0:bc2961fa1ef0 | 102 | * @retval NRF_ERROR_INVALID_PARAM Unexpected return code from @ref pm_buffer_init. |
| Jonathan Austin |
0:bc2961fa1ef0 | 103 | * @retval NRF_ERROR_INVALID_STATE FDS has not been initalized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 104 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 105 | ret_code_t pdb_register(pdb_evt_handler_t evt_handler); |
| Jonathan Austin |
0:bc2961fa1ef0 | 106 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 107 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 108 | /**@brief Function for allocating persistent bond storage for a peer. |
| Jonathan Austin |
0:bc2961fa1ef0 | 109 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 110 | * @return The ID of the newly allocated storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 111 | * @retval PM_PEER_ID_INVALID If no peer ID is available. |
| Jonathan Austin |
0:bc2961fa1ef0 | 112 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 113 | pm_peer_id_t pdb_peer_allocate(void); |
| Jonathan Austin |
0:bc2961fa1ef0 | 114 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 115 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 116 | /**@brief Function for freeing a peer's persistent bond storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 117 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 118 | * @note This function will call @ref pdb_write_buf_release on the data for this peer. |
| Jonathan Austin |
0:bc2961fa1ef0 | 119 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 120 | * @param[in] peer_id ID to be freed. |
| Jonathan Austin |
0:bc2961fa1ef0 | 121 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 122 | * @retval NRF_SUCCESS Peer ID was released and clear operation was initiated successfully. |
| Jonathan Austin |
0:bc2961fa1ef0 | 123 | * @retval NRF_ERROR_BUSY Another peer_id clear was already requested or could not be started. |
| Jonathan Austin |
0:bc2961fa1ef0 | 124 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 125 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 126 | ret_code_t pdb_peer_free(pm_peer_id_t peer_id); |
| Jonathan Austin |
0:bc2961fa1ef0 | 127 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 128 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 129 | /**@brief Function for retrieving pointers to read-only peer data. |
| Jonathan Austin |
0:bc2961fa1ef0 | 130 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 131 | * @note Reading this pointer is not safe in the strictest sense. If a safe read is required: |
| Jonathan Austin |
0:bc2961fa1ef0 | 132 | * - Disable interrupts |
| Jonathan Austin |
0:bc2961fa1ef0 | 133 | * - Call this function. If the return code is @ref NRF_SUCCESS, the following read is safe. |
| Jonathan Austin |
0:bc2961fa1ef0 | 134 | * - Read memory. |
| Jonathan Austin |
0:bc2961fa1ef0 | 135 | * - Enable interrupts. |
| Jonathan Austin |
0:bc2961fa1ef0 | 136 | * @note This buffer does not need to be released. It is a pointer directly to flash. |
| Jonathan Austin |
0:bc2961fa1ef0 | 137 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 138 | * @param[in] peer_id ID of peer to retrieve data for. |
| Jonathan Austin |
0:bc2961fa1ef0 | 139 | * @param[in] data_id Which piece of data to get. |
| Jonathan Austin |
0:bc2961fa1ef0 | 140 | * @param[out] p_peer_data Pointer to immutable peer data. |
| Jonathan Austin |
0:bc2961fa1ef0 | 141 | * @param[out] p_token Token that can be used to lock data in flash and check data validity. |
| Jonathan Austin |
0:bc2961fa1ef0 | 142 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 143 | * @retval NRF_SUCCESS Data retrieved successfully. |
| Jonathan Austin |
0:bc2961fa1ef0 | 144 | * @retval NRF_ERROR_INVALID_PARAM Data ID or Peer ID was invalid or unallocated. |
| Jonathan Austin |
0:bc2961fa1ef0 | 145 | * @retval NRF_ERROR_NULL p_peer_data was NULL. |
| Jonathan Austin |
0:bc2961fa1ef0 | 146 | * @retval NRF_ERROR_NOT_FOUND This data was not found for this peer ID. |
| Jonathan Austin |
0:bc2961fa1ef0 | 147 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 148 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 149 | ret_code_t pdb_read_buf_get(pm_peer_id_t peer_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 150 | pm_peer_data_id_t data_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 151 | pm_peer_data_flash_t * p_peer_data, |
| Jonathan Austin |
0:bc2961fa1ef0 | 152 | pm_store_token_t * p_token); |
| Jonathan Austin |
0:bc2961fa1ef0 | 153 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 154 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 155 | /**@brief Function for retrieving pointers to a write buffer for peer data. |
| Jonathan Austin |
0:bc2961fa1ef0 | 156 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 157 | * @details This function will provide pointers to a buffer of the data. The data buffer will not be |
| Jonathan Austin |
0:bc2961fa1ef0 | 158 | * written to persistent storage until @ref pdb_write_buf_store is called. The buffer is |
| Jonathan Austin |
0:bc2961fa1ef0 | 159 | * released by calling either @ref pdb_write_buf_release, @ref pdb_write_buf_store, or |
| Jonathan Austin |
0:bc2961fa1ef0 | 160 | * @ref pdb_peer_free. |
| Jonathan Austin |
0:bc2961fa1ef0 | 161 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 162 | * When the data_id refers to a variable length data type, the available size is written |
| Jonathan Austin |
0:bc2961fa1ef0 | 163 | * to the data, both the top-level, and any internal length fields. |
| Jonathan Austin |
0:bc2961fa1ef0 | 164 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 165 | * @note Calling this function on a peer_id/data_id pair that already has a buffer created will |
| Jonathan Austin |
0:bc2961fa1ef0 | 166 | * give the same buffer, not create a new one. If n_bufs was increased since last time, the |
| Jonathan Austin |
0:bc2961fa1ef0 | 167 | * buffer might be relocated to be able to provide additional room. In this case, the data |
| Jonathan Austin |
0:bc2961fa1ef0 | 168 | * will be copied. If n_bufs was increased since last time, this function might return @ref |
| Jonathan Austin |
0:bc2961fa1ef0 | 169 | * NRF_ERROR_BUSY. In that case, the buffer is automatically released. |
| Jonathan Austin |
0:bc2961fa1ef0 | 170 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 171 | * @param[in] peer_id ID of peer to get a write buffer for. |
| Jonathan Austin |
0:bc2961fa1ef0 | 172 | * @param[in] data_id Which piece of data to get. |
| Jonathan Austin |
0:bc2961fa1ef0 | 173 | * @param[in] n_bufs The number of contiguous buffers needed. |
| Jonathan Austin |
0:bc2961fa1ef0 | 174 | * @param[out] p_peer_data Pointers to mutable peer data. |
| Jonathan Austin |
0:bc2961fa1ef0 | 175 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 176 | * @retval NRF_SUCCESS Data retrieved successfully. |
| Jonathan Austin |
0:bc2961fa1ef0 | 177 | * @retval NRF_ERROR_INVALID_PARAM Data ID or Peer ID was invalid or unallocated, or n_bufs was 0 |
| Jonathan Austin |
0:bc2961fa1ef0 | 178 | * or more than the total available buffers. |
| Jonathan Austin |
0:bc2961fa1ef0 | 179 | * @retval NRF_ERROR_NULL p_peer_data was NULL. |
| Jonathan Austin |
0:bc2961fa1ef0 | 180 | * @retval NRF_ERROR_BUSY Not enough buffer(s) available. |
| Jonathan Austin |
0:bc2961fa1ef0 | 181 | * @retval NRF_ERROR_INTERNAL Unexpected internal error. |
| Jonathan Austin |
0:bc2961fa1ef0 | 182 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 183 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 184 | ret_code_t pdb_write_buf_get(pm_peer_id_t peer_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 185 | pm_peer_data_id_t data_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 186 | uint32_t n_bufs, |
| Jonathan Austin |
0:bc2961fa1ef0 | 187 | pm_peer_data_t * p_peer_data); |
| Jonathan Austin |
0:bc2961fa1ef0 | 188 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 189 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 190 | /**@brief Function for freeing a write buffer allocated with @ref pdb_write_buf_get. |
| Jonathan Austin |
0:bc2961fa1ef0 | 191 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 192 | * @note This function will not write peer data to persistent memory. Data in released buffer will |
| Jonathan Austin |
0:bc2961fa1ef0 | 193 | * be lost. |
| Jonathan Austin |
0:bc2961fa1ef0 | 194 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 195 | * @note This function will undo any previous call to @ref pdb_write_buf_store_prepare for this |
| Jonathan Austin |
0:bc2961fa1ef0 | 196 | * piece of data. |
| Jonathan Austin |
0:bc2961fa1ef0 | 197 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 198 | * @param[in] peer_id ID of peer to release buffer for. |
| Jonathan Austin |
0:bc2961fa1ef0 | 199 | * @param[in] data_id Which piece of data to release buffer for. |
| Jonathan Austin |
0:bc2961fa1ef0 | 200 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 201 | * @retval NRF_SUCCESS Successfully released buffer. |
| Jonathan Austin |
0:bc2961fa1ef0 | 202 | * @retval NRF_ERROR_NOT_FOUND No buffer was allocated for this peer ID/data ID pair. |
| Jonathan Austin |
0:bc2961fa1ef0 | 203 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 204 | * @retval NRF_ERROR_INTERNAL Unexpected internal error. |
| Jonathan Austin |
0:bc2961fa1ef0 | 205 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 206 | ret_code_t pdb_write_buf_release(pm_peer_id_t peer_id, pm_peer_data_id_t data_id); |
| Jonathan Austin |
0:bc2961fa1ef0 | 207 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 208 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 209 | /**@brief Function for reserving space in persistent storage for data in a buffer. |
| Jonathan Austin |
0:bc2961fa1ef0 | 210 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 211 | * @note This function only works for data which has a write buffer allocated. If the write buffer |
| Jonathan Austin |
0:bc2961fa1ef0 | 212 | * is released, this prepare is undone. |
| Jonathan Austin |
0:bc2961fa1ef0 | 213 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 214 | * @note If space has already been reserved for this data, nothing is done. |
| Jonathan Austin |
0:bc2961fa1ef0 | 215 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 216 | * @param[in] peer_id The peer whose data to reserve space for. |
| Jonathan Austin |
0:bc2961fa1ef0 | 217 | * @param[in] data_id The type of data to reserve space for. |
| Jonathan Austin |
0:bc2961fa1ef0 | 218 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 219 | * @retval NRF_SUCCESS Successfully reserved space in persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 220 | * @retval NRF_ERROR_NO_MEM Not enough room in persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 221 | * @retval NRF_ERROR_BUSY Could not process request at this time. Reattempt later. |
| Jonathan Austin |
0:bc2961fa1ef0 | 222 | * @retval NRF_ERROR_NOT_FOUND No buffer has been allocated for this peer ID/data ID pair. |
| Jonathan Austin |
0:bc2961fa1ef0 | 223 | * @retval NRF_ERROR_INVALID_PARAM Data ID or Peer ID was invalid or unallocated. |
| Jonathan Austin |
0:bc2961fa1ef0 | 224 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 225 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 226 | ret_code_t pdb_write_buf_store_prepare(pm_peer_id_t peer_id, pm_peer_data_id_t data_id); |
| Jonathan Austin |
0:bc2961fa1ef0 | 227 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 228 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 229 | /**@brief Function for writing data into persistent storage. Writing happens asynchronously. |
| Jonathan Austin |
0:bc2961fa1ef0 | 230 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 231 | * @note This will unlock the data after it has been written. |
| Jonathan Austin |
0:bc2961fa1ef0 | 232 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 233 | * @param[in] peer_id ID of peer to store data for. |
| Jonathan Austin |
0:bc2961fa1ef0 | 234 | * @param[in] data_id Which piece of data to store. |
| Jonathan Austin |
0:bc2961fa1ef0 | 235 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 236 | * @retval NRF_SUCCESS Data storing was successfully started. |
| Jonathan Austin |
0:bc2961fa1ef0 | 237 | * @retval NRF_ERROR_NO_MEM No space available in persistent storage. Please clear some |
| Jonathan Austin |
0:bc2961fa1ef0 | 238 | * space, the operation will be reattempted after the next compress |
| Jonathan Austin |
0:bc2961fa1ef0 | 239 | * procedure. This error will not happen if |
| Jonathan Austin |
0:bc2961fa1ef0 | 240 | * @ref pdb_write_buf_store_prepare is called beforehand. |
| Jonathan Austin |
0:bc2961fa1ef0 | 241 | * @retval NRF_ERROR_INVALID_PARAM Data ID was invalid. |
| Jonathan Austin |
0:bc2961fa1ef0 | 242 | * @retval NRF_ERROR_NOT_FOUND No buffer has been allocated for this peer ID/data ID pair. |
| Jonathan Austin |
0:bc2961fa1ef0 | 243 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 244 | * @retval NRF_ERROR_INTERNAL Unexpected internal error. |
| Jonathan Austin |
0:bc2961fa1ef0 | 245 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 246 | ret_code_t pdb_write_buf_store(pm_peer_id_t peer_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 247 | pm_peer_data_id_t data_id); |
| Jonathan Austin |
0:bc2961fa1ef0 | 248 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 249 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 250 | /**@brief Function for clearing data from persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 251 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 252 | * @param[in] peer_id ID of peer to clear data for. |
| Jonathan Austin |
0:bc2961fa1ef0 | 253 | * @param[in] data_id Which piece of data to clear. |
| Jonathan Austin |
0:bc2961fa1ef0 | 254 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 255 | * @retval NRF_SUCCESS Data clear was successfully started. |
| Jonathan Austin |
0:bc2961fa1ef0 | 256 | * @retval NRF_ERROR_INVALID_PARAM Data ID was invalid. |
| Jonathan Austin |
0:bc2961fa1ef0 | 257 | * @retval NRF_ERROR_NOT_FOUND Nothing to clear for this data for this peer ID. |
| Jonathan Austin |
0:bc2961fa1ef0 | 258 | * @retval NRF_ERROR_BUSY Could not process request at this time. Reattempt later. |
| Jonathan Austin |
0:bc2961fa1ef0 | 259 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 260 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 261 | ret_code_t pdb_clear(pm_peer_id_t peer_id, pm_peer_data_id_t data_id); |
| Jonathan Austin |
0:bc2961fa1ef0 | 262 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 263 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 264 | /**@brief Function for querying the number of valid peer IDs available. I.E the number of peers |
| Jonathan Austin |
0:bc2961fa1ef0 | 265 | * in persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 266 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 267 | * @return The number of valid peer IDs. |
| Jonathan Austin |
0:bc2961fa1ef0 | 268 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 269 | uint32_t pdb_n_peers(void); |
| Jonathan Austin |
0:bc2961fa1ef0 | 270 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 271 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 272 | /**@brief Function for getting the next peer ID in the sequence of all used peer IDs. Can be |
| Jonathan Austin |
0:bc2961fa1ef0 | 273 | * used to loop through all used peer IDs. |
| Jonathan Austin |
0:bc2961fa1ef0 | 274 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 275 | * @note @ref PM_PEER_ID_INVALID is considered to be before the first and after the last ordinary |
| Jonathan Austin |
0:bc2961fa1ef0 | 276 | * peer ID. |
| Jonathan Austin |
0:bc2961fa1ef0 | 277 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 278 | * @param[in] prev_peer_id The previous peer ID. |
| Jonathan Austin |
0:bc2961fa1ef0 | 279 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 280 | * @return The next peer ID. |
| Jonathan Austin |
0:bc2961fa1ef0 | 281 | * @return The first ordinary peer ID if prev_peer_id was @ref PM_PEER_ID_INVALID. |
| Jonathan Austin |
0:bc2961fa1ef0 | 282 | * @retval PM_PEER_ID_INVALID if prev_peer_id was the last ordinary peer ID. |
| Jonathan Austin |
0:bc2961fa1ef0 | 283 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 284 | pm_peer_id_t pdb_next_peer_id_get(pm_peer_id_t prev_peer_id); |
| Jonathan Austin |
0:bc2961fa1ef0 | 285 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 286 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 287 | /**@brief Function for updating currently stored peer data to a new version |
| Jonathan Austin |
0:bc2961fa1ef0 | 288 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 289 | * @details Updating happens asynchronously. |
| Jonathan Austin |
0:bc2961fa1ef0 | 290 | * Expect a @ref PDS_EVT_STORED or @ref PDS_EVT_ERROR_STORE for the store token |
| Jonathan Austin |
0:bc2961fa1ef0 | 291 | * and a @ref PDS_EVT_ERROR_CLEAR or @ref PDS_EVT_ERROR_CLEAR for the old token |
| Jonathan Austin |
0:bc2961fa1ef0 | 292 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 293 | * @param[in] peer_data New data |
| Jonathan Austin |
0:bc2961fa1ef0 | 294 | * @param[in] old_token Store token for the old data |
| Jonathan Austin |
0:bc2961fa1ef0 | 295 | * @param[out] p_store_token Store token for the new data |
| Jonathan Austin |
0:bc2961fa1ef0 | 296 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 297 | * @retval NRF_SUCESS The update was initiated successfully |
| Jonathan Austin |
0:bc2961fa1ef0 | 298 | * @retval NRF_ERROR_NOT_FOUND The old store token was invalid. |
| Jonathan Austin |
0:bc2961fa1ef0 | 299 | * @retval NRF_ERROR_NULL Data contained a NULL pointer. |
| Jonathan Austin |
0:bc2961fa1ef0 | 300 | * @retval NRF_ERROR_NO_MEM No space available in persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 301 | * @retval NRF_ERROR_BUSY FDS or underlying modules are busy and can't take any |
| Jonathan Austin |
0:bc2961fa1ef0 | 302 | * more requests |
| Jonathan Austin |
0:bc2961fa1ef0 | 303 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 304 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 305 | ret_code_t pdb_peer_data_update(pm_peer_data_const_t peer_data, |
| Jonathan Austin |
0:bc2961fa1ef0 | 306 | pm_store_token_t old_token, |
| Jonathan Austin |
0:bc2961fa1ef0 | 307 | pm_store_token_t * p_store_token); |
| Jonathan Austin |
0:bc2961fa1ef0 | 308 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 309 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 310 | /**@brief Function for reading data directly from persistent storage to external memory. |
| Jonathan Austin |
0:bc2961fa1ef0 | 311 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 312 | * @param[in] peer_id ID of peer to read data for. |
| Jonathan Austin |
0:bc2961fa1ef0 | 313 | * @param[in] data_id Which piece of data to read. |
| Jonathan Austin |
0:bc2961fa1ef0 | 314 | * @param[inout] p_peer_data Where to store the data. If the data to be read has variable length, |
| Jonathan Austin |
0:bc2961fa1ef0 | 315 | * the appropriate length field needs to reflect the available buffer |
| Jonathan Austin |
0:bc2961fa1ef0 | 316 | * space. On a successful read, the length field is updated to match the |
| Jonathan Austin |
0:bc2961fa1ef0 | 317 | * length of the read data. |
| Jonathan Austin |
0:bc2961fa1ef0 | 318 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 319 | * @retval NRF_SUCCESS Data successfully read. |
| Jonathan Austin |
0:bc2961fa1ef0 | 320 | * @retval NRF_ERROR_INVALID_PARAM Data ID or Peer ID was invalid or unallocated. |
| Jonathan Austin |
0:bc2961fa1ef0 | 321 | * @retval NRF_ERROR_NULL p_peer_data contained a NULL pointer. |
| Jonathan Austin |
0:bc2961fa1ef0 | 322 | * @retval NRF_ERROR_NOT_FOUND This data was not found for this peer ID. |
| Jonathan Austin |
0:bc2961fa1ef0 | 323 | * @retval NRF_ERROR_DATA_SIZE The provided buffer was not large enough. |
| Jonathan Austin |
0:bc2961fa1ef0 | 324 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 325 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 326 | ret_code_t pdb_raw_read(pm_peer_id_t peer_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 327 | pm_peer_data_id_t data_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 328 | pm_peer_data_t * p_peer_data); |
| Jonathan Austin |
0:bc2961fa1ef0 | 329 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 330 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 331 | /**@brief Function for writing data directly to persistent storage from external memory. |
| Jonathan Austin |
0:bc2961fa1ef0 | 332 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 333 | * @param[in] peer_id ID of peer to write data for. |
| Jonathan Austin |
0:bc2961fa1ef0 | 334 | * @param[in] p_peer_data Data to store. |
| Jonathan Austin |
0:bc2961fa1ef0 | 335 | * @param[out] p_store_token A token identifying this particular store operation. The token can be |
| Jonathan Austin |
0:bc2961fa1ef0 | 336 | * used to identify events pertaining to this operation. |
| Jonathan Austin |
0:bc2961fa1ef0 | 337 | * |
| Jonathan Austin |
0:bc2961fa1ef0 | 338 | * @retval NRF_SUCCESS Data successfully written. |
| Jonathan Austin |
0:bc2961fa1ef0 | 339 | * @retval NRF_ERROR_INVALID_PARAM Data ID or Peer ID was invalid or unallocated. |
| Jonathan Austin |
0:bc2961fa1ef0 | 340 | * @retval NRF_ERROR_NULL p_peer_data contained a NULL pointer. |
| Jonathan Austin |
0:bc2961fa1ef0 | 341 | * @retval NRF_ERROR_NO_MEM No space available in persistent storage. |
| Jonathan Austin |
0:bc2961fa1ef0 | 342 | * @retval NRF_ERROR_INVALID_LENGTH Data length above the maximum allowed. |
| Jonathan Austin |
0:bc2961fa1ef0 | 343 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
| Jonathan Austin |
0:bc2961fa1ef0 | 344 | */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 345 | ret_code_t pdb_raw_store(pm_peer_id_t peer_id, |
| Jonathan Austin |
0:bc2961fa1ef0 | 346 | pm_peer_data_const_t * p_peer_data, |
| Jonathan Austin |
0:bc2961fa1ef0 | 347 | pm_store_token_t * p_store_token); |
| Jonathan Austin |
0:bc2961fa1ef0 | 348 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 349 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 350 | /** @} */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 351 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 352 | #endif /* PEER_DATABASE_H__ */ |
| Jonathan Austin |
0:bc2961fa1ef0 | 353 | |
| Jonathan Austin |
0:bc2961fa1ef0 | 354 |