Utility APIs

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

Functions
api_result_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...
api_result_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...
api_result_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...
api_result_t	dm_handle_initialize (dm_handle_t *p_handle)
	Function for initializing Device Manager handle. More...
api_result_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...

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

api_result_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_instance	Application instance to be set.
[out]	p_handle	Device Manager handle for which the instance is to be copied.

Return values

NRF_SUCCESS	On success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATE	If the API is called without module initialization and/or application registration.
NRF_ERROR_NULL	If p_handle and/or p_addr is NULL.

api_result_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.

This routine is used to get distributed keys with a bonded device. This API is currently only available on S120 (GAP Central role).

Parameters

[in]	p_handle	Device Manager handle identifying the peer.
[out]	p_key_dist	Pointer to distributed keys.

Return values

NRF_SUCCESS	On success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATE	If the API is called without module initialization and/or application registration.
NRF_ERROR_NULL	If the p_handle and/or p_key_dist pointer is NULL.
NRF_ERROR_INVALID_ADDR	If the peer is not identified by the handle provided by the application.

api_result_t dm_handle_initialize

(

dm_handle_t *

p_handle

)

Function for initializing Device Manager handle.

Parameters

[in]

p_handle

Device Manager handle to be initialized.

Return values

NRF_SUCCESS	On success.
NRF_ERROR_NULL	If p_handle is NULL.

Note

This routine is permitted before initialization of the module.

api_result_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_handle	Identifies the peer device whose address is requested. Can not be NULL.
[out]	p_addr	Pointer where address is to be copied. Can not be NULL.

Return values

NRF_SUCCESS	On success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATE	If the API is called without module initialization and/or application registration.
NRF_ERROR_NULL	If p_handle and/or p_addr is NULL.
NRF_ERROR_NOT_FOUND	If the peer could not be identified.

api_result_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_handle	Identifies the peer device whose address is requested to be set/updated.
[out]	p_addr	Address to be set/updated.

Return values

NRF_SUCCESS	On success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATE	If the API is called without module initialization and/or application registration.
NRF_ERROR_NULL	If p_handle and/or p_addr is NULL.
NRF_ERROR_INVALID_ADDR	If the peer is not identified by the handle provided by the application.
NRF_ERROR_INVALID_PARAM	If 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.