mbed official / mbed

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_TY51822R3/TOOLCHAIN_IAR/peer_database.h@171:3a7713b1edbc, 2018-11-08 (annotated)

Committer:
AnnaBridge
Date:
Thu Nov 08 11:45:42 2018 +0000
Revision:
171:3a7713b1edbc
Parent:
TARGET_NRF51_DONGLE/TARGET_NORDIC/TARGET_NRF5x/TARGET_SDK_11/ble/peer_manager/peer_database.h@169:a7c7b631e539 
mbed library. Release version 164

Who changed what in which revision?

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