nRF5 SDK v16.0.0
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
Database Discovery

Database discovery module. More...

Modules

 Database discovery module configuration
 

Data Structures

struct  ble_db_discovery_evt_t
 Structure containing the event from the DB discovery module to the application. More...
 
struct  ble_db_discovery_user_evt_t
 Structure containing the pending event. More...
 
struct  ble_db_discovery_t
 Structure for holding the information related to the GATT database at the server. More...
 
struct  ble_db_discovery_init_t
 DB discovery module initialization struct. More...
 

Macros

#define BLE_DB_DISCOVERY_DEF(_name)
 Macro for defining a ble_db_discovery instance. More...
 
#define BLE_DB_DISCOVERY_ARRAY_DEF(_name, _cnt)
 Macro for defining multiple ble_db_discovery instances. More...
 
#define BLE_DB_DISCOVERY_MAX_SRV   6
 (defined(LINT)) More...
 

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
}
 DB Discovery event type. More...
 

Functions

uint32_t ble_db_discovery_init (ble_db_discovery_init_t *p_db_init)
 Function for initializing the DB Discovery module. More...
 
uint32_t ble_db_discovery_close (ble_db_discovery_t *const p_db_discovery)
 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 *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_evt_t const *p_ble_evt, void *p_context)
 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. Only the following descriptors will be searched for at the peer: Client Characteristic Configuration, Characteristic Extended Properties, Characteristic User Description, and Report Reference.
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_ARRAY_DEF (   _name,
  _cnt 
)
Value:
static ble_db_discovery_t _name[_cnt] = {MACRO_REPEAT(_cnt, DB_INIT)}; \
NRF_SDH_BLE_OBSERVERS(_name ## _obs, \

Macro for defining multiple ble_db_discovery instances.

Parameters
_nameName of the array of instances.
_cntNumber of instances to define.
#define BLE_DB_DISCOVERY_DEF (   _name)

Macro for defining a ble_db_discovery instance.

Parameters
_nameName of the instance.
#define BLE_DB_DISCOVERY_MAX_SRV   6

(defined(LINT))

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

DB Discovery event type.

Enumerator
BLE_DB_DISCOVERY_COMPLETE 

Event indicating that the discovery of one service 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 instance is available.

Function Documentation

uint32_t ble_db_discovery_close ( ble_db_discovery_t *const  p_db_discovery)

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. When using more than one DB Discovery instance, this function should be called for each instance.

Parameters
[out]p_db_discoveryPointer to the DB discovery structure.
Return values
NRF_SUCCESSOperation 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_uuidPointer 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_SUCCESSOperation success.
NRF_ERROR_NULLWhen a NULL pointer is passed as input.
NRF_ERROR_INVALID_STATEIf this function is called without calling the ble_db_discovery_init.
NRF_ERROR_NO_MEMThe maximum number of registrations allowed by this module has been reached.
uint32_t ble_db_discovery_init ( ble_db_discovery_init_t p_db_init)

Function for initializing the DB Discovery module.

Parameters
[in]p_db_initPointer to DB discovery initialization structure.
Return values
NRF_SUCCESSOn successful initialization.
NRF_ERROR_NULLIf the initialization structure was NULL or the structure content is empty.
void ble_db_discovery_on_ble_evt ( ble_evt_t const *  p_ble_evt,
void *  p_context 
)

Function for handling the Application's BLE Stack events.

Parameters
[in]p_ble_evtPointer to the BLE event received.
[in,out]p_contextPointer to the DB Discovery structure.
uint32_t ble_db_discovery_start ( ble_db_discovery_t p_db_discovery,
uint16_t  conn_handle 
)

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

Parameters
[out]p_db_discoveryPointer to the DB Discovery structure.
[in]conn_handleThe handle of the connection for which the discovery should be started.
Return values
NRF_SUCCESSOperation success.
NRF_ERROR_NULLWhen a NULL pointer is passed as input.
NRF_ERROR_INVALID_STATEIf this function is called without calling the ble_db_discovery_init, or without calling ble_db_discovery_evt_register.
NRF_ERROR_BUSYIf a discovery is already in progress using p_db_discovery. Use a different ble_db_discovery_t structure, or wait for a DB Discovery event before retrying.
Returns
This API propagates the error code returned by functions: nrf_ble_gq_conn_handle_register and nrf_ble_gq_item_add.

Documentation feedback | Developer Zone | Subscribe | Updated