GATT Discovery Manager

The GATT Discovery Manager handles service discovery on GATT servers.

When a client connects to a peer device that has a desired server, service discovery is necessary to ensure that the client interacts with the server’s characteristics using the correct attributes handles. Service discovery is also important because Bluetooth® LE advertising does not mandate that all services are advertised. To actually know if a service is present on a peer device, you must perform a service discovery.

The GATT Discovery Manager simplifies the usage of Zephyr’s bt_gatt_discover() function by processing the data using predefined filters.

The GATT Discovery Manager is used, for example, in the Bluetooth: Central HIDS sample.

Limitations

Only one discovery procedure at a time can be running.

API documentation

Header file: include/bluetooth/gatt_dm.h
Source file: subsys/bluetooth/gatt_dm.c
group bt_gatt_dm

Module for GATT Discovery Manager.

Functions

struct bt_gatt_service_val *bt_gatt_dm_attr_service_val(const struct bt_gatt_dm_attr *attr)

Access service value saved with service attribute.

This function access the service value parsed and saved previously in the user_data attribute field.

Note

Use it only on the attribute parsed in this module. To access service attribute use bt_gatt_dm_service_get function.

Parameters:

  • attr – [in] Service attribute

Returns:

The service value from the parsed attribute or NULL when attribute UUID value is unexpected.

struct bt_gatt_chrc *bt_gatt_dm_attr_chrc_val(const struct bt_gatt_dm_attr *attr)

Access characteristic value saved with characteristic attribute.

This function access the characteristic value parsed and saved previously in the user_data attribute field.

Note

Use it only on the attribute parsed in this module. To access characteristic attribute use bt_gatt_dm_char_next function.

Parameters:

  • attr – [in] Characteristic attribute

Returns:

The characteristic value from parser attribute or NULL when attribute UUID value is unexpected.

struct bt_conn *bt_gatt_dm_conn_get(struct bt_gatt_dm *dm)

Get the connection object.

Function returns connection object that is used by given discovery manager instance.

Parameters:

  • dm – [in] Discovery Manager instance

Returns:

Connection object.

size_t bt_gatt_dm_attr_cnt(const struct bt_gatt_dm *dm)

Get total number of attributes decoded.

The number of attributes including the service attribute. It means that service without any attribute would return 1 here.

Parameters:

  • dm – [in] Discovery Manager instance.

Returns:

Total number of attributes parsed.

const struct bt_gatt_dm_attr *bt_gatt_dm_service_get(const struct bt_gatt_dm *dm)

Get service value.

Function returns the value that contains UUID and attribute end handler of the service found.

Parameters:

  • dm – [in] Discovery Manager instance.

Returns:

The pointer service value structure.

const struct bt_gatt_dm_attr *bt_gatt_dm_char_next(const struct bt_gatt_dm *dm, const struct bt_gatt_dm_attr *prev)

Get next characteristic.

Parameters:

  • dm – [in] Discovery Manager instance.

  • prev – [in] An attribute where start to search. If NULL - the first characteristic in the service would be found. Note: It can be the previous characteristic attribute or the last descriptor inside the previous attribute. Function would start searching for the next characteristic from that point.

Returns:

The pointer for an attribute that describes the characteristic or NULL if no more characteristic is present.

const struct bt_gatt_dm_attr *bt_gatt_dm_char_by_uuid(const struct bt_gatt_dm *dm, const struct bt_uuid *uuid)

Get the characteristic by its UUID.

Function finds characteristic attribute by the UUID stored in its characteristic value. If the selected characteristic is not found in parsed service it returns NULL.

Parameters:

  • dm – [in] Discovery instance

  • uuid – [in] The UUID of the characteristic

Returns:

The characteristic attribute (the one with UUID set to BT_UUID_GATT_CHRC) with the selected UUID inside the characteristic value. Returns NULL if no such characteristic is present in the current service.

const struct bt_gatt_dm_attr *bt_gatt_dm_attr_by_handle(const struct bt_gatt_dm *dm, uint16_t handle)

Get attribute by handle.

Function returns any type of the attribute using its handle.

Parameters:

  • dm – [in] Discovery Manager instance.

  • handle – [in] The handle to find

Returns:

The pointer to the attribute or NULL if there is no attribute with such a pointer.

const struct bt_gatt_dm_attr *bt_gatt_dm_attr_next(const struct bt_gatt_dm *dm, const struct bt_gatt_dm_attr *prev)

Get next attribute.

Function returns the attribute next to the given one. It returns any type of the attribute.

