Peer Database
[Peer_manager]

Event handler for events from the peer_data_storage module.

Parameters:

[in]

p_event

The event that has happened.

Definition at line 90 of file peer_database.h.

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.

Definition at line 54 of file peer_database.h.

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.

Definition at line 721 of file peer_database.c.

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.

Definition at line 729 of file peer_database.c.

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.

Definition at line 740 of file peer_database.c.

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.

Definition at line 359 of file peer_database.c.

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.

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.

Definition at line 370 of file peer_database.c.

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.
	inout]	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.

Definition at line 751 of file peer_database.c.

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.

Definition at line 760 of file peer_database.c.

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.

Definition at line 378 of file peer_database.c.

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.

Definition at line 326 of file peer_database.c.

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.

Definition at line 429 of file peer_database.c.

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.

Definition at line 536 of file peer_database.c.

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.

Definition at line 630 of file peer_database.c.

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.

Definition at line 564 of file peer_database.c.