An internal module of Peer Manager . This module provides a Peer Manager-specific API to the persistent storage. More...

Data Structures
struct	pds_evt_t
	Events that can come from the peer_data_storage module. More...

Macros
#define	PDS_PREPARE_TOKEN_INVALID 0

#define	PDS_STORE_TOKEN_INVALID 0

Typedefs
typedef void(*	pds_evt_handler_t )( pds_evt_t const *p_event)
	Event handler for events from the peer_data_storage module. More...

Enumerations
enum	pds_convert_t { peer_id_to_instance_id = 16384, instance_id_to_peer_id = -peer_id_to_instance_id, peer_data_id_to_type_id = 32768, type_id_to_peer_data_id = -peer_data_id_to_type_id }

enum	pds_evt_id_t { PDS_EVT_STORED , PDS_EVT_CLEARED , PDS_EVT_PEER_ID_CLEAR , PDS_EVT_ERROR_STORE , PDS_EVT_ERROR_CLEAR , PDS_EVT_ERROR_PEER_ID_CLEAR , PDS_EVT_COMPRESSED }
	The types of events that can come from the peer_data_storage module. More...

Functions
ret_code_t	pds_register ( pds_evt_handler_t evt_handler)
	Function for registering for events from the peer database. More...

ret_code_t	pds_peer_data_read_ptr_get ( pm_peer_id_t peer_id, pm_peer_data_id_t data_id, pm_peer_data_flash_t p_data, pm_store_token_t p_token)
	Function for retrieving a direct pointer to peer data in persistent storage. More...

ret_code_t	pds_peer_data_lock ( pm_store_token_t store_token)
	Function to lock the flash data (to defer compression from invalidating data) More...

ret_code_t	pds_peer_data_verify ( pm_store_token_t store_token)
	Function to verify flash data integrity. More...

ret_code_t	pds_peer_data_read ( pm_peer_id_t peer_id, pm_peer_data_id_t data_id, pm_peer_data_t p_data, fds_length_t p_len_words)
	Function for retrieving peer data from persistent storage by making a copy. More...

ret_code_t	pds_peer_data_write_prepare ( pm_peer_data_const_t const p_peer_data, pm_prepare_token_t p_prepare_token)
	Function for preparing persistent storage for a write. More...

ret_code_t	pds_peer_data_write_prepare_cancel ( pm_prepare_token_t prepare_token)
	Function for undoing a previous call to pds_peer_data_write_prepare . More...

ret_code_t	pds_peer_data_write_prepared ( pm_peer_id_t peer_id, pm_peer_data_const_t const p_peer_data, pm_prepare_token_t prepare_token, pm_store_token_t p_store_token)
	Function for writing prepared (reserved) peer data to persistent storage. More...

ret_code_t	pds_peer_data_write ( pm_peer_id_t peer_id, pm_peer_data_const_t const p_peer_data, pm_store_token_t p_store_token)
	Function for writing peer data to persistent storage. More...

ret_code_t	pds_peer_data_update ( pm_peer_id_t peer_id, pm_peer_data_const_t const peer_data, pm_store_token_t old_token, pm_store_token_t p_store_token)
	Function for updating currently stored peer data to a new version. More...

ret_code_t	pds_peer_data_clear ( pm_peer_id_t peer_id, pm_peer_data_id_t data_id)
	Function for clearing peer data from persistent storage. More...

pm_peer_id_t	pds_peer_id_allocate (void)
	Function for claiming an unused peer ID. More...

ret_code_t	pds_peer_id_free ( pm_peer_id_t peer_id)
	Function for freeing a peer ID and clearing all data associated with it in persistent storage. More...

bool	pds_peer_id_is_allocated ( pm_peer_id_t peer_id)
	Function for finding out whether a peer ID is in use. More...

pm_peer_id_t	pds_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. Can be used to loop through all used peer IDs. More...

uint32_t	pds_n_peers (void)
	Function for querying the number of valid peer IDs available. I.E the number of peers in persistent storage. More...

Detailed Description

An internal module of Peer Manager . This module provides a Peer Manager-specific API to the persistent storage.

Typedef Documentation

typedef void(* pds_evt_handler_t)( pds_evt_t const *p_event)

Event handler for events from the peer_data_storage module.

Parameters

[in]	event	The event that has happened.
[in]	peer_id	The id of the peer the event pertains to.
[in]	flags	The data the event pertains to.

Enumeration Type Documentation

enum pds_evt_id_t

The types of events that can come from the peer_data_storage module.

Enumerator
PDS_EVT_STORED	The specified data has been successfully stored.
PDS_EVT_CLEARED	The specified data has been successfully cleared.
PDS_EVT_PEER_ID_CLEAR	The peer id has been successfully cleared.
PDS_EVT_ERROR_STORE	The specified data could not be stored.
PDS_EVT_ERROR_CLEAR	The specified data could not be cleared.
PDS_EVT_ERROR_PEER_ID_CLEAR	The peer id has been successfully cleared.
PDS_EVT_COMPRESSED	A compress procedure has finished successfully.

Function Documentation

uint32_t pds_n_peers ( void )

