| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
Bond Management Service
BLE Services

Bond Management Service (BMS) module. More...

## Modules
| BMS feature bits

## Data Structures
struct | nrf_ble_bms_features_t
| Supported features. More...
struct | nrf_ble_bms_auth_code_t
| Received authorization codes. More...
struct | nrf_ble_bms_evt_t
| BMS events. More...
struct | nrf_ble_bms_ctrlpt_t
| BMS control points. More...
struct | nrf_ble_bms_bond_cbs_t
| BMS bond management callbacks. More...
struct | nrf_ble_bms_init_t
| BMS initialization structure that contains all information needed to initialize the service. More...
struct | nrf_ble_bms_s
| Status information for the service. More...

## Macros
#define | NRF_BLE_BMS_FEATURE_LEN 3
| Length of the Feature Characteristic (in bytes).
#define | NRF_BLE_BMS_CTRLPT_MAX_LEN 128
| Maximum length of the Bond Management Control Point Characteristic (in bytes).
#define | NRF_BLE_BMS_CTRLPT_MIN_LEN 1
| Minimum length of the Bond Management Control Point Characteristic (in bytes).
#define | NRF_BLE_BMS_AUTH_CODE_MAX_LEN NRF_BLE_BMS_CTRLPT_MAX_LEN - 1
| Maximum length of the Bond Management Control Point Authorization Code (in bytes).
#define | NRF_BLE_BMS_OPCODE_NOT_SUPPORTED (BLE_GATT_STATUS_ATTERR_APP_BEGIN + 0)
| Error sent back when receiving a control point write with an unsupported opcode.
#define | NRF_BLE_BMS_OPERATION_FAILED (BLE_GATT_STATUS_ATTERR_APP_BEGIN + 1)
| Error sent back when a control point operation fails.

## Typedefs
typedef struct nrf_ble_bms_s | nrf_ble_bms_t
typedef void(* | nrf_ble_bms_bond_handler_t )(nrf_ble_bms_t const *p_bms)
| BMS event handler type.
typedef void(* | ble_bms_evt_handler_t )(nrf_ble_bms_t *p_bms, nrf_ble_bms_evt_t *p_evt)
| BMS event handler type. The event handler returns a BLE GATT status code.

## Enumerations
enum | nrf_ble_bms_op_t { NRF_BLE_BMS_OP_DEL_BOND_REQ_DEVICE_BR_LE = 0x01, NRF_BLE_BMS_OP_DEL_BOND_REQ_DEVICE_BR_ONLY = 0x02, NRF_BLE_BMS_OP_DEL_BOND_REQ_DEVICE_LE_ONLY = 0x03, NRF_BLE_BMS_OP_DEL_ALL_BONDS_ON_SERVER_BR_LE = 0x04, NRF_BLE_BMS_OP_DEL_ALL_BONDS_ON_SERVER_BR_ONLY = 0x05, NRF_BLE_BMS_OP_DEL_ALL_BONDS_ON_SERVER_LE_ONLY = 0x06, NRF_BLE_BMS_OP_DEL_ALL_BUT_ACTIVE_BOND_BR_LE = 0x07, NRF_BLE_BMS_OP_DEL_ALL_BUT_ACTIVE_BOND_BR_ONLY = 0x08, NRF_BLE_BMS_OP_DEL_ALL_BUT_ACTIVE_BOND_LE_ONLY = 0x09, NRF_BLE_BMS_OP_NONE = 0xFF }
| BMS Control Point opcodes. More...
enum | nrf_ble_bms_auth_status_t { NRF_BLE_BMS_AUTH_STATUS_ALLOWED, NRF_BLE_BMS_AUTH_STATUS_DENIED, NRF_BLE_BMS_AUTH_STATUS_PENDING }
| Authorization status values. More...
enum | nrf_ble_bms_evt_type_t { NRF_BLE_BMS_EVT_AUTH }
| BMS event types. More...

## Functions
ret_code_t | nrf_ble_bms_auth_response (nrf_ble_bms_t *p_bms, bool authorize)
| Function for responding to an authorization request. More...
ret_code_t | nrf_ble_bms_init (nrf_ble_bms_t *p_bms, nrf_ble_bms_init_t *p_bms_init)
| Function for initializing the Bond Management Service. More...
ret_code_t | nrf_ble_bms_set_conn_handle (nrf_ble_bms_t *p_bms, uint16_t conn_handle)
| Function for assigning handles to the Bond Management Service instance. More...
void | nrf_ble_bms_on_ble_evt (nrf_ble_bms_t *p_bms, ble_evt_t *p_ble_evt)
| Function for handling Bond Management BLE stack events. More...
uint16_t | nrf_ble_bms_on_qwr_evt (nrf_ble_bms_t *p_bms, nrf_ble_qwr_t *p_qwr, nrf_ble_qwr_evt_t *p_evt)
| Function for handling events from the Queued Writes module. More...

## Detailed Description

Bond Management Service (BMS) module.

This module implements the Bond Management Service (BMS). By writing to the Bond Management Control Point, the connected peer can request the deletion of bond information from the device. If authorization is configured, the application must supply an event handler for receiving Bond Management Service events. Using this handler, the service requests authorization when a procedure is requested by writing to the Bond Management Control Point.

Note
  The application must propagate BLE stack events to the Bond Management Service module by calling nrf_ble_bms_on_ble_evt() from the SoftDevice Event Handler callback. If the application uses the Queued Writes module, the application must propagate Queued Write events to the Bond Management Service module by calling nrf_ble_bms_on_qwr_evt() from the Queued Writes module callback.

