Peer Manager Standard Event Handlers

Standard event handlers implementing some best practices for BLE security. More...

Functions
void	pm_handler_on_pm_evt (pm_evt_t const *p_pm_evt)
	Standard function for making Peer Manager calls based on Peer Manager events. More...
void	pm_handler_pm_evt_log (pm_evt_t const *p_pm_evt)
	Auxiliary standard function for logging Peer Manager events. More...
void	pm_handler_flash_clean (pm_evt_t const *p_pm_evt)
	Auxiliary standard function for maintaining room in flash based on Peer Manager events. More...
void	pm_handler_flash_clean_on_return (void)
	Function to call when a Peer Manager function returns NRF_ERROR_STORAGE_FULL. More...
void	pm_handler_disconnect_on_sec_failure (pm_evt_t const *p_pm_evt)
	Auxiliary standard function for disconnecting when the connection could not be secured. More...
void	pm_handler_secure_on_connection (ble_evt_t const *p_ble_evt)
	Function for securing a connection when it is established. More...
void	pm_handler_secure_on_error (ble_evt_t const *p_ble_evt)
	Function for securing a connection if a GATT read or write operation lacks security. More...

Detailed Description

Standard event handlers implementing some best practices for BLE security.

Function Documentation

void pm_handler_disconnect_on_sec_failure

(

pm_evt_t const *

p_pm_evt

)

Auxiliary standard function for disconnecting when the connection could not be secured.

This function disconnects whenever connection security fails, i.e. whenever it receives a PM_EVT_CONN_SEC_FAILED.

Note

In normal circumstances, this function should be called for every Peer Manager event.

This function is a supplement to, not a replacement for pm_handler_on_pm_evt.

Parameters

[in]

p_pm_evt

Peer Manager event to handle.

void pm_handler_flash_clean

(

pm_evt_t const *

p_pm_evt

)

Auxiliary standard function for maintaining room in flash based on Peer Manager events.

This function does the following:

• Ranks peers by when they last connected.
• Garbage collects the flash when needed.
• Deletes the lowest ranked peer(s) when garbage collection is insufficient.

Note

See also pm_handler_flash_clean_on_return.

In normal circumstances, this function should be called for every Peer Manager event.

This function is a supplement to, not a replacement for pm_handler_on_pm_evt.

Parameters

[in]

p_pm_evt

Peer Manager event to handle.

void pm_handler_flash_clean_on_return

(

void

)

Function to call when a Peer Manager function returns NRF_ERROR_STORAGE_FULL.

Note

This should only be used if pm_handler_flash_clean is also used.

void pm_handler_on_pm_evt

(

pm_evt_t const *

p_pm_evt

)

Standard function for making Peer Manager calls based on Peer Manager events.

This function does the following:

• Logs all PM events using Logger module, at different severity levels.
• Starts encryption if connected to an already bonded peer. This is affected by PM_HANDLER_SEC_DELAY_MS.
• Calls Common application error handler on fatal errors.

Note

In normal circumstances, this function should be called for every Peer Manager event.

Parameters

[in]

p_pm_evt

Peer Manager event to handle.

void pm_handler_pm_evt_log

(

pm_evt_t const *

p_pm_evt

)

Auxiliary standard function for logging Peer Manager events.

This function logs all PM events using Logger module, at different severity levels. The PM_LOG_ENABLED and other PM_LOG_* configs control these log messages.

Note

This function is called internally by pm_handler_on_pm_evt.

Parameters

[in]

p_pm_evt

Peer Manager event to log.

void pm_handler_secure_on_connection

(

ble_evt_t const *

p_ble_evt

)

Function for securing a connection when it is established.

This function starts security when receiving a BLE_GAP_EVT_CONNECTED event. This is affected by PM_HANDLER_SEC_DELAY_MS.

Note

In normal circumstances, this function should be called for every BLE event.

Parameters

[in]

p_ble_evt

BLE event to handle.

void pm_handler_secure_on_error

(

ble_evt_t const *

p_ble_evt

)

Function for securing a connection if a GATT read or write operation lacks security.

This function starts pairing if a GATTC procedure fails with insufficient encryption or insufficient authentication. This is meant to delay performing pairing/bonding until it is actually needed to access resources. This is affected by PM_HANDLER_SEC_DELAY_MS.

Note

When using this handler, the failed GATTC operation must be retried by the user.

This does not work when using Write Without Response (BLE_GATT_OP_WRITE_CMD) because the server does not send any response, even on error. Instead, the write will be silently dropped by the server.

In normal circumstances, this function should be called for every BLE event.

Parameters

[in]

p_ble_evt

BLE event to handle.