Direct-BT  2.3.1
Direct-BT - Direct Bluetooth Programming.
Public Types | Public Member Functions | Static Public Member Functions | List of all members
direct_bt::BTGattHandler Class Reference

A thread safe GATT handler associated to one device via one L2CAP connection. More...

#include <BTGattHandler.hpp>

Collaboration diagram for direct_bt::BTGattHandler:

Public Types

enum  Defaults : int32_t { Defaults::MAX_ATT_MTU = 512, Defaults::MIN_ATT_MTU = 23 }
 

Public Member Functions

 BTGattHandler (const std::shared_ptr< BTDevice > &device, L2CAPComm &l2cap_att) noexcept
 Constructing a new BTGattHandler instance with its opened and connected L2CAP channel. More...
 
 BTGattHandler (const BTGattHandler &)=delete
 
void operator= (const BTGattHandler &)=delete
 
 ~BTGattHandler () noexcept
 Destructor closing this instance including L2CAP channel, see disconnect(). More...
 
std::shared_ptr< BTDevicegetDeviceUnchecked () const noexcept
 
std::shared_ptr< BTDevicegetDeviceChecked () const
 
bool isConnected () const noexcept
 
bool hasIOError () const noexcept
 
std::string getStateString () const noexcept
 
bool disconnect (const bool disconnectDevice, const bool ioErrorCause) noexcept
 Disconnect this BTGattHandler and optionally the associated device. More...
 
uint16_t getServerMTU () const noexcept
 
uint16_t getUsedMTU () const noexcept
 
BTGattCharRef findCharacterisicsByValueHandle (const uint16_t charValueHandle) noexcept
 Find and return the BTGattChar within internal primary services via given characteristic value handle. More...
 
BTGattCharRef findCharacterisicsByValueHandle (const uint16_t charValueHandle, jau::darray< BTGattServiceRef > &services) noexcept
 Find and return the BTGattChar within given list of primary services via given characteristic value handle. More...
 
BTGattCharRef findCharacterisicsByValueHandle (const uint16_t charValueHandle, BTGattServiceRef service) noexcept
 Find and return the BTGattChar within given primary service via given characteristic value handle. More...
 
jau::darray< BTGattServiceRef > & discoverCompletePrimaryServices (std::shared_ptr< BTGattHandler > shared_this)
 Discover all primary services and all its characteristics declarations including their client config. More...
 
jau::darray< BTGattServiceRef > & getServices () noexcept
 Returns a reference of the internal kept BTGattService list. More...
 
std::shared_ptr< GattGenericAccessSvcgetGenericAccess () noexcept
 Returns the internal kept shared GattGenericAccessSvc instance. More...
 
bool discoverPrimaryServices (std::shared_ptr< BTGattHandler > shared_this, jau::darray< BTGattServiceRef > &result)
 Discover all primary services only. More...
 
bool discoverCharacteristics (BTGattServiceRef &service)
 Discover all characteristics of a service and declaration attributes only. More...
 
bool discoverDescriptors (BTGattServiceRef &service)
 BT Core Spec v5.2: Vol 3, Part G GATT: 4.7.1 Discover All Characteristic Descriptors. More...
 
bool readValue (const uint16_t handle, POctets &res, int expectedLength=-1)
 Generic read GATT value and long value. More...
 
bool readCharacteristicValue (const BTGattChar &c, POctets &res, int expectedLength=-1)
 BT Core Spec v5.2: Vol 3, Part G GATT: 4.8.1 Read Characteristic Value. More...
 
bool readDescriptorValue (BTGattDesc &cd, int expectedLength=-1)
 BT Core Spec v5.2: Vol 3, Part G GATT: 4.12.1 Read Characteristic Descriptor. More...
 
bool writeValue (const uint16_t handle, const TROOctets &value, const bool withResponse)
 Generic write GATT value and long value. More...
 
bool writeDescriptorValue (const BTGattDesc &cd)
 BT Core Spec v5.2: Vol 3, Part G GATT: 4.12.3 Write Characteristic Descriptors. More...
 
bool writeCharacteristicValue (const BTGattChar &c, const TROOctets &value)
 BT Core Spec v5.2: Vol 3, Part G GATT: 4.9.3 Write Characteristic Value. More...
 
bool writeCharacteristicValueNoResp (const BTGattChar &c, const TROOctets &value)
 BT Core Spec v5.2: Vol 3, Part G GATT: 4.9.1 Write Characteristic Value Without Response. More...
 