## Enumeration Type Documentation

enum nrf_ble_bms_auth_status_t

Authorization status values.

Enumerator
NRF_BLE_BMS_AUTH_STATUS_ALLOWED | Authorization is granted.
NRF_BLE_BMS_AUTH_STATUS_DENIED | Authorization is denied.
NRF_BLE_BMS_AUTH_STATUS_PENDING | Authorization is pending.

enum nrf_ble_bms_evt_type_t

BMS event types.

Enumerator
NRF_BLE_BMS_EVT_AUTH | Event that indicates that the application shall verify the supplied authentication code.

enum nrf_ble_bms_op_t

BMS Control Point opcodes.

Enumerator
NRF_BLE_BMS_OP_DEL_BOND_REQ_DEVICE_BR_LE | Initiates the procedure to delete the bond of the requesting device on BR/EDR and LE transports.
NRF_BLE_BMS_OP_DEL_BOND_REQ_DEVICE_BR_ONLY | Initiates the procedure to delete the bond of the requesting device on BR/EDR transport.
NRF_BLE_BMS_OP_DEL_BOND_REQ_DEVICE_LE_ONLY | Initiates the procedure to delete the bond of the requesting device on LE transport.
NRF_BLE_BMS_OP_DEL_ALL_BONDS_ON_SERVER_BR_LE | Initiates the procedure to delete all bonds on the device on BR/EDR and LE transports.
NRF_BLE_BMS_OP_DEL_ALL_BONDS_ON_SERVER_BR_ONLY | Initiates the procedure to delete all bonds on the device on BR/EDR transport.
NRF_BLE_BMS_OP_DEL_ALL_BONDS_ON_SERVER_LE_ONLY | Initiates the procedure to delete all bonds on the device on LE transport.
NRF_BLE_BMS_OP_DEL_ALL_BUT_ACTIVE_BOND_BR_LE | Initiates the procedure to delete all bonds except for the one of the requesting device on BR/EDR and LE transports.
NRF_BLE_BMS_OP_DEL_ALL_BUT_ACTIVE_BOND_BR_ONLY | Initiates the procedure to delete all bonds except for the one of the requesting device on BR/EDR transport.
NRF_BLE_BMS_OP_DEL_ALL_BUT_ACTIVE_BOND_LE_ONLY | Initiates the procedure to delete all bonds except for the one of the requesting device on LE transport.
NRF_BLE_BMS_OP_NONE | Indicates an invalid opcode or no pending opcode.

## Function Documentation

ret_code_t nrf_ble_bms_auth_response | ( | nrf_ble_bms_t * | p_bms,
|  | bool | authorize
| ) |  |

Function for responding to an authorization request.

This function should be called when receiving the NRF_BLE_BMS_EVT_AUTH event to respond to the service with an authorization result.

Parameters

  [in] | p_bms | BMS structure.
  [in] | authorize | Authorization response. True if the authorization is considered successful.

Return values

  NRF_ERROR_NULL | If `p_bms` was NULL.
  NRF_ERROR_INVALID_STATE | If no authorization request was pending.
  NRF_SUCCESS | If the response was received successfully.

ret_code_t nrf_ble_bms_init | ( | nrf_ble_bms_t * | p_bms,
|  | nrf_ble_bms_init_t * | p_bms_init
| ) |  |

Function for initializing the Bond Management Service.

Parameters

  [out] | p_bms | BMS structure.
  [in] | p_bms_init | Information needed to initialize the service.

Return values

  NRF_ERROR_NULL | If `p_bms` or `p_bms_init` was NULL.
  NRF_SUCCESS | If the service was initialized successfully. Otherwise, an error code is returned.

void nrf_ble_bms_on_ble_evt | ( | nrf_ble_bms_t * | p_bms,
|  | ble_evt_t * | p_ble_evt
| ) |  |

Function for handling Bond Management BLE stack events.

This function handles all events from the BLE stack that are of interest to the Bond Management Service.

Parameters

  [in] | p_bms | BMS structure.
  [in] | p_ble_evt | Event received from the BLE stack.

uint16_t nrf_ble_bms_on_qwr_evt | ( | nrf_ble_bms_t * | p_bms,
|  | nrf_ble_qwr_t * | p_qwr,
|  | nrf_ble_qwr_evt_t * | p_evt
| ) |  |

Function for handling events from the Queued Writes module.

Parameters

  [in] | p_bms | BMS structure.
  [in] | p_qwr | Queued Write structure.
  [in] | p_evt | Event received from the Queued Writes module.

Return values

  BLE_GATT_STATUS_SUCCESS | If the received event is accepted.
  NRF_BLE_QWR_REJ_REQUEST_ERR_CODE | If the received event is not relevant for any of this module's attributes.
  BLE_BMS_OPCODE_NOT_SUPPORTED | If the received opcode is not supported.
  BLE_GATT_STATUS_ATTERR_INSUF_AUTHORIZATION | If the application handler returns that the authorization code is not valid.

ret_code_t nrf_ble_bms_set_conn_handle | ( | nrf_ble_bms_t * | p_bms,
|  | uint16_t | conn_handle
| ) |  |

Function for assigning handles to the Bond Management Service instance.

Call this function when a link with a peer has been established to associate the link to this instance of the module.

Parameters

  [in] | p_bms | Pointer to the BMS structure instance to associate.
  [in] | conn_handle | Connection handle to be associated with the given BMS instance.

Return values

  NRF_ERROR_NULL | If `p_bms` was NULL.
  NRF_SUCCESS | If the operation was successful.