Peer Data Storage

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.