Nordic Semiconductor / nRF51822

Nordic stack and drivers for the mbed BLE API

Dependents:   BLE_ANCS_SDAPI BLE_temperature BLE_HeartRate writable_gatt ... more

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?

UserRevisionLine numberNew 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