Function for querying the number of valid peer IDs available. I.E the number of peers in persistent storage.

Returns: The number of valid peer IDs, or 0 if module is not initialized.

pm_peer_id_t pds_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. Can be used to loop through all used peer IDs.

Note: PM_PEER_ID_INVALID is considered to be before the first and after the last ordinary peer ID.

Parameters

[in] prev_peer_id The previous peer ID.

Returns: The next peer ID.; The first ordinary peer ID if prev_peer_id was PM_PEER_ID_INVALID .

Return values

PM_PEER_ID_INVALID if prev_peer_id was the last ordinary peer ID or the module is not initialized.

ret_code_t pds_peer_data_clear	(	pm_peer_id_t	peer_id ,
		pm_peer_data_id_t	data_id
	)

Function for clearing peer data from persistent storage.

Clearing happens asynchronously. Expect a PDS_EVT_CLEARED or PDS_EVT_ERROR_CLEAR event.

Parameters

[in]	peer_id	The id of the peer the data pertains to.
[in]	data_id	Which data to clear.

Return values

NRF_SUCCESS	The clear was initiated successfully.
NRF_ERROR_INVALID_PARAM	Data ID or was invalid.
NRF_ERROR_NOT_FOUND	Nothing to clear for this peer ID.
NRF_ERROR_INVALID_STATE	Module is not initialized.

ret_code_t pds_peer_data_lock ( pm_store_token_t store_token )

Function to lock the flash data (to defer compression from invalidating data)

Parameters

[in] store_token The token representing the item to lock

ret_code_t pds_peer_data_read	(	pm_peer_id_t	peer_id ,
		pm_peer_data_id_t	data_id ,
		pm_peer_data_t *	p_data ,
		fds_length_t *	p_len_words
	)

Function for retrieving peer data from persistent storage by making a copy.

Parameters

[in]	peer_id	The id of the peer whose data to read.
[in]	data_id	Which piece of data to read.
[out]	p_data	Pointer to the peer data.
[in,out]	p_len_words	Length available to copy to (in words). If set to NULL, then no copy will be made and the length will be reflected in p_len_words after the call returns.

Return values

NRF_SUCCESS	The read was successful.
NRF_ERROR_INVALID_PARAM	Invalid data_id.
NRF_ERROR_NULL	data contained a NULL pointer.
NRF_ERROR_NOT_FOUND	The requested data was not found in persistent storage.
NRF_ERROR_NO_MEM	The length of stored data too large to copy out
NRF_ERROR_INVALID_STATE	Module is not initialized.

ret_code_t pds_peer_data_read_ptr_get	(	pm_peer_id_t	peer_id ,
		pm_peer_data_id_t	data_id ,
		pm_peer_data_flash_t *	p_data ,
		pm_store_token_t *	p_token
	)

Function for retrieving a direct pointer to peer data in persistent storage.

Parameters

[in]	peer_id	The id of the peer whose data to read.
[in]	data_id	Which data to get.
[out]	p_data	The peer data pointer.
[out]	p_token	Token that can be used to lock data in flash and check data validity.

Return values

NRF_SUCCESS	The pointer was successfully retrieved.
NRF_ERROR_INVALID_PARAM	Invalid data_id.
NRF_ERROR_NULL	p_data was NULL.
NRF_ERROR_NOT_FOUND	The requested data was not found in persistent storage.
NRF_ERROR_INVALID_STATE	Module is not initialized.

ret_code_t pds_peer_data_update	(	pm_peer_id_t	peer_id ,
		pm_peer_data_const_t const *	peer_data ,
		pm_store_token_t	old_token ,
		pm_store_token_t *	p_store_token
	)

Function for updating currently stored peer data to a new version.

Updating happens asynchronously. Expect a PDS_EVT_STORED or PDS_EVT_ERROR_STORE for the store token and a PDS_EVT_ERROR_CLEAR or PDS_EVT_ERROR_CLEAR for the old token

Parameters

[in]	peer_id	The peer which the data is associated to.
[in]	peer_data	New data.
[in]	old_token	Store token for the old data.
[out]	p_store_token	Store token for the new data.

Return values

NRF_SUCESS	The update was initiated successfully
NRF_ERROR_NOT_FOUND	The old store token was invalid.
NRF_ERROR_NULL	Data contained a NULL pointer.
NRF_ERROR_NO_MEM	No space available in persistent storage.
NRF_ERROR_BUSY	FDS or underlying modules are busy and can't take any more requests
NRF_ERROR_INVALID_STATE	Module is not initialized.

ret_code_t pds_peer_data_verify ( pm_store_token_t store_token )

Function to verify flash data integrity.

Parameters

[in] store_token The token representing the item to lock

Return values

NRF_SUCCESS	The data integrity is valid.
NRF_ERROR_NULL	The token is invalid.
NRF_ERROR_INVALID_DATA	The data integrity is not valid.
NRF_ERROR_INVALID_STATE	Module is not initialized.

ret_code_t pds_peer_data_write	(	pm_peer_id_t	peer_id ,
		pm_peer_data_const_t const *	p_peer_data ,
		pm_store_token_t *	p_store_token
	)

