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. More...
Modules | |
| Peer Manager defined security errors | |
| All versions of Peer IDs. | |
| The data ID for each iteration of the data formats in flash. | |
Data Structures | |
| struct | pm_conn_sec_status_t |
| Security status of a connection. More... | |
| struct | pm_conn_secured_evt_t |
| Parameters specific to the PM_EVT_CONN_SEC_SUCCEEDED event. More... | |
| struct | pm_conn_secure_failed_evt_t |
| Parameters specific to the PM_EVT_CONN_SEC_FAILED event. More... | |
| struct | pm_peer_data_update_succeeded_evt_t |
| Parameters specific to the PM_EVT_PEER_DATA_UPDATE_SUCCEEDED event. More... | |
| struct | pm_peer_data_update_failed_t |
| Parameters specific to the PM_EVT_PEER_DATA_UPDATE_FAILED event. More... | |
| struct | pm_failure_evt_t |
| Standard parameters for failure events. More... | |
| struct | pm_evt_t |
| An event from the Peer Manager module. More... | |
| struct | pm_conn_sec_config_t |
| Configuration of a security procedure. More... | |
| struct | pm_peer_data_bonding_t |
| Data associated with a bond to a peer. More... | |
| struct | pm_peer_data_local_gatt_db_t |
| Data on a local GATT database. More... | |
Macros | |
| #define | PM_PEER_ID_INVALID 0xFFFF |
| Invalid value for pm_peer_id_t. | |
| #define | PM_STORE_TOKEN_INVALID 0 |
| Invalid value for store token. | |
| #define | PM_PEER_ID_N_AVAILABLE_IDS 256 |
| The number of available peer IDs. | |
| #define | PM_LOCAL_DB_LEN_OVERHEAD_BYTES offsetof(pm_peer_data_local_gatt_db_t, data) |
| The static-length part of the local GATT data struct. | |
| #define | PM_CONN_SEC_ERROR_BASE 0x1000 |
| The base for Peer Manager defined errors. See Peer Manager defined security errors and pm_sec_error_code_t. | |
| #define | PM_PEER_DATA_ID_IS_VALID(data_id) |
| Macro to check whether a data type is valid, thus one of the valid enum values. More... | |
Typedefs | |
| typedef void(* | pm_evt_handler_t )(pm_evt_t const *p_event) |
| Event handler for events from the Peer Manager module. More... | |
| typedef uint16_t | pm_peer_id_t |
| Handle to uniquely identify a peer for which we have persistently stored data. | |
| typedef uint32_t | pm_prepare_token_t |
| Type that is used for write prepares (used to reserve space in flash). | |
| typedef uint32_t | pm_store_token_t |
| Type that is used to hold a reference to a stored item in flash. | |
| typedef uint16_t | pm_sec_error_code_t |
| Errors from security procedures in Peer Manager. More... | |
Functions | |
| ret_code_t | pm_init (void) |
| Function for initializing the Peer Manager. More... | |
| ret_code_t | pm_register (pm_evt_handler_t event_handler) |
| Function for registering an event handler with the Peer Manager. More... | |
| ret_code_t | pm_sec_params_set (ble_gap_sec_params_t *p_sec_params) |
| Function for providing pairing and bonding parameters to use for pairing procedures. More... | |
| void | pm_on_ble_evt (ble_evt_t *p_ble_evt) |
| Function for passing BLE events to the Peer Manager. More... | |
| ret_code_t | pm_conn_secure (uint16_t conn_handle, bool force_repairing) |
| Function for establishing encryption on a connection, and optionally establishing a bond. More... | |
| void | pm_conn_sec_config_reply (uint16_t conn_handle, pm_conn_sec_config_t *p_conn_sec_config) |
| Function for providing security configuration for a link. More... | |
| void | pm_local_database_has_changed (void) |
| Function for manually informing that the local database has changed. More... | |
| ret_code_t | pm_conn_sec_status_get (uint16_t conn_handle, pm_conn_sec_status_t *p_conn_sec_status) |
| Function for getting the security status of a connection. More... | |
| ret_code_t | pm_lesc_public_key_set (ble_gap_lesc_p256_pk_t *p_public_key) |
| Experimental function for specifying the public key to use for LESC operations. More... | |
| ret_code_t | pm_whitelist_create (pm_peer_id_t *p_peer_ids, uint8_t n_peer_ids, ble_gap_whitelist_t *p_whitelist) |
| Function for constructing a whitelist for use when advertising. More... | |
| ret_code_t | pm_whitelist_custom (ble_gap_whitelist_t *p_whitelist) |
| Function for informing the Peer Manager of what whitelist should be used. More... | |
| ret_code_t | pm_conn_handle_get (pm_peer_id_t peer_id, uint16_t *p_conn_handle) |
| Function for getting the connection handle of the connection with a bonded peer. More... | |
| ret_code_t | pm_peer_id_get (uint16_t conn_handle, pm_peer_id_t *p_peer_id) |
| Function for getting the peer ID of a connected peer. More... | |
| pm_peer_id_t | pm_next_peer_id_get (pm_peer_id_t prev_peer_id) |
| Function for getting the next peer ID in the sequence of all used peer IDs. More... | |
| uint32_t | pm_peer_count (void) |
| Function for querying the number of valid peer IDs that are available. More... | |
Functions (Peer Data) | |
| ret_code_t | pm_peer_data_load (pm_peer_id_t peer_id, pm_peer_data_id_t data_id, void *p_data, uint16_t *p_len) |
| Function for retrieving stored data of a peer. More... | |
| ret_code_t | pm_peer_data_bonding_load (pm_peer_id_t peer_id, pm_peer_data_bonding_t *p_data) |
| Function for reading a peer's bonding data (PM_PEER_DATA_ID_BONDING). More... | |
| ret_code_t | pm_peer_data_remote_db_load (pm_peer_id_t peer_id, ble_gatt_db_srv_t *p_data, uint16_t *p_len) |
| Function for reading a peer's remote DB values. (PM_PEER_DATA_ID_GATT_REMOTE). More... | |
| ret_code_t | pm_peer_data_app_data_load (pm_peer_id_t peer_id, uint8_t *p_data, uint16_t *p_len) |
| Function for reading a peer's application data. (PM_PEER_DATA_ID_APPLICATION). More... | |
| ret_code_t | pm_peer_data_store (pm_peer_id_t peer_id, pm_peer_data_id_t data_id, void const *p_data, uint16_t len, pm_store_token_t *p_token) |
| Function for setting or updating stored data of a peer. More... | |
| 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) |
| Function for setting or updating a peer's bonding data (PM_PEER_DATA_ID_BONDING). More... | |
| ret_code_t | pm_peer_data_remote_db_store (pm_peer_id_t peer_id, ble_gatt_db_srv_t const *p_data, uint16_t len, pm_store_token_t *p_token) |
| Function for setting or updating a peer's remote DB values. (PM_PEER_DATA_ID_GATT_REMOTE). More... | |
| ret_code_t | pm_peer_data_app_data_store (pm_peer_id_t peer_id, uint8_t const *p_data, uint16_t len, pm_store_token_t *p_token) |
| Function for setting or updating a peer's application data. (PM_PEER_DATA_ID_APPLICATION). More... | |
| ret_code_t | pm_peer_data_delete (pm_peer_id_t peer_id, pm_peer_data_id_t data_id) |
| Function for deleting a peer's stored pieces of data. More... | |
| 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) |
| Function for manually adding a peer to the persistent storage. More... | |
| ret_code_t | pm_peer_delete (pm_peer_id_t peer_id) |
| Function for freeing persistent storage for a peer. More... | |
| ret_code_t | pm_peers_delete (void) |
| Function for deleting all data stored for all peers. More... | |
| 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) |
| Function for finding the highest and lowest ranked peers. More... | |
| ret_code_t | pm_peer_rank_highest (pm_peer_id_t peer_id) |
| Function for updating the rank of a peer to be highest among all stored peers. More... | |
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.
The API consists of functions for configuring the pairing and encryption behavior of the device and functions for manipulating the stored data.
| #define PM_PEER_DATA_ID_IS_VALID | ( | data_id | ) |
Macro to check whether a data type is valid, thus one of the valid enum values.
| [in] | data_id | The data type to check. |
| typedef void(* pm_evt_handler_t)(pm_evt_t const *p_event) |
Event handler for events from the Peer Manager module.
| [in] | p_event | The event that has occurred. |
| typedef uint16_t pm_sec_error_code_t |
Errors from security procedures in Peer Manager.
Possible values are defined in Peer Manager defined security errors and GAP Security status.
Different procedures that can lead to an encrypted link.
| enum pm_evt_id_t |
Types of events that can come from the Peer Manager module.
| Enumerator | |
|---|---|
| PM_EVT_BONDED_PEER_CONNECTED |
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 BLE_GAP_EVT_CONNECTED event. When we are peripheral, this event might in rare cases arrive later. |
| PM_EVT_CONN_SEC_START |
A security procedure has started on a link, initiated either locally or remotely. The security procedure is using the last parameters provided via pm_sec_params_set. This event is always followed by either a PM_EVT_CONN_SEC_SUCCEEDED or a PM_EVT_CONN_SEC_FAILED event. This is an informational event; no action is needed for the procedure to proceed. |
| PM_EVT_CONN_SEC_SUCCEEDED |
A link has been encrypted, either as a result of a call to 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 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. |
| PM_EVT_CONN_SEC_FAILED |
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. |
| PM_EVT_CONN_SEC_CONFIG_REQ |
The peer (central) has requested pairing, but a bond already exists with that peer. Reply by calling pm_conn_sec_config_reply before the event handler returns. If no reply is sent, a default is used. |
| PM_EVT_STORAGE_FULL |
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. |
| PM_EVT_ERROR_UNEXPECTED |
An unrecoverable error happened inside Peer Manager. An operation failed with the provided error. |
| PM_EVT_PEER_DATA_UPDATE_SUCCEEDED |
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. |
| PM_EVT_PEER_DATA_UPDATE_FAILED |
A piece of peer data could not be stored, updated, or cleared in flash storage. This event is sent instead of PM_EVT_PEER_DATA_UPDATE_SUCCEEDED for the failed operation. |
| PM_EVT_PEER_DELETE_SUCCEEDED |
A peer was cleared from flash storage, for example because a call to pm_peer_delete succeeded. This event can also be sent as part of a call to pm_peers_delete or internal cleanup. |
| PM_EVT_PEER_DELETE_FAILED |
A peer could not be cleared from flash storage. This event is sent instead of PM_EVT_PEER_DELETE_SUCCEEDED for the failed operation. |
| PM_EVT_PEERS_DELETE_SUCCEEDED |
A call to pm_peers_delete has completed successfully. Flash storage now contains no peer data. |
| PM_EVT_PEERS_DELETE_FAILED |
A call to 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 PM_EVT_PEERS_DELETE_SUCCEEDED or PM_EVT_PEERS_DELETE_FAILED events are sent until the next time pm_peers_delete is called. |
| PM_EVT_LOCAL_DB_CACHE_APPLIED |
Local database values for a peer (taken from flash storage) have been provided to the SoftDevice. |
| PM_EVT_LOCAL_DB_CACHE_APPLY_FAILED |
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 pm_peer_data_store). |
| PM_EVT_SERVICE_CHANGED_IND_SENT |
A service changed indication has been sent to a peer, as a result of a call to pm_local_database_has_changed. This event will be followed by a PM_EVT_SERVICE_CHANGED_IND_CONFIRMED event if the peer acknowledges the indication. |
| PM_EVT_SERVICE_CHANGED_IND_CONFIRMED |
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. |
| enum pm_peer_data_id_t |
The different types of data associated with a peer.
| Enumerator | |
|---|---|
| PM_PEER_DATA_ID_FIRST |
The smallest data ID. |
| PM_PEER_DATA_ID_BONDING |
The data ID of the second version of bonding data. The data ID for bonding data. See pm_peer_data_bonding_t. |
| PM_PEER_DATA_ID_SERVICE_CHANGED_PENDING |
The data ID of the first version of the service changed pending flag. The data ID for service changed state. |
| PM_PEER_DATA_ID_GATT_LOCAL |
The data ID of the second version of local GATT data. The data ID for local GATT data (sys attributes). See pm_peer_data_local_gatt_db_t. |
| PM_PEER_DATA_ID_GATT_REMOTE |
The data ID of the second version of remote GATT data. The data ID for remote GATT data. |
| PM_PEER_DATA_ID_PEER_RANK |
The data ID of the first version of the rank. The data ID for peer rank. See pm_peer_rank_highest. |
| PM_PEER_DATA_ID_APPLICATION |
The data ID of the first version of application data. The data ID for application data. |
| PM_PEER_DATA_ID_LAST |
The data ID after the last valid one. One more than the highest data ID. |
| PM_PEER_DATA_ID_INVALID |
A data ID guaranteed to be invalid. |
| enum pm_peer_data_op_t |
| ret_code_t pm_conn_handle_get | ( | pm_peer_id_t | peer_id, |
| uint16_t * | p_conn_handle | ||
| ) |
Function for getting the connection handle of the connection with a bonded peer.
| [in] | peer_id | The peer ID of the bonded peer. |
| [out] | p_conn_handle | Connection handle, or BLE_ERROR_INVALID_CONN_HANDLE if the peer is not connected. |
| NRF_SUCCESS | If the connection handle was determined successfully. |
| NRF_ERROR_NULL | If p_conn_handle was NULL. |
| NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized. |
| void pm_conn_sec_config_reply | ( | uint16_t | conn_handle, |
| pm_conn_sec_config_t * | p_conn_sec_config | ||
| ) |
Function for providing security configuration for a link.
This function is optional, and must be called in reply to a 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 pm_conn_sec_config_t for the value of the default.
| [in] | conn_handle | The connection to set the configuration for. |
| [in] | p_conn_sec_config | The configuration. |
| ret_code_t pm_conn_sec_status_get | ( | uint16_t | conn_handle, |
| pm_conn_sec_status_t * | p_conn_sec_status | ||
| ) |
Function for getting the security status of a connection.
| [in] | conn_handle | Connection handle of the link as provided by the SoftDevice. |
| [out] | p_conn_sec_status | Security status of the link. |
| NRF_SUCCESS | If pairing was initiated successfully. |
| BLE_ERROR_INVALID_CONN_HANDLE | If the connection handle is invalid. |
| NRF_ERROR_NULL | If p_conn_sec_status was NULL. |
| NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized. |
| ret_code_t pm_conn_secure | ( | uint16_t | conn_handle, |
| bool | force_repairing | ||
| ) |
Function for establishing encryption on a connection, and optionally establishing a bond.
This function attempts to secure the link that is specified by conn_handle. It uses the parameters that were previously provided in a call to 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 sec_params, the function attempts to establish encryption with the existing keys. If no key exists, the function attempts to pair and bond according to the currently active sec_params.
If the function completes successfully, a PM_EVT_CONN_SEC_START event is sent. The procedure might be queued, in which case the 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 BLE_GAP_EVT_TIMEOUT event occurs with the source BLE_GAP_TIMEOUT_SRC_SECURITY_REQUEST. Otherwise, the peer initiates security, in which case things happen as if the peer had initiated security itself. See PM_EVT_CONN_SEC_START for information about peer-initiated security.
| [in] | conn_handle | Connection handle of the link as provided by the SoftDevice. |
| [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. |
| NRF_SUCCESS | If the operation completed successfully. |
| NRF_ERROR_TIMEOUT | If there was an SMP time-out, so that no more SMP operations can be performed on this link. |
| BLE_ERROR_INVALID_CONN_HANDLE | If the connection handle is invalid. |
| NRF_ERROR_NOT_FOUND | If the security parameters have not been set. |
| NRF_ERROR_NO_MEM | If there is no more space in flash. |
| NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized, or the peer is disconnected or in the process of disconnecting. |
| NRF_ERROR_INTERNAL | If another error occurred. |
| ret_code_t pm_init | ( | void | ) |
Function for initializing the Peer Manager.
You must initialize the Peer Manager before you can call any other Peer Manager functions.
| NRF_SUCCESS | If initialization was successful. |
| NRF_ERROR_INTERNAL | If another error occurred. |
| ret_code_t pm_lesc_public_key_set | ( | ble_gap_lesc_p256_pk_t * | p_public_key | ) |
Experimental function for specifying the public key to use for LESC operations.
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.
| [in] | p_public_key | The public key to use for all subsequent LESC operations. |
| NRF_SUCCESS | Pairing initiated successfully. |
| NRF_ERROR_INVALID_STATE | Peer Manager is not initialized. |
| void pm_local_database_has_changed | ( | void | ) |
Function for manually informing that the local database has changed.
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 PM_EVT_SERVICE_CHANGED_IND_SENT event occurs, followed by a 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, this no indications are sent peers, and no events are sent to the user.
| pm_peer_id_t pm_next_peer_id_get | ( | pm_peer_id_t | prev_peer_id | ) |
Function for getting the next peer ID in the sequence of all used peer IDs.
This function can be used to loop through all used peer IDs. The order in which peer IDs are returned should be considered unpredictable. PM_PEER_ID_INVALID is considered to be before the first and after the last used peer ID.
To loop through all peer IDs exactly once, use the following constuct:
| [in] | prev_peer_id | The previous peer ID. |
prev_peer_id was PM_PEER_ID_INVALID, the next peer ID is the first used peer ID. If prev_peer_id was the last used peer ID, the function returns PM_PEER_ID_INVALID. | void pm_on_ble_evt | ( | ble_evt_t * | p_ble_evt | ) |
Function for passing BLE events to the Peer Manager.
For the module to work as expected, this function must be called with each BLE event from the SoftDevice. It must be called after ble_conn_state_on_ble_evt, but before the application processes the event.
Calling this function before pm_init is safe, but without effect.
| [in] | p_ble_evt | BLE stack event that is dispatched to the function. |
| uint32_t pm_peer_count | ( | void | ) |
Function for querying the number of valid peer IDs that are available.
This function returns the number of peers for which there is data in persistent storage.
| ret_code_t pm_peer_data_app_data_load | ( | pm_peer_id_t | peer_id, |
| uint8_t * | p_data, | ||
| uint16_t * | p_len | ||
| ) |
Function for reading a peer's application data. (PM_PEER_DATA_ID_APPLICATION).
See pm_peer_data_load for parameters and return values.
| ret_code_t pm_peer_data_app_data_store | ( | pm_peer_id_t | peer_id, |
| uint8_t const * | p_data, | ||
| uint16_t | len, | ||
| pm_store_token_t * | p_token | ||
| ) |
Function for setting or updating a peer's application data. (PM_PEER_DATA_ID_APPLICATION).
See pm_peer_data_store 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 | ||
| ) |
Function for reading a peer's bonding data (PM_PEER_DATA_ID_BONDING).
See pm_peer_data_load 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 | ||
| ) |
Function for setting or updating a peer's bonding data (PM_PEER_DATA_ID_BONDING).
See pm_peer_data_store for parameters and return values.
| ret_code_t pm_peer_data_delete | ( | pm_peer_id_t | peer_id, |
| pm_peer_data_id_t | data_id | ||
| ) |
Function for deleting a peer's stored pieces of data.
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 pm_peer_delete.
| [in] | peer_id | Peer ID to clear data for. |
| [in] | data_id | Which data to clear. |
| NRF_SUCCESS | If the clear procedure was initiated successfully. |
| NRF_ERROR_INVALID_PARAM | If data_id was PM_PEER_DATA_ID_BONDING or invalid, or peer_id was invalid. |
| NRF_ERROR_NOT_FOUND | If there was no data to clear for this peer ID/data ID combination. |
| NRF_ERROR_BUSY | If the underlying flash handler is busy with other flash operations. Try again after receiving a Peer Manager event. |
| NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized. |
| NRF_ERROR_INTERNAL | If another error occurred. |
| ret_code_t pm_peer_data_load | ( | pm_peer_id_t | peer_id, |
| pm_peer_data_id_t | data_id, | ||
| void * | p_data, | ||
| uint16_t * | p_len | ||
| ) |
Function for retrieving stored data of a peer.
| [in] | peer_id | Peer ID to get data for. |
| [in] | data_id | Which type of data to read. |
| [out] | p_data | Where to put the retrieved data. |
| [in,out] | p_len | In: The length in bytes of p_data. Out: The length in bytes of the read data, if the read was successful. |
| NRF_SUCCESS | If the data was read successfully. |
| NRF_ERROR_INVALID_PARAM | If the the data type or the peer ID was invalid or unallocated, or if the length in p_length was not a multiple of 4. |
| NRF_ERROR_NULL | If a pointer parameter was NULL. |
| NRF_ERROR_NOT_FOUND | If no stored data was found for this peer ID/data ID combination. |
| NRF_ERROR_DATA_SIZE | If the provided buffer was not large enough. |
| NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized. |
| ret_code_t pm_peer_data_remote_db_load | ( | pm_peer_id_t | peer_id, |
| ble_gatt_db_srv_t * | p_data, | ||
| uint16_t * | p_len | ||
| ) |
Function for reading a peer's remote DB values. (PM_PEER_DATA_ID_GATT_REMOTE).
See pm_peer_data_load 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, | ||
| uint16_t | len, | ||
| pm_store_token_t * | p_token | ||
| ) |
Function for setting or updating a peer's remote DB values. (PM_PEER_DATA_ID_GATT_REMOTE).
See pm_peer_data_store for parameters and return values.
| ret_code_t pm_peer_data_store | ( | pm_peer_id_t | peer_id, |
| pm_peer_data_id_t | data_id, | ||
| void const * | p_data, | ||
| uint16_t | len, | ||
| pm_store_token_t * | p_token | ||
| ) |
Function for setting or updating stored data of a peer.
| [in] | peer_id | Peer ID to set data for. |
| [in] | data_id | Which type of data to set. |
| [in] | p_data | New value to set. |
| [in] | len | The length in bytes of p_data. |
| [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. |
| NRF_SUCCESS | If the data is scheduled to be written to persistent storage. |
| NRF_ERROR_NULL | If p_data is NULL. |
| NRF_ERROR_NOT_FOUND | If no peer was found for the peer ID. |
| NRF_ERROR_BUSY | If the underlying flash handler is busy with other flash operations. Try again after receiving a Peer Manager event. |
| NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized. |
| ret_code_t pm_peer_delete | ( | pm_peer_id_t | peer_id | ) |
Function for freeing persistent storage for a peer.
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 PM_EVT_PEER_DELETE_SUCCEEDED or PM_EVT_PEER_DELETE_FAILED event is sent.
| [in] | peer_id | Peer ID to be freed and have all associated data deleted. |
| NRF_SUCCESS | If the operation was initiated successfully. |
| NRF_ERROR_INVALID_PARAM | If the peer ID was not valid. |
| 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 | ||
| ) |
Function for getting the peer ID of a connected peer.
| [in] | conn_handle | Connection handle. |
| [out] | p_peer_id | Peer ID, or PM_PEER_ID_INVALID if the peer is not bonded or conn_handle does not refer to a connection. |
| NRF_SUCCESS | If the peer ID was retrieved successfully. |
| NRF_ERROR_NULL | If p_peer_id was NULL. |
| NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized. |
| 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 | ||
| ) |
Function for manually adding a peer to the persistent storage.
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.
| [in] | p_bonding_data | The bonding data of the new peer (must contain a public/static address or a non-zero IRK). |
| [out] | p_new_peer_id | Peer ID for the new peer, or an existing peer if a match was found. |
| [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. |
| NRF_SUCCESS | If the store operation for bonding data was initiated successfully. |
| NRF_ERROR_NULL | If p_bonding_data or p_new_peer_id is NULL. |
| NRF_ERROR_NO_MEM | If there is no more space in persistent storage, so that the new peer cannot be allocated. |
| NRF_ERROR_BUSY | If the underlying flash handler is busy with other flash operations. Try again after receiving a Peer Manager event. |
| NRF_ERROR_INVALID_PARAM | If the bonding data is invalid. |
| NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized. |
| ret_code_t pm_peer_rank_highest | ( | pm_peer_id_t | peer_id | ) |
Function for updating the rank of a peer to be highest among all stored peers.
If this function returns NRF_SUCCESS, either a PM_EVT_PEER_DATA_UPDATE_SUCCEEDED or a PM_EVT_PEER_DATA_UPDATE_FAILED event is sent with a PM_STORE_TOKEN_INVALID store token when the operation is complete. Until the operation is complete, this function returns NRF_ERROR_BUSY.
When the operation is complete, the peer is the highest ranked peer as reported by pm_peer_ranks_get.
| [in] | peer_id | The peer to rank highest. |
| NRF_SUCCESS | If the peer's rank is, or will be updated to be highest. |
| 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. |
| NRF_ERROR_INTERNAL | If another error occurred. |
| NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized. |
| 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 | ||
| ) |
Function for finding the highest and lowest ranked peers.
The rank is saved in persistent storage under the data ID PM_PEER_DATA_ID_PEER_RANK.
The interpretation of rank is up to the user, because the rank is only updated by calling pm_peer_rank_highest or by manipulating the value using a PM_PEER_DATA_FUNCTIONS function.
| [out] | p_highest_ranked_peer | The peer ID with the highest rank of all peers, for example, the most recently used peer. |
| [out] | p_highest_rank | The highest rank. |
| [out] | p_lowest_ranked_peer | The peer ID with the lowest rank of all peers, for example, the least recently used peer. |
| [out] | p_lowest_rank | The lowest rank. |
| NRF_SUCCESS | If the operation completed successfully. |
| NRF_ERROR_NOT_FOUND | If no peers were found. |
| NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized. |
| NRF_ERROR_INTERNAL | If another error occurred. |
| ret_code_t pm_peers_delete | ( | void | ) |
Function for deleting all data stored for all peers.
This function sends either a PM_EVT_PEERS_DELETE_SUCCEEDED or a PM_EVT_PEERS_DELETE_FAILED event. In addition, a PM_EVT_PEER_DELETE_SUCCEEDED or PM_EVT_PEER_DELETE_FAILED event is sent for each deleted peer.
| NRF_SUCCESS | If the deletion process was initiated successfully. |
| NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized. |
| NRF_ERROR_INTERNAL | If another error occurred. |
| ret_code_t pm_register | ( | pm_evt_handler_t | event_handler | ) |
Function for registering an event handler with the Peer Manager.
| [in] | event_handler | Callback for events from the Peer Manager module. event_handler is called for every event that the Peer Manager sends after this function is called. |
| NRF_SUCCESS | If initialization was successful. |
| NRF_ERROR_NULL | If event_handler was NULL. |
| NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized. |
| ret_code_t pm_sec_params_set | ( | ble_gap_sec_params_t * | p_sec_params | ) |
Function for providing pairing and bonding parameters to use for pairing procedures.
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_sec_params, in which case the Peer Manager starts rejecting all procedures again.
| [in] | p_sec_params | Security parameters to be used for subsequent security procedures. |
| NRF_SUCCESS | If the parameters were set successfully. |
| NRF_ERROR_INVALID_PARAM | If the combination of parameters is invalid. |
| NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized. |
| NRF_ERROR_INTERNAL | If another error occurred. |
| ret_code_t pm_whitelist_create | ( | pm_peer_id_t * | p_peer_ids, |
| uint8_t | n_peer_ids, | ||
| ble_gap_whitelist_t * | p_whitelist | ||
| ) |
Function for constructing a whitelist for use when advertising.
This function constructs a whitelist that contains the addresses and IRKs of the provided peer IDs. If p_peer_ids is NULL, the first (lowest) 8 peer IDs are chosen. If ble_gap_whitelist_t::pp_addrs in p_whitelist is NULL, the whitelist contains only IRKs, and vice versa.
| [in] | p_peer_ids | The IDs of the peers to be added to the whitelist, or NULL. |
| [in] | n_peer_ids | The number of peer IDs in p_peer_ids. |
| [in,out] | p_whitelist | The constructed whitelist. Note that p_whitelist->pp_addrs must be NULL or point to an array with size BLE_GAP_WHITELIST_ADDR_MAX_COUNT and p_whitelist->pp_irks must be NULL or point to an array with size BLE_GAP_WHITELIST_IRK_MAX_COUNT. |
| NRF_SUCCESS | If the whitelist was created successfully. |
| NRF_ERROR_NULL | If p_whitelist was NULL. |
| NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized. |
| ret_code_t pm_whitelist_custom | ( | ble_gap_whitelist_t * | p_whitelist | ) |
Function for informing the Peer Manager of what whitelist should be used.
This function should be used if the application wants to use a whitelist that is created in the application. When using Peer Manager, this function must be called to inform that the custom whitelist should be used instead of the one in Peer Manager.
| [in] | p_whitelist | The whitelist. |
| NRF_SUCCESS | If the operation completed successfully. |
| NRF_ERROR_NULL | If p_whitelist was NULL. |
| NRF_ERROR_NOT_FOUND | If one or more of the whitelist's IRKs was not found in the Peer Manager's persistent storage. |
| NRF_ERROR_INVALID_STATE | If the Peer Manager is not initialized. |