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

Committer:
AnnaBridge
Date:
Thu Nov 08 11:45:42 2018 +0000
Revision:
171:3a7713b1edbc
Parent:
TARGET_NRF51_DK/TARGET_NORDIC/TARGET_NRF5x/TARGET_SDK_11/ble/peer_manager/peer_manager.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 /**
AnnaBridge 146:22da6e220af6 42 * @file peer_manager.h
AnnaBridge 146:22da6e220af6 43 *
AnnaBridge 146:22da6e220af6 44 * @defgroup peer_manager Peer Manager
AnnaBridge 146:22da6e220af6 45 * @ingroup ble_sdk_lib
AnnaBridge 146:22da6e220af6 46 * @{
AnnaBridge 146:22da6e220af6 47 * @brief Module for managing BLE bonding, which includes controlling encryption and pairing
AnnaBridge 146:22da6e220af6 48 * procedures as well as persistently storing different pieces of data that must be stored
AnnaBridge 146:22da6e220af6 49 * when bonded.
AnnaBridge 146:22da6e220af6 50 *
AnnaBridge 146:22da6e220af6 51 * @details The API consists of functions for configuring the pairing and encryption behavior of the
AnnaBridge 146:22da6e220af6 52 * device and functions for manipulating the stored data.
AnnaBridge 146:22da6e220af6 53 */
AnnaBridge 146:22da6e220af6 54
AnnaBridge 146:22da6e220af6 55
AnnaBridge 146:22da6e220af6 56 #ifndef PEER_MANAGER_H__
AnnaBridge 146:22da6e220af6 57 #define PEER_MANAGER_H__
AnnaBridge 146:22da6e220af6 58
AnnaBridge 146:22da6e220af6 59 #include <stdint.h>
AnnaBridge 146:22da6e220af6 60 #include <stdbool.h>
AnnaBridge 146:22da6e220af6 61 #include "sdk_common.h"
AnnaBridge 146:22da6e220af6 62 #include "nrf_ble.h"
AnnaBridge 146:22da6e220af6 63 #include "nrf_ble_gap.h"
AnnaBridge 146:22da6e220af6 64 #include "peer_manager_types.h"
AnnaBridge 146:22da6e220af6 65 #include "peer_database.h"
AnnaBridge 146:22da6e220af6 66
AnnaBridge 146:22da6e220af6 67
AnnaBridge 146:22da6e220af6 68
AnnaBridge 146:22da6e220af6 69 /**@brief Security status of a connection.
AnnaBridge 146:22da6e220af6 70 */
AnnaBridge 146:22da6e220af6 71 typedef struct
AnnaBridge 146:22da6e220af6 72 {
AnnaBridge 146:22da6e220af6 73 uint8_t connected : 1; /**< @brief The connection is active (not disconnected). */
AnnaBridge 146:22da6e220af6 74 uint8_t encrypted : 1; /**< @brief Communication on this link is encrypted. */
AnnaBridge 146:22da6e220af6 75 uint8_t mitm_protected : 1; /**< @brief The encrypted communication is also protected against man-in-the-middle attacks. */
AnnaBridge 146:22da6e220af6 76 uint8_t bonded : 1; /**< @brief The peer is bonded with us. */
AnnaBridge 146:22da6e220af6 77 } pm_conn_sec_status_t;
AnnaBridge 146:22da6e220af6 78
AnnaBridge 146:22da6e220af6 79
AnnaBridge 146:22da6e220af6 80 /**@brief Types of events that can come from the @ref peer_manager module.
AnnaBridge 146:22da6e220af6 81 */
AnnaBridge 146:22da6e220af6 82 typedef enum
AnnaBridge 146:22da6e220af6 83 {
AnnaBridge 146:22da6e220af6 84 PM_EVT_BONDED_PEER_CONNECTED, /**< @brief A connected peer has been identified as one with which we have a bond. When performing bonding with a peer for the first time, this event will not be sent until a new connection is established with the peer. When we are central, this event is always sent when the Peer Manager receives the @ref BLE_GAP_EVT_CONNECTED event. When we are peripheral, this event might in rare cases arrive later. */
AnnaBridge 146:22da6e220af6 85 PM_EVT_CONN_SEC_START, /**< @brief A security procedure has started on a link, initiated either locally or remotely. The security procedure is using the last parameters provided via @ref pm_sec_params_set. This event is always followed by either a @ref PM_EVT_CONN_SEC_SUCCEEDED or a @ref PM_EVT_CONN_SEC_FAILED event. This is an informational event; no action is needed for the procedure to proceed. */
AnnaBridge 146:22da6e220af6 86 PM_EVT_CONN_SEC_SUCCEEDED, /**< @brief A link has been encrypted, either as a result of a call to @ref pm_conn_secure or a result of an action by the peer. The event structure contains more information about the circumstances. This event might contain a peer ID with the value @ref PM_PEER_ID_INVALID, which means that the peer (central) used an address that could not be identified, but it used an encryption key (LTK) that is present in the database. */
AnnaBridge 146:22da6e220af6 87 PM_EVT_CONN_SEC_FAILED, /**< @brief A pairing or encryption procedure has failed. In some cases, this means that security is not possible on this link (temporarily or permanently). How to handle this error depends on the application. */
AnnaBridge 146:22da6e220af6 88 PM_EVT_CONN_SEC_CONFIG_REQ, /**< @brief The peer (central) has requested pairing, but a bond already exists with that peer. Reply by calling @ref pm_conn_sec_config_reply before the event handler returns. If no reply is sent, a default is used. */
AnnaBridge 146:22da6e220af6 89 PM_EVT_STORAGE_FULL, /**< @brief There is no more room for peer data in flash storage. To solve this problem, delete data that is not needed anymore and run a garbage collection procedure in FDS. */
AnnaBridge 146:22da6e220af6 90 PM_EVT_ERROR_UNEXPECTED, /**< @brief An unrecoverable error happened inside Peer Manager. An operation failed with the provided error. */
AnnaBridge 146:22da6e220af6 91 PM_EVT_PEER_DATA_UPDATE_SUCCEEDED, /**< @brief A piece of peer data was stored, updated, or cleared in flash storage. This event is sent for all successful changes to peer data, also those initiated internally in Peer Manager. To identify an operation, compare the store token in the event with the store token received during the initiating function call. Events from internally initiated changes might have invalid store tokens. */
AnnaBridge 146:22da6e220af6 92 PM_EVT_PEER_DATA_UPDATE_FAILED, /**< @brief A piece of peer data could not be stored, updated, or cleared in flash storage. This event is sent instead of @ref PM_EVT_PEER_DATA_UPDATE_SUCCEEDED for the failed operation. */
AnnaBridge 146:22da6e220af6 93 PM_EVT_PEER_DELETE_SUCCEEDED, /**< @brief A peer was cleared from flash storage, for example because a call to @ref pm_peer_delete succeeded. This event can also be sent as part of a call to @ref pm_peers_delete or internal cleanup. */
AnnaBridge 146:22da6e220af6 94 PM_EVT_PEER_DELETE_FAILED, /**< @brief A peer could not be cleared from flash storage. This event is sent instead of @ref PM_EVT_PEER_DELETE_SUCCEEDED for the failed operation. */
AnnaBridge 146:22da6e220af6 95 PM_EVT_PEERS_DELETE_SUCCEEDED, /**< @brief A call to @ref pm_peers_delete has completed successfully. Flash storage now contains no peer data. */
AnnaBridge 146:22da6e220af6 96 PM_EVT_PEERS_DELETE_FAILED, /**< @brief A call to @ref pm_peers_delete has failed, which means that at least one of the peers could not be deleted. Other peers might have been deleted, or might still be queued to be deleted. No more @ref PM_EVT_PEERS_DELETE_SUCCEEDED or @ref PM_EVT_PEERS_DELETE_FAILED events are sent until the next time @ref pm_peers_delete is called. */
AnnaBridge 146:22da6e220af6 97 PM_EVT_LOCAL_DB_CACHE_APPLIED, /**< @brief Local database values for a peer (taken from flash storage) have been provided to the SoftDevice. */
AnnaBridge 146:22da6e220af6 98 PM_EVT_LOCAL_DB_CACHE_APPLY_FAILED, /**< @brief Local database values for a peer (taken from flash storage) were rejected by the SoftDevice, which means that either the database has changed or the user has manually set the local database to an invalid value (using @ref pm_peer_data_store). */
AnnaBridge 146:22da6e220af6 99 PM_EVT_SERVICE_CHANGED_IND_SENT, /**< @brief A service changed indication has been sent to a peer, as a result of a call to @ref pm_local_database_has_changed. This event will be followed by a @ref PM_EVT_SERVICE_CHANGED_IND_CONFIRMED event if the peer acknowledges the indication. */
AnnaBridge 146:22da6e220af6 100 PM_EVT_SERVICE_CHANGED_IND_CONFIRMED, /**< @brief A service changed indication that was sent has been confirmed by a peer. The peer can now be considered aware that the local database has changed. */
AnnaBridge 146:22da6e220af6 101 } pm_evt_id_t;
AnnaBridge 146:22da6e220af6 102
AnnaBridge 146:22da6e220af6 103
AnnaBridge 146:22da6e220af6 104 /**@brief Parameters specific to the @ref PM_EVT_CONN_SEC_SUCCEEDED event.
AnnaBridge 146:22da6e220af6 105 */
AnnaBridge 146:22da6e220af6 106 typedef struct
AnnaBridge 146:22da6e220af6 107 {
AnnaBridge 146:22da6e220af6 108 pm_conn_sec_procedure_t procedure; /**< @brief The procedure that led to securing the link. */
AnnaBridge 146:22da6e220af6 109 } pm_conn_secured_evt_t;
AnnaBridge 146:22da6e220af6 110
AnnaBridge 146:22da6e220af6 111
AnnaBridge 146:22da6e220af6 112 /**@brief Parameters specific to the @ref PM_EVT_CONN_SEC_FAILED event.
AnnaBridge 146:22da6e220af6 113 */
AnnaBridge 146:22da6e220af6 114 typedef struct
AnnaBridge 146:22da6e220af6 115 {
AnnaBridge 146:22da6e220af6 116 pm_conn_sec_procedure_t procedure; /**< @brief The procedure that failed. */
AnnaBridge 146:22da6e220af6 117 pm_sec_error_code_t error; /**< @brief An error code that describes the failure. */
AnnaBridge 146:22da6e220af6 118 uint8_t error_src; /**< @brief The party that raised the error, see @ref BLE_GAP_SEC_STATUS_SOURCES. */
AnnaBridge 146:22da6e220af6 119 } pm_conn_secure_failed_evt_t;
AnnaBridge 146:22da6e220af6 120
AnnaBridge 146:22da6e220af6 121
AnnaBridge 146:22da6e220af6 122 /**@brief Actions that can be performed to peer data in persistent storage.
AnnaBridge 146:22da6e220af6 123 */
AnnaBridge 146:22da6e220af6 124 typedef enum
AnnaBridge 146:22da6e220af6 125 {
AnnaBridge 146:22da6e220af6 126 PM_PEER_DATA_OP_UPDATE, /**< @brief Writing or overwriting the data. */
AnnaBridge 146:22da6e220af6 127 PM_PEER_DATA_OP_DELETE, /**< @brief Removing the data. */
AnnaBridge 146:22da6e220af6 128 } pm_peer_data_op_t;
AnnaBridge 146:22da6e220af6 129
AnnaBridge 146:22da6e220af6 130
AnnaBridge 146:22da6e220af6 131 /**@brief Parameters specific to the @ref PM_EVT_PEER_DATA_UPDATE_SUCCEEDED event.
AnnaBridge 146:22da6e220af6 132 */
AnnaBridge 146:22da6e220af6 133 typedef struct
AnnaBridge 146:22da6e220af6 134 {
AnnaBridge 146:22da6e220af6 135 pm_peer_data_id_t data_id; /**< @brief The type of the data that was changed. */
AnnaBridge 146:22da6e220af6 136 pm_peer_data_op_t action; /**< @brief What happened to the data. */
AnnaBridge 146:22da6e220af6 137 uint8_t flash_changed : 1; /**< @brief If this is false, no operation was done in flash, because the value was already what it should be. Please note that in certain scenarios, this flag will be true even if the new value is the same as the old. */
AnnaBridge 146:22da6e220af6 138 pm_store_token_t token; /**< @brief Token that identifies the operation. For @ref PM_PEER_DATA_OP_DELETE actions, this token can be disregarded. For @ref PM_PEER_DATA_OP_UPDATE actions, compare this token with the token that is received from a call to a @ref PM_PEER_DATA_FUNCTIONS function. */
AnnaBridge 146:22da6e220af6 139 } pm_peer_data_update_succeeded_evt_t;
AnnaBridge 146:22da6e220af6 140
AnnaBridge 146:22da6e220af6 141
AnnaBridge 146:22da6e220af6 142 /**@brief Parameters specific to the @ref PM_EVT_PEER_DATA_UPDATE_FAILED event.
AnnaBridge 146:22da6e220af6 143 */
AnnaBridge 146:22da6e220af6 144 typedef struct
AnnaBridge 146:22da6e220af6 145 {
AnnaBridge 146:22da6e220af6 146 pm_peer_data_id_t data_id; /**< @brief The type of the data that was supposed to be changed. */
AnnaBridge 146:22da6e220af6 147 pm_peer_data_op_t action; /**< @brief The action that failed. */
AnnaBridge 146:22da6e220af6 148 pm_store_token_t token; /**< @brief Token that identifies the operation. For @ref PM_PEER_DATA_OP_DELETE actions, this token can be disregarded. For @ref PM_PEER_DATA_OP_UPDATE actions, compare this token with the token that is received from a call to a @ref PM_PEER_DATA_FUNCTIONS function. */
AnnaBridge 146:22da6e220af6 149 ret_code_t error; /**< @brief An error code that describes the failure. */
AnnaBridge 146:22da6e220af6 150 } pm_peer_data_update_failed_t;
AnnaBridge 146:22da6e220af6 151
AnnaBridge 146:22da6e220af6 152
AnnaBridge 146:22da6e220af6 153 /**@brief Standard parameters for failure events.
AnnaBridge 146:22da6e220af6 154 */
AnnaBridge 146:22da6e220af6 155 typedef struct
AnnaBridge 146:22da6e220af6 156 {
AnnaBridge 146:22da6e220af6 157 ret_code_t error; /**< @brief The error that occurred. */
AnnaBridge 146:22da6e220af6 158 } pm_failure_evt_t;
AnnaBridge 146:22da6e220af6 159
AnnaBridge 146:22da6e220af6 160
AnnaBridge 146:22da6e220af6 161 /**@brief An event from the @ref peer_manager module.
AnnaBridge 146:22da6e220af6 162 *
AnnaBridge 146:22da6e220af6 163 * @details The structure contains both standard parameters and parameters that are specific to some events.
AnnaBridge 146:22da6e220af6 164 */
AnnaBridge 146:22da6e220af6 165 typedef struct
AnnaBridge 146:22da6e220af6 166 {
AnnaBridge 146:22da6e220af6 167 pm_evt_id_t evt_id; /**< @brief The type of the event. */
AnnaBridge 146:22da6e220af6 168 uint16_t conn_handle; /**< @brief The connection that this event pertains to, or @ref BLE_CONN_HANDLE_INVALID. */
AnnaBridge 146:22da6e220af6 169 pm_peer_id_t peer_id; /**< @brief The bonded peer that this event pertains to, or @ref PM_PEER_ID_INVALID. */
AnnaBridge 146:22da6e220af6 170 union
AnnaBridge 146:22da6e220af6 171 {
AnnaBridge 146:22da6e220af6 172 pm_conn_secured_evt_t conn_sec_succeeded; /**< @brief Parameters specific to the @ref PM_EVT_CONN_SEC_SUCCEEDED event. */
AnnaBridge 146:22da6e220af6 173 pm_conn_secure_failed_evt_t conn_sec_failed; /**< @brief Parameters specific to the @ref PM_EVT_CONN_SEC_FAILED event. */
AnnaBridge 146:22da6e220af6 174 pm_peer_data_update_succeeded_evt_t peer_data_update_succeeded; /**< @brief Parameters specific to the @ref PM_EVT_PEER_DATA_UPDATE_SUCCEEDED event. */
AnnaBridge 146:22da6e220af6 175 pm_peer_data_update_failed_t peer_data_update_failed; /**< @brief Parameters specific to the @ref PM_EVT_PEER_DATA_UPDATE_FAILED event. */
AnnaBridge 146:22da6e220af6 176 pm_failure_evt_t peer_delete_failed; /**< @brief Parameters specific to the @ref PM_EVT_PEER_DELETE_FAILED event. */
AnnaBridge 146:22da6e220af6 177 pm_failure_evt_t peers_delete_failed_evt; /**< @brief Parameters specific to the @ref PM_EVT_PEERS_DELETE_FAILED event. */
AnnaBridge 146:22da6e220af6 178 pm_failure_evt_t error_unexpected; /**< @brief Parameters specific to the @ref PM_EVT_PEER_DELETE_FAILED event. */
AnnaBridge 146:22da6e220af6 179 } params;
AnnaBridge 146:22da6e220af6 180 } pm_evt_t;
AnnaBridge 146:22da6e220af6 181
AnnaBridge 146:22da6e220af6 182
AnnaBridge 146:22da6e220af6 183 /**@brief Event handler for events from the @ref peer_manager module.
AnnaBridge 146:22da6e220af6 184 *
AnnaBridge 146:22da6e220af6 185 * @sa pm_register
AnnaBridge 146:22da6e220af6 186 *
AnnaBridge 146:22da6e220af6 187 * @param[in] p_event The event that has occurred.
AnnaBridge 146:22da6e220af6 188 */
AnnaBridge 146:22da6e220af6 189 typedef void (*pm_evt_handler_t)(pm_evt_t const * p_event);
AnnaBridge 146:22da6e220af6 190
AnnaBridge 146:22da6e220af6 191
AnnaBridge 146:22da6e220af6 192 /**@brief Function for initializing the Peer Manager.
AnnaBridge 146:22da6e220af6 193 *
AnnaBridge 146:22da6e220af6 194 * @details You must initialize the Peer Manager before you can call any other Peer Manager
AnnaBridge 146:22da6e220af6 195 * functions.
AnnaBridge 146:22da6e220af6 196 *
AnnaBridge 146:22da6e220af6 197 * @retval NRF_SUCCESS If initialization was successful.
AnnaBridge 146:22da6e220af6 198 * @retval NRF_ERROR_INTERNAL If another error occurred.
AnnaBridge 146:22da6e220af6 199 */
AnnaBridge 146:22da6e220af6 200 ret_code_t pm_init(void);
AnnaBridge 146:22da6e220af6 201
AnnaBridge 146:22da6e220af6 202
AnnaBridge 146:22da6e220af6 203 /**@brief Function for registering an event handler with the Peer Manager.
AnnaBridge 146:22da6e220af6 204 *
AnnaBridge 146:22da6e220af6 205 * @param[in] event_handler Callback for events from the @ref peer_manager module. @p event_handler
AnnaBridge 146:22da6e220af6 206 * is called for every event that the Peer Manager sends after this
AnnaBridge 146:22da6e220af6 207 * function is called.
AnnaBridge 146:22da6e220af6 208 *
AnnaBridge 146:22da6e220af6 209 * @retval NRF_SUCCESS If initialization was successful.
AnnaBridge 146:22da6e220af6 210 * @retval NRF_ERROR_NULL If @p event_handler was NULL.
AnnaBridge 146:22da6e220af6 211 * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized.
AnnaBridge 146:22da6e220af6 212 */
AnnaBridge 146:22da6e220af6 213 ret_code_t pm_register(pm_evt_handler_t event_handler);
AnnaBridge 146:22da6e220af6 214
AnnaBridge 146:22da6e220af6 215
AnnaBridge 146:22da6e220af6 216 /**@brief Function for providing pairing and bonding parameters to use for pairing procedures.
AnnaBridge 146:22da6e220af6 217 *
AnnaBridge 146:22da6e220af6 218 * @details Until this function is called, all bonding procedures that are initiated by the
AnnaBridge 146:22da6e220af6 219 * peer are rejected.
AnnaBridge 146:22da6e220af6 220 *
AnnaBridge 146:22da6e220af6 221 * This function can be called multiple times with different parameters, even with NULL as
AnnaBridge 146:22da6e220af6 222 * @p p_sec_params, in which case the Peer Manager starts rejecting all procedures again.
AnnaBridge 146:22da6e220af6 223 *
AnnaBridge 146:22da6e220af6 224 * @param[in] p_sec_params Security parameters to be used for subsequent security procedures.
AnnaBridge 146:22da6e220af6 225 *
AnnaBridge 146:22da6e220af6 226 * @retval NRF_SUCCESS If the parameters were set successfully.
AnnaBridge 146:22da6e220af6 227 * @retval NRF_ERROR_INVALID_PARAM If the combination of parameters is invalid.
AnnaBridge 146:22da6e220af6 228 * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized.
AnnaBridge 146:22da6e220af6 229 * @retval NRF_ERROR_INTERNAL If another error occurred.
AnnaBridge 146:22da6e220af6 230 */
AnnaBridge 146:22da6e220af6 231 ret_code_t pm_sec_params_set(ble_gap_sec_params_t * p_sec_params);
AnnaBridge 146:22da6e220af6 232
AnnaBridge 146:22da6e220af6 233
AnnaBridge 146:22da6e220af6 234 /**@brief Function for passing BLE events to the Peer Manager.
AnnaBridge 146:22da6e220af6 235 *
AnnaBridge 146:22da6e220af6 236 * @details For the module to work as expected, this function must be called with each BLE event
AnnaBridge 146:22da6e220af6 237 * from the SoftDevice. It must be called after @ref ble_conn_state_on_ble_evt, but before
AnnaBridge 146:22da6e220af6 238 * the application processes the event.
AnnaBridge 146:22da6e220af6 239 *
AnnaBridge 146:22da6e220af6 240 * Calling this function before @ref pm_init is safe, but without effect.
AnnaBridge 146:22da6e220af6 241 *
AnnaBridge 146:22da6e220af6 242 * @param[in] p_ble_evt BLE stack event that is dispatched to the function.
AnnaBridge 146:22da6e220af6 243 */
AnnaBridge 146:22da6e220af6 244 void pm_on_ble_evt(ble_evt_t * p_ble_evt);
AnnaBridge 146:22da6e220af6 245
AnnaBridge 146:22da6e220af6 246
AnnaBridge 146:22da6e220af6 247 /**@brief Function for establishing encryption on a connection, and optionally establishing a bond.
AnnaBridge 146:22da6e220af6 248 *
AnnaBridge 146:22da6e220af6 249 * @details This function attempts to secure the link that is specified by @p conn_handle. It uses
AnnaBridge 146:22da6e220af6 250 * the parameters that were previously provided in a call to @ref pm_sec_params_set.
AnnaBridge 146:22da6e220af6 251 *
AnnaBridge 146:22da6e220af6 252 * If the connection is a master connection, calling this function starts a security
AnnaBridge 146:22da6e220af6 253 * procedure on the link. If we have keys from a previous bonding procedure with this peer
AnnaBridge 146:22da6e220af6 254 * and the keys meet the security requirements in the currently active sec_params, the
AnnaBridge 146:22da6e220af6 255 * function attempts to establish encryption with the existing keys. If no key exists, the
AnnaBridge 146:22da6e220af6 256 * function attempts to pair and bond according to the currently active sec_params.
AnnaBridge 146:22da6e220af6 257 *
AnnaBridge 146:22da6e220af6 258 * If the function completes successfully, a @ref PM_EVT_CONN_SEC_START event is sent.
AnnaBridge 146:22da6e220af6 259 * The procedure might be queued, in which case the @ref PM_EVT_CONN_SEC_START event is
AnnaBridge 146:22da6e220af6 260 * delayed until the procedure is initiated in the SoftDevice.
AnnaBridge 146:22da6e220af6 261 *
AnnaBridge 146:22da6e220af6 262 * If the connection is a slave connection, the function sends a security request to
AnnaBridge 146:22da6e220af6 263 * the peer (master). It is up to the peer then to initiate pairing or encryption.
AnnaBridge 146:22da6e220af6 264 * If the peer ignores the request, a @ref BLE_GAP_EVT_TIMEOUT event occurs
AnnaBridge 146:22da6e220af6 265 * with the source @ref BLE_GAP_TIMEOUT_SRC_SECURITY_REQUEST. Otherwise, the peer initiates
AnnaBridge 146:22da6e220af6 266 * security, in which case things happen as if the peer had initiated security itself.
AnnaBridge 146:22da6e220af6 267 * See @ref PM_EVT_CONN_SEC_START for information about peer-initiated security.
AnnaBridge 146:22da6e220af6 268 *
AnnaBridge 146:22da6e220af6 269 * @param[in] conn_handle Connection handle of the link as provided by the SoftDevice.
AnnaBridge 146:22da6e220af6 270 * @param[in] force_repairing Whether to force a pairing procedure even if there is an existing
AnnaBridge 146:22da6e220af6 271 * encryption key. This argument is relevant only for
AnnaBridge 146:22da6e220af6 272 * the central role. Recommended value: false.
AnnaBridge 146:22da6e220af6 273 *
AnnaBridge 146:22da6e220af6 274 * @retval NRF_SUCCESS If the operation completed successfully.
AnnaBridge 146:22da6e220af6 275 * @retval NRF_ERROR_TIMEOUT If there was an SMP time-out, so that no more SMP
AnnaBridge 146:22da6e220af6 276 * operations can be performed on this link.
AnnaBridge 146:22da6e220af6 277 * @retval BLE_ERROR_INVALID_CONN_HANDLE If the connection handle is invalid.
AnnaBridge 146:22da6e220af6 278 * @retval NRF_ERROR_NOT_FOUND If the security parameters have not been set.
AnnaBridge 146:22da6e220af6 279 * @retval NRF_ERROR_NO_MEM If there is no more space in flash.
AnnaBridge 146:22da6e220af6 280 * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized, or the peer is
AnnaBridge 146:22da6e220af6 281 * disconnected or in the process of disconnecting.
AnnaBridge 146:22da6e220af6 282 * @retval NRF_ERROR_INTERNAL If another error occurred.
AnnaBridge 146:22da6e220af6 283 */
AnnaBridge 146:22da6e220af6 284 ret_code_t pm_conn_secure(uint16_t conn_handle, bool force_repairing);
AnnaBridge 146:22da6e220af6 285
AnnaBridge 146:22da6e220af6 286
AnnaBridge 146:22da6e220af6 287 /**@brief Function for providing security configuration for a link.
AnnaBridge 146:22da6e220af6 288 *
AnnaBridge 146:22da6e220af6 289 * @details This function is optional, and must be called in reply to a @ref
AnnaBridge 146:22da6e220af6 290 * PM_EVT_CONN_SEC_CONFIG_REQ event, before the Peer Manager event handler returns. If it
AnnaBridge 146:22da6e220af6 291 * is not called in time, a default configuration is used. See @ref pm_conn_sec_config_t
AnnaBridge 146:22da6e220af6 292 * for the value of the default.
AnnaBridge 146:22da6e220af6 293 *
AnnaBridge 146:22da6e220af6 294 * @param[in] conn_handle The connection to set the configuration for.
AnnaBridge 146:22da6e220af6 295 * @param[in] p_conn_sec_config The configuration.
AnnaBridge 146:22da6e220af6 296 */
AnnaBridge 146:22da6e220af6 297 void pm_conn_sec_config_reply(uint16_t conn_handle, pm_conn_sec_config_t * p_conn_sec_config);
AnnaBridge 146:22da6e220af6 298
AnnaBridge 146:22da6e220af6 299
AnnaBridge 146:22da6e220af6 300 /**@brief Function for manually informing that the local database has changed.
AnnaBridge 146:22da6e220af6 301 *
AnnaBridge 146:22da6e220af6 302 * @details This function sends a service changed indication to all bonded and/or connected peers
AnnaBridge 146:22da6e220af6 303 * that subscribe to this indication. If a bonded peer is not connected, the indication is
AnnaBridge 146:22da6e220af6 304 * sent when it reconnects. Every time an indication is sent, a @ref
AnnaBridge 146:22da6e220af6 305 * PM_EVT_SERVICE_CHANGED_IND_SENT event occurs, followed by a @ref
AnnaBridge 146:22da6e220af6 306 * PM_EVT_SERVICE_CHANGED_IND_CONFIRMED when the peer sends its confirmation. Peers that
AnnaBridge 146:22da6e220af6 307 * are not subscribed to the service changed indication when this function is called do not
AnnaBridge 146:22da6e220af6 308 * receive an indication, and no events are sent to the user. Likewise, if the service
AnnaBridge 146:22da6e220af6 309 * changed characteristic is not present in the local database, this no indications are
AnnaBridge 146:22da6e220af6 310 * sent peers, and no events are sent to the user.
AnnaBridge 146:22da6e220af6 311 */
AnnaBridge 146:22da6e220af6 312 void pm_local_database_has_changed(void);
AnnaBridge 146:22da6e220af6 313
AnnaBridge 146:22da6e220af6 314
AnnaBridge 146:22da6e220af6 315 /**@brief Function for getting the security status of a connection.
AnnaBridge 146:22da6e220af6 316 *
AnnaBridge 146:22da6e220af6 317 * @param[in] conn_handle Connection handle of the link as provided by the SoftDevice.
AnnaBridge 146:22da6e220af6 318 * @param[out] p_conn_sec_status Security status of the link.
AnnaBridge 146:22da6e220af6 319 *
AnnaBridge 146:22da6e220af6 320 * @retval NRF_SUCCESS If pairing was initiated successfully.
AnnaBridge 146:22da6e220af6 321 * @retval BLE_ERROR_INVALID_CONN_HANDLE If the connection handle is invalid.
AnnaBridge 146:22da6e220af6 322 * @retval NRF_ERROR_NULL If @p p_conn_sec_status was NULL.
AnnaBridge 146:22da6e220af6 323 * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized.
AnnaBridge 146:22da6e220af6 324 */
AnnaBridge 146:22da6e220af6 325 ret_code_t pm_conn_sec_status_get(uint16_t conn_handle, pm_conn_sec_status_t * p_conn_sec_status);
AnnaBridge 146:22da6e220af6 326
AnnaBridge 146:22da6e220af6 327
AnnaBridge 146:22da6e220af6 328 /**@brief Experimental function for specifying the public key to use for LESC operations.
AnnaBridge 146:22da6e220af6 329 *
AnnaBridge 146:22da6e220af6 330 * @details This function can be called multiple times. The specified public key will be used for
AnnaBridge 146:22da6e220af6 331 * all subsequent LESC (LE Secure Connections) operations until the next time this function
AnnaBridge 146:22da6e220af6 332 * is called.
AnnaBridge 146:22da6e220af6 333 *
AnnaBridge 146:22da6e220af6 334 * @note The key must continue to reside in application memory as it is not copied by Peer Manager.
AnnaBridge 146:22da6e220af6 335 *
AnnaBridge 146:22da6e220af6 336 * @param[in] p_public_key The public key to use for all subsequent LESC operations.
AnnaBridge 146:22da6e220af6 337 *
AnnaBridge 146:22da6e220af6 338 * @retval NRF_SUCCESS Pairing initiated successfully.
AnnaBridge 146:22da6e220af6 339 * @retval NRF_ERROR_INVALID_STATE Peer Manager is not initialized.
AnnaBridge 146:22da6e220af6 340 */
AnnaBridge 146:22da6e220af6 341 ret_code_t pm_lesc_public_key_set(ble_gap_lesc_p256_pk_t * p_public_key);
AnnaBridge 146:22da6e220af6 342
AnnaBridge 146:22da6e220af6 343
AnnaBridge 146:22da6e220af6 344 /**
AnnaBridge 146:22da6e220af6 345 * @brief Function for constructing a whitelist for use when advertising.
AnnaBridge 146:22da6e220af6 346 *
AnnaBridge 146:22da6e220af6 347 * @details This function constructs a whitelist that contains the addresses and IRKs of the
AnnaBridge 146:22da6e220af6 348 * provided peer IDs. If @p p_peer_ids is NULL, the first (lowest) 8 peer IDs are chosen.
AnnaBridge 146:22da6e220af6 349 * If @ref ble_gap_whitelist_t.pp_addrs in @p p_whitelist is NULL, the whitelist contains
AnnaBridge 146:22da6e220af6 350 * only IRKs, and vice versa.
AnnaBridge 146:22da6e220af6 351 *
AnnaBridge 146:22da6e220af6 352 * @note When using a whitelist, always use the whitelist that was created or set by the most recent
AnnaBridge 146:22da6e220af6 353 * call to this function or to @ref pm_whitelist_custom.
AnnaBridge 146:22da6e220af6 354 * @note Do not call this function while advertising or scanning with another whitelist.
AnnaBridge 146:22da6e220af6 355 *
AnnaBridge 146:22da6e220af6 356 * @param[in] p_peer_ids The IDs of the peers to be added to the whitelist, or NULL.
AnnaBridge 146:22da6e220af6 357 * @param[in] n_peer_ids The number of peer IDs in @p p_peer_ids.
AnnaBridge 146:22da6e220af6 358 * @param[in,out] p_whitelist The constructed whitelist. Note that @p p_whitelist->pp_addrs
AnnaBridge 146:22da6e220af6 359 * must be NULL or point to an array with size @ref
AnnaBridge 146:22da6e220af6 360 * BLE_GAP_WHITELIST_ADDR_MAX_COUNT and @p p_whitelist->pp_irks
AnnaBridge 146:22da6e220af6 361 * must be NULL or point to an array with size @ref
AnnaBridge 146:22da6e220af6 362 * BLE_GAP_WHITELIST_IRK_MAX_COUNT.
AnnaBridge 146:22da6e220af6 363 *
AnnaBridge 146:22da6e220af6 364 * @retval NRF_SUCCESS If the whitelist was created successfully.
AnnaBridge 146:22da6e220af6 365 * @retval NRF_ERROR_NULL If @p p_whitelist was NULL.
AnnaBridge 146:22da6e220af6 366 * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized.
AnnaBridge 146:22da6e220af6 367 */
AnnaBridge 146:22da6e220af6 368 ret_code_t pm_whitelist_create(pm_peer_id_t * p_peer_ids,
AnnaBridge 146:22da6e220af6 369 uint8_t n_peer_ids,
AnnaBridge 146:22da6e220af6 370 ble_gap_whitelist_t * p_whitelist);
AnnaBridge 146:22da6e220af6 371
AnnaBridge 146:22da6e220af6 372
AnnaBridge 146:22da6e220af6 373 /**
AnnaBridge 146:22da6e220af6 374 * @brief Function for informing the Peer Manager of what whitelist should be used.
AnnaBridge 146:22da6e220af6 375 *
AnnaBridge 146:22da6e220af6 376 * @details This function should be used if the application wants to use a whitelist that is
AnnaBridge 146:22da6e220af6 377 * created in the application. When using Peer Manager, this function must be called to
AnnaBridge 146:22da6e220af6 378 * inform that the custom whitelist should be used instead of the one in Peer Manager.
AnnaBridge 146:22da6e220af6 379 *
AnnaBridge 146:22da6e220af6 380 * @note When using a whitelist, always use the whitelist that was created or set by the most recent
AnnaBridge 146:22da6e220af6 381 * call to this function or to @ref pm_whitelist_create.
AnnaBridge 146:22da6e220af6 382 * @note Do not call this function while advertising or scanning with another whitelist.
AnnaBridge 146:22da6e220af6 383 * @note Do not add any IRKs to the whitelist that are not present in the Peer Manager's persistent
AnnaBridge 146:22da6e220af6 384 * storage.
AnnaBridge 146:22da6e220af6 385 *
AnnaBridge 146:22da6e220af6 386 * @param[in] p_whitelist The whitelist.
AnnaBridge 146:22da6e220af6 387 *
AnnaBridge 146:22da6e220af6 388 * @retval NRF_SUCCESS If the operation completed successfully.
AnnaBridge 146:22da6e220af6 389 * @retval NRF_ERROR_NULL If @p p_whitelist was NULL.
AnnaBridge 146:22da6e220af6 390 * @retval NRF_ERROR_NOT_FOUND If one or more of the whitelist's IRKs was not found in the Peer
AnnaBridge 146:22da6e220af6 391 * Manager's persistent storage.
AnnaBridge 146:22da6e220af6 392 * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized.
AnnaBridge 146:22da6e220af6 393 */
AnnaBridge 146:22da6e220af6 394 ret_code_t pm_whitelist_custom(ble_gap_whitelist_t * p_whitelist);
AnnaBridge 146:22da6e220af6 395
AnnaBridge 146:22da6e220af6 396
AnnaBridge 146:22da6e220af6 397 /**
AnnaBridge 146:22da6e220af6 398 * @brief Function for getting the connection handle of the connection with a bonded peer.
AnnaBridge 146:22da6e220af6 399 *
AnnaBridge 146:22da6e220af6 400 * @param[in] peer_id The peer ID of the bonded peer.
AnnaBridge 146:22da6e220af6 401 * @param[out] p_conn_handle Connection handle, or @ref BLE_ERROR_INVALID_CONN_HANDLE if the peer
AnnaBridge 146:22da6e220af6 402 * is not connected.
AnnaBridge 146:22da6e220af6 403 *
AnnaBridge 146:22da6e220af6 404 * @retval NRF_SUCCESS If the connection handle was determined successfully.
AnnaBridge 146:22da6e220af6 405 * @retval NRF_ERROR_NULL If @p p_conn_handle was NULL.
AnnaBridge 146:22da6e220af6 406 * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized.
AnnaBridge 146:22da6e220af6 407 */
AnnaBridge 146:22da6e220af6 408 ret_code_t pm_conn_handle_get(pm_peer_id_t peer_id, uint16_t * p_conn_handle);
AnnaBridge 146:22da6e220af6 409
AnnaBridge 146:22da6e220af6 410
AnnaBridge 146:22da6e220af6 411 /**@brief Function for getting the peer ID of a connected peer.
AnnaBridge 146:22da6e220af6 412 *
AnnaBridge 146:22da6e220af6 413 * @param[in] conn_handle Connection handle.
AnnaBridge 146:22da6e220af6 414 * @param[out] p_peer_id Peer ID, or @ref PM_PEER_ID_INVALID if the peer is not bonded or
AnnaBridge 146:22da6e220af6 415 * @p conn_handle does not refer to a connection.
AnnaBridge 146:22da6e220af6 416 *
AnnaBridge 146:22da6e220af6 417 * @retval NRF_SUCCESS If the peer ID was retrieved successfully.
AnnaBridge 146:22da6e220af6 418 * @retval NRF_ERROR_NULL If @p p_peer_id was NULL.
AnnaBridge 146:22da6e220af6 419 * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized.
AnnaBridge 146:22da6e220af6 420 */
AnnaBridge 146:22da6e220af6 421 ret_code_t pm_peer_id_get(uint16_t conn_handle, pm_peer_id_t * p_peer_id);
AnnaBridge 146:22da6e220af6 422
AnnaBridge 146:22da6e220af6 423
AnnaBridge 146:22da6e220af6 424 /**@brief Function for getting the next peer ID in the sequence of all used peer IDs.
AnnaBridge 146:22da6e220af6 425 *
AnnaBridge 146:22da6e220af6 426 * @details This function can be used to loop through all used peer IDs. The order in which
AnnaBridge 146:22da6e220af6 427 * peer IDs are returned should be considered unpredictable. @ref PM_PEER_ID_INVALID
AnnaBridge 146:22da6e220af6 428 * is considered to be before the first and after the last used peer ID.
AnnaBridge 146:22da6e220af6 429 *
AnnaBridge 146:22da6e220af6 430 * @details To loop through all peer IDs exactly once, use the following constuct:
AnnaBridge 146:22da6e220af6 431 * @code{c}
AnnaBridge 146:22da6e220af6 432 * pm_peer_id_t current_peer_id = pm_next_peer_id_get(PM_PEER_ID_INVALID);
AnnaBridge 146:22da6e220af6 433 * while (current_peer_id != PM_PEER_ID_INVALID)
AnnaBridge 146:22da6e220af6 434 * {
AnnaBridge 146:22da6e220af6 435 * // Do something with current_peer_id.
AnnaBridge 146:22da6e220af6 436 * current_peer_id = pm_next_peer_id_get(current_peer_id)
AnnaBridge 146:22da6e220af6 437 * }
AnnaBridge 146:22da6e220af6 438 * @endcode
AnnaBridge 146:22da6e220af6 439 *
AnnaBridge 146:22da6e220af6 440 * @param[in] prev_peer_id The previous peer ID.
AnnaBridge 146:22da6e220af6 441 *
AnnaBridge 146:22da6e220af6 442 * @return The next peer ID. If @p prev_peer_id was @ref PM_PEER_ID_INVALID, the
AnnaBridge 146:22da6e220af6 443 * next peer ID is the first used peer ID. If @p prev_peer_id was the last
AnnaBridge 146:22da6e220af6 444 * used peer ID, the function returns @ref PM_PEER_ID_INVALID.
AnnaBridge 146:22da6e220af6 445 */
AnnaBridge 146:22da6e220af6 446 pm_peer_id_t pm_next_peer_id_get(pm_peer_id_t prev_peer_id);
AnnaBridge 146:22da6e220af6 447
AnnaBridge 146:22da6e220af6 448
AnnaBridge 146:22da6e220af6 449 /**@brief Function for querying the number of valid peer IDs that are available.
AnnaBridge 146:22da6e220af6 450 *
AnnaBridge 146:22da6e220af6 451 * @details This function returns the number of peers for which there is data in persistent storage.
AnnaBridge 146:22da6e220af6 452 *
AnnaBridge 146:22da6e220af6 453 * @return The number of valid peer IDs.
AnnaBridge 146:22da6e220af6 454 */
AnnaBridge 146:22da6e220af6 455 uint32_t pm_peer_count(void);
AnnaBridge 146:22da6e220af6 456
AnnaBridge 146:22da6e220af6 457
AnnaBridge 146:22da6e220af6 458
AnnaBridge 146:22da6e220af6 459
AnnaBridge 146:22da6e220af6 460 /**@anchor PM_PEER_DATA_FUNCTIONS
AnnaBridge 146:22da6e220af6 461 * @name Functions (Peer Data)
AnnaBridge 146:22da6e220af6 462 * Functions for manipulating peer data.
AnnaBridge 146:22da6e220af6 463 * @{
AnnaBridge 146:22da6e220af6 464 */
AnnaBridge 146:22da6e220af6 465
AnnaBridge 146:22da6e220af6 466 /**
AnnaBridge 146:22da6e220af6 467 * @{
AnnaBridge 146:22da6e220af6 468 */
AnnaBridge 146:22da6e220af6 469
AnnaBridge 146:22da6e220af6 470 /**@brief Function for retrieving stored data of a peer.
AnnaBridge 146:22da6e220af6 471 *
AnnaBridge 146:22da6e220af6 472 * @note The length of the provided buffer must be a multiple of 4.
AnnaBridge 146:22da6e220af6 473 *
AnnaBridge 146:22da6e220af6 474 * @param[in] peer_id Peer ID to get data for.
AnnaBridge 146:22da6e220af6 475 * @param[in] data_id Which type of data to read.
AnnaBridge 146:22da6e220af6 476 * @param[out] p_data Where to put the retrieved data.
AnnaBridge 146:22da6e220af6 477 * @param[inout] p_len In: The length in bytes of @p p_data.
AnnaBridge 146:22da6e220af6 478 * Out: The length in bytes of the read data, if the read was successful.
AnnaBridge 146:22da6e220af6 479 *
AnnaBridge 146:22da6e220af6 480 * @retval NRF_SUCCESS If the data was read successfully.
AnnaBridge 146:22da6e220af6 481 * @retval NRF_ERROR_INVALID_PARAM If the the data type or the peer ID was invalid or unallocated,
AnnaBridge 146:22da6e220af6 482 * or if the length in @p p_length was not a multiple of 4.
AnnaBridge 146:22da6e220af6 483 * @retval NRF_ERROR_NULL If a pointer parameter was NULL.
AnnaBridge 146:22da6e220af6 484 * @retval NRF_ERROR_NOT_FOUND If no stored data was found for this peer ID/data ID combination.
AnnaBridge 146:22da6e220af6 485 * @retval NRF_ERROR_DATA_SIZE If the provided buffer was not large enough.
AnnaBridge 146:22da6e220af6 486 * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized.
AnnaBridge 146:22da6e220af6 487 */
AnnaBridge 146:22da6e220af6 488 ret_code_t pm_peer_data_load(pm_peer_id_t peer_id,
AnnaBridge 146:22da6e220af6 489 pm_peer_data_id_t data_id,
AnnaBridge 146:22da6e220af6 490 void * p_data,
AnnaBridge 146:22da6e220af6 491 uint16_t * p_len);
AnnaBridge 146:22da6e220af6 492
AnnaBridge 146:22da6e220af6 493 /**@brief Function for reading a peer's bonding data (@ref PM_PEER_DATA_ID_BONDING).
AnnaBridge 146:22da6e220af6 494 * @details See @ref pm_peer_data_load for parameters and return values. */
AnnaBridge 146:22da6e220af6 495 ret_code_t pm_peer_data_bonding_load(pm_peer_id_t peer_id,
AnnaBridge 146:22da6e220af6 496 pm_peer_data_bonding_t * p_data);
AnnaBridge 146:22da6e220af6 497
AnnaBridge 146:22da6e220af6 498 /**@brief Function for reading a peer's remote DB values. (@ref PM_PEER_DATA_ID_GATT_REMOTE).
AnnaBridge 146:22da6e220af6 499 * @details See @ref pm_peer_data_load for parameters and return values. */
AnnaBridge 146:22da6e220af6 500 ret_code_t pm_peer_data_remote_db_load(pm_peer_id_t peer_id,
AnnaBridge 146:22da6e220af6 501 ble_gatt_db_srv_t * p_data,
AnnaBridge 146:22da6e220af6 502 uint16_t * p_len);
AnnaBridge 146:22da6e220af6 503
AnnaBridge 146:22da6e220af6 504 /**@brief Function for reading a peer's application data. (@ref PM_PEER_DATA_ID_APPLICATION).
AnnaBridge 146:22da6e220af6 505 * @details See @ref pm_peer_data_load for parameters and return values. */
AnnaBridge 146:22da6e220af6 506 ret_code_t pm_peer_data_app_data_load(pm_peer_id_t peer_id,
AnnaBridge 146:22da6e220af6 507 uint8_t * p_data,
AnnaBridge 146:22da6e220af6 508 uint16_t * p_len);
AnnaBridge 146:22da6e220af6 509 /** @}*/
AnnaBridge 146:22da6e220af6 510
AnnaBridge 146:22da6e220af6 511
AnnaBridge 146:22da6e220af6 512 /**
AnnaBridge 146:22da6e220af6 513 * @{
AnnaBridge 146:22da6e220af6 514 */
AnnaBridge 146:22da6e220af6 515
AnnaBridge 146:22da6e220af6 516 /**@brief Function for setting or updating stored data of a peer.
AnnaBridge 146:22da6e220af6 517 *
AnnaBridge 146:22da6e220af6 518 * @note Writing the data to persistent storage happens asynchronously. Therefore, the buffer
AnnaBridge 146:22da6e220af6 519 * that contains the data must be kept alive until the operation has completed.
AnnaBridge 146:22da6e220af6 520 *
AnnaBridge 146:22da6e220af6 521 * @note The data written using this function may later be overwritten as a result of internal
AnnaBridge 146:22da6e220af6 522 * operations in the Peer Manager. A Peer Manager event is sent each time data is updated,
AnnaBridge 146:22da6e220af6 523 * regardless of whether the operation originated internally or from action by the user.
AnnaBridge 146:22da6e220af6 524 *
AnnaBridge 146:22da6e220af6 525 * @param[in] peer_id Peer ID to set data for.
AnnaBridge 146:22da6e220af6 526 * @param[in] data_id Which type of data to set.
AnnaBridge 146:22da6e220af6 527 * @param[in] p_data New value to set.
AnnaBridge 146:22da6e220af6 528 * @param[in] len The length in bytes of @p p_data.
AnnaBridge 146:22da6e220af6 529 * @param[out] p_token A token that identifies this particular store operation. The token can be
AnnaBridge 146:22da6e220af6 530 * used to identify events that pertain to this operation. This parameter can
AnnaBridge 146:22da6e220af6 531 * be NULL.
AnnaBridge 146:22da6e220af6 532 *
AnnaBridge 146:22da6e220af6 533 * @retval NRF_SUCCESS If the data is scheduled to be written to persistent storage.
AnnaBridge 146:22da6e220af6 534 * @retval NRF_ERROR_NULL If @p p_data is NULL.
AnnaBridge 146:22da6e220af6 535 * @retval NRF_ERROR_NOT_FOUND If no peer was found for the peer ID.
AnnaBridge 146:22da6e220af6 536 * @retval NRF_ERROR_BUSY If the underlying flash handler is busy with other flash
AnnaBridge 146:22da6e220af6 537 * operations. Try again after receiving a Peer Manager event.
AnnaBridge 146:22da6e220af6 538 * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized.
AnnaBridge 146:22da6e220af6 539 */
AnnaBridge 146:22da6e220af6 540 ret_code_t pm_peer_data_store(pm_peer_id_t peer_id,
AnnaBridge 146:22da6e220af6 541 pm_peer_data_id_t data_id,
AnnaBridge 146:22da6e220af6 542 void const * p_data,
AnnaBridge 146:22da6e220af6 543 uint16_t len,
AnnaBridge 146:22da6e220af6 544 pm_store_token_t * p_token);
AnnaBridge 146:22da6e220af6 545
AnnaBridge 146:22da6e220af6 546 /**@brief Function for setting or updating a peer's bonding data (@ref PM_PEER_DATA_ID_BONDING).
AnnaBridge 146:22da6e220af6 547 * @details See @ref pm_peer_data_store for parameters and return values. */
AnnaBridge 146:22da6e220af6 548 ret_code_t pm_peer_data_bonding_store(pm_peer_id_t peer_id,
AnnaBridge 146:22da6e220af6 549 pm_peer_data_bonding_t const * p_data,
AnnaBridge 146:22da6e220af6 550 pm_store_token_t * p_token);
AnnaBridge 146:22da6e220af6 551
AnnaBridge 146:22da6e220af6 552 /**@brief Function for setting or updating a peer's remote DB values. (@ref PM_PEER_DATA_ID_GATT_REMOTE).
AnnaBridge 146:22da6e220af6 553 * @details See @ref pm_peer_data_store for parameters and return values. */
AnnaBridge 146:22da6e220af6 554 ret_code_t pm_peer_data_remote_db_store(pm_peer_id_t peer_id,
AnnaBridge 146:22da6e220af6 555 ble_gatt_db_srv_t const * p_data,
AnnaBridge 146:22da6e220af6 556 uint16_t len,
AnnaBridge 146:22da6e220af6 557 pm_store_token_t * p_token);
AnnaBridge 146:22da6e220af6 558
AnnaBridge 146:22da6e220af6 559 /**@brief Function for setting or updating a peer's application data. (@ref PM_PEER_DATA_ID_APPLICATION).
AnnaBridge 146:22da6e220af6 560 * @details See @ref pm_peer_data_store for parameters and return values. */
AnnaBridge 146:22da6e220af6 561 ret_code_t pm_peer_data_app_data_store(pm_peer_id_t peer_id,
AnnaBridge 146:22da6e220af6 562 uint8_t const * p_data,
AnnaBridge 146:22da6e220af6 563 uint16_t len,
AnnaBridge 146:22da6e220af6 564 pm_store_token_t * p_token);
AnnaBridge 146:22da6e220af6 565 /** @}*/
AnnaBridge 146:22da6e220af6 566
AnnaBridge 146:22da6e220af6 567
AnnaBridge 146:22da6e220af6 568 /**
AnnaBridge 146:22da6e220af6 569 * @{
AnnaBridge 146:22da6e220af6 570 */
AnnaBridge 146:22da6e220af6 571
AnnaBridge 146:22da6e220af6 572 /**@brief Function for deleting a peer's stored pieces of data.
AnnaBridge 146:22da6e220af6 573 *
AnnaBridge 146:22da6e220af6 574 * @details This function deletes specific data that is stored for a peer. Note that bonding data
AnnaBridge 146:22da6e220af6 575 * cannot be cleared separately.
AnnaBridge 146:22da6e220af6 576 *
AnnaBridge 146:22da6e220af6 577 * To delete all data for a peer (including bonding data), use @ref pm_peer_delete.
AnnaBridge 146:22da6e220af6 578 *
AnnaBridge 146:22da6e220af6 579 * @note Clearing data in persistent storage happens asynchronously.
AnnaBridge 146:22da6e220af6 580 *
AnnaBridge 146:22da6e220af6 581 * @param[in] peer_id Peer ID to clear data for.
AnnaBridge 146:22da6e220af6 582 * @param[in] data_id Which data to clear.
AnnaBridge 146:22da6e220af6 583 *
AnnaBridge 146:22da6e220af6 584 * @retval NRF_SUCCESS If the clear procedure was initiated successfully.
AnnaBridge 146:22da6e220af6 585 * @retval NRF_ERROR_INVALID_PARAM If @p data_id was PM_PEER_DATA_ID_BONDING or invalid, or
AnnaBridge 146:22da6e220af6 586 * @p peer_id was invalid.
AnnaBridge 146:22da6e220af6 587 * @retval NRF_ERROR_NOT_FOUND If there was no data to clear for this peer ID/data ID combination.
AnnaBridge 146:22da6e220af6 588 * @retval NRF_ERROR_BUSY If the underlying flash handler is busy with other flash
AnnaBridge 146:22da6e220af6 589 * operations. Try again after receiving a Peer Manager event.
AnnaBridge 146:22da6e220af6 590 * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized.
AnnaBridge 146:22da6e220af6 591 * @retval NRF_ERROR_INTERNAL If another error occurred.
AnnaBridge 146:22da6e220af6 592 */
AnnaBridge 146:22da6e220af6 593 ret_code_t pm_peer_data_delete(pm_peer_id_t peer_id, pm_peer_data_id_t data_id);
AnnaBridge 146:22da6e220af6 594
AnnaBridge 146:22da6e220af6 595
AnnaBridge 146:22da6e220af6 596 /**@brief Function for manually adding a peer to the persistent storage.
AnnaBridge 146:22da6e220af6 597 *
AnnaBridge 146:22da6e220af6 598 * @details This function allocates a new peer ID and stores bonding data for the new peer. The
AnnaBridge 146:22da6e220af6 599 * bonding data is necessary to prevent ambiguity/inconsistency in peer data.
AnnaBridge 146:22da6e220af6 600 *
AnnaBridge 146:22da6e220af6 601 * @param[in] p_bonding_data The bonding data of the new peer (must contain a public/static
AnnaBridge 146:22da6e220af6 602 * address or a non-zero IRK).
AnnaBridge 146:22da6e220af6 603 * @param[out] p_new_peer_id Peer ID for the new peer, or an existing peer if a match was found.
AnnaBridge 146:22da6e220af6 604 * @param[out] p_token A token that identifies this particular store operation (storing the
AnnaBridge 146:22da6e220af6 605 * bonding data). The token can be used to identify events that pertain
AnnaBridge 146:22da6e220af6 606 * to this operation. This parameter can be NULL.
AnnaBridge 146:22da6e220af6 607 *
AnnaBridge 146:22da6e220af6 608 * @retval NRF_SUCCESS If the store operation for bonding data was initiated successfully.
AnnaBridge 146:22da6e220af6 609 * @retval NRF_ERROR_NULL If @p p_bonding_data or @p p_new_peer_id is NULL.
AnnaBridge 146:22da6e220af6 610 * @retval NRF_ERROR_NO_MEM If there is no more space in persistent storage, so that the new
AnnaBridge 146:22da6e220af6 611 * peer cannot be allocated.
AnnaBridge 146:22da6e220af6 612 * @retval NRF_ERROR_BUSY If the underlying flash handler is busy with other flash
AnnaBridge 146:22da6e220af6 613 * operations. Try again after receiving a Peer Manager event.
AnnaBridge 146:22da6e220af6 614 * @retval NRF_ERROR_INVALID_PARAM If the bonding data is invalid.
AnnaBridge 146:22da6e220af6 615 * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized.
AnnaBridge 146:22da6e220af6 616 */
AnnaBridge 146:22da6e220af6 617 ret_code_t pm_peer_new(pm_peer_id_t * p_new_peer_id,
AnnaBridge 146:22da6e220af6 618 pm_peer_data_bonding_t * p_bonding_data,
AnnaBridge 146:22da6e220af6 619 pm_store_token_t * p_token);
AnnaBridge 146:22da6e220af6 620
AnnaBridge 146:22da6e220af6 621
AnnaBridge 146:22da6e220af6 622 /**@brief Function for freeing persistent storage for a peer.
AnnaBridge 146:22da6e220af6 623 *
AnnaBridge 146:22da6e220af6 624 * @details This function deletes every piece of data that is associated with the specified peer and
AnnaBridge 146:22da6e220af6 625 * frees the peer ID to be used for another peer. The deletion happens asynchronously, and
AnnaBridge 146:22da6e220af6 626 * the peer ID is not freed until the data is deleted. When the operation finishes, a @ref
AnnaBridge 146:22da6e220af6 627 * PM_EVT_PEER_DELETE_SUCCEEDED or @ref PM_EVT_PEER_DELETE_FAILED event is sent.
AnnaBridge 146:22da6e220af6 628 *
AnnaBridge 146:22da6e220af6 629 * @warning Use this function only when not connected to or connectable for the peer that is being
AnnaBridge 146:22da6e220af6 630 * deleted. If the peer is or becomes connected or data is manually written in flash during
AnnaBridge 146:22da6e220af6 631 * this procedure (until the success or failure event happens), the behavior is undefined.
AnnaBridge 146:22da6e220af6 632 *
AnnaBridge 146:22da6e220af6 633 * @param[in] peer_id Peer ID to be freed and have all associated data deleted.
AnnaBridge 146:22da6e220af6 634 *
AnnaBridge 146:22da6e220af6 635 * @retval NRF_SUCCESS If the operation was initiated successfully.
AnnaBridge 146:22da6e220af6 636 * @retval NRF_ERROR_INVALID_PARAM If the peer ID was not valid.
AnnaBridge 146:22da6e220af6 637 * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized.
AnnaBridge 146:22da6e220af6 638 */
AnnaBridge 146:22da6e220af6 639 ret_code_t pm_peer_delete(pm_peer_id_t peer_id);
AnnaBridge 146:22da6e220af6 640
AnnaBridge 146:22da6e220af6 641
AnnaBridge 146:22da6e220af6 642 /**@brief Function for deleting all data stored for all peers.
AnnaBridge 146:22da6e220af6 643 *
AnnaBridge 146:22da6e220af6 644 * @details This function sends either a @ref PM_EVT_PEERS_DELETE_SUCCEEDED or a @ref
AnnaBridge 146:22da6e220af6 645 * PM_EVT_PEERS_DELETE_FAILED event. In addition, a @ref PM_EVT_PEER_DELETE_SUCCEEDED or
AnnaBridge 146:22da6e220af6 646 * @ref PM_EVT_PEER_DELETE_FAILED event is sent for each deleted peer.
AnnaBridge 146:22da6e220af6 647 *
AnnaBridge 146:22da6e220af6 648 * @note No event is sent when there is no peer data in flash.
AnnaBridge 146:22da6e220af6 649 *
AnnaBridge 146:22da6e220af6 650 * @warning Use this function only when not connected or connectable. If a peer is or becomes
AnnaBridge 146:22da6e220af6 651 * connected or a @ref PM_PEER_DATA_FUNCTIONS function is used during this procedure (until
AnnaBridge 146:22da6e220af6 652 * the success or failure event happens), the behavior is undefined.
AnnaBridge 146:22da6e220af6 653 *
AnnaBridge 146:22da6e220af6 654 * @retval NRF_SUCCESS If the deletion process was initiated successfully.
AnnaBridge 146:22da6e220af6 655 * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized.
AnnaBridge 146:22da6e220af6 656 * @retval NRF_ERROR_INTERNAL If another error occurred.
AnnaBridge 146:22da6e220af6 657 */
AnnaBridge 146:22da6e220af6 658 ret_code_t pm_peers_delete(void);
AnnaBridge 146:22da6e220af6 659 /** @}*/
AnnaBridge 146:22da6e220af6 660
AnnaBridge 146:22da6e220af6 661
AnnaBridge 146:22da6e220af6 662 /**
AnnaBridge 146:22da6e220af6 663 * @{
AnnaBridge 146:22da6e220af6 664 */
AnnaBridge 146:22da6e220af6 665
AnnaBridge 146:22da6e220af6 666
AnnaBridge 146:22da6e220af6 667 /**@brief Function for finding the highest and lowest ranked peers.
AnnaBridge 146:22da6e220af6 668 *
AnnaBridge 146:22da6e220af6 669 * @details The rank is saved in persistent storage under the data ID @ref PM_PEER_DATA_ID_PEER_RANK.
AnnaBridge 146:22da6e220af6 670 *
AnnaBridge 146:22da6e220af6 671 * @details The interpretation of rank is up to the user, because the rank is only updated by
AnnaBridge 146:22da6e220af6 672 * calling @ref pm_peer_rank_highest or by manipulating the value using a @ref
AnnaBridge 146:22da6e220af6 673 * PM_PEER_DATA_FUNCTIONS function.
AnnaBridge 146:22da6e220af6 674 *
AnnaBridge 146:22da6e220af6 675 * @note Any argument that is NULL is ignored.
AnnaBridge 146:22da6e220af6 676 *
AnnaBridge 146:22da6e220af6 677 * @param[out] p_highest_ranked_peer The peer ID with the highest rank of all peers, for example,
AnnaBridge 146:22da6e220af6 678 * the most recently used peer.
AnnaBridge 146:22da6e220af6 679 * @param[out] p_highest_rank The highest rank.
AnnaBridge 146:22da6e220af6 680 * @param[out] p_lowest_ranked_peer The peer ID with the lowest rank of all peers, for example,
AnnaBridge 146:22da6e220af6 681 * the least recently used peer.
AnnaBridge 146:22da6e220af6 682 * @param[out] p_lowest_rank The lowest rank.
AnnaBridge 146:22da6e220af6 683 *
AnnaBridge 146:22da6e220af6 684 * @retval NRF_SUCCESS If the operation completed successfully.
AnnaBridge 146:22da6e220af6 685 * @retval NRF_ERROR_NOT_FOUND If no peers were found.
AnnaBridge 146:22da6e220af6 686 * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized.
AnnaBridge 146:22da6e220af6 687 * @retval NRF_ERROR_INTERNAL If another error occurred.
AnnaBridge 146:22da6e220af6 688 */
AnnaBridge 146:22da6e220af6 689 ret_code_t pm_peer_ranks_get(pm_peer_id_t * p_highest_ranked_peer,
AnnaBridge 146:22da6e220af6 690 uint32_t * p_highest_rank,
AnnaBridge 146:22da6e220af6 691 pm_peer_id_t * p_lowest_ranked_peer,
AnnaBridge 146:22da6e220af6 692 uint32_t * p_lowest_rank);
AnnaBridge 146:22da6e220af6 693
AnnaBridge 146:22da6e220af6 694
AnnaBridge 146:22da6e220af6 695 /**@brief Function for updating the rank of a peer to be highest among all stored peers.
AnnaBridge 146:22da6e220af6 696 *
AnnaBridge 146:22da6e220af6 697 * @details If this function returns @ref NRF_SUCCESS, either a @ref PM_EVT_PEER_DATA_UPDATE_SUCCEEDED or a
AnnaBridge 146:22da6e220af6 698 * @ref PM_EVT_PEER_DATA_UPDATE_FAILED event is sent with a @ref
AnnaBridge 146:22da6e220af6 699 * PM_STORE_TOKEN_INVALID store token when the operation is complete. Until the operation
AnnaBridge 146:22da6e220af6 700 * is complete, this function returns @ref NRF_ERROR_BUSY.
AnnaBridge 146:22da6e220af6 701 *
AnnaBridge 146:22da6e220af6 702 * When the operation is complete, the peer is the highest ranked peer as reported by
AnnaBridge 146:22da6e220af6 703 * @ref pm_peer_ranks_get.
AnnaBridge 146:22da6e220af6 704 *
AnnaBridge 146:22da6e220af6 705 * @note The @ref PM_EVT_PEER_DATA_UPDATE_SUCCEEDED event can arrive before the function returns if the peer
AnnaBridge 146:22da6e220af6 706 * is already ranked highest. In this case, the @ref pm_peer_data_update_succeeded_evt_t::flash_changed flag
AnnaBridge 146:22da6e220af6 707 * in the event will be false.
AnnaBridge 146:22da6e220af6 708 *
AnnaBridge 146:22da6e220af6 709 * @param[in] peer_id The peer to rank highest.
AnnaBridge 146:22da6e220af6 710 *
AnnaBridge 146:22da6e220af6 711 * @retval NRF_SUCCESS If the peer's rank is, or will be updated to be highest.
AnnaBridge 146:22da6e220af6 712 * @retval NRF_ERROR_BUSY If the underlying flash handler is busy with other flash
AnnaBridge 146:22da6e220af6 713 * operations, or if a previous call to this function has not
AnnaBridge 146:22da6e220af6 714 * completed. Try again after receiving a Peer Manager event.
AnnaBridge 146:22da6e220af6 715 * @retval NRF_ERROR_INTERNAL If another error occurred.
AnnaBridge 146:22da6e220af6 716 * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized.
AnnaBridge 146:22da6e220af6 717 */
AnnaBridge 146:22da6e220af6 718 ret_code_t pm_peer_rank_highest(pm_peer_id_t peer_id);
AnnaBridge 146:22da6e220af6 719
AnnaBridge 146:22da6e220af6 720 /** @}*/
AnnaBridge 146:22da6e220af6 721
AnnaBridge 146:22da6e220af6 722 /** @} */
AnnaBridge 146:22da6e220af6 723
AnnaBridge 146:22da6e220af6 724 /** @} */
AnnaBridge 146:22da6e220af6 725
AnnaBridge 146:22da6e220af6 726 #endif // PEER_MANAGER_H__