Parameters:

  • dm – [in] Discovery Manager instance.

  • prev – [in] Previous attribute or NULL if we wish to get first attribute (just after service).

Returns:

Attribute next to the prev or the first attribute if NULL is given.

const struct bt_gatt_dm_attr *bt_gatt_dm_desc_by_uuid(const struct bt_gatt_dm *dm, const struct bt_gatt_dm_attr *attr_chrc, const struct bt_uuid *uuid)

Search the descriptor by UUID.

Function searches for the descriptor with given UUID inside given characteristic.

Parameters:

  • dm – [in] Discovery Manager instance.

  • attr_chrc – [in] The characteristic attribute where to search

  • uuid – [in] The UUID of the searched descriptor.

Returns:

Pointer to the attribute or NULL if the attribute cannot be found.

const struct bt_gatt_dm_attr *bt_gatt_dm_desc_next(const struct bt_gatt_dm *dm, const struct bt_gatt_dm_attr *prev)

Get next descriptor.

Function returns next descriptor. The difference between this function and bt_gatt_dm_attr_next is that it returns NULL also when returned attribute appears to be next characteristic.

Parameters:

  • dm – [in] Discovery Manager instance.

  • prev – [in] Previous attribute. The characteristic if we wish to get first descriptor or previous descriptor. If NULL or pointer to service attribute is given the result is undefined.

Returns:

The pointer to the descriptor attribute or NULL if there is no more descriptors in the characteristic.

int bt_gatt_dm_start(struct bt_conn *conn, const struct bt_uuid *svc_uuid, const struct bt_gatt_dm_cb *cb, void *context)

Start service discovery.

This function is asynchronous. Discovery results are passed through the supplied callback.

If svc_uuid is set to the service UUID, all service instances may be discovered. Call bt_gatt_dm_continue to discover the next service instance.

Note

Only one discovery procedure can be started simultaneously. To start another one, wait for the result of the previous procedure to finish and call bt_gatt_dm_data_release if it was successful.

Note

If svc_uuid is set to NULL, all services may be discovered. To process the next service, call bt_gatt_dm_continue.

Parameters:

  • conn – [in] Connection object.

  • svc_uuid – [in] UUID of target service or NULL if any service should be discovered.

  • cb – [in] Callback structure.

  • context – [inout] Context argument to be passed to callback functions.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int bt_gatt_dm_continue(struct bt_gatt_dm *dm, void *context)

Continue service discovery.

This function continues service discovery. Call it after the previous data was released by bt_gatt_dm_data_release.

Parameters:

  • dm – [inout] Discovery Manager instance.

  • context – [in] Context argument to be passed to callback functions.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int bt_gatt_dm_data_release(struct bt_gatt_dm *dm)

Release data associated with service discovery.

After calling this function, you cannot rely on the discovery data that was passed with the discovery completed callback (see bt_gatt_dm_cb).

Parameters:

  • dm – [in] Discovery Manager instance

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

static inline void bt_gatt_dm_data_print(const struct bt_gatt_dm *dm)

Print service discovery data.

This function prints GATT attributes that belong to the discovered service.

Parameters:

  • dm – [in] Discovery Manager instance

struct bt_gatt_dm_attr
#include <gatt_dm.h>

Discovery Manager GATT attribute.

This structure is used to hold GATT attribute information. The Discovery Manager attribute descriptor is a reduced version of bt_gatt_attr. The new definition is used to save memory that is used by this module.

Public Members

struct bt_uuid *uuid

Attribute UUID

uint16_t handle

Attribute handle

uint8_t perm

Attribute permissions

struct bt_gatt_dm_cb
#include <gatt_dm.h>

Discovery callback structure.

This structure is used for tracking the result of a discovery.

Public Members

void (*completed)(struct bt_gatt_dm *dm, void *context)

Discovery completed callback.

The discovery procedure has completed successfully.

Note

You must release the discovery data with bt_gatt_dm_data_release if you want to start another discovery.

Param dm:

[inout] Discovery Manager instance

Param context:

[inout] The value passed to gatt_db_discovery_start()

void (*service_not_found)(struct bt_conn *conn, void *context)

Service not found callback.

The targeted service could not be found during the discovery.

Param conn:

[inout] Connection object.

Param context:

[inout] The value passed to gatt_db_discovery_start()

void (*error_found)(struct bt_conn *conn, int err, void *context)

Discovery error found callback.

The discovery procedure has failed.

Param conn:

[inout] Connection object.

Param err:

[in] The error code.

Param context:

[inout] The value passed to gatt_db_discovery_start()