nRF51 SDK - S110 SoftDevice
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Utility APIs

This section describes the utility APIs offered by the module. More...

Functions

ret_code_t dm_application_instance_set (dm_application_instance_t const *p_appl_instance, dm_handle_t *p_handle)
 Function for Setting/Copying Application instance to Device Manager handle. More...
 
ret_code_t dm_peer_addr_get (dm_handle_t const *p_handle, ble_gap_addr_t *p_addr)
 Function for getting a peer's device address. More...
 
ret_code_t dm_peer_addr_set (dm_handle_t const *p_handle, ble_gap_addr_t const *p_addr)
 Function for setting/updating a peer's device address. More...
 
ret_code_t dm_handle_initialize (dm_handle_t *p_handle)
 Function for initializing Device Manager handle. More...
 
ret_code_t dm_distributed_keys_get (dm_handle_t const *p_handle, dm_sec_keyset_t *p_key_dist)
 Function for getting distributed keys for a device. More...
 
ret_code_t dm_handle_get (uint16_t conn_handle, dm_handle_t *p_handle)
 Function for getting the corresponding dm_handle_t based on the connection handle. More...
 

Detailed Description

This section describes the utility APIs offered by the module.

APIs defined in this section are utility or assisting/helper APIs.

Function Documentation

ret_code_t dm_application_instance_set ( dm_application_instance_t const *  p_appl_instance,
dm_handle_t p_handle 
)

Function for Setting/Copying Application instance to Device Manager handle.

Parameters
[in]p_appl_instanceApplication instance to be set.
[out]p_handleDevice Manager handle for which the instance is to be copied.
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 and/or p_addr is NULL.
ret_code_t dm_distributed_keys_get ( dm_handle_t const *  p_handle,
dm_sec_keyset_t p_key_dist 
)

Function for getting distributed keys for a device.

Parameters
[in]p_handleDevice Manager handle identifying the peer.
[out]p_key_distPointer to distributed keys.
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 the p_handle and/or p_key_dist pointer is NULL.
NRF_ERROR_INVALID_ADDRIf the peer is not identified by the handle provided by the application.
ret_code_t dm_handle_get ( uint16_t  conn_handle,
dm_handle_t p_handle 
)

Function for getting the corresponding dm_handle_t based on the connection handle.

Parameters
[in]conn_handleConnection handle as provided by the SoftDevice.
[in,out]p_handlePointer to the p_handle containg the application instance for the registered application. If the application instance is valid then the p_handle will be filled with requested data.
Return values
NRF_SUCCESSOn success, else an error code indicating reason for failure.
NRF_ERROR_NULLIf the p_handle pointer is NULL.
NRF_ERROR_NOT_FOUNDIf no p_handle is found for the provided connection handle.
ret_code_t dm_handle_initialize ( dm_handle_t p_handle)

Function for initializing Device Manager handle.

Parameters
[in]p_handleDevice Manager handle to be initialized.
Return values
NRF_SUCCESSOn success.
NRF_ERROR_NULLIf p_handle is NULL.
Note
This routine is permitted before initialization of the module.
ret_code_t dm_peer_addr_get ( dm_handle_t const *  p_handle,
ble_gap_addr_t p_addr 
)

Function for getting a peer's device address.

Parameters
[in]p_handleIdentifies the peer device whose address is requested. Can not be NULL.
[out]p_addrPointer where address is to be copied. Can not be NULL.
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 and/or p_addr is NULL.
NRF_ERROR_NOT_FOUNDIf the peer could not be identified.
ret_code_t dm_peer_addr_set ( dm_handle_t const *  p_handle,
ble_gap_addr_t const *  p_addr 
)

Function for setting/updating a peer's device address.

Parameters
[in]p_handleIdentifies the peer device whose address is requested to be set/updated.
[out]p_addrAddress to be set/updated.
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 and/or p_addr is NULL.
NRF_ERROR_INVALID_ADDRIf the peer is not identified by the handle provided by the application.
NRF_ERROR_INVALID_PARAMIf this procedure is requested while connected to the peer or if the address type was set to BLE_GAP_ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE.
Note
Setting or updating a peer's device address is permitted only for a peer that is bonded and disconnected.
Updated address is reflected only after DM_EVT_DEVICE_CONTEXT_STORED is notified to the application for this bonded device instance. In order to avoid abnormal behaviour, it is recommended to not invite/initiate connections on the updated address unless this event has been notified.