Peer Database

An internal module of Peer Manager. A module for simple management of reading and writing of peer data into persistent storage. More...

Data Structures
struct	pdb_evt_t
	Events that can come from the peer_database module. More...

Macros
#define	PDB_WRITE_BUF_SIZE   (sizeof(pm_peer_data_bonding_t))

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

Enumerations
enum	pdb_evt_id_t {   PDB_EVT_WRITE_BUF_STORED,   PDB_EVT_RAW_STORED,   PDB_EVT_RAW_STORE_FAILED,   PDB_EVT_CLEARED,   PDB_EVT_CLEAR_FAILED,   PDB_EVT_COMPRESSED,   PDB_EVT_ERROR_NO_MEM,   PDB_EVT_ERROR_UNEXPECTED }
	Events that can come from the peer_database module. More...

Functions
ret_code_t	pdb_register (pdb_evt_handler_t evt_handler)
	Function for registering for events from the peer database. More...
pm_peer_id_t	pdb_peer_allocate (void)
	Function for allocating persistent bond storage for a peer. More...
ret_code_t	pdb_peer_free (pm_peer_id_t peer_id)
	Function for freeing a peer's persistent bond storage. More...
ret_code_t	pdb_read_buf_get (pm_peer_id_t peer_id, pm_peer_data_id_t data_id, pm_peer_data_flash_t *p_peer_data, pm_store_token_t *p_token)
	Function for retrieving pointers to read-only peer data. More...
ret_code_t	pdb_write_buf_get (pm_peer_id_t peer_id, pm_peer_data_id_t data_id, uint32_t n_bufs, pm_peer_data_t *p_peer_data)
	Function for retrieving pointers to a write buffer for peer data. More...
ret_code_t	pdb_write_buf_release (pm_peer_id_t peer_id, pm_peer_data_id_t data_id)
	Function for freeing a write buffer allocated with pdb_write_buf_get. More...
ret_code_t	pdb_write_buf_store_prepare (pm_peer_id_t peer_id, pm_peer_data_id_t data_id)
	Function for reserving space in persistent storage for data in a buffer. More...
ret_code_t	pdb_write_buf_store (pm_peer_id_t peer_id, pm_peer_data_id_t data_id)
	Function for writing data into persistent storage. Writing happens asynchronously. More...
ret_code_t	pdb_clear (pm_peer_id_t peer_id, pm_peer_data_id_t data_id)
	Function for clearing data from persistent storage. More...
uint32_t	pdb_n_peers (void)
	Function for querying the number of valid peer IDs available. I.E the number of peers in persistent storage. More...
