/** * Copyright (c) 2015 - 2020, Nordic Semiconductor ASA * * All rights reserved. * * Redistribution and use in source and binary forms, with or without modification, * are permitted provided that the following conditions are met: * * 1. Redistributions of source code must retain the above copyright notice, this * list of conditions and the following disclaimer. * * 2. Redistributions in binary form, except as embedded into a Nordic * Semiconductor ASA integrated circuit in a product or a software update for * such product, must reproduce the above copyright notice, this list of * conditions and the following disclaimer in the documentation and/or other * materials provided with the distribution. * * 3. Neither the name of Nordic Semiconductor ASA nor the names of its * contributors may be used to endorse or promote products derived from this * software without specific prior written permission. * * 4. This software, with or without modification, must only be used with a * Nordic Semiconductor ASA integrated circuit. * * 5. Any software provided in binary form under this license must not be reverse * engineered, decompiled, modified and/or disassembled. * * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * */ /** * @file peer_manager.h * * @defgroup peer_manager Peer Manager * @ingroup ble_sdk_lib * @{ * @brief Module for managing BLE bonding, which includes controlling encryption and pairing * procedures as well as persistently storing different pieces of data that must be stored * when bonded. * * @details The API consists of functions for configuring the pairing and encryption behavior of the * device and functions for manipulating the stored data. * * This module uses Flash Data Storage (FDS) to interface with persistent storage. The * Peer Manager needs exclusive use of certain FDS file IDs and record keys. See * @ref lib_fds_functionality_keys for more information. */ #ifndef PEER_MANAGER_H__ #define PEER_MANAGER_H__ #include #include #include "sdk_common.h" #include "ble.h" #include "ble_gap.h" #include "peer_manager_types.h" #include "peer_database.h" #ifdef __cplusplus extern "C" { #endif /**@brief Peer list filtrations. They determine which peer ID will be added to list. */ typedef enum { PM_PEER_ID_LIST_ALL_ID, /**< Add all peers. */ PM_PEER_ID_LIST_SKIP_NO_ID_ADDR = BIT_0, /**< Add only peers with an ID address (static address). */ PM_PEER_ID_LIST_SKIP_NO_IRK = BIT_1, /**< Add only peers with a valid IRK. This implies @ref PM_PEER_ID_LIST_SKIP_NO_ID_ADDR, since all peers with IRKs have ID addresses. */ PM_PEER_ID_LIST_SKIP_NO_CAR = BIT_2, /**< Add only peers with Central Address Resolution characteristic set to 0. */ PM_PEER_ID_LIST_SKIP_ALL = PM_PEER_ID_LIST_SKIP_NO_IRK | /**< All above filters applied. */ PM_PEER_ID_LIST_SKIP_NO_CAR } pm_peer_id_list_skip_t; /**@brief Function for initializing the Peer Manager. * * @details You must initialize the Peer Manager before you can call any other Peer Manager * functions. * * @retval NRF_SUCCESS If initialization was successful. * @retval NRF_ERROR_INTERNAL If an internal error occurred. */ ret_code_t pm_init(void); /**@brief Function for registering an event handler with the Peer Manager. * * @param[in] event_handler Callback for events from the @ref peer_manager module. @p event_handler * is called for every event that the Peer Manager sends after this * function is called. * * @retval NRF_SUCCESS If initialization was successful. * @retval NRF_ERROR_NULL If @p event_handler was NULL. * @retval NRF_ERROR_NO_MEM If no more registrations can happen. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. */ ret_code_t pm_register(pm_evt_handler_t event_handler); /**@brief Function for providing pairing and bonding parameters to use for pairing procedures. * * @details Until this function is called, all bonding procedures that are initiated by the * peer are rejected. * * This function can be called multiple times with different parameters, even with NULL as * @p p_sec_params, in which case the Peer Manager starts rejecting all procedures again. * * @param[in] p_sec_params Security parameters to be used for subsequent security procedures. * * @retval NRF_SUCCESS If the parameters were set successfully. * @retval NRF_ERROR_INVALID_PARAM If the combination of parameters is invalid. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. * @retval NRF_ERROR_INTERNAL If an internal error occurred. */ ret_code_t pm_sec_params_set(ble_gap_sec_params_t * p_sec_params); /**@brief Function for establishing encryption on a connection, and optionally establishing a bond. * * @details This function attempts to secure the link that is specified by @p conn_handle. It uses * the parameters that were previously provided in a call to @ref pm_sec_params_set. * * If the connection is a master connection, calling this function starts a security * procedure on the link. If we have keys from a previous bonding procedure with this peer * and the keys meet the security requirements in the currently active security parameters, * the function attempts to establish encryption with the existing keys. If no key exists, * the function attempts to perform pairing and bonding according to the currently active * security parameters. * * If the function completes successfully, a @ref PM_EVT_CONN_SEC_START event is sent. * The procedure might be queued, in which case the @ref PM_EVT_CONN_SEC_START event is * delayed until the procedure is initiated in the SoftDevice. * * If the connection is a slave connection, the function sends a security request to * the peer (master). It is up to the peer then to initiate pairing or encryption. * If the peer ignores the request, a @ref BLE_GAP_EVT_AUTH_STATUS event occurs * with the status @ref BLE_GAP_SEC_STATUS_TIMEOUT. Otherwise, the peer initiates * security, in which case things happen as if the peer had initiated security itself. * See @ref PM_EVT_CONN_SEC_START for information about peer-initiated security. * * @param[in] conn_handle Connection handle of the link as provided by the SoftDevice. * @param[in] force_repairing Whether to force a pairing procedure even if there is an existing * encryption key. This argument is relevant only for * the central role. Recommended value: false. * * @retval NRF_SUCCESS If the operation completed successfully. * @retval NRF_ERROR_BUSY If a security procedure is already in progress on the link, * or if the link is disconnecting or disconnected. * @retval NRF_ERROR_TIMEOUT If there was an SMP time-out, so that no more security * operations can be performed on this link. * @retval BLE_ERROR_INVALID_CONN_HANDLE If the connection handle is invalid. * @retval NRF_ERROR_NOT_FOUND If the security parameters have not been set, either by * @ref pm_sec_params_set or by @ref pm_conn_sec_params_reply. * @retval NRF_ERROR_INVALID_DATA If the peer is bonded, but no LTK was found in the stored * bonding data. Repairing was not requested. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. * @retval NRF_ERROR_INTERNAL If an internal error occurred. */ ret_code_t pm_conn_secure(uint16_t conn_handle, bool force_repairing); /**@brief Function for providing security configuration for a link. * * @details This function is optional, and must be called in reply to a @ref * PM_EVT_CONN_SEC_CONFIG_REQ event, before the Peer Manager event handler returns. If it * is not called in time, a default configuration is used. See @ref pm_conn_sec_config_t * for the value of the default. * * @param[in] conn_handle The connection to set the configuration for. * @param[in] p_conn_sec_config The configuration. */ void pm_conn_sec_config_reply(uint16_t conn_handle, pm_conn_sec_config_t * p_conn_sec_config); /**@brief Function for providing security parameters for a link. * * @details This function is optional, and must be called in reply to a @ref * PM_EVT_CONN_SEC_PARAMS_REQ event, before the Peer Manager event handler returns. If it * is not called in time, the parameters given in @ref pm_sec_params_set are used. * * @param[in] conn_handle The connection to set the parameters for. * @param[in] p_sec_params The parameters. If NULL, the security procedure is rejected. * @param[in] p_context The context found in the request event that this function replies to. * * @retval NRF_SUCCESS Successful reply. * @retval NRF_ERROR_NULL p_sec_params or p_context was null. * @retval NRF_ERROR_INVALID_PARAM Value of p_sec_params was invalid. * @retval NRF_ERROR_INVALID_STATE This module is not initialized. */ ret_code_t pm_conn_sec_params_reply(uint16_t conn_handle, ble_gap_sec_params_t * p_sec_params, void const * p_context); /**@brief Function for manually informing that the local database has changed. * * @details This function sends a service changed indication to all bonded and/or connected peers * that subscribe to this indication. If a bonded peer is not connected, the indication is * sent when it reconnects. Every time an indication is sent, a @ref * PM_EVT_SERVICE_CHANGED_IND_SENT event occurs, followed by a @ref * PM_EVT_SERVICE_CHANGED_IND_CONFIRMED when the peer sends its confirmation. Peers that * are not subscribed to the service changed indication when this function is called do not * receive an indication, and no events are sent to the user. Likewise, if the service * changed characteristic is not present in the local database, or if the @ref * PM_SERVICE_CHANGED_ENABLED is set to 0, no indications are sent peers, and no events are * sent to the user. */ void pm_local_database_has_changed(void); /**@brief Function for getting the security status of a connection. * * @param[in] conn_handle Connection handle of the link as provided by the SoftDevice. * @param[out] p_conn_sec_status Security status of the link. * * @retval NRF_SUCCESS If pairing was initiated successfully. * @retval BLE_ERROR_INVALID_CONN_HANDLE If the connection handle is invalid. * @retval NRF_ERROR_NULL If @p p_conn_sec_status was NULL. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. */ ret_code_t pm_conn_sec_status_get(uint16_t conn_handle, pm_conn_sec_status_t * p_conn_sec_status); /**@brief Function for comparing the security status of a connection against a baseline. * * @param[in] conn_handle Connection handle of the link as provided by the SoftDevice. * @param[out] p_sec_status_req Target baseline security status to compare against. * * @retval true If the security status of the connection matches or exceeds the baseline on all * points. * @retval false If the security status of the connection does not fulfil the baseline, or could * not be retrieved. */ bool pm_sec_is_sufficient(uint16_t conn_handle, pm_conn_sec_status_t * p_sec_status_req); /**@brief Experimental function for specifying the public key to use for LESC operations. * * @details This function can be called multiple times. The specified public key will be used for * all subsequent LESC (LE Secure Connections) operations until the next time this function * is called. * * @note The key must continue to reside in application memory as it is not copied by Peer Manager. * * @note This function is deprecated. LESC keys are now handled internally if @ref PM_LESC_ENABLED * is true. If @ref PM_LESC_ENABLED is false, this function works as before. * * @param[in] p_public_key The public key to use for all subsequent LESC operations. * * @retval NRF_SUCCESS If pairing was initiated successfully. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. * @retval NRF_ERROR_FORBIDDEN If LESC module support is enabled (see @ref PM_LESC_ENABLED). */ ret_code_t pm_lesc_public_key_set(ble_gap_lesc_p256_pk_t * p_public_key); /**@brief Function for setting or clearing the whitelist. * * When using the S13x SoftDevice v3.x, this function sets or clears the whitelist. * When using the S13x SoftDevice v2.x, this function caches a list of * peers that can be retrieved later by @ref pm_whitelist_get to pass to the @ref lib_ble_advertising. * * To clear the current whitelist, pass either NULL as @p p_peers or zero as @p peer_cnt. * * @param[in] p_peers The peers to add to the whitelist. Pass NULL to clear the current whitelist. * @param[in] peer_cnt The number of peers to add to the whitelist. The number must not be greater than * @ref BLE_GAP_WHITELIST_ADDR_MAX_COUNT. Pass zero to clear the current * whitelist. * * @retval NRF_SUCCESS If the whitelist was successfully set or cleared. * @retval BLE_GAP_ERROR_WHITELIST_IN_USE If a whitelist is already in use and cannot be set. * @retval BLE_ERROR_GAP_INVALID_BLE_ADDR If a peer in @p p_peers has an address that cannot * be used for whitelisting. * @retval NRF_ERROR_NOT_FOUND If any of the peers in @p p_peers cannot be found. * @retval NRF_ERROR_DATA_SIZE If @p peer_cnt is greater than * @ref BLE_GAP_WHITELIST_ADDR_MAX_COUNT. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. */ ret_code_t pm_whitelist_set(pm_peer_id_t const * p_peers, uint32_t peer_cnt); /**@brief Function for retrieving the previously set whitelist. * * The function retrieves the whitelist of GAP addresses and IRKs that was * previously set by @ref pm_whitelist_set. * * To retrieve only GAP addresses or only IRKs, provide only one of the * buffers. If a buffer is provided, its size must be specified. * * @param[out] p_addrs The buffer where to store GAP addresses. Pass NULL to retrieve * only IRKs (in that case, @p p_irks must not be NULL). * @param[in,out] p_addr_cnt In: The size of the @p p_addrs buffer. * May be NULL if and only if @p p_addrs is NULL. * Out: The number of GAP addresses copied into the buffer. * If @p p_addrs is NULL, this parameter remains unchanged. * @param[out] p_irks The buffer where to store IRKs. Pass NULL to retrieve * only GAP addresses (in that case, @p p_addrs must not NULL). * @param[in,out] p_irk_cnt In: The size of the @p p_irks buffer. * May be NULL if and only if @p p_irks is NULL. * Out: The number of IRKs copied into the buffer. * If @p p_irks is NULL, this paramater remains unchanged. * * @retval NRF_SUCCESS If the whitelist was successfully retrieved. * @retval BLE_ERROR_GAP_INVALID_BLE_ADDR If a peer has an address that cannot be used for * whitelisting (this error can occur only * when using the S13x SoftDevice v2.x). * @retval NRF_ERROR_NULL If a required parameter is NULL. * @retval NRF_ERROR_NO_MEM If the provided buffers are too small. * @retval NRF_ERROR_NOT_FOUND If the data for any of the cached whitelisted peers * cannot be found. It might have been deleted. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. */ ret_code_t pm_whitelist_get(ble_gap_addr_t * p_addrs, uint32_t * p_addr_cnt, ble_gap_irk_t * p_irks, uint32_t * p_irk_cnt); /**@brief Function for setting and clearing the device identities list. * * @note When entering directed advertising, make sure the active identities list does not contain * peers that have no Central Address Resolution. See @ref pm_peer_id_list with skip_id * @ref PM_PEER_ID_LIST_SKIP_NO_CAR. * * @param[in] p_peers The peers to add to the device identities list. Pass NULL to clear * the device identities list. * @param[in] peer_cnt The number of peers. Pass zero to clear the device identities list. * * @retval NRF_SUCCESS If the device identities list was successfully * set or cleared. * @retval NRF_ERROR_NOT_FOUND If a peer is invalid or its data could not * be found in flash. * @retval BLE_ERROR_GAP_INVALID_BLE_ADDR If a peer has an address that cannot be * used for whitelisting. * @retval BLE_ERROR_GAP_DEVICE_IDENTITIES_IN_USE If the device identities list is in use and * cannot be set. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. * @retval NRF_ERROR_NOT_SUPPORTED If using a SoftDevice that does not support * device identities, e.g. S130 v2.0. */ ret_code_t pm_device_identities_list_set(pm_peer_id_t const * p_peers, uint32_t peer_cnt); /**@brief Function for setting the local Bluetooth identity address. * * @details The local Bluetooth identity address is the address that identifies the device * to other peers. The address type must be either @ref BLE_GAP_ADDR_TYPE_PUBLIC or @ref * BLE_GAP_ADDR_TYPE_RANDOM_STATIC. The identity address cannot be changed while roles are running. * * The SoftDevice sets a default address of type @ref BLE_GAP_ADDR_TYPE_RANDOM_STATIC when it is * enabled. This default address is a random number that is populated during the IC manufacturing * process. It remains unchanged for the lifetime of each IC, but the application can use this * function to assign a different identity address. * * The identity address is distributed to the peer during bonding. Changing the identity address * means bonded devices might not recognize us. * * @note The SoftDevice functions @ref sd_ble_gap_addr_set and @ref sd_ble_gap_privacy_set must not * be called when using the Peer Manager. Use the Peer Manager equivalents instead. * * @param[in] p_addr The GAP address to be set. * * @retval NRF_SUCCESS If the identity address was set successfully. * @retval NRF_ERROR_NULL If @p p_addr is NULL. * @retval NRF_ERROR_INVALID_ADDR If the @p p_addr pointer is invalid. * @retval BLE_ERROR_GAP_INVALID_BLE_ADDR If the BLE address is invalid. * @retval NRF_ERROR_BUSY If the SoftDevice was busy. Process SoftDevice events * and retry. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized or if this function * was called while advertising, scanning, or while connected. * @retval NRF_ERROR_INTERNAL If an internal error occurred. */ ret_code_t pm_id_addr_set(ble_gap_addr_t const * p_addr); /**@brief Function for retrieving the local Bluetooth identity address. * * This function always returns the identity address, irrespective of the privacy settings. * This means that the address type will always be either @ref BLE_GAP_ADDR_TYPE_PUBLIC or @ref * BLE_GAP_ADDR_TYPE_RANDOM_STATIC. * * @param[out] p_addr Pointer to the address structure to be filled in. * * @retval NRF_SUCCESS If the address was retrieved successfully. * @retval NRF_ERROR_NULL If @p p_addr is NULL. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. */ ret_code_t pm_id_addr_get(ble_gap_addr_t * p_addr); /**@brief Function for configuring privacy settings. * * The privacy settings cannot be configured while advertising, scanning, or while in a connection. * * @note The SoftDevice functions @ref sd_ble_gap_addr_set * and @ref sd_ble_gap_privacy_set must not be called when using the Peer Manager. * Use this function instead. * * @param[in] p_privacy_params Privacy settings. * * @retval NRF_SUCCESS If the privacy settings were configured successfully. * @retval NRF_ERROR_NULL If @p p_privacy_params is NULL. * @retval NRF_ERROR_BUSY If the operation could not be performed at this time. * Process SoftDevice events and retry. * @retval NRF_ERROR_INVALID_PARAM If the address type is invalid. * @retval NRF_ERROR_INVALID_STATE If this function is called while BLE roles using * privacy are enabled. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. */ ret_code_t pm_privacy_set(pm_privacy_params_t const * p_privacy_params); /**@brief Function for retrieving privacy settings. * * The privacy settings that are returned include the current IRK as well. * * @param[out] p_privacy_params Privacy settings. * * @retval NRF_SUCCESS If the privacy settings were retrieved successfully. * @retval NRF_ERROR_NULL If @p p_privacy_params or @p p_privacy_params->p_device_irk is * NULL. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. */ ret_code_t pm_privacy_get(pm_privacy_params_t * p_privacy_params); /**@brief Function for resolving a resolvable address with an identity resolution key (IRK). * * @param[in] p_addr A private random resolvable address. * @param[in] p_irk An identity resolution key (IRK). * * @retval true The IRK used matched the one used to create the address. * @retval false The IRK used did not match the one used to create the address, or an argument was * NULL or invalid. */ bool pm_address_resolve(ble_gap_addr_t const * p_addr, ble_gap_irk_t const * p_irk); /**@brief Function for getting the connection handle of the connection with a bonded peer. * * @param[in] peer_id The peer ID of the bonded peer. * @param[out] p_conn_handle Connection handle, or @ref BLE_CONN_HANDLE_INVALID if the peer * is not connected. * * @retval NRF_SUCCESS If the connection handle was retrieved successfully. * @retval NRF_ERROR_NULL If @p p_conn_handle was NULL. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. */ ret_code_t pm_conn_handle_get(pm_peer_id_t peer_id, uint16_t * p_conn_handle); /**@brief Function for retrieving the ID of a peer, given its connection handle. * * @param[in] conn_handle The connection handle of the peer. * @param[out] p_peer_id The peer ID, or @ref PM_PEER_ID_INVALID if the peer is not bonded or * @p conn_handle does not refer to a valid connection. * * @retval NRF_SUCCESS If the peer ID was retrieved successfully. * @retval NRF_ERROR_NULL If @p p_peer_id was NULL. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. */ ret_code_t pm_peer_id_get(uint16_t conn_handle, pm_peer_id_t * p_peer_id); /**@brief Function for retrieving a filtered list of peer IDs. * * @details This function starts searching from @p first_peer_id. IDs ordering * is the same as for @ref pm_next_peer_id_get(). If the first_peer_id * is @ref PM_PEER_ID_INVALID, the function starts searching from the first ID. * The function looks for the ID's number specified by @p p_list_size. Only those IDs that * match @p skip_id are added to the list. The number of returned elements is determined * by @p p_list_size. * * @warning The size of the @p p_peer_list buffer must be equal or greater than @p p_list_size. * * @param[out] p_peer_list Pointer to peer IDs list buffer. * @param[in,out] p_list_size The amount of IDs to return / The number of returned IDs. * @param[in] first_peer_id The first ID from which the search begins. IDs ordering * is the same as for @ref pm_next_peer_id_get() * @param[in] skip_id It determines which peer ID will be added to list. * * @retval NRF_SUCCESS If the ID list has been filled out. * @retval NRF_ERROR_INVALID_PARAM If @p skip_id was invalid. * @retval NRF_ERROR_NULL If peer_list or list_size was NULL. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. */ ret_code_t pm_peer_id_list(pm_peer_id_t * p_peer_list, uint32_t * const p_list_size, pm_peer_id_t first_peer_id, pm_peer_id_list_skip_t skip_id); /**@brief Function for getting the next peer ID in the sequence of all used peer IDs. * * @details This function can be used to loop through all used peer IDs. The order in which * peer IDs are returned should be considered unpredictable. @ref PM_PEER_ID_INVALID * is considered to be before the first and after the last used peer ID. * * @details To loop through all peer IDs exactly once, use the following constuct: * @code{c} * pm_peer_id_t current_peer_id = pm_next_peer_id_get(PM_PEER_ID_INVALID); * while (current_peer_id != PM_PEER_ID_INVALID) * { * // Do something with current_peer_id. * current_peer_id = pm_next_peer_id_get(current_peer_id) * } * @endcode * * @note This function does not report peer IDs that are pending deletion. * * @param[in] prev_peer_id The previous peer ID. * * @return The next peer ID. If @p prev_peer_id was @ref PM_PEER_ID_INVALID, the * next peer ID is the first used peer ID. If @p prev_peer_id was the last * used peer ID, the function returns @ref PM_PEER_ID_INVALID. */ pm_peer_id_t pm_next_peer_id_get(pm_peer_id_t prev_peer_id); /**@brief Function for querying the number of valid peer IDs that are available. * * @details This function returns the number of peers for which there is data in persistent storage. * * @return The number of valid peer IDs. */ uint32_t pm_peer_count(void); /**@anchor PM_PEER_DATA_FUNCTIONS * @name Functions (Peer Data) * Functions for manipulating peer data. * @{ */ /** * @{ */ /**@brief Function for retrieving stored data of a peer. * * @note The length of the provided buffer must be a multiple of 4. * * @param[in] peer_id Peer ID to get data for. * @param[in] data_id Which type of data to read. * @param[out] p_data Where to put the retrieved data. The documentation for * @ref pm_peer_data_id_t specifies what data type each data ID is stored as. * @param[in,out] p_len In: The length in bytes of @p p_data. * Out: The length in bytes of the read data, if the read was successful. * * @retval NRF_SUCCESS If the data was read successfully. * @retval NRF_ERROR_INVALID_PARAM If the data type or the peer ID was invalid or unallocated. * @retval NRF_ERROR_NULL If a pointer parameter was NULL. * @retval NRF_ERROR_NOT_FOUND If no stored data was found for this peer ID/data ID combination. * @retval NRF_ERROR_DATA_SIZE If the provided buffer was not large enough. The data is still * copied, filling the provided buffer. Note that this error can * occur even if loading the same size as was stored, because the * underlying layers round the length up to the nearest word (4 bytes) * when storing. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. */ ret_code_t pm_peer_data_load(pm_peer_id_t peer_id, pm_peer_data_id_t data_id, void * p_data, uint32_t * p_len); /**@brief Function for reading a peer's bonding data (@ref PM_PEER_DATA_ID_BONDING). * @details See @ref pm_peer_data_load for parameters and return values. */ ret_code_t pm_peer_data_bonding_load(pm_peer_id_t peer_id, pm_peer_data_bonding_t * p_data); /**@brief Function for reading a peer's remote DB values. (@ref PM_PEER_DATA_ID_GATT_REMOTE). * @details See @ref pm_peer_data_load for parameters and return values. */ ret_code_t pm_peer_data_remote_db_load(pm_peer_id_t peer_id, ble_gatt_db_srv_t * p_data, uint32_t * p_len); /**@brief Function for reading a peer's application data. (@ref PM_PEER_DATA_ID_APPLICATION). * @details See @ref pm_peer_data_load for parameters and return values. */ ret_code_t pm_peer_data_app_data_load(pm_peer_id_t peer_id, void * p_data, uint32_t * p_len); /** @}*/ /** * @{ */ /**@brief Function for setting or updating stored data of a peer. * * @note Writing the data to persistent storage happens asynchronously. Therefore, the buffer * that contains the data must be kept alive until the operation has completed. * * @note The data written using this function might later be overwritten as a result of internal * operations in the Peer Manager. A Peer Manager event is sent each time data is updated, * regardless of whether the operation originated internally or from action by the user. * Data with @p data_id @ref PM_PEER_DATA_ID_GATT_REMOTE @ref PM_PEER_DATA_ID_APPLICATION is * never (over)written internally. * * @param[in] peer_id Peer ID to set data for. * @param[in] data_id Which type of data to set. * @param[in] p_data New value to set. The documentation for @ref pm_peer_data_id_t specifies * what data type each data ID should be stored as. * @param[in] len The length in bytes of @p p_data. * @param[out] p_token A token that identifies this particular store operation. The token can be * used to identify events that pertain to this operation. This parameter can * be NULL. * * @retval NRF_SUCCESS If the data is scheduled to be written to persistent storage. * @retval NRF_ERROR_NULL If @p p_data is NULL. * @retval NRF_ERROR_NOT_FOUND If no peer was found for the peer ID. * @retval NRF_ERROR_INVALID_ADDR If @p p_data is not word-aligned (4 bytes). * @retval NRF_ERROR_BUSY If the underlying flash handler is busy with other flash * operations. Try again after receiving a Peer Manager event. * @retval NRF_ERROR_STORAGE_FULL If there is not enough space in persistent storage. * @retval NRF_ERROR_FORBIDDEN If data ID is @ref PM_PEER_DATA_ID_BONDING and the new bonding * data also corresponds to another bonded peer. No data is written * so duplicate entries are avoided. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. */ ret_code_t pm_peer_data_store(pm_peer_id_t peer_id, pm_peer_data_id_t data_id, void const * p_data, uint32_t len, pm_store_token_t * p_token); /**@brief Function for setting or updating a peer's bonding data (@ref PM_PEER_DATA_ID_BONDING). * @details See @ref pm_peer_data_store for parameters and return values. */ ret_code_t pm_peer_data_bonding_store(pm_peer_id_t peer_id, pm_peer_data_bonding_t const * p_data, pm_store_token_t * p_token); /**@brief Function for setting or updating a peer's remote DB values. (@ref PM_PEER_DATA_ID_GATT_REMOTE). * @details See @ref pm_peer_data_store for parameters and return values. */ ret_code_t pm_peer_data_remote_db_store(pm_peer_id_t peer_id, ble_gatt_db_srv_t const * p_data, uint32_t len, pm_store_token_t * p_token); /**@brief Function for setting or updating a peer's application data. (@ref PM_PEER_DATA_ID_APPLICATION). * @details See @ref pm_peer_data_store for parameters and return values. */ ret_code_t pm_peer_data_app_data_store(pm_peer_id_t peer_id, void const * p_data, uint32_t len, pm_store_token_t * p_token); /** @}*/ /** * @{ */ /**@brief Function for deleting a peer's stored pieces of data. * * @details This function deletes specific data that is stored for a peer. Note that bonding data * cannot be cleared separately. * * To delete all data for a peer (including bonding data), use @ref pm_peer_delete. * * @note Clearing data in persistent storage happens asynchronously. * * @param[in] peer_id Peer ID to clear data for. * @param[in] data_id Which data to clear. * * @retval NRF_SUCCESS If the clear procedure was initiated successfully. * @retval NRF_ERROR_INVALID_PARAM If @p data_id was PM_PEER_DATA_ID_BONDING or invalid, or * @p peer_id was invalid. * @retval NRF_ERROR_NOT_FOUND If there was no data to clear for this peer ID/data ID combination. * @retval NRF_ERROR_BUSY If the underlying flash handler is busy with other flash * operations. Try again after receiving a Peer Manager event. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. * @retval NRF_ERROR_INTERNAL If an internal error occurred. */ ret_code_t pm_peer_data_delete(pm_peer_id_t peer_id, pm_peer_data_id_t data_id); /**@brief Function for manually adding a peer to the persistent storage. * * @details This function allocates a new peer ID and stores bonding data for the new peer. The * bonding data is necessary to prevent ambiguity/inconsistency in peer data. * * @param[in] p_bonding_data The bonding data of the new peer (must contain a public/static * address or a non-zero IRK). * @param[out] p_new_peer_id Peer ID for the new peer, or an existing peer if a match was found. * @param[out] p_token A token that identifies this particular store operation (storing the * bonding data). The token can be used to identify events that pertain * to this operation. This parameter can be NULL. * * @retval NRF_SUCCESS If the store operation for bonding data was initiated successfully. * @retval NRF_ERROR_NULL If @p p_bonding_data or @p p_new_peer_id is NULL. * @retval NRF_ERROR_INVALID_ADDR If @p p_bonding_data is not word-aligned (4 bytes). * @retval NRF_ERROR_STORAGE_FULL If there is not enough space in persistent storage. * @retval NRF_ERROR_NO_MEM If there are no more available peer IDs. * @retval NRF_ERROR_BUSY If the underlying flash filesystem is busy with other flash * operations. Try again after receiving a Peer Manager event. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. * @retval NRF_ERROR_INTERNAL If an internal error occurred. */ ret_code_t pm_peer_new(pm_peer_id_t * p_new_peer_id, pm_peer_data_bonding_t * p_bonding_data, pm_store_token_t * p_token); /**@brief Function for freeing persistent storage for a peer. * * @details This function deletes every piece of data that is associated with the specified peer and * frees the peer ID to be used for another peer. The deletion happens asynchronously, and * the peer ID is not freed until the data is deleted. When the operation finishes, a @ref * PM_EVT_PEER_DELETE_SUCCEEDED or @ref PM_EVT_PEER_DELETE_FAILED event is sent. * * @warning Use this function only when not connected to or connectable for the peer that is being * deleted. If the peer is or becomes connected or data is manually written in flash during * this procedure (until the success or failure event happens), the behavior is undefined. * * @param[in] peer_id Peer ID to be freed and have all associated data deleted. * * @retval NRF_SUCCESS If the operation was initiated successfully. * @retval NRF_ERROR_INVALID_PARAM If the peer ID was not valid. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. */ ret_code_t pm_peer_delete(pm_peer_id_t peer_id); /**@brief Function for deleting all data stored for all peers. * * @details This function sends either a @ref PM_EVT_PEERS_DELETE_SUCCEEDED or a @ref * PM_EVT_PEERS_DELETE_FAILED event. In addition, a @ref PM_EVT_PEER_DELETE_SUCCEEDED or * @ref PM_EVT_PEER_DELETE_FAILED event is sent for each deleted peer. * * @note When there is no peer data in flash the @ref PM_EVT_PEER_DELETE_SUCCEEDED event is sent synchronously. * * @warning Use this function only when not connected or connectable. If a peer is or becomes * connected or a @ref PM_PEER_DATA_FUNCTIONS function is used during this procedure (until * the success or failure event happens), the behavior is undefined. * * @retval NRF_SUCCESS If the deletion process was initiated successfully. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. * @retval NRF_ERROR_INTERNAL If an internal error occurred. */ ret_code_t pm_peers_delete(void); /** @}*/ /** * @{ */ /**@brief Function for finding the highest and lowest ranked peers. * * @details The rank is saved in persistent storage under the data ID @ref PM_PEER_DATA_ID_PEER_RANK. * * @details The interpretation of rank is up to the user, because the rank is only updated by * calling @ref pm_peer_rank_highest or by manipulating the value using a @ref * PM_PEER_DATA_FUNCTIONS function. * * @note Peers with no stored rank are not considered. * @note Any argument that is NULL is ignored. * * @param[out] p_highest_ranked_peer The peer ID with the highest rank of all peers, for example, * the most recently used peer. * @param[out] p_highest_rank The highest rank. * @param[out] p_lowest_ranked_peer The peer ID with the lowest rank of all peers, for example, * the least recently used peer. * @param[out] p_lowest_rank The lowest rank. * * @retval NRF_SUCCESS If the operation completed successfully. * @retval NRF_ERROR_NOT_FOUND If no peer with stored peer rank was found. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. * @retval NRF_ERROR_INTERNAL If an internal error occurred. * @retval NRF_ERROR_NOT_SUPPORTED If peer rank functionality has been disabled via the @ref * PM_PEER_RANKS_ENABLED configuration option. */ ret_code_t pm_peer_ranks_get(pm_peer_id_t * p_highest_ranked_peer, uint32_t * p_highest_rank, pm_peer_id_t * p_lowest_ranked_peer, uint32_t * p_lowest_rank); /**@brief Function for updating the rank of a peer to be highest among all stored peers. * * @details If this function returns @ref NRF_SUCCESS, either a @ref PM_EVT_PEER_DATA_UPDATE_SUCCEEDED or a * @ref PM_EVT_PEER_DATA_UPDATE_FAILED event is sent with a @ref * PM_STORE_TOKEN_INVALID store token when the operation is complete. Until the operation * is complete, this function returns @ref NRF_ERROR_BUSY. * * When the operation is complete, the peer is the highest ranked peer as reported by * @ref pm_peer_ranks_get. * * @note The @ref PM_EVT_PEER_DATA_UPDATE_SUCCEEDED event can arrive before the function returns if the peer * is already ranked highest. In this case, the @ref pm_peer_data_update_succeeded_evt_t::flash_changed flag * in the event will be false. * * @param[in] peer_id The peer to rank highest. * * @retval NRF_SUCCESS If the peer's rank is, or will be updated to be highest. * @retval NRF_ERROR_INVALID_PARAM If @p peer_id is invalid, or doesn't exist in flash. * @retval NRF_ERROR_STORAGE_FULL If there is not enough space in persistent storage. * @retval NRF_ERROR_BUSY If the underlying flash handler is busy with other flash * operations, or if a previous call to this function has not * completed. Try again after receiving a Peer Manager event. * @retval NRF_ERROR_INVALID_STATE If the Peer Manager is not initialized. * @retval NRF_ERROR_RESOURCES If the highest rank is UINT32_MAX, so the new rank would wrap * around to 0. To fix this, manually update all ranks to smaller * values, while still keeping their order. * @retval NRF_ERROR_INTERNAL If an internal error occurred. * @retval NRF_ERROR_NOT_SUPPORTED If peer rank functionality has been disabled via the @ref * PM_PEER_RANKS_ENABLED configuration option. */ ret_code_t pm_peer_rank_highest(pm_peer_id_t peer_id); /** @}*/ /** @} */ /** @} */ #ifdef __cplusplus } #endif #endif // PEER_MANAGER_H__