Nordic stack and drivers for the mbed BLE API
Fork of nRF51822 by
TARGET_MCU_NRF51822/sdk/source/ble/peer_manager/peer_database.h@638:c90ae1400bf2, 2016-09-14 (annotated)
- Committer:
- Vincent Coubard
- Date:
- Wed Sep 14 14:39:43 2016 +0100
- Revision:
- 638:c90ae1400bf2
Sync with bdab10dc0f90748b6989c8b577771bb403ca6bd8 from ARMmbed/mbed-os.
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
Vincent Coubard |
638:c90ae1400bf2 | 1 | /* |
Vincent Coubard |
638:c90ae1400bf2 | 2 | * Copyright (c) Nordic Semiconductor ASA |
Vincent Coubard |
638:c90ae1400bf2 | 3 | * All rights reserved. |
Vincent Coubard |
638:c90ae1400bf2 | 4 | * |
Vincent Coubard |
638:c90ae1400bf2 | 5 | * Redistribution and use in source and binary forms, with or without modification, |
Vincent Coubard |
638:c90ae1400bf2 | 6 | * are permitted provided that the following conditions are met: |
Vincent Coubard |
638:c90ae1400bf2 | 7 | * |
Vincent Coubard |
638:c90ae1400bf2 | 8 | * 1. Redistributions of source code must retain the above copyright notice, this |
Vincent Coubard |
638:c90ae1400bf2 | 9 | * list of conditions and the following disclaimer. |
Vincent Coubard |
638:c90ae1400bf2 | 10 | * |
Vincent Coubard |
638:c90ae1400bf2 | 11 | * 2. Redistributions in binary form must reproduce the above copyright notice, this |
Vincent Coubard |
638:c90ae1400bf2 | 12 | * list of conditions and the following disclaimer in the documentation and/or |
Vincent Coubard |
638:c90ae1400bf2 | 13 | * other materials provided with the distribution. |
Vincent Coubard |
638:c90ae1400bf2 | 14 | * |
Vincent Coubard |
638:c90ae1400bf2 | 15 | * 3. Neither the name of Nordic Semiconductor ASA nor the names of other |
Vincent Coubard |
638:c90ae1400bf2 | 16 | * contributors to this software may be used to endorse or promote products |
Vincent Coubard |
638:c90ae1400bf2 | 17 | * derived from this software without specific prior written permission. |
Vincent Coubard |
638:c90ae1400bf2 | 18 | * |
Vincent Coubard |
638:c90ae1400bf2 | 19 | * |
Vincent Coubard |
638:c90ae1400bf2 | 20 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND |
Vincent Coubard |
638:c90ae1400bf2 | 21 | * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED |
Vincent Coubard |
638:c90ae1400bf2 | 22 | * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE |
Vincent Coubard |
638:c90ae1400bf2 | 23 | * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR |
Vincent Coubard |
638:c90ae1400bf2 | 24 | * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES |
Vincent Coubard |
638:c90ae1400bf2 | 25 | * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; |
Vincent Coubard |
638:c90ae1400bf2 | 26 | * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON |
Vincent Coubard |
638:c90ae1400bf2 | 27 | * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
Vincent Coubard |
638:c90ae1400bf2 | 28 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS |
Vincent Coubard |
638:c90ae1400bf2 | 29 | * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
Vincent Coubard |
638:c90ae1400bf2 | 30 | * |
Vincent Coubard |
638:c90ae1400bf2 | 31 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 32 | |
Vincent Coubard |
638:c90ae1400bf2 | 33 | |
Vincent Coubard |
638:c90ae1400bf2 | 34 | #ifndef PEER_DATABASE_H__ |
Vincent Coubard |
638:c90ae1400bf2 | 35 | #define PEER_DATABASE_H__ |
Vincent Coubard |
638:c90ae1400bf2 | 36 | |
Vincent Coubard |
638:c90ae1400bf2 | 37 | #include <stdint.h> |
Vincent Coubard |
638:c90ae1400bf2 | 38 | #include "peer_manager_types.h" |
Vincent Coubard |
638:c90ae1400bf2 | 39 | #include "sdk_errors.h" |
Vincent Coubard |
638:c90ae1400bf2 | 40 | |
Vincent Coubard |
638:c90ae1400bf2 | 41 | /** |
Vincent Coubard |
638:c90ae1400bf2 | 42 | * @defgroup peer_database Peer Database |
Vincent Coubard |
638:c90ae1400bf2 | 43 | * @ingroup peer_manager |
Vincent Coubard |
638:c90ae1400bf2 | 44 | * @{ |
Vincent Coubard |
638:c90ae1400bf2 | 45 | * @brief An internal module of @ref peer_manager. A module for simple management of reading and |
Vincent Coubard |
638:c90ae1400bf2 | 46 | * writing of peer data into persistent storage. |
Vincent Coubard |
638:c90ae1400bf2 | 47 | * |
Vincent Coubard |
638:c90ae1400bf2 | 48 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 49 | |
Vincent Coubard |
638:c90ae1400bf2 | 50 | #define PDB_WRITE_BUF_SIZE (sizeof(pm_peer_data_bonding_t)) |
Vincent Coubard |
638:c90ae1400bf2 | 51 | |
Vincent Coubard |
638:c90ae1400bf2 | 52 | /**@brief Events that can come from the peer_database module. |
Vincent Coubard |
638:c90ae1400bf2 | 53 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 54 | typedef enum |
Vincent Coubard |
638:c90ae1400bf2 | 55 | { |
Vincent Coubard |
638:c90ae1400bf2 | 56 | PDB_EVT_WRITE_BUF_STORED, /**< A pdb_write_buf_store operation has completed successfully. */ |
Vincent Coubard |
638:c90ae1400bf2 | 57 | PDB_EVT_RAW_STORED, /**< A pdb_raw_store operation has completed successfully. */ |
Vincent Coubard |
638:c90ae1400bf2 | 58 | PDB_EVT_RAW_STORE_FAILED, /**< A pdb_raw_store operation has failed. */ |
Vincent Coubard |
638:c90ae1400bf2 | 59 | PDB_EVT_CLEARED, /**< A pdb_clear operation has completed successfully. */ |
Vincent Coubard |
638:c90ae1400bf2 | 60 | PDB_EVT_CLEAR_FAILED, /**< A pdb_clear operation has failed. */ |
Vincent Coubard |
638:c90ae1400bf2 | 61 | PDB_EVT_COMPRESSED, /**< A compress procedure has completed. */ |
Vincent Coubard |
638:c90ae1400bf2 | 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. */ |
Vincent Coubard |
638:c90ae1400bf2 | 63 | PDB_EVT_ERROR_UNEXPECTED, /**< An unexpected error occurred. This is a fatal error. */ |
Vincent Coubard |
638:c90ae1400bf2 | 64 | } pdb_evt_id_t; |
Vincent Coubard |
638:c90ae1400bf2 | 65 | |
Vincent Coubard |
638:c90ae1400bf2 | 66 | /**@brief Events that can come from the peer_database module. |
Vincent Coubard |
638:c90ae1400bf2 | 67 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 68 | typedef struct |
Vincent Coubard |
638:c90ae1400bf2 | 69 | { |
Vincent Coubard |
638:c90ae1400bf2 | 70 | pdb_evt_id_t evt_id; /**< The event that has happened. */ |
Vincent Coubard |
638:c90ae1400bf2 | 71 | pm_peer_id_t peer_id; /**< The id of the peer the event pertains to. */ |
Vincent Coubard |
638:c90ae1400bf2 | 72 | pm_peer_data_id_t data_id; /**< The data the event pertains to. */ |
Vincent Coubard |
638:c90ae1400bf2 | 73 | union |
Vincent Coubard |
638:c90ae1400bf2 | 74 | { |
Vincent Coubard |
638:c90ae1400bf2 | 75 | struct |
Vincent Coubard |
638:c90ae1400bf2 | 76 | { |
Vincent Coubard |
638:c90ae1400bf2 | 77 | pm_store_token_t store_token; /**< A token identifying the store operation this event pertains to. */ |
Vincent Coubard |
638:c90ae1400bf2 | 78 | } raw_stored_evt; |
Vincent Coubard |
638:c90ae1400bf2 | 79 | struct |
Vincent Coubard |
638:c90ae1400bf2 | 80 | { |
Vincent Coubard |
638:c90ae1400bf2 | 81 | pm_store_token_t store_token; /**< A token identifying the store operation this event pertains to. */ |
Vincent Coubard |
638:c90ae1400bf2 | 82 | } error_raw_store_evt; |
Vincent Coubard |
638:c90ae1400bf2 | 83 | } params; |
Vincent Coubard |
638:c90ae1400bf2 | 84 | } pdb_evt_t; |
Vincent Coubard |
638:c90ae1400bf2 | 85 | |
Vincent Coubard |
638:c90ae1400bf2 | 86 | /**@brief Event handler for events from the peer_data_storage module. |
Vincent Coubard |
638:c90ae1400bf2 | 87 | * |
Vincent Coubard |
638:c90ae1400bf2 | 88 | * @param[in] p_event The event that has happened. |
Vincent Coubard |
638:c90ae1400bf2 | 89 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 90 | typedef void (*pdb_evt_handler_t)(pdb_evt_t const * p_event); |
Vincent Coubard |
638:c90ae1400bf2 | 91 | |
Vincent Coubard |
638:c90ae1400bf2 | 92 | |
Vincent Coubard |
638:c90ae1400bf2 | 93 | /**@brief Function for registering for events from the peer database. |
Vincent Coubard |
638:c90ae1400bf2 | 94 | * |
Vincent Coubard |
638:c90ae1400bf2 | 95 | * @note This function will initialize the module if it is not already initialized. |
Vincent Coubard |
638:c90ae1400bf2 | 96 | * |
Vincent Coubard |
638:c90ae1400bf2 | 97 | * @param[in] evt_handler Event handler to register. |
Vincent Coubard |
638:c90ae1400bf2 | 98 | * |
Vincent Coubard |
638:c90ae1400bf2 | 99 | * @retval NRF_SUCCESS Registration successful. |
Vincent Coubard |
638:c90ae1400bf2 | 100 | * @retval NRF_ERROR_NO_MEM No more event handlers can be registered. |
Vincent Coubard |
638:c90ae1400bf2 | 101 | * @retval NRF_ERROR_NULL evt_handler was NULL. |
Vincent Coubard |
638:c90ae1400bf2 | 102 | * @retval NRF_ERROR_INVALID_PARAM Unexpected return code from @ref pm_buffer_init. |
Vincent Coubard |
638:c90ae1400bf2 | 103 | * @retval NRF_ERROR_INVALID_STATE FDS has not been initalized. |
Vincent Coubard |
638:c90ae1400bf2 | 104 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 105 | ret_code_t pdb_register(pdb_evt_handler_t evt_handler); |
Vincent Coubard |
638:c90ae1400bf2 | 106 | |
Vincent Coubard |
638:c90ae1400bf2 | 107 | |
Vincent Coubard |
638:c90ae1400bf2 | 108 | /**@brief Function for allocating persistent bond storage for a peer. |
Vincent Coubard |
638:c90ae1400bf2 | 109 | * |
Vincent Coubard |
638:c90ae1400bf2 | 110 | * @return The ID of the newly allocated storage. |
Vincent Coubard |
638:c90ae1400bf2 | 111 | * @retval PM_PEER_ID_INVALID If no peer ID is available. |
Vincent Coubard |
638:c90ae1400bf2 | 112 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 113 | pm_peer_id_t pdb_peer_allocate(void); |
Vincent Coubard |
638:c90ae1400bf2 | 114 | |
Vincent Coubard |
638:c90ae1400bf2 | 115 | |
Vincent Coubard |
638:c90ae1400bf2 | 116 | /**@brief Function for freeing a peer's persistent bond storage. |
Vincent Coubard |
638:c90ae1400bf2 | 117 | * |
Vincent Coubard |
638:c90ae1400bf2 | 118 | * @note This function will call @ref pdb_write_buf_release on the data for this peer. |
Vincent Coubard |
638:c90ae1400bf2 | 119 | * |
Vincent Coubard |
638:c90ae1400bf2 | 120 | * @param[in] peer_id ID to be freed. |
Vincent Coubard |
638:c90ae1400bf2 | 121 | * |
Vincent Coubard |
638:c90ae1400bf2 | 122 | * @retval NRF_SUCCESS Peer ID was released and clear operation was initiated successfully. |
Vincent Coubard |
638:c90ae1400bf2 | 123 | * @retval NRF_ERROR_BUSY Another peer_id clear was already requested or could not be started. |
Vincent Coubard |
638:c90ae1400bf2 | 124 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
Vincent Coubard |
638:c90ae1400bf2 | 125 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 126 | ret_code_t pdb_peer_free(pm_peer_id_t peer_id); |
Vincent Coubard |
638:c90ae1400bf2 | 127 | |
Vincent Coubard |
638:c90ae1400bf2 | 128 | |
Vincent Coubard |
638:c90ae1400bf2 | 129 | /**@brief Function for retrieving pointers to read-only peer data. |
Vincent Coubard |
638:c90ae1400bf2 | 130 | * |
Vincent Coubard |
638:c90ae1400bf2 | 131 | * @note Reading this pointer is not safe in the strictest sense. If a safe read is required: |
Vincent Coubard |
638:c90ae1400bf2 | 132 | * - Disable interrupts |
Vincent Coubard |
638:c90ae1400bf2 | 133 | * - Call this function. If the return code is @ref NRF_SUCCESS, the following read is safe. |
Vincent Coubard |
638:c90ae1400bf2 | 134 | * - Read memory. |
Vincent Coubard |
638:c90ae1400bf2 | 135 | * - Enable interrupts. |
Vincent Coubard |
638:c90ae1400bf2 | 136 | * @note This buffer does not need to be released. It is a pointer directly to flash. |
Vincent Coubard |
638:c90ae1400bf2 | 137 | * |
Vincent Coubard |
638:c90ae1400bf2 | 138 | * @param[in] peer_id ID of peer to retrieve data for. |
Vincent Coubard |
638:c90ae1400bf2 | 139 | * @param[in] data_id Which piece of data to get. |
Vincent Coubard |
638:c90ae1400bf2 | 140 | * @param[out] p_peer_data Pointer to immutable peer data. |
Vincent Coubard |
638:c90ae1400bf2 | 141 | * @param[out] p_token Token that can be used to lock data in flash and check data validity. |
Vincent Coubard |
638:c90ae1400bf2 | 142 | * |
Vincent Coubard |
638:c90ae1400bf2 | 143 | * @retval NRF_SUCCESS Data retrieved successfully. |
Vincent Coubard |
638:c90ae1400bf2 | 144 | * @retval NRF_ERROR_INVALID_PARAM Data ID or Peer ID was invalid or unallocated. |
Vincent Coubard |
638:c90ae1400bf2 | 145 | * @retval NRF_ERROR_NULL p_peer_data was NULL. |
Vincent Coubard |
638:c90ae1400bf2 | 146 | * @retval NRF_ERROR_NOT_FOUND This data was not found for this peer ID. |
Vincent Coubard |
638:c90ae1400bf2 | 147 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
Vincent Coubard |
638:c90ae1400bf2 | 148 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 149 | ret_code_t pdb_read_buf_get(pm_peer_id_t peer_id, |
Vincent Coubard |
638:c90ae1400bf2 | 150 | pm_peer_data_id_t data_id, |
Vincent Coubard |
638:c90ae1400bf2 | 151 | pm_peer_data_flash_t * p_peer_data, |
Vincent Coubard |
638:c90ae1400bf2 | 152 | pm_store_token_t * p_token); |
Vincent Coubard |
638:c90ae1400bf2 | 153 | |
Vincent Coubard |
638:c90ae1400bf2 | 154 | |
Vincent Coubard |
638:c90ae1400bf2 | 155 | /**@brief Function for retrieving pointers to a write buffer for peer data. |
Vincent Coubard |
638:c90ae1400bf2 | 156 | * |
Vincent Coubard |
638:c90ae1400bf2 | 157 | * @details This function will provide pointers to a buffer of the data. The data buffer will not be |
Vincent Coubard |
638:c90ae1400bf2 | 158 | * written to persistent storage until @ref pdb_write_buf_store is called. The buffer is |
Vincent Coubard |
638:c90ae1400bf2 | 159 | * released by calling either @ref pdb_write_buf_release, @ref pdb_write_buf_store, or |
Vincent Coubard |
638:c90ae1400bf2 | 160 | * @ref pdb_peer_free. |
Vincent Coubard |
638:c90ae1400bf2 | 161 | * |
Vincent Coubard |
638:c90ae1400bf2 | 162 | * When the data_id refers to a variable length data type, the available size is written |
Vincent Coubard |
638:c90ae1400bf2 | 163 | * to the data, both the top-level, and any internal length fields. |
Vincent Coubard |
638:c90ae1400bf2 | 164 | * |
Vincent Coubard |
638:c90ae1400bf2 | 165 | * @note Calling this function on a peer_id/data_id pair that already has a buffer created will |
Vincent Coubard |
638:c90ae1400bf2 | 166 | * give the same buffer, not create a new one. If n_bufs was increased since last time, the |
Vincent Coubard |
638:c90ae1400bf2 | 167 | * buffer might be relocated to be able to provide additional room. In this case, the data |
Vincent Coubard |
638:c90ae1400bf2 | 168 | * will be copied. If n_bufs was increased since last time, this function might return @ref |
Vincent Coubard |
638:c90ae1400bf2 | 169 | * NRF_ERROR_BUSY. In that case, the buffer is automatically released. |
Vincent Coubard |
638:c90ae1400bf2 | 170 | * |
Vincent Coubard |
638:c90ae1400bf2 | 171 | * @param[in] peer_id ID of peer to get a write buffer for. |
Vincent Coubard |
638:c90ae1400bf2 | 172 | * @param[in] data_id Which piece of data to get. |
Vincent Coubard |
638:c90ae1400bf2 | 173 | * @param[in] n_bufs The number of contiguous buffers needed. |
Vincent Coubard |
638:c90ae1400bf2 | 174 | * @param[out] p_peer_data Pointers to mutable peer data. |
Vincent Coubard |
638:c90ae1400bf2 | 175 | * |
Vincent Coubard |
638:c90ae1400bf2 | 176 | * @retval NRF_SUCCESS Data retrieved successfully. |
Vincent Coubard |
638:c90ae1400bf2 | 177 | * @retval NRF_ERROR_INVALID_PARAM Data ID or Peer ID was invalid or unallocated, or n_bufs was 0 |
Vincent Coubard |
638:c90ae1400bf2 | 178 | * or more than the total available buffers. |
Vincent Coubard |
638:c90ae1400bf2 | 179 | * @retval NRF_ERROR_NULL p_peer_data was NULL. |
Vincent Coubard |
638:c90ae1400bf2 | 180 | * @retval NRF_ERROR_BUSY Not enough buffer(s) available. |
Vincent Coubard |
638:c90ae1400bf2 | 181 | * @retval NRF_ERROR_INTERNAL Unexpected internal error. |
Vincent Coubard |
638:c90ae1400bf2 | 182 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
Vincent Coubard |
638:c90ae1400bf2 | 183 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 184 | ret_code_t pdb_write_buf_get(pm_peer_id_t peer_id, |
Vincent Coubard |
638:c90ae1400bf2 | 185 | pm_peer_data_id_t data_id, |
Vincent Coubard |
638:c90ae1400bf2 | 186 | uint32_t n_bufs, |
Vincent Coubard |
638:c90ae1400bf2 | 187 | pm_peer_data_t * p_peer_data); |
Vincent Coubard |
638:c90ae1400bf2 | 188 | |
Vincent Coubard |
638:c90ae1400bf2 | 189 | |
Vincent Coubard |
638:c90ae1400bf2 | 190 | /**@brief Function for freeing a write buffer allocated with @ref pdb_write_buf_get. |
Vincent Coubard |
638:c90ae1400bf2 | 191 | * |
Vincent Coubard |
638:c90ae1400bf2 | 192 | * @note This function will not write peer data to persistent memory. Data in released buffer will |
Vincent Coubard |
638:c90ae1400bf2 | 193 | * be lost. |
Vincent Coubard |
638:c90ae1400bf2 | 194 | * |
Vincent Coubard |
638:c90ae1400bf2 | 195 | * @note This function will undo any previous call to @ref pdb_write_buf_store_prepare for this |
Vincent Coubard |
638:c90ae1400bf2 | 196 | * piece of data. |
Vincent Coubard |
638:c90ae1400bf2 | 197 | * |
Vincent Coubard |
638:c90ae1400bf2 | 198 | * @param[in] peer_id ID of peer to release buffer for. |
Vincent Coubard |
638:c90ae1400bf2 | 199 | * @param[in] data_id Which piece of data to release buffer for. |
Vincent Coubard |
638:c90ae1400bf2 | 200 | * |
Vincent Coubard |
638:c90ae1400bf2 | 201 | * @retval NRF_SUCCESS Successfully released buffer. |
Vincent Coubard |
638:c90ae1400bf2 | 202 | * @retval NRF_ERROR_NOT_FOUND No buffer was allocated for this peer ID/data ID pair. |
Vincent Coubard |
638:c90ae1400bf2 | 203 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
Vincent Coubard |
638:c90ae1400bf2 | 204 | * @retval NRF_ERROR_INTERNAL Unexpected internal error. |
Vincent Coubard |
638:c90ae1400bf2 | 205 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 206 | ret_code_t pdb_write_buf_release(pm_peer_id_t peer_id, pm_peer_data_id_t data_id); |
Vincent Coubard |
638:c90ae1400bf2 | 207 | |
Vincent Coubard |
638:c90ae1400bf2 | 208 | |
Vincent Coubard |
638:c90ae1400bf2 | 209 | /**@brief Function for reserving space in persistent storage for data in a buffer. |
Vincent Coubard |
638:c90ae1400bf2 | 210 | * |
Vincent Coubard |
638:c90ae1400bf2 | 211 | * @note This function only works for data which has a write buffer allocated. If the write buffer |
Vincent Coubard |
638:c90ae1400bf2 | 212 | * is released, this prepare is undone. |
Vincent Coubard |
638:c90ae1400bf2 | 213 | * |
Vincent Coubard |
638:c90ae1400bf2 | 214 | * @note If space has already been reserved for this data, nothing is done. |
Vincent Coubard |
638:c90ae1400bf2 | 215 | * |
Vincent Coubard |
638:c90ae1400bf2 | 216 | * @param[in] peer_id The peer whose data to reserve space for. |
Vincent Coubard |
638:c90ae1400bf2 | 217 | * @param[in] data_id The type of data to reserve space for. |
Vincent Coubard |
638:c90ae1400bf2 | 218 | * |
Vincent Coubard |
638:c90ae1400bf2 | 219 | * @retval NRF_SUCCESS Successfully reserved space in persistent storage. |
Vincent Coubard |
638:c90ae1400bf2 | 220 | * @retval NRF_ERROR_NO_MEM Not enough room in persistent storage. |
Vincent Coubard |
638:c90ae1400bf2 | 221 | * @retval NRF_ERROR_BUSY Could not process request at this time. Reattempt later. |
Vincent Coubard |
638:c90ae1400bf2 | 222 | * @retval NRF_ERROR_NOT_FOUND No buffer has been allocated for this peer ID/data ID pair. |
Vincent Coubard |
638:c90ae1400bf2 | 223 | * @retval NRF_ERROR_INVALID_PARAM Data ID or Peer ID was invalid or unallocated. |
Vincent Coubard |
638:c90ae1400bf2 | 224 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
Vincent Coubard |
638:c90ae1400bf2 | 225 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 226 | ret_code_t pdb_write_buf_store_prepare(pm_peer_id_t peer_id, pm_peer_data_id_t data_id); |
Vincent Coubard |
638:c90ae1400bf2 | 227 | |
Vincent Coubard |
638:c90ae1400bf2 | 228 | |
Vincent Coubard |
638:c90ae1400bf2 | 229 | /**@brief Function for writing data into persistent storage. Writing happens asynchronously. |
Vincent Coubard |
638:c90ae1400bf2 | 230 | * |
Vincent Coubard |
638:c90ae1400bf2 | 231 | * @note This will unlock the data after it has been written. |
Vincent Coubard |
638:c90ae1400bf2 | 232 | * |
Vincent Coubard |
638:c90ae1400bf2 | 233 | * @param[in] peer_id ID of peer to store data for. |
Vincent Coubard |
638:c90ae1400bf2 | 234 | * @param[in] data_id Which piece of data to store. |
Vincent Coubard |
638:c90ae1400bf2 | 235 | * |
Vincent Coubard |
638:c90ae1400bf2 | 236 | * @retval NRF_SUCCESS Data storing was successfully started. |
Vincent Coubard |
638:c90ae1400bf2 | 237 | * @retval NRF_ERROR_NO_MEM No space available in persistent storage. Please clear some |
Vincent Coubard |
638:c90ae1400bf2 | 238 | * space, the operation will be reattempted after the next compress |
Vincent Coubard |
638:c90ae1400bf2 | 239 | * procedure. This error will not happen if |
Vincent Coubard |
638:c90ae1400bf2 | 240 | * @ref pdb_write_buf_store_prepare is called beforehand. |
Vincent Coubard |
638:c90ae1400bf2 | 241 | * @retval NRF_ERROR_INVALID_PARAM Data ID was invalid. |
Vincent Coubard |
638:c90ae1400bf2 | 242 | * @retval NRF_ERROR_NOT_FOUND No buffer has been allocated for this peer ID/data ID pair. |
Vincent Coubard |
638:c90ae1400bf2 | 243 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
Vincent Coubard |
638:c90ae1400bf2 | 244 | * @retval NRF_ERROR_INTERNAL Unexpected internal error. |
Vincent Coubard |
638:c90ae1400bf2 | 245 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 246 | ret_code_t pdb_write_buf_store(pm_peer_id_t peer_id, |
Vincent Coubard |
638:c90ae1400bf2 | 247 | pm_peer_data_id_t data_id); |
Vincent Coubard |
638:c90ae1400bf2 | 248 | |
Vincent Coubard |
638:c90ae1400bf2 | 249 | |
Vincent Coubard |
638:c90ae1400bf2 | 250 | /**@brief Function for clearing data from persistent storage. |
Vincent Coubard |
638:c90ae1400bf2 | 251 | * |
Vincent Coubard |
638:c90ae1400bf2 | 252 | * @param[in] peer_id ID of peer to clear data for. |
Vincent Coubard |
638:c90ae1400bf2 | 253 | * @param[in] data_id Which piece of data to clear. |
Vincent Coubard |
638:c90ae1400bf2 | 254 | * |
Vincent Coubard |
638:c90ae1400bf2 | 255 | * @retval NRF_SUCCESS Data clear was successfully started. |
Vincent Coubard |
638:c90ae1400bf2 | 256 | * @retval NRF_ERROR_INVALID_PARAM Data ID was invalid. |
Vincent Coubard |
638:c90ae1400bf2 | 257 | * @retval NRF_ERROR_NOT_FOUND Nothing to clear for this data for this peer ID. |
Vincent Coubard |
638:c90ae1400bf2 | 258 | * @retval NRF_ERROR_BUSY Could not process request at this time. Reattempt later. |
Vincent Coubard |
638:c90ae1400bf2 | 259 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
Vincent Coubard |
638:c90ae1400bf2 | 260 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 261 | ret_code_t pdb_clear(pm_peer_id_t peer_id, pm_peer_data_id_t data_id); |
Vincent Coubard |
638:c90ae1400bf2 | 262 | |
Vincent Coubard |
638:c90ae1400bf2 | 263 | |
Vincent Coubard |
638:c90ae1400bf2 | 264 | /**@brief Function for querying the number of valid peer IDs available. I.E the number of peers |
Vincent Coubard |
638:c90ae1400bf2 | 265 | * in persistent storage. |
Vincent Coubard |
638:c90ae1400bf2 | 266 | * |
Vincent Coubard |
638:c90ae1400bf2 | 267 | * @return The number of valid peer IDs. |
Vincent Coubard |
638:c90ae1400bf2 | 268 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 269 | uint32_t pdb_n_peers(void); |
Vincent Coubard |
638:c90ae1400bf2 | 270 | |
Vincent Coubard |
638:c90ae1400bf2 | 271 | |
Vincent Coubard |
638:c90ae1400bf2 | 272 | /**@brief Function for getting the next peer ID in the sequence of all used peer IDs. Can be |
Vincent Coubard |
638:c90ae1400bf2 | 273 | * used to loop through all used peer IDs. |
Vincent Coubard |
638:c90ae1400bf2 | 274 | * |
Vincent Coubard |
638:c90ae1400bf2 | 275 | * @note @ref PM_PEER_ID_INVALID is considered to be before the first and after the last ordinary |
Vincent Coubard |
638:c90ae1400bf2 | 276 | * peer ID. |
Vincent Coubard |
638:c90ae1400bf2 | 277 | * |
Vincent Coubard |
638:c90ae1400bf2 | 278 | * @param[in] prev_peer_id The previous peer ID. |
Vincent Coubard |
638:c90ae1400bf2 | 279 | * |
Vincent Coubard |
638:c90ae1400bf2 | 280 | * @return The next peer ID. |
Vincent Coubard |
638:c90ae1400bf2 | 281 | * @return The first ordinary peer ID if prev_peer_id was @ref PM_PEER_ID_INVALID. |
Vincent Coubard |
638:c90ae1400bf2 | 282 | * @retval PM_PEER_ID_INVALID if prev_peer_id was the last ordinary peer ID. |
Vincent Coubard |
638:c90ae1400bf2 | 283 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 284 | pm_peer_id_t pdb_next_peer_id_get(pm_peer_id_t prev_peer_id); |
Vincent Coubard |
638:c90ae1400bf2 | 285 | |
Vincent Coubard |
638:c90ae1400bf2 | 286 | |
Vincent Coubard |
638:c90ae1400bf2 | 287 | /**@brief Function for updating currently stored peer data to a new version |
Vincent Coubard |
638:c90ae1400bf2 | 288 | * |
Vincent Coubard |
638:c90ae1400bf2 | 289 | * @details Updating happens asynchronously. |
Vincent Coubard |
638:c90ae1400bf2 | 290 | * Expect a @ref PDS_EVT_STORED or @ref PDS_EVT_ERROR_STORE for the store token |
Vincent Coubard |
638:c90ae1400bf2 | 291 | * and a @ref PDS_EVT_ERROR_CLEAR or @ref PDS_EVT_ERROR_CLEAR for the old token |
Vincent Coubard |
638:c90ae1400bf2 | 292 | * |
Vincent Coubard |
638:c90ae1400bf2 | 293 | * @param[in] peer_data New data |
Vincent Coubard |
638:c90ae1400bf2 | 294 | * @param[in] old_token Store token for the old data |
Vincent Coubard |
638:c90ae1400bf2 | 295 | * @param[out] p_store_token Store token for the new data |
Vincent Coubard |
638:c90ae1400bf2 | 296 | * |
Vincent Coubard |
638:c90ae1400bf2 | 297 | * @retval NRF_SUCESS The update was initiated successfully |
Vincent Coubard |
638:c90ae1400bf2 | 298 | * @retval NRF_ERROR_NOT_FOUND The old store token was invalid. |
Vincent Coubard |
638:c90ae1400bf2 | 299 | * @retval NRF_ERROR_NULL Data contained a NULL pointer. |
Vincent Coubard |
638:c90ae1400bf2 | 300 | * @retval NRF_ERROR_NO_MEM No space available in persistent storage. |
Vincent Coubard |
638:c90ae1400bf2 | 301 | * @retval NRF_ERROR_BUSY FDS or underlying modules are busy and can't take any |
Vincent Coubard |
638:c90ae1400bf2 | 302 | * more requests |
Vincent Coubard |
638:c90ae1400bf2 | 303 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
Vincent Coubard |
638:c90ae1400bf2 | 304 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 305 | ret_code_t pdb_peer_data_update(pm_peer_data_const_t peer_data, |
Vincent Coubard |
638:c90ae1400bf2 | 306 | pm_store_token_t old_token, |
Vincent Coubard |
638:c90ae1400bf2 | 307 | pm_store_token_t * p_store_token); |
Vincent Coubard |
638:c90ae1400bf2 | 308 | |
Vincent Coubard |
638:c90ae1400bf2 | 309 | |
Vincent Coubard |
638:c90ae1400bf2 | 310 | /**@brief Function for reading data directly from persistent storage to external memory. |
Vincent Coubard |
638:c90ae1400bf2 | 311 | * |
Vincent Coubard |
638:c90ae1400bf2 | 312 | * @param[in] peer_id ID of peer to read data for. |
Vincent Coubard |
638:c90ae1400bf2 | 313 | * @param[in] data_id Which piece of data to read. |
Vincent Coubard |
638:c90ae1400bf2 | 314 | * @param[inout] p_peer_data Where to store the data. If the data to be read has variable length, |
Vincent Coubard |
638:c90ae1400bf2 | 315 | * the appropriate length field needs to reflect the available buffer |
Vincent Coubard |
638:c90ae1400bf2 | 316 | * space. On a successful read, the length field is updated to match the |
Vincent Coubard |
638:c90ae1400bf2 | 317 | * length of the read data. |
Vincent Coubard |
638:c90ae1400bf2 | 318 | * |
Vincent Coubard |
638:c90ae1400bf2 | 319 | * @retval NRF_SUCCESS Data successfully read. |
Vincent Coubard |
638:c90ae1400bf2 | 320 | * @retval NRF_ERROR_INVALID_PARAM Data ID or Peer ID was invalid or unallocated. |
Vincent Coubard |
638:c90ae1400bf2 | 321 | * @retval NRF_ERROR_NULL p_peer_data contained a NULL pointer. |
Vincent Coubard |
638:c90ae1400bf2 | 322 | * @retval NRF_ERROR_NOT_FOUND This data was not found for this peer ID. |
Vincent Coubard |
638:c90ae1400bf2 | 323 | * @retval NRF_ERROR_DATA_SIZE The provided buffer was not large enough. |
Vincent Coubard |
638:c90ae1400bf2 | 324 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
Vincent Coubard |
638:c90ae1400bf2 | 325 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 326 | ret_code_t pdb_raw_read(pm_peer_id_t peer_id, |
Vincent Coubard |
638:c90ae1400bf2 | 327 | pm_peer_data_id_t data_id, |
Vincent Coubard |
638:c90ae1400bf2 | 328 | pm_peer_data_t * p_peer_data); |
Vincent Coubard |
638:c90ae1400bf2 | 329 | |
Vincent Coubard |
638:c90ae1400bf2 | 330 | |
Vincent Coubard |
638:c90ae1400bf2 | 331 | /**@brief Function for writing data directly to persistent storage from external memory. |
Vincent Coubard |
638:c90ae1400bf2 | 332 | * |
Vincent Coubard |
638:c90ae1400bf2 | 333 | * @param[in] peer_id ID of peer to write data for. |
Vincent Coubard |
638:c90ae1400bf2 | 334 | * @param[in] p_peer_data Data to store. |
Vincent Coubard |
638:c90ae1400bf2 | 335 | * @param[out] p_store_token A token identifying this particular store operation. The token can be |
Vincent Coubard |
638:c90ae1400bf2 | 336 | * used to identify events pertaining to this operation. |
Vincent Coubard |
638:c90ae1400bf2 | 337 | * |
Vincent Coubard |
638:c90ae1400bf2 | 338 | * @retval NRF_SUCCESS Data successfully written. |
Vincent Coubard |
638:c90ae1400bf2 | 339 | * @retval NRF_ERROR_INVALID_PARAM Data ID or Peer ID was invalid or unallocated. |
Vincent Coubard |
638:c90ae1400bf2 | 340 | * @retval NRF_ERROR_NULL p_peer_data contained a NULL pointer. |
Vincent Coubard |
638:c90ae1400bf2 | 341 | * @retval NRF_ERROR_NO_MEM No space available in persistent storage. |
Vincent Coubard |
638:c90ae1400bf2 | 342 | * @retval NRF_ERROR_INVALID_LENGTH Data length above the maximum allowed. |
Vincent Coubard |
638:c90ae1400bf2 | 343 | * @retval NRF_ERROR_INVALID_STATE Module is not initialized. |
Vincent Coubard |
638:c90ae1400bf2 | 344 | */ |
Vincent Coubard |
638:c90ae1400bf2 | 345 | ret_code_t pdb_raw_store(pm_peer_id_t peer_id, |
Vincent Coubard |
638:c90ae1400bf2 | 346 | pm_peer_data_const_t * p_peer_data, |
Vincent Coubard |
638:c90ae1400bf2 | 347 | pm_store_token_t * p_store_token); |
Vincent Coubard |
638:c90ae1400bf2 | 348 | |
Vincent Coubard |
638:c90ae1400bf2 | 349 | |
Vincent Coubard |
638:c90ae1400bf2 | 350 | /** @} */ |
Vincent Coubard |
638:c90ae1400bf2 | 351 | |
Vincent Coubard |
638:c90ae1400bf2 | 352 | #endif /* PEER_DATABASE_H__ */ |
Vincent Coubard |
638:c90ae1400bf2 | 353 | |
Vincent Coubard |
638:c90ae1400bf2 | 354 |