nRF51 SDK: Context Management APIs

| nRF51 SDK

- Home
- Related Pages
- API Reference
- Data Structures

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions
Context Management APIs
Device Module 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.