Function for writing peer data to persistent storage.

Writing happens asynchronously. Expect a PDS_EVT_STORED or PDS_EVT_ERROR_STORE event.

Parameters

[in]	peer_id	The id of the peer the data pertains to.
[in]	p_peer_data	The peer data.
[out]	p_store_token	A token identifying this particular store operation. The token can be used to identify events pertaining to this operation.

Return values

NRF_SUCCESS	The write was initiated successfully.
NRF_ERROR_INVALID_PARAM	Invalid data ID or store_flags.
NRF_ERROR_NULL	Data contained a NULL pointer.
NRF_ERROR_NO_MEM	No space available in persistent storage. This can only happen if p_prepare_token is NULL.
NRF_ERROR_BUSY	FDS or underlying modules are busy and can't take any more requests
NRF_ERROR_INVALID_STATE	Module is not initialized.

ret_code_t pds_peer_data_write_prepare	(	pm_peer_data_const_t const *	p_peer_data ,
		pm_prepare_token_t *	p_prepare_token
	)

Function for preparing persistent storage for a write.

If this call succeeds, space is reserved in persistent storage, so the write will fit.

Note: If space has already been prepared for this peer_id/data_id pair, no new space will be reserved, unless the previous reservation had too small size.

Parameters

[in]	p_peer_data	Data to prepare for. The data needs not be ready, but length and type values must.
[out]	p_prepare_token	A token identifying the prepared memory area.

Return values

NRF_SUCCESS	The call was successful.
NRF_ERROR_INVALID_PARAM	Invalid data ID.
NRF_ERROR_INVALID_LENGTH	Data length above the maximum allowed.
NRF_ERROR_NO_MEM	No space available in persistent storage.
NRF_ERROR_INVALID_STATE	Module is not initialized.

ret_code_t pds_peer_data_write_prepare_cancel ( pm_prepare_token_t prepare_token )

Function for undoing a previous call to pds_peer_data_write_prepare .

Parameters

[in] prepare_token A token identifying the prepared memory area to cancel.

Return values

NRF_SUCCESS	The call was successful.
NRF_ERROR_NOT_FOUND	Invalid peer ID and/or prepare token.
NRF_ERROR_INVALID_STATE	Module is not initialized.

ret_code_t pds_peer_data_write_prepared	(	pm_peer_id_t	peer_id ,
		pm_peer_data_const_t const *	p_peer_data ,
		pm_prepare_token_t	prepare_token ,
		pm_store_token_t *	p_store_token
	)

Function for writing prepared (reserved) peer data to persistent storage.

Writing happens asynchronously. Expect a PDS_EVT_STORED or PDS_EVT_ERROR_STORE event.

Parameters

[in]	peer_id	The id of the peer the data pertains to.
[in]	p_peer_data	The peer data.
[in]	prepare_token	A token identifying the prepared memory area to write into. If the prepare token is invalid, e.g. PDS_PREPARE_TOKEN_INVALID, the prepare/write sequence will happen atomically.
[out]	p_store_token	A token identifying this particular store operation. The token can be used to identify events pertaining to this operation.

Return values

NRF_SUCCESS	The write was initiated successfully.
NRF_ERROR_INVALID_PARAM	Invalid data ID or store_flags.
NRF_ERROR_INVALID_LENGTH	Length of data longer than in prepare call.
NRF_ERROR_NULL	data contained a NULL pointer.
NRF_ERROR_NO_MEM	No space available in persistent storage. This can only happen if p_prepare_token is NULL.
NRF_ERROR_BUSY	FDS or underlying modules are busy and can't take any more requests
NRF_ERROR_INVALID_STATE	Module is not initialized.

pm_peer_id_t pds_peer_id_allocate ( void )

Function for claiming an unused peer ID.

Returns: The first unused peer ID.

Return values

PM_PEER_ID_INVALID If no peer ID is available or module is not initialized.

ret_code_t pds_peer_id_free ( pm_peer_id_t peer_id )

Function for freeing a peer ID and clearing all data associated with it in persistent storage.

Parameters

[in] peer_id Peer ID to free.

Return values

NRF_SUCCESS	The clear was initiated successfully
NRF_ERROR_BUSY	Another peer_id clear was already requested or fds queue full

bool pds_peer_id_is_allocated ( pm_peer_id_t peer_id )

Function for finding out whether a peer ID is in use.

Parameters

[in] peer_id The peer ID to inquire about.

Return values

true	peer_id is in use.
false	peer_id is free, or the module is not initialized.

ret_code_t pds_register ( pds_evt_handler_t evt_handler )

Function for registering for events from the peer database.

Note: This function will initialize the module if it is not already initialized.

Parameters

[in] evt_handler Event handler to register.

Return values

NRF_SUCCESS	Registration successful.
NRF_ERROR_NO_MEM	No more event handlers can be registered.
NRF_ERROR_NULL	evt_handler was NULL.
NRF_ERROR_INVALID_PARAM	Unexpected return code from pm_buffer_init .
NRF_ERROR_INVALID_STATE	FDS has not been initalized.

Peer Data Storage

nRF5 SDK v10.0.0

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation