nRF51 SDK - S130 SoftDevice
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
APIs to set up or read status of security on a link.

This section describes APIs to set up Security. These APIs require that the peer is connected before the procedures can be requested. More...

Functions

ret_code_t dm_security_setup_req (dm_handle_t *p_handle)
 Function for requesting setting up security on a link. More...
 
ret_code_t dm_security_status_req (dm_handle_t const *p_handle, dm_security_status_t *p_status)
 Function for reading the status of the security on a link. More...
 
ret_code_t dm_whitelist_create (dm_application_instance_t const *p_handle, ble_gap_whitelist_t *p_whitelist)
 Function for creating the whitelist. More...
 

Detailed Description

This section describes APIs to set up Security. These APIs require that the peer is connected before the procedures can be requested.

This group allows application to request security procedures or get the status of the security on a link.

Function Documentation

ret_code_t dm_security_setup_req ( dm_handle_t p_handle)

Function for requesting setting up security on a link.

This API initiates security procedures with a peer device.

Note
For the GAP Central role, in case peer is not bonded, request to bond/pair is initiated. If it is bonded, the link is re-encrypted using the existing bond information. For the GAP peripheral role, a Slave security request is sent.

If a pairing procedure is initiated successfully, application is notified of DM_EVT_SECURITY_SETUP_COMPLETE. A result indicating success or failure is notified along with the event. In case the link is re-encrypted using existing bond information, DM_EVT_LINK_SECURED is notified to the application.

Parameters
[in]p_handleIdentifies the link on which security is desired.
Return values
NRF_SUCCESSOn success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATEIf the API is called without module initialization and/or application registration.
NRF_ERROR_NULLIf p_handle is NULL.
NRF_ERROR_INVALID_ADDRIf the peer is not identified by the handle provided by the application or if the peer is not connected when this procedure is requested.
ret_code_t dm_security_status_req ( dm_handle_t const *  p_handle,
dm_security_status_t p_status 
)

Function for reading the status of the security on a link.

This API allows application to query status of security on a link.

Parameters
[in]p_handleIdentifies the link on which security is desired.
[out]p_statusPointer where security status is provided to the application. See dm_security_status_t for possible statuses that can be expected.
Return values
NRF_SUCCESSOr appropriate error code indicating reason for failure.
NRF_ERROR_INVALID_STATEIf the API is called without module initialization and/or application registration.
NRF_ERROR_NULLIf p_handle or p_status is NULL.
NRF_ERROR_INVALID_ADDRIf peer is not identified by the handle provided by the application or if peer is not connected when this procedure is requested.
ret_code_t dm_whitelist_create ( dm_application_instance_t const *  p_handle,
ble_gap_whitelist_t p_whitelist 
)

Function for creating the whitelist.

This API allows application to create whitelist based on bonded peer devices in module data base.

Parameters
[in]p_handleIdentifies the application requesting whitelist creation.
[in,out]p_whitelistPointer where created whitelist is provided to the application.
Note
'addr_count' and 'irk_count' fields of the structure should be populated with the maximum number of devices that the application wishes to request in the whitelist. If the number of bonded devices is less than requested, the fields are updated with that number of devices. If the number of devices are more than requested, the module will populate the list with devices in the order the bond was established with the peer devices. Also, if this routine is called when a connection exists with one or more peer devices, those connected devices are not added to the whitelist.
Return values
NRF_SUCCESSOn success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATEIf the API is called without module initialization and/or application registration.
NRF_ERROR_NULLIf p_handle or p_whitelist is NULL.