Direct-BT
2.3.1
Direct-BT - Direct Bluetooth Programming.
|
A thread safe GATT handler associated to one device via one L2CAP connection. More...
#include <BTGattHandler.hpp>
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< BTDevice > | getDeviceUnchecked () const noexcept |
std::shared_ptr< BTDevice > | getDeviceChecked () 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< GattGenericAccessSvc > | getGenericAccess () 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< GattGenericAccessSvc > | getGenericAccess (jau::darray< BTGattServiceRef > &primServices) |
Higher level semantic functionality. More... | |
std::shared_ptr< GattGenericAccessSvc > | getGenericAccess (jau::darray< BTGattCharRef > &genericAccessCharDeclList) |
std::shared_ptr< GattDeviceInformationSvc > | getDeviceInformation (jau::darray< BTGattServiceRef > &primServices) |
std::shared_ptr< GattDeviceInformationSvc > | getDeviceInformation (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) |
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.
|
strong |
Enumerator | |
---|---|
MAX_ATT_MTU | |
MIN_ATT_MTU |
Definition at line 142 of file BTGattHandler.hpp.
|
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.
|
delete |
|
noexcept |
Destructor closing this instance including L2CAP channel, see disconnect().
Definition at line 334 of file BTGattHandler.cpp.
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.
Definition at line 105 of file BTGattHandler.cpp.
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.
Definition at line 908 of file BTGattHandler.cpp.
|
noexcept |
Disconnect this BTGattHandler and optionally the associated device.
disconnectDevice | if true, associated device will also be disconnected, otherwise not. |
ioErrorCause | if true, reason for disconnection is an IO error |
Definition at line 341 of file BTGattHandler.cpp.
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.
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
shared_this | shared pointer of this instance, used to forward a weak_ptr to BTGattService for back-reference. Reference is validated. |
Definition at line 513 of file BTGattHandler.cpp.
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.
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
shared_this | shared pointer of this instance, used to forward a weak_ptr to BTGattService for back-reference. Reference is validated. |
result | vector containing all discovered primary services |
Definition at line 528 of file BTGattHandler.cpp.
|
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.
|
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.
|
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.
std::shared_ptr< BTDevice > BTGattHandler::getDeviceChecked | ( | ) | const |
Definition at line 75 of file BTGattHandler.cpp.
std::shared_ptr< GattDeviceInformationSvc > BTGattHandler::getDeviceInformation | ( | jau::darray< BTGattCharRef > & | deviceInfoCharDeclList | ) |
std::shared_ptr< GattDeviceInformationSvc > BTGattHandler::getDeviceInformation | ( | jau::darray< BTGattServiceRef > & | primServices | ) |
Definition at line 1096 of file BTGattHandler.cpp.
|
inlinenoexcept |
|
inlinenoexcept |
Returns the internal kept shared GattGenericAccessSvc instance.
This instance is created via discoverCompletePrimaryServices().
Definition at line 322 of file BTGattHandler.hpp.
std::shared_ptr< GattGenericAccessSvc > BTGattHandler::getGenericAccess | ( | jau::darray< BTGattCharRef > & | genericAccessCharDeclList | ) |
std::shared_ptr< GattGenericAccessSvc > BTGattHandler::getGenericAccess | ( | jau::darray< BTGattServiceRef > & | primServices | ) |
Higher level semantic functionality.
Definition at line 986 of file BTGattHandler.cpp.
|
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.
|
inlinenoexcept |
Definition at line 265 of file BTGattHandler.hpp.
|
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.
|
inlinenoexcept |
Definition at line 255 of file BTGattHandler.hpp.
|
inlinenoexcept |
Definition at line 266 of file BTGattHandler.hpp.
|
inlinenoexcept |
Definition at line 254 of file BTGattHandler.hpp.
|
inlinenoexcept |
Definition at line 253 of file BTGattHandler.hpp.
|
inlinestaticconstexpr |
Definition at line 149 of file BTGattHandler.hpp.
|
delete |
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.
true
if successful, otherwise false in case no GATT services exists etc. Definition at line 994 of file BTGattHandler.cpp.
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.
Definition at line 753 of file BTGattHandler.cpp.
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.
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.
|
noexcept |
Definition at line 145 of file BTGattHandler.cpp.
|
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.
associatedCharacteristic | the match criteria to remove any BTGattCharListener from the list |
Definition at line 137 of file BTGattHandler.cpp.
|
noexcept |
Remove all event listener from the list.
Returns the number of removed event listener.
Definition at line 166 of file BTGattHandler.cpp.
|
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.
|
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.
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.
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.
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.
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.
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.