bool configNotificationIndication (BTGattDesc &cd, const bool enableNotification, const bool enableIndication)
 BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.3 Client Characteristic Configuration. More...
 
bool addCharListener (std::shared_ptr< BTGattCharListener > l)
 Add the given listener to the list if not already present. More...
 
bool removeCharListener (std::shared_ptr< BTGattCharListener > l) noexcept
 Remove the given listener from the list. More...
 
bool removeCharListener (const BTGattCharListener *l) noexcept
 Remove the given listener from the list. More...
 
int removeAllAssociatedCharListener (std::shared_ptr< BTGattChar > associatedChar) noexcept
 Remove all BTGattCharListener from the list, which are associated to the given BTGattChar. More...
 
int removeAllAssociatedCharListener (const BTGattChar *associatedChar) noexcept
 
int removeAllCharListener () noexcept
 Remove all event listener from the list. More...
 
void setSendIndicationConfirmation (const bool v)
 Enable or disable sending an immediate confirmation for received indication events from the device. More...
 
bool getSendIndicationConfirmation () noexcept
 Returns whether sending an immediate confirmation for received indication events from the device is enabled. More...
 
std::shared_ptr< GattGenericAccessSvcgetGenericAccess (jau::darray< BTGattServiceRef > &primServices)
 Higher level semantic functionality. More...
 
std::shared_ptr< GattGenericAccessSvcgetGenericAccess (jau::darray< BTGattCharRef > &genericAccessCharDeclList)
 
std::shared_ptr< GattDeviceInformationSvcgetDeviceInformation (jau::darray< BTGattServiceRef > &primServices)
 
std::shared_ptr< GattDeviceInformationSvcgetDeviceInformation (jau::darray< BTGattCharRef > &deviceInfoCharDeclList)
 
bool ping ()
 Issues a ping to the device, validating whether it is still reachable. More...
 

Static Public Member Functions

static constexpr int number (const Defaults d)
 

Detailed Description

A thread safe GATT handler associated to one device via one L2CAP connection.

Implementation utilizes a lock free ringbuffer receiving data within its separate thread.

Controlling Environment variables, see BTGattEnv.

Definition at line 140 of file BTGattHandler.hpp.

Member Enumeration Documentation

◆ Defaults

enum direct_bt::BTGattHandler::Defaults : int32_t
strong
Enumerator
MAX_ATT_MTU 
MIN_ATT_MTU 

Definition at line 142 of file BTGattHandler.hpp.

Constructor & Destructor Documentation

◆ BTGattHandler() [1/2]

BTGattHandler::BTGattHandler ( const std::shared_ptr< BTDevice > &  device,
L2CAPComm l2cap_att 
)
noexcept

Constructing a new BTGattHandler instance with its opened and connected L2CAP channel.

After successful l2cap connection, the MTU will be exchanged. See getServerMTU() and getUsedMTU(), the latter is in use.

Definition at line 277 of file BTGattHandler.cpp.

Here is the call graph for this function:

◆ BTGattHandler() [2/2]

direct_bt::BTGattHandler::BTGattHandler ( const BTGattHandler )
delete

◆ ~BTGattHandler()

BTGattHandler::~BTGattHandler ( )
noexcept

Destructor closing this instance including L2CAP channel, see disconnect().

Definition at line 334 of file BTGattHandler.cpp.

Here is the call graph for this function:

Member Function Documentation

◆ addCharListener()

bool BTGattHandler::addCharListener ( std::shared_ptr< BTGattCharListener l)

Add the given listener to the list if not already present.

Returns true if the given listener is not element of the list and has been newly added, otherwise false.

Examples
dbt_scanner01.cpp.

Definition at line 105 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ configNotificationIndication()

bool BTGattHandler::configNotificationIndication ( BTGattDesc cd,
const bool  enableNotification,
const bool  enableIndication 
)

BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.3 Client Characteristic Configuration.

Method enables notification and/or indication for the corresponding characteristic at BLE level.

It is recommended to utilize notification over indication, as its link-layer handshake and higher potential bandwidth may deliver material higher performance.

Throws an IllegalArgumentException if the given BTGattDesc is not a ClientCharacteristicConfiguration.

Examples
dbt_scanner01.cpp.

Definition at line 908 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ disconnect()

bool BTGattHandler::disconnect ( const bool  disconnectDevice,
const bool  ioErrorCause 
)
noexcept

