nRF51 SDK - S130 SoftDevice
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Context Management APIs

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

Functions

ret_code_t dm_device_add (dm_handle_t *p_handle, dm_device_context_t const *p_context)
 
ret_code_t dm_device_delete (dm_handle_t const *p_handle)
 Function for deleting a peer device context and all related information from the database. More...
 
ret_code_t dm_device_delete_all (dm_application_instance_t const *p_handle)
 Function for deleting all peer device context and all related information from the database. More...
 
ret_code_t dm_service_context_set (dm_handle_t const *p_handle, dm_service_context_t const *p_context)
 Function for setting Service Context for a peer device identified by 'p_handle' parameter. More...
 
ret_code_t dm_service_context_get (dm_handle_t const *p_handle, dm_service_context_t *p_context)
 Function for getting Service Context for a peer device identified by 'p_handle' parameter. More...
 
ret_code_t dm_service_context_delete (dm_handle_t const *p_handle)
 Function for deleting a Service Context for a peer device identified by the 'p_handle' parameter. More...
 
ret_code_t dm_application_context_set (dm_handle_t const *p_handle, dm_application_context_t const *p_context)
 Function for setting Application Context for a peer device identified by the 'p_handle' parameter. More...
 
ret_code_t dm_application_context_get (dm_handle_t const *p_handle, dm_application_context_t *p_context)
 Function for getting Application Context for a peer device identified by the 'p_handle' parameter. More...
 
ret_code_t dm_application_context_delete (dm_handle_t const *p_handle)
 Function for deleting Application Context for a peer device identified by the '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 allow the 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 instead of mapping all the information with a device context.

Function Documentation

ret_code_t dm_application_context_delete ( dm_handle_t const *  p_handle)

Function for deleting Application Context for a peer device identified by the 'p_handle' parameter.

Delete Application Context for a peer device identified by the 'p_handle' parameter. If this API returns NRF_SUCCESS, DM_EVT_APPL_CONTEXT_DELETED event is notified to the application. The event result notified along with the event and indicates success or failure of this procedure.

Parameters
[in]p_handleIdentifies peer device for which procedure is requested.
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 is NULL.
NRF_ERROR_INVALID_ADDRIf peer is not identified the handle provided by the application.
DM_NO_APP_CONTEXTIf no application context was set that can be deleted.
Note
The API returns FEATURE_NOT_ENABLED if the DEVICE_MANAGER_APP_CONTEXT_SIZE is set to zero.
ret_code_t dm_application_context_get ( dm_handle_t const *  p_handle,
dm_application_context_t p_context 
)

Function for getting Application Context for a peer device identified by the 'p_handle' parameter.

Get Application Context for a peer device identified by the 'p_handle' parameter. If this API returns NRF_SUCCESS, DM_EVT_APPL_CONTEXT_LOADED event is notified to the application. Event result notified along with the event indicates success or failure of this procedure.

Parameters
[in]p_handleIdentifies peer device for which procedure is requested.
[in]p_contextApplication context being requested. The context information includes length of data and pointer to the contextual data is provided.
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_context is NULL.
NRF_ERROR_INVALID_ADDRIf the peer is not identified by the handle provided by the application.
DM_NO_APP_CONTEXTIf no application context was set that can be fetched.
Note
The API returns FEATURE_NOT_ENABLED in case DEVICE_MANAGER_APP_CONTEXT_SIZE is set to zero.
ret_code_t dm_application_context_set ( dm_handle_t const *  p_handle,
dm_application_context_t const *  p_context 
)

Function for setting Application Context for a peer device identified by the 'p_handle' parameter.

This application allows the setting of the application context for the peer device identified by the '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. Note 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_handleIdentifies peer device for which procedure is requested.
[in]p_contextApplication context being set. The context information includes length of the data and pointer to the contextual data being set. The memory pointed to by the data pointer 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 notified by the event DM_EVT_APPL_CONTEXT_STORED. The event result is notified along with the event and indicates success or failure of this procedure.
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_context is NULL.
NRF_ERROR_INVALID_ADDRIf peer is not identified the handle provided by the application.
Note
The API returns FEATURE_NOT_ENABLED in case DEVICE_MANAGER_APP_CONTEXT_SIZE is set to zero.
ret_code_t dm_device_delete ( dm_handle_t const *  p_handle)

Function for deleting a peer device context and all related information from the database.

Delete peer device context and all related information from database. If this API returns NRF_SUCCESS, DM_EVT_DEVICE_CONTEXT_DELETED event is notified to the application. Event result notified along with the event indicates success or failure of this procedure.

Parameters
[in]p_handleIdentifies the peer device to be deleted.
Return values
NRF_SUCCESSon success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATEIn the API is called without module initialization and/or application registration.
NRF_ERROR_NULLIf p_handle is NULL.
NRF_ERROR_INVALID_ADDRIf peer is not identified the handle provided by the application.
Note
Deleting device context results in deleting service and application context for the bonded device. The respective events DM_EVT_SERVICE_CONTEXT_DELETED and DM_EVT_APPL_CONTEXT_DELETED are not notified to the application.
ret_code_t dm_device_delete_all ( dm_application_instance_t const *  p_handle)

Function for deleting all peer device context and all related information from the database.

Delete peer device context and all related information from database. If this API returns NRF_SUCCESS, DM_EVT_DEVICE_CONTEXT_DELETED event is notified to the application for each device that is deleted from the data base. Event result notified along with the event indicates success or failure of this procedure.

Parameters
[in]p_handleIdentifies application instance that is requesting the deletion of all bonded devices.
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 peer is not identified the handle provided by the application.
Note
Deleting device context results in deleting both service and application context for the bonded device. The respective events DM_EVT_SERVICE_CONTEXT_DELETED and DM_EVT_APPL_CONTEXT_DELETED are not notified to the application.
ret_code_t dm_service_context_delete ( dm_handle_t const *  p_handle)

Function for deleting a Service Context for a peer device identified by the 'p_handle' parameter.

This API allows application to delete a Service Context identified for a peer device identified by the 'p_handle' parameter. If this API returns NRF_SUCCESS, DM_EVT_SERVICE_CONTEXT_DELETED event is notified to the application. Event result is notified along with the event and indicates success or failure of this procedure.

Parameters
[in]p_handleIdentifies peer device for which procedure is requested.
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.
ret_code_t dm_service_context_get ( dm_handle_t const *  p_handle,
dm_service_context_t p_context 
)

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

Get Service Context for a peer device identified by the 'p_handle' parameter. If this API returns NRF_SUCCESS, DM_EVT_SERVICE_CONTEXT_LOADED event is notified to the application. The event result is notified along with the event indicates success or failure of this procedure.

Parameters
[in]p_handleIdentifies peer device for which procedure is requested.
[in]p_contextApplication context being requested. The context information includes length of the data and a pointer to the data. Note that requesting a 'get' of application does not need to provide memory, the pointer to data will be pointing to service data and hence no data movement is involved.
Return values
NRF_SUCCESSOn success, else an error code indicating reason for failure.
NRF_ERROR_INVALID_STATEIn case 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.
ret_code_t dm_service_context_set ( dm_handle_t const *  p_handle,
dm_service_context_t const *  p_context 
)

Function for setting 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 the 'p_handle' parameter. This API is useful when the Service Context cannot be requested from the SoftDevice, but needs to be 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_handleIdentifies peer device for which the procedure is requested.
[in]p_contextService 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. The Event result is notified along with the event and indicates success or failure of this procedure.
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.