Peer Manager

Macro to check whether a data type is valid, thus one of the valid enum values.

Parameters

[in]

data_id

The data type to check.

Event handler for events from the Peer Manager module.

See Also

pm_register

Parameters

[in]

p_event

The event that has occurred.

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.

Types of events that can come from the Peer Manager module.

The different types of data associated with a peer.

Actions that can be performed to peer data in persistent storage.

Function for getting the connection handle of the connection with a bonded peer.

Parameters

[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.

Return values

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.

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.

Parameters

[in]	conn_handle	The connection to set the configuration for.
[in]	p_conn_sec_config	The configuration.

Function for getting the security status of a connection.

Parameters

[in]	conn_handle	Connection handle of the link as provided by the SoftDevice.
[out]	p_conn_sec_status	Security status of the link.

Return values

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.

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.

Parameters

[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.

Return values

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.

Function for initializing the Peer Manager.

You must initialize the Peer Manager before you can call any other Peer Manager functions.

Return values

NRF_SUCCESS	If initialization was successful.
NRF_ERROR_INTERNAL	If another error occurred.

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.

Note

The key must continue to reside in application memory as it is not copied by Peer Manager.

Parameters

[in]

p_public_key

The public key to use for all subsequent LESC operations.

Return values

NRF_SUCCESS	Pairing initiated successfully.
NRF_ERROR_INVALID_STATE	Peer Manager is not initialized.

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.

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:

Parameters

[in]

prev_peer_id

The previous peer ID.

Returns

The next peer ID. If 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 .

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.

Parameters

[in]

p_ble_evt

BLE stack event that is dispatched to the function.

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.

Returns

The number of valid peer IDs.

Function for reading a peer's application data. ( PM_PEER_DATA_ID_APPLICATION ).

See pm_peer_data_load for parameters and return values.

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.

Function for reading a peer's bonding data ( PM_PEER_DATA_ID_BONDING ).

See pm_peer_data_load for parameters and return values.

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.

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 .

Note

Clearing data in persistent storage happens asynchronously.

Parameters

[in]	peer_id	Peer ID to clear data for.
[in]	data_id	Which data to clear.

Return values

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.

Function for retrieving stored data of a peer.

Note

The length of the provided buffer must be a multiple of 4.

Parameters

[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.

Return values

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.

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.

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.

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.

The data written using this function may 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.

Parameters

[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.

Return values

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.

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.

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.

Parameters

[in]

peer_id

Peer ID to be freed and have all associated data deleted.

Return values

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.

Function for getting the peer ID of a connected peer.

Parameters

[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.

Return values

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.

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.

Parameters

[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.

Return values

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.

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 .

Note

The PM_EVT_PEER_DATA_UPDATE_SUCCEEDED event can arrive before the function returns if the peer is already ranked highest. In this case, the pm_peer_data_update_succeeded_evt_t::flash_changed flag in the event will be false.

Parameters

[in]

peer_id

The peer to rank highest.

Return values

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.

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.

Note

Any argument that is NULL is ignored.

Parameters

[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.

Return values

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.

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.

Note

No event is sent when there is no peer data in flash.

Warning

Use this function only when not connected or connectable. If a peer is or becomes connected or a PM_PEER_DATA_FUNCTIONS function is used during this procedure (until the success or failure event happens), the behavior is undefined.

Return values

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.

Function for registering an event handler with the Peer Manager.

Parameters

[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.

Return values

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.

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.

Parameters

[in]

p_sec_params

Security parameters to be used for subsequent security procedures.

Return values

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.

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.

Note

When using a whitelist, always use the whitelist that was created or set by the most recent call to this function or to pm_whitelist_custom .

Do not call this function while advertising or scanning with another whitelist.

Parameters

[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 .

Return values

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.

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.

Note

When using a whitelist, always use the whitelist that was created or set by the most recent call to this function or to pm_whitelist_create .

Do not call this function while advertising or scanning with another whitelist.

Do not add any IRKs to the whitelist that are not present in the Peer Manager's persistent storage.

Parameters

[in]

p_whitelist

The whitelist.

Return values

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.