Disconnect this BTGattHandler and optionally the associated device.

Parameters
disconnectDeviceif true, associated device will also be disconnected, otherwise not.
ioErrorCauseif true, reason for disconnection is an IO error
Returns
true if successful, otherwise false

Definition at line 341 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ discoverCharacteristics()

bool BTGattHandler::discoverCharacteristics ( BTGattServiceRef service)

Discover all characteristics of a service and declaration attributes only.

BT Core Spec v5.2: Vol 3, Part G GATT: 4.6.1 Discover All Characteristics of a Service

BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.1 Characterisic Declaration Attribute Value

Definition at line 592 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ discoverCompletePrimaryServices()

jau::darray< BTGattServiceRef > & BTGattHandler::discoverCompletePrimaryServices ( std::shared_ptr< BTGattHandler shared_this)

Discover all primary services and all its characteristics declarations including their client config.

BT Core Spec v5.2: Vol 3, Part G GATT: 4.4.1 Discover All Primary Services

Method returns reference to BTGattHandler's internal BTGattService vector of discovered services

Parameters
shared_thisshared pointer of this instance, used to forward a weak_ptr to BTGattService for back-reference. Reference is validated.
Returns
BTGattHandler's internal BTGattService vector of discovered services
Examples
dbt_scanner01.cpp.

Definition at line 513 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ discoverDescriptors()

bool BTGattHandler::discoverDescriptors ( BTGattServiceRef service)

BT Core Spec v5.2: Vol 3, Part G GATT: 4.7.1 Discover All Characteristic Descriptors.

Definition at line 657 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ discoverPrimaryServices()

bool BTGattHandler::discoverPrimaryServices ( std::shared_ptr< BTGattHandler shared_this,
jau::darray< BTGattServiceRef > &  result 
)

Discover all primary services only.

BT Core Spec v5.2: Vol 3, Part G GATT: 4.4.1 Discover All Primary Services

Parameters
shared_thisshared pointer of this instance, used to forward a weak_ptr to BTGattService for back-reference. Reference is validated.
resultvector containing all discovered primary services
Returns
true on success, otherwise false

Definition at line 528 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ findCharacterisicsByValueHandle() [1/3]

BTGattCharRef BTGattHandler::findCharacterisicsByValueHandle ( const uint16_t  charValueHandle)
noexcept

Find and return the BTGattChar within internal primary services via given characteristic value handle.

Returns nullptr if not found.

Definition at line 489 of file BTGattHandler.cpp.

◆ findCharacterisicsByValueHandle() [2/3]

BTGattCharRef BTGattHandler::findCharacterisicsByValueHandle ( const uint16_t  charValueHandle,
BTGattServiceRef  service 
)
noexcept

Find and return the BTGattChar within given primary service via given characteristic value handle.

Returns nullptr if not found.

Definition at line 503 of file BTGattHandler.cpp.

◆ findCharacterisicsByValueHandle() [3/3]

BTGattCharRef BTGattHandler::findCharacterisicsByValueHandle ( const uint16_t  charValueHandle,
jau::darray< BTGattServiceRef > &  services 
)
noexcept

Find and return the BTGattChar within given list of primary services via given characteristic value handle.

Returns nullptr if not found.

Definition at line 493 of file BTGattHandler.cpp.

◆ getDeviceChecked()

std::shared_ptr< BTDevice > BTGattHandler::getDeviceChecked ( ) const

Definition at line 75 of file BTGattHandler.cpp.

◆ getDeviceInformation() [1/2]

std::shared_ptr< GattDeviceInformationSvc > BTGattHandler::getDeviceInformation ( jau::darray< BTGattCharRef > &  deviceInfoCharDeclList)

Definition at line 1026 of file BTGattHandler.cpp.

Here is the call graph for this function:

◆ getDeviceInformation() [2/2]

std::shared_ptr< GattDeviceInformationSvc > BTGattHandler::getDeviceInformation ( jau::darray< BTGattServiceRef > &  primServices)
Examples
dbt_scanner00.cpp, dbt_scanner01.cpp, and dbt_scanner10.cpp.

Definition at line 1096 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getDeviceUnchecked()

std::shared_ptr<BTDevice> direct_bt::BTGattHandler::getDeviceUnchecked ( ) const
inlinenoexcept

Definition at line 250 of file BTGattHandler.hpp.

Here is the caller graph for this function:

◆ getGenericAccess() [1/3]