pm_peer_id_t	pdb_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...
ret_code_t	pdb_peer_data_update (pm_peer_data_const_t 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	pdb_raw_read (pm_peer_id_t peer_id, pm_peer_data_id_t data_id, pm_peer_data_t *p_peer_data)
	Function for reading data directly from persistent storage to external memory. More...
ret_code_t	pdb_raw_store (pm_peer_id_t peer_id, pm_peer_data_const_t *p_peer_data, pm_store_token_t *p_store_token)
	Function for writing data directly to persistent storage from external memory. More...

Detailed Description

An internal module of Peer Manager. A module for simple management of reading and writing of peer data into persistent storage.

Typedef Documentation

typedef void(* pdb_evt_handler_t)(pdb_evt_t const *p_event)

Event handler for events from the peer_data_storage module.

Parameters

[in]

p_event

The event that has happened.

Enumeration Type Documentation

enum pdb_evt_id_t

Events that can come from the peer_database module.

Enumerator
PDB_EVT_WRITE_BUF_STORED	A pdb_write_buf_store operation has completed successfully.
PDB_EVT_RAW_STORED	A pdb_raw_store operation has completed successfully.
PDB_EVT_RAW_STORE_FAILED	A pdb_raw_store operation has failed.
PDB_EVT_CLEARED	A pdb_clear operation has completed successfully.
PDB_EVT_CLEAR_FAILED	A pdb_clear operation has failed.
PDB_EVT_COMPRESSED	A compress procedure has completed.
PDB_EVT_ERROR_NO_MEM	An operation is blocked because the flash is full. It will be reattempted automatically after the next compress procedure.
PDB_EVT_ERROR_UNEXPECTED	An unexpected error occurred. This is a fatal error.

Function Documentation

ret_code_t pdb_clear	(	pm_peer_id_t	peer_id,
		pm_peer_data_id_t	data_id
	)

Function for clearing data from persistent storage.

Parameters

[in]	peer_id	ID of peer to clear data for.
[in]	data_id	Which piece of data to clear.

Return values

NRF_SUCCESS	Data clear was successfully started.
NRF_ERROR_INVALID_PARAM	Data ID was invalid.
NRF_ERROR_NOT_FOUND	Nothing to clear for this data for this peer ID.
NRF_ERROR_BUSY	Could not process request at this time. Reattempt later.
NRF_ERROR_INVALID_STATE	Module is not initialized.

uint32_t pdb_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.

pm_peer_id_t pdb_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.

pm_peer_id_t pdb_peer_allocate

(

void

)

Function for allocating persistent bond storage for a peer.

Returns

The ID of the newly allocated storage.

Return values

PM_PEER_ID_INVALID

If no peer ID is available.

ret_code_t pdb_peer_data_update	(	pm_peer_data_const_t	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_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 pdb_peer_free

(

pm_peer_id_t

peer_id

)

Function for freeing a peer's persistent bond storage.

Note

This function will call pdb_write_buf_release on the data for this peer.

Parameters

[in]

peer_id

ID to be freed.

Return values

NRF_SUCCESS	Peer ID was released and clear operation was initiated successfully.
NRF_ERROR_BUSY	Another peer_id clear was already requested or could not be started.
NRF_ERROR_INVALID_STATE	Module is not initialized.

ret_code_t pdb_raw_read	(	pm_peer_id_t	peer_id,
		pm_peer_data_id_t	data_id,
		pm_peer_data_t *	p_peer_data
	)

Function for reading data directly from persistent storage to external memory.

Parameters

[in]	peer_id	ID of peer to read data for.
[in]	data_id	Which piece of data to read.
[in,out]	p_peer_data	Where to store the data. If the data to be read has variable length, the appropriate length field needs to reflect the available buffer space. On a successful read, the length field is updated to match the length of the read data.

Return values

NRF_SUCCESS	Data successfully read.
NRF_ERROR_INVALID_PARAM	Data ID or Peer ID was invalid or unallocated.
NRF_ERROR_NULL	p_peer_data contained a NULL pointer.
NRF_ERROR_NOT_FOUND	This data was not found for this peer ID.
NRF_ERROR_DATA_SIZE	The provided buffer was not large enough.
NRF_ERROR_INVALID_STATE	Module is not initialized.

ret_code_t pdb_raw_store	(	pm_peer_id_t	peer_id,
		pm_peer_data_const_t *	p_peer_data,
		pm_store_token_t *	p_store_token
	)

Function for writing data directly to persistent storage from external memory.

Parameters

[in]	peer_id	ID of peer to write data for.
[in]	p_peer_data	Data to store.
[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	Data successfully written.
NRF_ERROR_INVALID_PARAM	Data ID or Peer ID was invalid or unallocated.
NRF_ERROR_NULL	p_peer_data contained a NULL pointer.
NRF_ERROR_NO_MEM	No space available in persistent storage.
NRF_ERROR_INVALID_LENGTH	Data length above the maximum allowed.
NRF_ERROR_INVALID_STATE	Module is not initialized.

ret_code_t pdb_read_buf_get	(	pm_peer_id_t	peer_id,
		pm_peer_data_id_t	data_id,
		pm_peer_data_flash_t *	p_peer_data,
		pm_store_token_t *	p_token
	)

Function for retrieving pointers to read-only peer data.

Note

Reading this pointer is not safe in the strictest sense. If a safe read is required:

• Disable interrupts
• Call this function. If the return code is NRF_SUCCESS, the following read is safe.
• Read memory.
• Enable interrupts.

This buffer does not need to be released. It is a pointer directly to flash.

Parameters

[in]	peer_id	ID of peer to retrieve data for.
[in]	data_id	Which piece of data to get.
[out]	p_peer_data	Pointer to immutable peer data.
[out]	p_token	Token that can be used to lock data in flash and check data validity.

Return values

NRF_SUCCESS	Data retrieved successfully.
NRF_ERROR_INVALID_PARAM	Data ID or Peer ID was invalid or unallocated.
NRF_ERROR_NULL	p_peer_data was NULL.
NRF_ERROR_NOT_FOUND	This data was not found for this peer ID.
NRF_ERROR_INVALID_STATE	Module is not initialized.

ret_code_t pdb_register

(

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

ret_code_t pdb_write_buf_get	(	pm_peer_id_t	peer_id,
		pm_peer_data_id_t	data_id,
		uint32_t	n_bufs,
		pm_peer_data_t *	p_peer_data
	)

Function for retrieving pointers to a write buffer for peer data.

This function will provide pointers to a buffer of the data. The data buffer will not be written to persistent storage until pdb_write_buf_store is called. The buffer is released by calling either pdb_write_buf_release, pdb_write_buf_store, or pdb_peer_free.

When the data_id refers to a variable length data type, the available size is written to the data, both the top-level, and any internal length fields.

Note

Calling this function on a peer_id/data_id pair that already has a buffer created will give the same buffer, not create a new one. If n_bufs was increased since last time, the buffer might be relocated to be able to provide additional room. In this case, the data will be copied. If n_bufs was increased since last time, this function might return NRF_ERROR_BUSY. In that case, the buffer is automatically released.

Parameters

[in]	peer_id	ID of peer to get a write buffer for.
[in]	data_id	Which piece of data to get.
[in]	n_bufs	The number of contiguous buffers needed.
[out]	p_peer_data	Pointers to mutable peer data.

Return values

NRF_SUCCESS	Data retrieved successfully.
NRF_ERROR_INVALID_PARAM	Data ID or Peer ID was invalid or unallocated, or n_bufs was 0 or more than the total available buffers.
NRF_ERROR_NULL	p_peer_data was NULL.
NRF_ERROR_BUSY	Not enough buffer(s) available.
NRF_ERROR_INTERNAL	Unexpected internal error.
NRF_ERROR_INVALID_STATE	Module is not initialized.

ret_code_t pdb_write_buf_release	(	pm_peer_id_t	peer_id,
		pm_peer_data_id_t	data_id
	)

Function for freeing a write buffer allocated with pdb_write_buf_get.

Note

This function will not write peer data to persistent memory. Data in released buffer will be lost.

This function will undo any previous call to pdb_write_buf_store_prepare for this piece of data.

Parameters

[in]	peer_id	ID of peer to release buffer for.
[in]	data_id	Which piece of data to release buffer for.

Return values

NRF_SUCCESS	Successfully released buffer.
NRF_ERROR_NOT_FOUND	No buffer was allocated for this peer ID/data ID pair.
NRF_ERROR_INVALID_STATE	Module is not initialized.
NRF_ERROR_INTERNAL	Unexpected internal error.

ret_code_t pdb_write_buf_store	(	pm_peer_id_t	peer_id,
		pm_peer_data_id_t	data_id
	)

Function for writing data into persistent storage. Writing happens asynchronously.

Note

This will unlock the data after it has been written.

Parameters

[in]	peer_id	ID of peer to store data for.
[in]	data_id	Which piece of data to store.

Return values

NRF_SUCCESS	Data storing was successfully started.
NRF_ERROR_NO_MEM	No space available in persistent storage. Please clear some space, the operation will be reattempted after the next compress procedure. This error will not happen if pdb_write_buf_store_prepare is called beforehand.
NRF_ERROR_INVALID_PARAM	Data ID was invalid.
NRF_ERROR_NOT_FOUND	No buffer has been allocated for this peer ID/data ID pair.
NRF_ERROR_INVALID_STATE	Module is not initialized.
NRF_ERROR_INTERNAL	Unexpected internal error.

ret_code_t pdb_write_buf_store_prepare	(	pm_peer_id_t	peer_id,
		pm_peer_data_id_t	data_id
	)

Function for reserving space in persistent storage for data in a buffer.

Note

This function only works for data which has a write buffer allocated. If the write buffer is released, this prepare is undone.

If space has already been reserved for this data, nothing is done.

Parameters

[in]	peer_id	The peer whose data to reserve space for.
[in]	data_id	The type of data to reserve space for.

Return values

NRF_SUCCESS	Successfully reserved space in persistent storage.
NRF_ERROR_NO_MEM	Not enough room in persistent storage.
NRF_ERROR_BUSY	Could not process request at this time. Reattempt later.
NRF_ERROR_NOT_FOUND	No buffer has been allocated for this peer ID/data ID pair.
NRF_ERROR_INVALID_PARAM	Data ID or Peer ID was invalid or unallocated.
NRF_ERROR_INVALID_STATE	Module is not initialized.