mbed official
The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.
Dependents: hello SerialTestv11 SerialTestv12 Sierpinski ... more
mbed 2
This is the mbed 2 library. If you'd like to learn about Mbed OS please see the mbed-os docs.
TARGET_TY51822R3/TOOLCHAIN_GCC_ARM/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?
| User | Revision | Line number | New 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 |
