Context Management APIs

Utility APIs offered by the device manager to get information about the peer if and when needed. More...

Functions
api_result_t	dm_device_add (dm_handle_t *p_handle, dm_device_context_t const *p_context)
	Add peer device context and all related information to database. More...
api_result_t	dm_device_delete (dm_handle_t const *p_handle)
	Delete peer device context and all related information from database. More...
api_result_t	dm_device_delete_all (dm_application_instance_t const *p_handle)
	Delete all peer device context and all related information from database. More...
api_result_t	dm_service_context_set (dm_handle_t const *p_handle, dm_service_context_t const *p_context)
	Set Service Context for a peer device identified by 'p_handle' parameter. More...
api_result_t	dm_service_context_get (dm_handle_t const *p_handle, dm_service_context_t *p_context)
	Get Application Context for a peer device identified by 'p_handle' parameter. More...
api_result_t	dm_service_context_delete (dm_handle_t const *p_handle)
	Delete Service Context identified for a peer device identified by 'p_handle' parameter. More...
api_result_t	dm_application_context_set (dm_handle_t const *p_handle, dm_application_context_t const *p_context)
	Set Application Context for a peer device identified by 'p_handle' parameter. More...
api_result_t	dm_application_context_get (dm_handle_t const *p_handle, dm_application_context_t *p_context)
	Get Application Context for a peer device identified by 'p_handle' parameter. More...
api_result_t	dm_application_context_delete (dm_handle_t const *p_handle)
	Delete Application Context for a peer device identified by 'p_handle' parameter. More...

Detailed Description

Utility APIs offered by the device manager to get information about the peer if and when needed.

This group of API allows application to access information that is not required to be maintained by the application but may be needed. Hence it is possible to get the information from the module is instead of mapping all the information with a device context by itself.

Function Documentation

api_result_t dm_application_context_delete

(

dm_handle_t const *

p_handle

)

Delete Application Context for a peer device identified by 'p_handle' parameter.

Parameters

[in]

p_handle

Identifies peer device for which procedure is requested.

Returns

NRF_SUCCESS or an appropriate error code indicating reason for failure.

api_result_t dm_application_context_get	(	dm_handle_t const *	p_handle,
		dm_application_context_t *	p_context
	)

Get Application Context for a peer device identified by 'p_handle' parameter.

Get Application Context for a peer device identified by 'p_handle' parameter.

Parameters

[in]	p_handle	Identifies peer device for which procedure is requested.
[in]	p_context	Application context being requested. The context information includes length of data and pointer to the contextual data is provided.

Returns

NRF_SUCCESS or an appropriate error code indicating reason for failure.

api_result_t dm_application_context_set	(	dm_handle_t const *	p_handle,
		dm_application_context_t const *	p_context
	)

Set Application Context for a peer device identified by 'p_handle' parameter.

This application allows setting application context for the peer device identified by 'p_handle'. Application context is stored persistently by the module and can be requested by the application at any time using the dm_application_context_get API. It should be noted that this procedure is permitted only for bonded devices. If the device is not bonded, application context cannot be set. However, it is not mandatory that the bonded device is connected when requesting this procedure.

Parameters

[in]	p_handle	Identifies peer device for which procedure is requested.
[in]	p_context	Application context being set. The context information includes length of data and pointer to the contextual data being set. The memory pointed to by the pointer to data is assumed to be resident when API is being called and can be freed or reused once the set procedure is complete. Set procedure completion is indicated by the event DM_EVT_APPL_CONTEXT_STORED.

Returns

NRF_SUCCESS or an appropriate error code indicating reason for failure.

api_result_t dm_device_add	(	dm_handle_t *	p_handle,
		dm_device_context_t const *	p_context
	)

Add peer device context and all related information to database.

Parameters

[out]	p_handle	Contains device identification of the new device added.
[in]	p_context	Contextual information added for the device.

Note

This API is envisioned to be used for adding device from out of band mechanism to the data base maintained by the module. Information added as a part of context shall include peer identification and bonding information.

Returns

NRF_SUCCESS or an appropriate error code indicating reason for failure.

api_result_t dm_device_delete

(

dm_handle_t const *

p_handle

)

Delete peer device context and all related information from database.

Parameters

[in]

p_handle

Identifies the peer device to be deleted.

Returns

NRF_SUCCESS or an appropriate error code indicating reason for failure.

api_result_t dm_device_delete_all

(

dm_application_instance_t const *

p_handle

)

Delete all peer device context and all related information from database.

Parameters

[in]

p_handle

Identifies application instance that is requesting delete of all bonded devices.

Returns

NRF_SUCCESS or an appropriate error code indicating reason for failure.

api_result_t dm_service_context_delete

(

dm_handle_t const *

p_handle

)

Delete Service Context identified for a peer device identified by 'p_handle' parameter.

This API allows application to delete Service Context identified for a peer device identified by 'p_handle' parameter.

Parameters

[in]	p_handle	Identifies peer device for which procedure is requested.
[in]	service_type	Identifies the service whose context is being deleted.

Returns

NRF_SUCCESS or an appropriate error code indicating reason for failure.

api_result_t dm_service_context_get	(	dm_handle_t const *	p_handle,
		dm_service_context_t *	p_context
	)

Get Application Context for a peer device identified by 'p_handle' parameter.

Parameters

[in]	p_handle	Identifies peer device for which procedure is requested.
[in]	p_context	Application context being requested. The context information includes length of data and pointer to the contextual data is provided. Note that requesting a 'get' of application does not need to provide memory, the pointer to data will be rightly pointing to application data and hence no data movement is involved.

Returns

NRF_SUCCESS or an appropriate error code indicating reason for failure.

api_result_t dm_service_context_set	(	dm_handle_t const *	p_handle,
		dm_service_context_t const *	p_context
	)

Set Service Context for a peer device identified by 'p_handle' parameter.

This API allows application to Set Service Context for a peer device identified by 'p_handle' parameter. This API is useful when Service Context cannot be requested from SoftDevice, but needs to assembled by the application or an another module or when service context is exchanged in an out of band way. This API could also be used to trigger a storing of service context into persistent memory. If this is desired, a NULL pointer could be passed to the p_context.

Parameters

[in]	p_handle	Identifies peer device for which procedure is requested.
[in]	p_context	Service context being set. The context information includes length of data and pointer to the contextual data being set. The memory pointed to by the pointer to data is assumed to be resident when API is being called and can be freed or reused once the set procedure is complete. Set procedure completion is indicated by the event DM_EVT_SERVICE_CONTEXT_STORED.

Returns

NRF_SUCCESS or an appropriate error code indicating reason for failure.