| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
Database Discovery
BLE libraries

Database discovery module. More...

## Modules
| Database discovery module configuration

## Data Structures
struct | ble_db_discovery_t
| Structure for holding the information related to the GATT database at the server. More...
struct | ble_db_discovery_evt_t
| Structure containing the event from the DB discovery module to the application. More...

## Macros
#define | BLE_DB_DISCOVERY_MAX_SRV 6

## Typedefs
typedef void(* | ble_db_discovery_evt_handler_t )(ble_db_discovery_evt_t *p_evt)
| DB Discovery event handler type.

## Enumerations
enum | ble_db_discovery_evt_type_t { BLE_DB_DISCOVERY_COMPLETE, BLE_DB_DISCOVERY_ERROR, BLE_DB_DISCOVERY_SRV_NOT_FOUND, BLE_DB_DISCOVERY_AVAILABLE }
| Type of the DB Discovery event. More...

## Functions
uint32_t | ble_db_discovery_init (ble_db_discovery_evt_handler_t evt_handler)
| Function for initializing the DB Discovery module. More...
uint32_t | ble_db_discovery_close (void)
| Function for closing the DB Discovery module. More...
uint32_t | ble_db_discovery_evt_register (const ble_uuid_t *const p_uuid)
| Function for registering with the DB Discovery module. More...
uint32_t | ble_db_discovery_start (ble_db_discovery_t *const p_db_discovery, uint16_t conn_handle)
| Function for starting the discovery of the GATT database at the server. More...
void | ble_db_discovery_on_ble_evt (ble_db_discovery_t *const p_db_discovery, const ble_evt_t *const p_ble_evt)
| Function for handling the Application's BLE Stack events. More...

## Detailed Description

Database discovery module.

This module contains the APIs and types exposed by the DB Discovery module. These APIs and types can be used by the application to perform discovery of a service and its characteristics at the peer server. This module can also be used to discover the desired services in multiple remote devices.

Warning
  The maximum number of characteristics per service that can be discovered by this module is determined by the number of characteristics in the service structure defined in db_disc_config.h. If the peer has more than the supported number of characteristics, then the first found will be discovered and any further characteristics will be ignored. No descriptors other than Client Characteristic Configuration Descriptors will be searched for at the peer.

Note
  Presently only one instance of a Primary Service can be discovered by this module. If there are multiple instances of the service at the peer, only the first instance of it at the peer is fetched and returned to the application.
  The application must propagate BLE stack events to this module by calling ble_db_discovery_on_ble_evt().

## Macro Definition Documentation

#define BLE_DB_DISCOVERY_MAX_SRV 6

Maximum number of services supported by this module. This also indicates the maximum number of users allowed to be registered to this module. (one user per service).

## Enumeration Type Documentation

enum ble_db_discovery_evt_type_t

Type of the DB Discovery event.

Enumerator
BLE_DB_DISCOVERY_COMPLETE | Event indicating that the GATT Database discovery is complete.
BLE_DB_DISCOVERY_ERROR | Event indicating that an internal error has occurred in the DB Discovery module. This could typically be because of the SoftDevice API returning an error code during the DB discover.
BLE_DB_DISCOVERY_SRV_NOT_FOUND | Event indicating that the service was not found at the peer.
BLE_DB_DISCOVERY_AVAILABLE | Event indicating that the DB discovery module is available.

## Function Documentation

uint32_t ble_db_discovery_close | ( | void |  | ) |

Function for closing the DB Discovery module.

This function will clear up any internal variables and states maintained by the module. To re-use the module after calling this function, the function ble_db_discovery_init must be called again.

Return values

  NRF_SUCCESS | Operation success.

uint32_t ble_db_discovery_evt_register | ( | const ble_uuid_t *const | p_uuid | ) |

Function for registering with the DB Discovery module.

The application can use this function to inform which service it is interested in discovering at the server.

Parameters

  [in] | p_uuid | Pointer to the UUID of the service to be discovered at the server.

Note
  The total number of services that can be discovered by this module is BLE_DB_DISCOVERY_MAX_SRV. This effectively means that the maximum number of registrations possible is equal to the BLE_DB_DISCOVERY_MAX_SRV.

Return values

  NRF_SUCCESS | Operation success.
  NRF_ERROR_NULL | When a NULL pointer is passed as input.
  NRF_ERROR_INVALID_STATE | If this function is called without calling the ble_db_discovery_init.
  NRF_ERROR_NO_MEM | The maximum number of registrations allowed by this module has been reached.

uint32_t ble_db_discovery_init | ( | ble_db_discovery_evt_handler_t | evt_handler | ) |

Function for initializing the DB Discovery module.

Parameters

  [in] | evt_handler | Event handler to be called by the DB discovery module when any event related to discovery of the registered service occurs.

Return values

  NRF_SUCCESS | On successful initialization.
  NRF_ERROR_NULL | If the handler was NULL.

void ble_db_discovery_on_ble_evt | ( | ble_db_discovery_t *const | p_db_discovery,
|  | const ble_evt_t *const | p_ble_evt
| ) |  |

Function for handling the Application's BLE Stack events.

Parameters

  [in,out] | p_db_discovery | Pointer to the DB Discovery structure.
  [in] | p_ble_evt | Pointer to the BLE event received.

uint32_t ble_db_discovery_start | ( | ble_db_discovery_t *const | p_db_discovery,
|  | uint16_t | conn_handle
| ) |  |

Function for starting the discovery of the GATT database at the server.

Warning
  p_db_discovery structure must be zero-initialized.

Parameters

  [out] | p_db_discovery | Pointer to the DB Discovery structure.
  [in] | conn_handle | The handle of the connection for which the discovery should be started.

Return values

  NRF_SUCCESS | Operation success.
  NRF_ERROR_NULL | When a NULL pointer is passed as input.
  NRF_ERROR_INVALID_STATE | If this function is called without calling the ble_db_discovery_init, or without calling ble_db_discovery_evt_register.
  NRF_ERROR_BUSY | If a discovery is already in progress for the current connection.

Returns
  This API propagates the error code returned by the SoftDevice API sd_ble_gattc_primary_services_discover.