std::shared_ptr<GattGenericAccessSvc> direct_bt::BTGattHandler::getGenericAccess ( )
inlinenoexcept

Returns the internal kept shared GattGenericAccessSvc instance.

This instance is created via discoverCompletePrimaryServices().

Definition at line 322 of file BTGattHandler.hpp.

Here is the caller graph for this function:

◆ getGenericAccess() [2/3]

std::shared_ptr< GattGenericAccessSvc > BTGattHandler::getGenericAccess ( jau::darray< BTGattCharRef > &  genericAccessCharDeclList)

Definition at line 951 of file BTGattHandler.cpp.

Here is the call graph for this function:

◆ getGenericAccess() [3/3]

std::shared_ptr< GattGenericAccessSvc > BTGattHandler::getGenericAccess ( jau::darray< BTGattServiceRef > &  primServices)

Higher level semantic functionality.

Definition at line 986 of file BTGattHandler.cpp.

Here is the call graph for this function:

◆ getSendIndicationConfirmation()

bool BTGattHandler::getSendIndicationConfirmation ( )
noexcept

Returns whether sending an immediate confirmation for received indication events from the device is enabled.

Default value is true.

This setting is per BTGattHandler and hence per BTDevice.

Definition at line 176 of file BTGattHandler.cpp.

◆ getServerMTU()

uint16_t direct_bt::BTGattHandler::getServerMTU ( ) const
inlinenoexcept
Examples
dbt_scanner01.cpp.

Definition at line 265 of file BTGattHandler.hpp.

Here is the caller graph for this function:

◆ getServices()

jau::darray<BTGattServiceRef>& direct_bt::BTGattHandler::getServices ( )
inlinenoexcept

Returns a reference of the internal kept BTGattService list.

The internal list will be populated via discoverCompletePrimaryServices().

Definition at line 314 of file BTGattHandler.hpp.

Here is the caller graph for this function:

◆ getStateString()

std::string direct_bt::BTGattHandler::getStateString ( ) const
inlinenoexcept
Examples
dbt_scanner01.cpp.

Definition at line 255 of file BTGattHandler.hpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getUsedMTU()

uint16_t direct_bt::BTGattHandler::getUsedMTU ( ) const
inlinenoexcept
Examples
dbt_scanner01.cpp.

Definition at line 266 of file BTGattHandler.hpp.

Here is the caller graph for this function:

◆ hasIOError()

bool direct_bt::BTGattHandler::hasIOError ( ) const
inlinenoexcept

Definition at line 254 of file BTGattHandler.hpp.

◆ isConnected()

bool direct_bt::BTGattHandler::isConnected ( ) const
inlinenoexcept
Examples
dbt_scanner00.cpp, dbt_scanner01.cpp, and dbt_scanner10.cpp.

Definition at line 253 of file BTGattHandler.hpp.

Here is the caller graph for this function:

◆ number()

static constexpr int direct_bt::BTGattHandler::number ( const Defaults  d)
inlinestaticconstexpr
Examples
dbt_scanner00.cpp, dbt_scanner01.cpp, and dbt_scanner10.cpp.

Definition at line 149 of file BTGattHandler.hpp.

Here is the caller graph for this function:

◆ operator=()

void direct_bt::BTGattHandler::operator= ( const BTGattHandler )
delete

◆ ping()

bool BTGattHandler::ping ( )

Issues a ping to the device, validating whether it is still reachable.

This method could be periodically utilized to shorten the underlying OS disconnect period after turning the device off, which lies within 7-13s.

In case the device is no more reachable, disconnect will be initiated due to the occurring IO error.

Returns
true if successful, otherwise false in case no GATT services exists etc.

Definition at line 994 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ readCharacteristicValue()

bool BTGattHandler::readCharacteristicValue ( const BTGattChar c,
POctets res,
int  expectedLength = -1 
)

BT Core Spec v5.2: Vol 3, Part G GATT: 4.8.1 Read Characteristic Value.

BT Core Spec v5.2: Vol 3, Part G GATT: 4.8.3 Read Long Characteristic Value

If expectedLength = 0, then only one ATT_READ_REQ/RSP will be used.

If expectedLength < 0, then long values using multiple ATT_READ_BLOB_REQ/RSP will be used until the response returns zero. This is the default parameter.

If expectedLength > 0, then long values using multiple ATT_READ_BLOB_REQ/RSP will be used if required until the response returns zero.

Examples
dbt_scanner01.cpp.

Definition at line 753 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ readDescriptorValue()

