Peer Database

nRF5 SDK v10.0.0
nRF51 SDK v10.0.0
Data Structures | Macros | Typedefs | Enumerations | Functions

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.

Please send us your feedback about the documentation! For technical questions, visit the Nordic Developer Zone .