nRF51 SDK: Functions

| nRF51 SDK

- Home
- Related Pages
- API Reference
- Data Structures

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions
Functions
Bonds and Persistent Data Manager

Functions/APIs implemented and exposed by this module. More...

## Functions

uint32_t | ble_bondmngr_init (ble_bondmngr_init_t *p_init)
| Function for initializing the Bond Manager. More...
void | ble_bondmngr_on_ble_evt (ble_evt_t *p_ble_evt)
| Function for handling all events from the BLE stack that relate to this module. More...
uint32_t | ble_bondmngr_bonded_centrals_store (void)
| Function for storing the bonded centrals data including bonding info and System Attributes into flash memory. More...
uint32_t | ble_bondmngr_bonded_centrals_delete (void)
| Function for deleting the bonded central database from flash. More...
uint32_t | ble_bondmngr_whitelist_get (ble_gap_whitelist_t *p_whitelist)
| Function for getting the whitelist containing all currently bonded centrals. More...
uint32_t | ble_bondmngr_central_addr_get (int8_t central_handle, ble_gap_addr_t *p_central_addr)
| Function for getting the central's address corresponding to a given central_handle. More...
uint32_t | ble_bondmngr_sys_attr_store (void)
| Function for storing the System Attributes of a newly connected central. More...
uint32_t | ble_bondmngr_central_ids_get (uint16_t *p_central_ids, uint16_t *p_length)
| Function for fetching the identifiers of known centrals. More...
uint32_t | ble_bondmngr_bonded_central_delete (uint16_t central_id)
| Function for deleting a single central from the database. More...
uint32_t | ble_bondmngr_is_link_encrypted (bool *status)
| Function to verify encryption status link with bonded central is encrypted or not. More...

## Detailed Description

Functions/APIs implemented and exposed by this module.

## Function Documentation

uint32_t ble_bondmngr_bonded_central_delete | ( | uint16_t | central_id | ) |

Function for deleting a single central from the database.

This function deletes the Bonding Information and System Attributes of a single central from the flash. The application can use the ble_bondmngr_central_ids_get function to fetch the identifiers of centrals present in the database and then call this function.

Warning
  This function could prevent the radio from running. Therefore it MUST be called ONLY when the application knows that the Bluetooth radio is not active. An example of such a state could be when the application is not in a connected state AND is also not advertising. If it is called in any other state, the behavior is undefined.

Parameters

  [in] | central_id | Identifier of the central to be deleted.

Returns
  NRF_SUCCESS on success. NRF_ERROR_INVALID_STATE is returned if the bond manager was not initialized. NRF_ERROR_NOT_FOUND if the central with the given identifier is not found in the database.

uint32_t ble_bondmngr_bonded_centrals_delete | ( | void |  | ) |

Function for deleting the bonded central database from flash.

After calling this function you should call ble_bondmngr_init() to re-initialize the RAM database.

Returns
  NRF_SUCCESS on success, an error_code otherwise.

uint32_t ble_bondmngr_bonded_centrals_store | ( | void |  | ) |

Function for storing the bonded centrals data including bonding info and System Attributes into flash memory.

If the data to be written is different from the existing data, this function erases the flash pages before writing to flash.

Warning
  This function could prevent the radio from running. Therefore it MUST be called ONLY when the application knows that the Bluetooth radio is not active. An example of such a state is when the application has received the Disconnected event and has not yet started advertising. If it is called in any other state, or if it is not called at all, the behavior is undefined.

Returns
  NRF_SUCCESS on success, an error_code otherwise.

uint32_t ble_bondmngr_central_addr_get | ( | int8_t | central_handle,
|  | ble_gap_addr_t * | p_central_addr
| ) |  |

Function for getting the central's address corresponding to a given central_handle.

Note
  This function returns NRF_ERROR_INVALID_PARAM if the given central has a private address.

Parameters

  [in] | central_handle | Central's handle.
  [out] | p_central_addr | Pointer to the central's address which can be used for directed advertising.

uint32_t ble_bondmngr_central_ids_get | ( | uint16_t * | p_central_ids,
|  | uint16_t * | p_length
| ) |  |

Function for fetching the identifiers of known centrals.

This function fetches the identifiers of the centrals that are currently in the database, or in other words, known to the bond manager.

Parameters

  [out] | p_central_ids | Pointer to the array of central identifiers. It is recommended that the length of this array be equal to MAX_NUMBER_OF_BONDED_CENTRALS * 2 bytes. If value of this pointer is NULL, only the number of centrals in the database will be filled in p_length. This can be used to find out the required size of the array pointed to by p_central_ids in a subsequent call.
  [in,out] | p_length | Pointer to the length of p_central_ids array provided as input. On return, this function will write the number of central identifiers found to p_length

Returns
  NRF_SUCCESS on success. NRF_ERROR_NULL if the input parameter p_length is NULL. NRF_ERROR_INVALID_STATE is returned if the bond manager was not initialized. NRF_ERROR_DATA_SIZE is returned if the length of the input parameter p_central_ids provided is not enough to fit in all the central identifiers in the database.

uint32_t ble_bondmngr_init | ( | ble_bondmngr_init_t * | p_init | ) |

Function for initializing the Bond Manager.

Parameters

  [in] | p_init | This contains information needed to initialize this module.

Returns
  NRF_SUCCESS on successful initialization, otherwise an error code.

uint32_t ble_bondmngr_is_link_encrypted | ( | bool * | status | ) |

Function to verify encryption status link with bonded central is encrypted or not.

This function provides status of encrption of the link with a bonded central. Its is recommended that the application can use the ble_bondmngr_central_ids_get function to verify if the central is in the database and then call this function.

Warning
  Currently the central id paramater is unused and is added only for future extension. As of today, only one link is permitted for the peripheral device, status of current link is provided. In future, with more possibilities in the topology, central_id will be needed to identify the central.

Parameters

  [out] | status | Status of encryption, true implies link encrypted.

Returns
  NRF_SUCCESS on success. NRF_ERROR_INVALID_STATE is returned if the bond manager was not initialized.

void ble_bondmngr_on_ble_evt | ( | ble_evt_t * | p_ble_evt | ) |

Function for handling all events from the BLE stack that relate to this module.

Parameters

  [in] | p_ble_evt | The event received from the BLE stack.

Returns
  NRF_SUCCESS if all operations went successfully, NRF_ERROR_NO_MEM if the maximum number of bonded centrals has been reached. Other error codes in other situations.

uint32_t ble_bondmngr_sys_attr_store | ( | void |  | ) |

Function for storing the System Attributes of a newly connected central.

This function fetches the System Attributes of the current central from the stack, adds it to the database in memory, and also stores it in the flash (without erasing any flash page). This function is intended to facilitate the storage of System Attributes when connected to new central (whose System Attributes are NOT yet stored in flash) even in connected state without affecting radio link. This function can, for example, be called after the CCCD is written by a central. The function will succeed if the central is a new central. See HID Keyboard Application or HID Mouse Application for sample usage.

Returns
  NRF_SUCCESS on success, otherwise an error code. NRF_ERROR_INVALID_STATE is returned if the System Attributes of the current central is already present in the flash because it is a previously known central.

uint32_t ble_bondmngr_whitelist_get | ( | ble_gap_whitelist_t * | p_whitelist | ) |

Function for getting the whitelist containing all currently bonded centrals.

This function populates the whitelist with either the IRKs or the public adresses of all bonded centrals.

Parameters

  [out] | p_whitelist | Whitelist structure with all bonded centrals.

Returns
  NRF_SUCCESS on success, an error_code otherwise.