bool BTGattHandler::readDescriptorValue ( BTGattDesc cd,
int  expectedLength = -1 
)

BT Core Spec v5.2: Vol 3, Part G GATT: 4.12.1 Read Characteristic Descriptor.

BT Core Spec v5.2: Vol 3, Part G GATT: 4.12.2 Read Long Characteristic Descriptor

If expectedLength = 0, then only one ATT_READ_REQ/RSP will be used.

If expectedLength < 0, then long values using multiple ATT_READ_BLOB_REQ/RSP will be used until the response returns zero. This is the default parameter.

If expectedLength > 0, then long values using multiple ATT_READ_BLOB_REQ/RSP will be used if required until the response returns zero.

Definition at line 743 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ readValue()

bool BTGattHandler::readValue ( const uint16_t  handle,
POctets res,
int  expectedLength = -1 
)

Generic read GATT value and long value.

If expectedLength = 0, then only one ATT_READ_REQ/RSP will be used.

If expectedLength < 0, then long values using multiple ATT_READ_BLOB_REQ/RSP will be used until the response returns zero. This is the default parameter.

If expectedLength > 0, then long values using multiple ATT_READ_BLOB_REQ/RSP will be used if required until the response returns zero.

Definition at line 762 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ removeAllAssociatedCharListener() [1/2]

int BTGattHandler::removeAllAssociatedCharListener ( const BTGattChar associatedChar)
noexcept

Definition at line 145 of file BTGattHandler.cpp.

◆ removeAllAssociatedCharListener() [2/2]

int BTGattHandler::removeAllAssociatedCharListener ( std::shared_ptr< BTGattChar associatedChar)
noexcept

Remove all BTGattCharListener from the list, which are associated to the given BTGattChar.

Implementation tests all listener's BTGattCharListener::match(const BTGattChar & characteristic) to match with the given associated characteristic.

Parameters
associatedCharacteristicthe match criteria to remove any BTGattCharListener from the list
Returns
number of removed listener.

Definition at line 137 of file BTGattHandler.cpp.

Here is the caller graph for this function:

◆ removeAllCharListener()

int BTGattHandler::removeAllCharListener ( )
noexcept

Remove all event listener from the list.

Returns the number of removed event listener.

Definition at line 166 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ removeCharListener() [1/2]

bool BTGattHandler::removeCharListener ( const BTGattCharListener l)
noexcept

Remove the given listener from the list.

Returns true if the given listener is an element of the list and has been removed, otherwise false.

Definition at line 121 of file BTGattHandler.cpp.

◆ removeCharListener() [2/2]

bool BTGattHandler::removeCharListener ( std::shared_ptr< BTGattCharListener l)
noexcept

Remove the given listener from the list.

Returns true if the given listener is an element of the list and has been removed, otherwise false.

Definition at line 112 of file BTGattHandler.cpp.

Here is the caller graph for this function:

◆ setSendIndicationConfirmation()

void BTGattHandler::setSendIndicationConfirmation ( const bool  v)

Enable or disable sending an immediate confirmation for received indication events from the device.

Default value is true.

This setting is per BTGattHandler and hence per BTDevice.

Definition at line 172 of file BTGattHandler.cpp.

◆ writeCharacteristicValue()

bool BTGattHandler::writeCharacteristicValue ( const BTGattChar c,
const TROOctets value 
)

BT Core Spec v5.2: Vol 3, Part G GATT: 4.9.3 Write Characteristic Value.

Definition at line 849 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ writeCharacteristicValueNoResp()

bool BTGattHandler::writeCharacteristicValueNoResp ( const BTGattChar c,
const TROOctets value 
)

BT Core Spec v5.2: Vol 3, Part G GATT: 4.9.1 Write Characteristic Value Without Response.

Definition at line 859 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ writeDescriptorValue()

bool BTGattHandler::writeDescriptorValue ( const BTGattDesc cd)

BT Core Spec v5.2: Vol 3, Part G GATT: 4.12.3 Write Characteristic Descriptors.

BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3 Characteristic Descriptor

BT Core Spec v5.2: Vol 3, Part G GATT: 3.3.3.3 Client Characteristic Configuration

Definition at line 835 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ writeValue()

bool BTGattHandler::writeValue ( const uint16_t  handle,
const TROOctets value,
const bool  withResponse 
)

Generic write GATT value and long value.

Definition at line 865 of file BTGattHandler.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

The documentation for this class was generated from the following files: