Direct-BT v3.3.0-1-gc2d430c
Direct-BT - Direct Bluetooth Programming.
BTDevice.hpp
Go to the documentation of this file.
1/*
2 * Author: Sven Gothel <sgothel@jausoft.com>
3 * Copyright (c) 2020 Gothel Software e.K.
4 * Copyright (c) 2020 ZAFENA AB
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining
7 * a copy of this software and associated documentation files (the
8 * "Software"), to deal in the Software without restriction, including
9 * without limitation the rights to use, copy, modify, merge, publish,
10 * distribute, sublicense, and/or sell copies of the Software, and to
11 * permit persons to whom the Software is furnished to do so, subject to
12 * the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be
15 * included in all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
20 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
21 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
22 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
23 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24 */
25
26#ifndef BT_DEVICE_HPP_
27#define BT_DEVICE_HPP_
28
29#include <cstring>
30#include <string>
31#include <memory>
32#include <cstdint>
33
34#include <mutex>
35
36#include <jau/darray.hpp>
37
38#include "BTTypes1.hpp"
39
40#include "HCIIoctl.hpp"
41#include "HCIComm.hpp"
42
43#include "MgmtTypes.hpp"
44#include "SMPHandler.hpp"
45#include "BTGattHandler.hpp"
46#include "SMPKeyBin.hpp"
47
48namespace direct_bt {
49
50 // *************************************************
51 // *************************************************
52 // *************************************************
53
54 /** \addtogroup DBTUserAPI
55 *
56 * @{
57 */
58
59 class BTAdapter; // forward
60 class AdapterStatusListener; // forward
61 typedef std::shared_ptr<AdapterStatusListener> AdapterStatusListenerRef; // forward
62
63 /**
64 * BTDevice represents one remote Bluetooth device.
65 *
66 * @anchor BTDeviceRoles
67 * Invariable remote BTDevice roles (see getRole()):
68 *
69 * - {@link BTRole::Master}: The remote device has discovered us and maybe is connected to us. The remote device acts as a ::GATTRole::Client.
70 * - {@link BTRole::Slave}: The remote device has advertised and maybe we are connected to it. The remote device acts as a ::GATTRole::Server.
71 *
72 * Note the local {@link BTAdapter}'s [opposite role](@ref BTAdapterRoles).
73 *
74 * @see BTAdapter
75 * @see [BTAdapter roles](@ref BTAdapterRoles).
76 * @see [BTGattHandler roles](@ref BTGattHandlerRoles).
77 * @see [Bluetooth Specification](https://www.bluetooth.com/specifications/bluetooth-core-specification/)
78 * @see [Direct-BT Overview](namespacedirect__bt.html#details)
79 */
80 class BTDevice : public BTObject
81 {
82 friend BTAdapter; // managing us: ctor and update(..) during discovery
83 friend BTGattHandler; // may issue detailed disconnect(..)
84
85 private:
86 BTAdapter & adapter;
87 BTRole btRole;
88 std::unique_ptr<L2CAPClient> l2cap_att;
89 uint64_t ts_last_discovery;
90 uint64_t ts_last_update;
91 std::string name;
92 int8_t rssi = 127; // The core spec defines 127 as the "not available" value
93 int8_t tx_power = 127; // The core spec defines 127 as the "not available" value
94 std::shared_ptr<EInfoReport> eir; // Merged EIR (using shared_ptr to allow CoW style update)
95 std::shared_ptr<EInfoReport> eir_ind; // AD_IND EIR
96 std::shared_ptr<EInfoReport> eir_scan_rsp; // AD_SCAN_RSP EIR
97 jau::relaxed_atomic_uint16 hciConnHandle;
101 std::shared_ptr<SMPHandler> smpHandler = nullptr;
102 std::recursive_mutex mtx_smpHandler;
103 std::shared_ptr<BTGattHandler> gattHandler = nullptr;
104 mutable std::recursive_mutex mtx_gattHandler;
105 mutable std::recursive_mutex mtx_connect;
106 mutable std::mutex mtx_eir;
107 jau::sc_atomic_bool isConnected;
108 jau::sc_atomic_bool allowDisconnect; // allowDisconnect = isConnected || 'isConnectIssued'
109 jau::relaxed_atomic_int32 supervision_timeout; // [ms]
110 jau::relaxed_atomic_uint32 smp_events; // registering smp events until next BTAdapter::smp_watchdog periodic timeout check
111
112 struct PairingData {
113 bool is_pre_paired = false;
118 SMPIOCapability io_cap_auto = SMPIOCapability::UNSET; // not cleared by clearSMPStates()
119
120 SMPPairingState state;
121 PairingMode mode;
122 bool res_requested_sec;
123 bool use_sc;
124 bool encryption_enabled;
125
126 std::uint32_t passKey_resp;
127
128 SMPAuthReqs authReqs_init, authReqs_resp;
129 SMPIOCapability ioCap_init, ioCap_resp;
130 SMPOOBDataFlag oobFlag_init, oobFlag_resp;
131 uint8_t maxEncsz_init, maxEncsz_resp;
132 SMPKeyType keys_init_exp, keys_resp_exp;
133 SMPKeyType keys_init_has, keys_resp_has;
134
135 // LTK: Set of Long Term Key data: ltk, ediv + rand
136 SMPLongTermKey ltk_init, ltk_resp;
137
138 // IRK
139 SMPIdentityResolvingKey irk_init, irk_resp;
140
141 // Identity Address Information
142 BDAddressAndType id_address_init, id_address_resp;
143
144 // CSRK
145 SMPSignatureResolvingKey csrk_init, csrk_resp;
146
147 // Link Key
148 SMPLinkKey lk_init, lk_resp;
149
150 /**
151 * Return verbose string representation of PairingData
152 * @param addressAndType remote address of the BTDevice
153 * @param role remote role of the BTDevice
154 */
155 std::string toString(const uint16_t dev_id, const BDAddressAndType& addressAndType, const BTRole& role) const;
156 };
157 PairingData pairing_data;
158 mutable std::recursive_mutex mtx_pairing;
159 std::condition_variable_any cv_pairing_state_changed;
160 mutable jau::sc_atomic_bool sync_data;
161
162 /** Private class only for private make_shared(). */
163 class ctor_cookie { friend BTDevice; ctor_cookie(const uint16_t secret) { (void)secret; } };
164
165 /** Private std::make_shared<BTDevice>(..) vehicle for friends. */
166 static std::shared_ptr<BTDevice> make_shared(BTAdapter & adapter, EInfoReport const & r) {
167 return std::make_shared<BTDevice>(BTDevice::ctor_cookie(0), adapter, r);
168 }
169
170 void clearData() noexcept;
171
172 bool updateIdentityAddress(BDAddressAndType const & identityAddress, bool sendEvent) noexcept;
173 bool updateVisibleAddress(BDAddressAndType const & randomPrivateAddress) noexcept;
174 EIRDataType update(EInfoReport const & data) noexcept;
175 EIRDataType update(GattGenericAccessSvc const &data, const uint64_t timestamp) noexcept;
176
177 void notifyDisconnected() noexcept;
178 void notifyConnected(const std::shared_ptr<BTDevice>& sthis, const uint16_t handle, const SMPIOCapability io_cap_has) noexcept;
179 void notifyLEFeatures(const std::shared_ptr<BTDevice>& sthis, const LE_Features features) noexcept;
180 void notifyLEPhyUpdateComplete(const HCIStatusCode status, const LE_PHYs Tx, const LE_PHYs Rx) noexcept;
181
182 /**
183 * Setup L2CAP channel connection to device incl. optional security encryption level off-thread.
184 * <p>
185 * Will be performed after connectLE(..), i.e. notifyConnected() and notifyLEFeatures(),
186 * initiated by the latter.
187 * </p>
188 */
189 void processL2CAPSetup(std::shared_ptr<BTDevice> sthis);
190
191 void validateConnectedSecParam(BTSecurityLevel& res_sec_level, SMPIOCapability& res_io_cap) const noexcept;
192
193 public:
194 /**
195 * Returns the validated security parameter BTSecurityLevel and SMPIOCapability
196 * in the designated references.
197 * <p>
198 * Validation is performed as follows:
199 * <pre>
200 * if( BTSecurityLevel::UNSET < sec_level ) {
201 * if( BTSecurityLevel::NONE == sec_level ||
202 * BTSecurityLevel::ENC_ONLY == sec_level )
203 * {
204 * // No authentication, maybe encryption
205 * res_sec_level = sec_level;
206 * res_io_cap = SMPIOCapability::NO_INPUT_NO_OUTPUT;
207 * } else if( hasSMPIOCapabilityAnyIO( io_cap ) ) {
208 * // Authentication w/ IO
209 * res_sec_level = sec_level;
210 * res_io_cap = io_cap;
211 * } else if( SMPIOCapability::NO_INPUT_NO_OUTPUT == io_cap ) {
212 * // Fall back: auto -> encryption only
213 * res_sec_level = BTSecurityLevel::ENC_ONLY;
214 * res_io_cap = SMPIOCapability::NO_INPUT_NO_OUTPUT;
215 * } else {
216 * // Use auth w/ SMPIOCapability::UNSET
217 * res_sec_level = sec_level;
218 * res_io_cap = io_cap;
219 * }
220 * } else {
221 * res_sec_level = BTSecurityLevel::UNSET;
222 * res_io_cap = io_cap;
223 * }
224 * </pre>
225 * </p>
226 * @param sec_level user value
227 * @param io_cap user value
228 * @param res_sec_level validated return value
229 * @param res_io_cap validated return value
230 */
231 static void validateSecParam(const BTSecurityLevel sec_level, const SMPIOCapability io_cap,
232 BTSecurityLevel& res_sec_level, SMPIOCapability& res_io_cap) noexcept;
233
234 private:
235
236 /**
237 * Established SMP host connection and security for L2CAP connection if sec_level > BTSecurityLevel::NONE.
238 * <p>
239 * Will be performed after connectLE(..), i.e. notifyConnected() and notifyLEFeatures().<br>
240 * Called from processL2CAPSetup, if supported.
241 * </p>
242 * <p>
243 * If sec_level > BTSecurityLevel::NONE, sets the BlueZ's L2CAP socket BT_SECURITY sec_level, determining the SMP security mode per connection.
244 * </p>
245 * <p>
246 * The SMPHandler is managed by this device instance and closed via disconnectSMP().
247 * </p>
248 *
249 * @param sec_level sec_level <= BTSecurityLevel::NONE will not set security level and returns false.
250 * @return true if a security level > BTSecurityLevel::NONE has been set successfully, false if no security level has been set or if it failed.
251 */
252 bool connectSMP(std::shared_ptr<BTDevice> sthis, const BTSecurityLevel sec_level) noexcept;
253
254 bool checkPairingKeyDistributionComplete() const noexcept;
255
256 bool updatePairingState(const std::shared_ptr<BTDevice>& sthis, const MgmtEvent& evt, const HCIStatusCode evtStatus, SMPPairingState claimed_state) noexcept;
257
258 /**
259 * Forwarded from HCIHandler -> BTAdapter -> this BTDevice
260 * <p>
261 * Will be initiated by processL2CAPSetup()'s security_level setup after connectLE(..), i.e. notifyConnected() and notifyLEFeatures().
262 * </p>
263 */
264 void hciSMPMsgCallback(const std::shared_ptr<BTDevice>& sthis, const SMPPDUMsg& msg, const HCIACLData::l2cap_frame& source) noexcept;
265
266 void getSMPEncStatus(bool& enc_done, bool& using_auth, bool& is_pre_paired);
267
268 /**
269 * Setup GATT via connectGATT() off-thread.
270 * <p>
271 * <p>
272 * Will be performed after connectLE(..), i.e. notifyConnected() and notifyLEFeatures().<br>
273 * Called from either processL2CAPSetup() w/o security or with SMP security readiness from hciSMPMsgCallback().
274 * </p>
275 */
276 void processDeviceReady(std::shared_ptr<BTDevice> sthis, const uint64_t timestamp);
277
278 /**
279 * Returns a newly established GATT connection.
280 * <p>
281 * Will be performed after connectLE(..) via notifyConnected(), processNotifyConnectedOffThread().
282 * </p>
283 * <p>
284 * The GATTHandler is managed by this device instance and closed via disconnectGATT().
285 * </p>
286 */
287 bool connectGATT(const std::shared_ptr<BTDevice>& sthis) noexcept;
288
289 /**
290 * Will be performed within disconnect() and notifyDisconnected().
291 */
292 void disconnectGATT(const int caller) noexcept;
293
294 /**
295 * Will be performed within disconnect() and notifyDisconnected().
296 */
297 void disconnectSMP(const int caller) noexcept;
298
299 void clearSMPStates(const bool connected) noexcept;
300
301 void sendMgmtEvDeviceDisconnected(std::unique_ptr<MgmtEvent> evt) noexcept;
302
303 public:
306
307 const uint64_t ts_creation;
308 /** Either the remote devices' initially reported (resolvable) random address or its (static) public identity address. */
310 /** Device's unique mac address and type tuple, might be its initially reported (resolvable) random address until pairing. */
312
313 /** Private ctor for private BTDevice::make_shared() intended for friends. */
314 BTDevice(const BTDevice::ctor_cookie& cc, BTAdapter & adapter, EInfoReport const & r);
315
316 BTDevice(const BTDevice&) = delete;
317 void operator=(const BTDevice&) = delete;
318
319 /**
320 * Releases this instance after calling {@link #remove()}.
321 */
322 ~BTDevice() noexcept override;
323
324 std::string get_java_class() const noexcept override {
325 return java_class();
326 }
327 static std::string java_class() noexcept {
328 return std::string(JAVA_DBT_PACKAGE "DBTDevice");
329 }
330
331 /** Returns the managing adapter */
332 BTAdapter & getAdapter() const { return adapter; }
333
334 /** Returns the shared pointer of this instance managed by the adapter. */
335 std::shared_ptr<BTDevice> getSharedInstance() const noexcept;
336
337 /**
338 * Return the fixed BTRole of this remote BTDevice.
339 * @see BTRole
340 * @see @ref BTDeviceRoles
341 * @since 2.4.0
342 */
343 BTRole getRole() const noexcept { return btRole; }
344
345 /**
346 * Return the local GATTRole operating for the remote BTDevice.
347 * @see @ref BTGattHandlerRoles
348 * @see @ref BTDeviceRoles
349 * @since 2.4.0
350 */
351 GATTRole getLocalGATTRole() const noexcept;
352
353 /**
354 * Returns the timestamp in monotonic milliseconds when this device instance has been created,
355 * either via its initial discovery or its initial direct connection.
356 * @see BasicTypes::getCurrentMilliseconds()
357 */
358 uint64_t getCreationTimestamp() const noexcept { return ts_creation; }
359
360 /**
361 * Returns the timestamp in monotonic milliseconds when this device instance has
362 * discovered or connected directly the last time.
363 * @see BasicTypes::getCurrentMilliseconds()
364 */
365 uint64_t getLastDiscoveryTimestamp() const noexcept { return ts_last_discovery; }
366
367 /**
368 * Returns the timestamp in monotonic milliseconds when this device instance underlying data
369 * has been updated the last time.
370 * @see BasicTypes::getCurrentMilliseconds()
371 */
372 uint64_t getLastUpdateTimestamp() const noexcept { return ts_last_update; }
373
374 /**
375 * @see getLastUpdateTimestamp()
376 */
377 uint64_t getLastUpdateAge(const uint64_t ts_now) const noexcept { return ts_now - ts_last_update; }
378
379 /**
380 * Returns the devices' unique EUI48 address and type tuple, might be its initially reported (resolvable) random address until pairing,
381 * i.e. BDAddressType::BDADDR_LE_RANDOM instead of BDAddressType::BDADDR_LE_PUBLIC.
382 * <p>
383 * After pairing or if the remote device uses a (static) public address,
384 * it is considered unique and BDAddressType::BDADDR_LE_PUBLIC.
385 * </p>
386 * @since 3.2.0
387 */
388 constexpr BDAddressAndType const & getAddressAndType() const noexcept { return addressAndType; }
389
390 /**
391 * Returns the devices' visible BDAddressAndType, i.e. BDAddressType::BDADDR_LE_RANDOM or BDAddressType::BDADDR_LE_PUBLIC
392 * <p>
393 * The devices' address as initially reported by the system might be a (resolvable) random address,
394 * i.e. BDAddressType::BDADDR_LE_RANDOM instead of BDAddressType::BDADDR_LE_PUBLIC.
395 * </p>
396 * @since 3.2.8
397 * @see #getAddressAndType()
398 */
400
401 /**
402 * Returns Received Signal Strength Indicator (RSSI)
403 * in dBm with ±6 dB accuracy of device as recognized at discovery and connect.
404 * <p>
405 * BT Core Spec v5.2: Vol 4, Part E HCI: 7.5.4 Read RSSI command
406 * </p>
407 * <p>
408 * Any positive RSSI value indicates how many dB the RSSI is above the upper limit,
409 * any negative value indicates how many dB the RSSI is below the lower limit.
410 * The value zero indicates that the RSSI is inside the Golden Receive Power Range.
411 * </p>
412 * <p>
413 * LE range [-127..20] with 0 inside the Golden Receive Power Range
414 * and 127 as "not available" value (core spec).
415 * </p>
416 * <pre>
417 * pathloss = Tx Power Level – RSSI
418 * </pre>
419 * @see #getTxPower()
420 */
421 int8_t getRSSI() const noexcept { return rssi; }
422
423 /**
424 * Return Tx Power Level in dBm with ±6 dB accuracy of device as recognized at discovery and connect.
425 * <p>
426 * Core Specification Supplement, Part A, Section 1.5.
427 * </p>
428 * <p>
429 * Range [-127..20] with 127 as "not available" value (core spec).
430 * </p>
431 * <pre>
432 * pathloss = Tx Power Level – RSSI
433 * </pre>
434 * @see #getRSSI()
435 */
436 int8_t getTxPower() const noexcept { return tx_power; }
437
438 /**
439 * Returns the remote device name.
440 *
441 * The name has been set by the advertised EInfoReport if available,
442 * otherwise by the GATT GenericAccess data post connection.
443 */
444 std::string const getName() const noexcept;
445
446 /**
447 * Return the merged advertised EInfoReport for this remote device.
448 *
449 * The EInfoReport is updated by new scan-reports (update) and when disconnected (empty).
450 * @since 2.5.3
451 */
452 EInfoReportRef getEIR() noexcept;
453
454 /**
455 * Return the latest advertised EInfoReport AD_IND variant for this remote device.
456 *
457 * The EInfoReport is replaced by new scan-reports only.
458 * @since 2.6.6
459 */
460 EInfoReportRef getEIRInd() noexcept;
461
462 /**
463 * Return the latest advertised EInfoReport AD_SCAN_RSP for this remote device.
464 *
465 * The EInfoReport is replaced by new scan-reports only.
466 * @since 2.6.6
467 */
468 EInfoReportRef getEIRScanRsp() noexcept;
469
470 std::string toString() const noexcept override { return toString(false); }
471
472 std::string toString(bool includeDiscoveredServices) const noexcept;
473
474 /**
475 * Add the given AdapterStatusListener to the list if not already present,
476 * intended to listen only for events matching this device.
477 *
478 * User needs to implement AdapterStatusListener::matchDevice() for the latter.
479 *
480 * The AdapterStatusListener is released at remove() or this device's destruction.
481 * <p>
482 * Returns true if the given listener is not element of the list and has been newly added,
483 * otherwise false.
484 * </p>
485 * <p>
486 * The newly added AdapterStatusListener will receive an initial
487 * AdapterStatusListener::adapterSettingsChanged(..) event,
488 * passing an empty AdapterSetting::NONE oldMask and changedMask, as well as current AdapterSetting newMask. <br>
489 * This allows the receiver to be aware of this adapter's current settings.
490 * </p>
491 * @since 2.3.0
492 * @see BTAdapter::addStatusListener()
493 * @see BTAdapter::removeStatusListener()
494 * @see BTAdapter::removeAllStatusListener()
495 * @see removeStatusListener()
496 */
497 bool addStatusListener(const AdapterStatusListenerRef& l) noexcept;
498
499 /**
500 * Remove the given listener from the list.
501 * <p>
502 * Returns true if the given listener is an element of the list and has been removed,
503 * otherwise false.
504 * </p>
505 * @since 2.3.0
506 * @see BTAdapter::removeStatusListener()
507 * @see BTAdapter::removeStatusListener()
508 * @see BTAdapter::removeAllStatusListener()
509 * @see addStatusListener()
510 */
511 bool removeStatusListener(const AdapterStatusListenerRef& l) noexcept;
512
513 /**
514 * Retrieves the current connection info for this device and returns the ConnectionInfo reference if successful,
515 * otherwise returns nullptr.
516 * <p>
517 * Before this method returns, the internal rssi and tx_power will be updated if any changed
518 * and therefore all BTAdapterStatusListener's deviceUpdated(..) method called for notification.
519 * </p>
520 */
521 std::shared_ptr<ConnectionInfo> getConnectionInfo() noexcept;
522
523 /**
524 * Return true if the device has been successfully connected, otherwise false.
525 */
526 bool getConnected() noexcept { return isConnected; }
527
528 /**
529 * Establish a HCI BDADDR_LE_PUBLIC or BDADDR_LE_RANDOM connection to this device.
530 * <p>
531 * BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.12 LE Create Connection command
532 * </p>
533 * <p>
534 * If this device's addressType is not BDADDR_LE_PUBLIC or BDADDR_LE_RANDOM,
535 * HCIStatusCode::UNACCEPTABLE_CONNECTION_PARAM is being returned.
536 * </p>
537 * <p>
538 * The actual new connection handle will be delivered asynchronous and
539 * the connection event can be caught via AdapterStatusListener::deviceConnected(..),
540 * or if failed via AdapterStatusListener::deviceDisconnected(..).
541 * </p>
542 * <p>
543 * The device is tracked by the managing adapter.
544 * </p>
545 * <p>
546 * Default parameter values are chosen for using public address resolution
547 * and usual connection latency, interval etc.
548 * </p>
549 * <p>
550 * Set window to the same value as the interval, enables continuous scanning.
551 * </p>
552 * <p>
553 * The associated BTAdapter's HCIHandler instance is used to connect,
554 * see HCIHandler::le_create_conn().
555 * </p>
556 *
557 * @param le_scan_interval in units of 0.625ms, default value 24 for 15ms; Value range [4 .. 0x4000] for [2.5ms .. 10.24s]
558 * @param le_scan_window in units of 0.625ms, default value 24 for 15ms; Value range [4 .. 0x4000] for [2.5ms .. 10.24s]. Shall be <= le_scan_interval
559 * @param conn_interval_min in units of 1.25ms, default value 8 for 10ms; Value range [6 .. 3200] for [7.5ms .. 4000ms]
560 * @param conn_interval_max in units of 1.25ms, default value 12 for 15ms; Value range [6 .. 3200] for [7.5ms .. 4000ms]
561 * @param conn_latency slave latency in units of connection events, default value 0; Value range [0 .. 0x01F3]. See Range of [0 - getHCIMaxConnLatency()].
562 * @param conn_supervision_timeout in units of 10ms, default value >= 10 x conn_interval_max; Value range [0xA-0x0C80] for [100ms - 32s]. We use 500ms minimum, i.e. getHCIConnSupervisorTimeout(0, 15, ::HCIConstInt::LE_CONN_MIN_TIMEOUT_MS).
563 * @return HCIStatusCode::SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.
564 */
565 HCIStatusCode connectLE(const uint16_t le_scan_interval=24, const uint16_t le_scan_window=24,
566 const uint16_t conn_interval_min=8, const uint16_t conn_interval_max=12,
567 const uint16_t conn_latency=0, const uint16_t conn_supervision_timeout=getHCIConnSupervisorTimeout(0, 15)) noexcept;
568
569 /**
570 * Establish a HCI BDADDR_BREDR connection to this device.
571 * <p>
572 * BT Core Spec v5.2: Vol 4, Part E HCI: 7.1.5 Create Connection command
573 * </p>
574 * <p>
575 * If this device's addressType is not BDADDR_BREDR,
576 * HCIStatusCode::UNACCEPTABLE_CONNECTION_PARAM is being returned.
577 * </p>
578 * <p>
579 * The actual new connection handle will be delivered asynchronous and
580 * the connection event can be caught via AdapterStatusListener::deviceConnected(..),
581 * or if failed via AdapterStatusListener::deviceDisconnected(..).
582 * </p>
583 * <p>
584 * The device is tracked by the managing adapter.
585 * </p>
586 * <p>
587 * The associated BTAdapter's HCIHandler instance is used to connect,
588 * see HCIHandler::create_conn().
589 * </p>
590 * @return HCIStatusCode::SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.
591 */
592 HCIStatusCode connectBREDR(const uint16_t pkt_type=HCI_DM1 | HCI_DM3 | HCI_DM5 | HCI_DH1 | HCI_DH3 | HCI_DH5,
593 const uint16_t clock_offset=0x0000, const uint8_t role_switch=0x01) noexcept;
594
595 /**
596 * Establish a default HCI connection to this device, using certain default parameter.
597 * <p>
598 * BT Core Spec v5.2: Vol 4, Part E HCI: 7.8.12 LE Create Connection command <br>
599 * BT Core Spec v5.2: Vol 4, Part E HCI: 7.1.5 Create Connection command
600 * </p>
601 * <p>
602 * Depending on this device's addressType,
603 * either a BREDR (BDADDR_BREDR) or LE (BDADDR_LE_PUBLIC, BDADDR_LE_RANDOM) connection is attempted.<br>
604 * If unacceptable, HCIStatusCode::UNACCEPTABLE_CONNECTION_PARAM is being returned.
605 * </p>
606 * <p>
607 * The actual new connection handle will be delivered asynchronous and
608 * the connection event can be caught via AdapterStatusListener::deviceConnected(..),
609 * or if failed via AdapterStatusListener::deviceDisconnected(..).
610 * <p>
611 * The device is tracked by the managing adapter.
612 * </p>
613 * <p>
614 * See connectLE() and connectBREDR() for more details.
615 * </p>
616 * @return HCIStatusCode::SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.
617 */
618 HCIStatusCode connectDefault() noexcept;
619
620
621 /** Return the HCI connection handle to the LE or BREDR peer, zero if not connected. */
622 uint16_t getConnectionHandle() const noexcept { return hciConnHandle; }
623
624 /**
625 * Request and return LE_PHYs bit for the given connection.
626 * <pre>
627 * BT Core Spec v5.2: Vol 4, Part E, 7.8.47 LE Read PHY command
628 * </pre>
629 * @param resTx reference for the resulting transmitter LE_PHYs bit
630 * @param resRx reference for the resulting receiver LE_PHYs bit
631 * @return HCIStatusCode
632 * @see getTxPhys()
633 * @see getRxPhys()
634 * @see getConnectedLE_PHY()
635 * @see setConnectedLE_PHY()
636 * @see BTAdapter::setDefaultLE_PHY()
637 * @since 2.4.0
638 */
639 HCIStatusCode getConnectedLE_PHY(LE_PHYs& resTx, LE_PHYs& resRx) noexcept;
640
641 /**
642 * Return the Tx LE_PHYs as notified via HCIMetaEventType::LE_PHY_UPDATE_COMPLETE
643 * or retrieved via getConnectedLE_PHY()
644 * @see getTxPhys()
645 * @see getRxPhys()
646 * @see getConnectedLE_PHY()
647 * @see setConnectedLE_PHY()
648 * @see BTAdapter::setDefaultLE_PHY()
649 * @since 2.4.0
650 */
651 LE_PHYs getTxPhys() const noexcept { return le_phy_tx; }
652
653 /**
654 * Return the Rx LE_PHYs as notified via HCIMetaEventType::LE_PHY_UPDATE_COMPLETE
655 * or retrieved via getConnectedLE_PHY()
656 * @see getTxPhys()
657 * @see getRxPhys()
658 * @see getConnectedLE_PHY()
659 * @see setConnectedLE_PHY()
660 * @see BTAdapter::setDefaultLE_PHY()
661 * @since 2.4.0
662 */
663 LE_PHYs getRxPhys() const noexcept { return le_phy_rx; }
664
665 /**
666 * Sets preference of used LE_PHYs for the given connection.
667 *
668 * - BT Core Spec v5.2: Vol 4, Part E, 7.8.49 LE Set PHY command
669 * - BT Core Spec v5.2: Vol 4, Part E, 7.7.65.12 LE PHY Update Complete event
670 *
671 * @param Tx transmitter LE_PHYs bit mask of preference if not set to LE_PHYs::NONE (ignored).
672 * @param Rx receiver LE_PHYs bit mask of preference if not set to LE_PHYs::NONE (ignored).
673 * @return
674 * @see getTxPhys()
675 * @see getRxPhys()
676 * @see getConnectedLE_PHY()
677 * @see setConnectedLE_PHY()
678 * @see BTAdapter::setDefaultLE_PHY()
679 * @since 2.4.0
680 */
681 HCIStatusCode setConnectedLE_PHY(const LE_PHYs Tx, const LE_PHYs Rx) noexcept;
682
683 /**
684 * Disconnect the LE or BREDR peer's GATT and HCI connection.
685 * <p>
686 * BT Core Spec v5.2: Vol 4, Part E HCI: 7.1.6 Disconnect command
687 * </p>
688 * <p>
689 * The actual disconnect event will be delivered asynchronous and
690 * the connection event can be caught via AdapterStatusListener::deviceDisconnected(..).
691 * </p>
692 * <p>
693 * The device will be removed from the managing adapter's connected devices
694 * when AdapterStatusListener::deviceDisconnected(..) has been received.
695 * </p>
696 * <p>
697 * An open GATTHandler will also be closed.<br>
698 * The connection to this device is removed, removing all connected profiles.
699 * </p>
700 * <p>
701 * An application using one thread per device and rapid connect, should either use disconnect() or remove(),
702 * but never issue remove() after disconnect(). Doing so would eventually delete the device being already
703 * in use by another thread due to discovery post disconnect!
704 * </p>
705 * <p>
706 * The associated BTAdapter's HCIHandler instance is used to disconnect,
707 * see HCIHandler::disconnect().
708 * </p>
709 * @return HCIStatusCode::SUCCESS if the command has been accepted, otherwise HCIStatusCode may disclose reason for rejection.
710 */
712
713 /**
714 * Returns true if this device has completed SMP pairing or keys are set via uploadKeys()
715 * @see uploadKeys()
716 * @since 3.2.3
717 */
718 bool isPrePaired() const noexcept { return pairing_data.is_pre_paired; }
719
720 /**
721 * Returns the responder SMP passkey, ranging from [0..999999].
722 * <p>
723 * Authentication (MITM) PASSKEY (produced by this responder adapter, acting as peripheral GATT server) and shall be displayed for the initiating remote device, see PairingMode::PASSKEY_ENTRY_ini
724 * </p>
725 * @see ::SMPPairingState::PASSKEY_NOTIFY
726 * @see ::SMPPairingState::COMPLETED
727 * @see AdapterStatusListener::deviceReady()
728 */
729 std::uint32_t getResponderSMPPassKey() const noexcept;
730
731 /** Returns getResponderSMPPassKey() as a canonical string, e.g. '012345'. */
733
734 /**
735 * Returns the available ::SMPKeyType mask for the responder (LL slave) or initiator (LL master).
736 * @param responder if true, queries the responder (LL slave) key, otherwise the initiator (LL master) key.
737 * @return ::SMPKeyType mask result
738 * @see ::SMPPairingState::COMPLETED
739 * @see AdapterStatusListener::deviceReady()
740 */
741 SMPKeyType getAvailableSMPKeys(const bool responder) const noexcept;
742
743 /**
744 * Copy all keys from the given SMPKeyBin into this BTDevice.
745 *
746 * Issue uploadKeys() to upload all SMP keys to the adapter
747 * before connecting to enable pre-pairing.
748 *
749 * If SMPKeyBin::isValid() and initiator or responder LTK available,
750 * the following procedure will be applied to this BTDevice:
751 *
752 * - If BTSecurityLevel _is_ BTSecurityLevel::NONE
753 * + Setting security to ::BTSecurityLevel::NONE and ::SMPIOCapability::NO_INPUT_NO_OUTPUT via BTDevice::setConnSecurity()
754 * - else if BTSecurityLevel > BTSecurityLevel::NONE
755 * + Setting security to ::BTSecurityLevel::ENC_ONLY and ::SMPIOCapability::NO_INPUT_NO_OUTPUT via BTDevice::setConnSecurity()
756 * - Copying all keys from SMPKeyBin to this device, without uploading to the adapter
757 *
758 * ::BTSecurityLevel::ENC_ONLY is set to avoid a new SMP ::PairingMode negotiation,
759 * which is undesired as this instances' stored LTK shall be used for ::PairingMode::PRE_PAIRED.
760 *
761 * @param bin
762 * @return true if successful, false if pairing is currently in progress
763 * @see isPrePaired()
764 * @see setLongTermKey()
765 * @see setIdentityResolvingKey()
766 * @see setSignatureResolvingKey()
767 * @see setLinkKey()
768 * @see uploadKeys()
769 * @since 2.4.0
770 */
771 bool setSMPKeyBin(const SMPKeyBin& bin) noexcept;
772
773 /**
774 * Upload all set keys to the adapter for pre-pairing.
775 *
776 * Must be called before connecting to this device, otherwise HCIStatusCode::CONNECTION_ALREADY_EXISTS will be returned.
777 *
778 * @return ::HCIStatusCode::SUCCESS if successful, otherwise the appropriate error code.
779 * @see isPrePaired()
780 * @see setLongTermKey()
781 * @see setIdentityResolvingKey()
782 * @see setSignatureResolvingKey()
783 * @see setLinkKey()
784 * @see setSMPKeyBin()
785 * @since 2.4.0
786 */
787 HCIStatusCode uploadKeys() noexcept;
788
789 /**
790 * Convenient combination of setSMPKeyBin() and uploadKeys()
791 * after validating given SMPKeyBin file and SMPKeyBin::getSecLevel() > req_min_level.
792 * @param bin the SMPKeyBin file
793 * @param req_min_level SMPKeyBin::getSecLevel() shall be greater or equal to this required minimum
794 * @return ::HCIStatusCode::SUCCESS if successful, otherwise the appropriate error code.
795 * @see isPrePaired()
796 * @see setSMPKeyBin()
797 * @see uploadKeys()
798 * @since 2.4.0
799 */
800 HCIStatusCode uploadKeys(const SMPKeyBin& bin, const BTSecurityLevel req_min_level) noexcept {
801 if( bin.isValid() && bin.getSecLevel() >= req_min_level && setSMPKeyBin(bin) ) {
802 return uploadKeys();
803 } else {
805 }
806 }
807
808 /**
809 * Convenient combination of SMPKeyBin::read(), setSMPKeyBin() and uploadKeys()
810 * after validating given SMPKeyBin file and SMPKeyBin::getSecLevel() > req_min_level.
811 * @param smp_key_bin_path director for the SMPKeyBin file, derived by this BTDevice
812 * @param req_min_level SMPKeyBin::getSecLevel() shall be greater or equal to this required minimum
813 * @return ::HCIStatusCode::SUCCESS if successful, otherwise the appropriate error code.
814 * @see isPrePaired()
815 * @see SMPKeyBin::read()
816 * @see setSMPKeyBin()
817 * @see uploadKeys()
818 * @since 2.4.0
819 */
820 HCIStatusCode uploadKeys(const std::string& smp_key_bin_path, const BTSecurityLevel req_min_level, const bool verbose_) noexcept {
821 return uploadKeys(SMPKeyBin::read(smp_key_bin_path, *this, verbose_), req_min_level);
822 }
823
824 /**
825 * Returns a copy of the Long Term Key (LTK), valid after connection and SMP pairing has been completed.
826 * @param responder true will return the responder's LTK info (remote device, LL slave), otherwise the initiator's (the LL master).
827 * @return the resulting key. SMPLongTermKeyInfo::enc_size will be zero if invalid.
828 * @see ::SMPPairingState::COMPLETED
829 * @see AdapterStatusListener::deviceReady()
830 */
831 SMPLongTermKey getLongTermKey(const bool responder) const noexcept;
832
833 /**
834 * Sets the Long Term Key (LTK) of this device for pre-paired encryption.
835 *
836 * Issue uploadKeys() to upload all SMP keys to the adapter
837 * before connecting to enable pre-pairing.
838 *
839 * @param ltk the pre-paired encryption LTK
840 * @see setSMPKeyBin()
841 * @see uploadKeys()
842 * @since 2.4.0
843 */
844 void setLongTermKey(const SMPLongTermKey& ltk) noexcept;
845
846 /**
847 * Returns a copy of the Identity Resolving Key (IRK), valid after connection and SMP pairing has been completed.
848 * @param responder true will return the responder's IRK info (LL slave), otherwise the initiator's (LL master).
849 * @return the resulting key
850 * @see ::SMPPairingState::COMPLETED
851 * @see AdapterStatusListener::deviceReady()
852 */
853 SMPIdentityResolvingKey getIdentityResolvingKey(const bool responder) const noexcept;
854
855 /**
856 * Sets the Identity Resolving Key (IRK) of this device for pre-paired encryption.
857 *
858 * Issue uploadKeys() to upload all SMP keys to the adapter
859 * before connecting to enable pre-pairing.
860 *
861 * @param irk the Identity Resolving Key (IRK)
862 * @see setSMPKeyBin()
863 * @see uploadKeys()
864 * @since 2.4.0
865 */
866 void setIdentityResolvingKey(const SMPIdentityResolvingKey& irk) noexcept;
867
868 /**
869 * Returns true if this remote device's IRK matches the given random private address (rpa)
870 * @param rpa random private address
871 * @see getIdentityResolvingKey()
872 */
873 bool matches_irk(const BDAddressAndType& rpa) noexcept;
874
875 /**
876 * Returns a copy of the Signature Resolving Key (CSRK), valid after connection and SMP pairing has been completed.
877 * @param responder true will return the responder's CSRK info (remote device, LL slave), otherwise the initiator's (the LL master).
878 * @return the resulting key
879 * @see ::SMPPairingState::COMPLETED
880 * @see AdapterStatusListener::deviceReady()
881 */
882 SMPSignatureResolvingKey getSignatureResolvingKey(const bool responder) const noexcept;
883
884 /**
885 * Sets the Signature Resolving Key (CSRK) of this device for pre-paired encryption.
886 *
887 * Issue uploadKeys() to upload all SMP keys to the adapter
888 * before connecting to enable pre-pairing.
889 *
890 * @param csrk the Signature Resolving Key (CSRK)
891 * @see setSMPKeyBin()
892 * @see uploadKeys()
893 * @since 2.4.0
894 */
895 void setSignatureResolvingKey(const SMPSignatureResolvingKey& csrk) noexcept;
896
897 /**
898 * Returns a copy of the Link Key (LK), valid after connection and SMP pairing has been completed.
899 * @param responder true will return the responder's LTK info (remote device, LL slave), otherwise the initiator's (the LL master).
900 * @return the resulting key
901 * @see ::SMPPairingState::COMPLETED
902 * @see AdapterStatusListener::deviceReady()
903 * @since 2.4.0
904 */
905 SMPLinkKey getLinkKey(const bool responder) const noexcept;
906
907 /**
908 * Sets the Link Key (LK) of this device for pre-paired encryption.
909 *
910 * Issue uploadKeys() to upload all SMP keys to the adapter
911 * before connecting to enable pre-pairing.
912 *
913 * @param lk the pre-paired encryption LK
914 * @see setSMPKeyBin()
915 * @see uploadKeys()
916 * @since 2.4.0
917 */
918 void setLinkKey(const SMPLinkKey& lk) noexcept;
919
920 /**
921 * Unpair this device from the adapter while staying connected.
922 * <p>
923 * All keys will be cleared within the adapter and host implementation.<br>
924 * Should rarely being used by user.<br>
925 * Internally being used to re-start pairing if GATT connection fails
926 * in PairingMode::PRE_PAIRED mode.
927 * </p>
928 *
929 * Unpair is performed by directly for a consistent and stable security workflow:
930 * - when a BTRole::Slave BTDevice is discovered, see AdapterStatusListener::deviceFound().
931 * - when a BTRole::Slave BTDevice is disconnected, see AdapterStatusListener::deviceDisconnected().
932 * - when a BTRole::Master BTDevice gets connected, see AdapterStatusListener::deviceConnected().
933 *
934 * @return HCIStatusCode::SUCCESS or an appropriate error status.
935 * @see AdapterStatusListener::deviceFound()
936 * @see AdapterStatusListener::deviceDisconnected()
937 * @see AdapterStatusListener::deviceConnected()
938 */
939 HCIStatusCode unpair() noexcept;
940
941 /**
942 * Return the ::BTSecurityLevel, determined when the connection is established.
943 * @see ::BTSecurityLevel
944 * @see ::SMPIOCapability
945 * @see getConnIOCapability()
946 * @see setConnSecurity()
947 * @see setConnSecurityAuto()
948 */
949 BTSecurityLevel getConnSecurityLevel() const noexcept;
950
951 /**
952 * Return the set ::SMPIOCapability value, determined when the connection is established.
953 * @see ::BTSecurityLevel
954 * @see ::SMPIOCapability
955 * @see getConnSecurityLevel()
956 * @see setConnSecurity()
957 * @see setConnSecurityAuto()
958 */
959 SMPIOCapability getConnIOCapability() const noexcept;
960
961 /**
962 * Sets the given ::BTSecurityLevel and ::SMPIOCapability used to connect to this device on the upcoming connection.<br>
963 * Parameter are validated using validateSecParam().
964 * <p>
965 * Method returns false if this device has already being connected,
966 * or BTDevice::connectLE() or BTDevice::connectBREDR() has been issued already.
967 * </p>
968 * <p>
969 * Method either changes both parameter for the upcoming connection or none at all.
970 * </p>
971 * @param[in] sec_level ::BTSecurityLevel to be applied.
972 * @param[in] io_cap ::SMPIOCapability to be applied, defaults to ::SMPIOCapability::UNSET
973 * @see ::BTSecurityLevel
974 * @see ::SMPIOCapability
975 * @see getConnSecurityLevel()
976 * @see getConnIOCapability()
977 * @see setConnSecurityAuto()
978 */
979 bool setConnSecurity(const BTSecurityLevel sec_level, const SMPIOCapability io_cap=SMPIOCapability::UNSET) noexcept;
980
981 /**
982 * Set automatic security negotiation of BTSecurityLevel and SMPIOCapability pairing mode.
983 * <p>
984 * Disabled by default and if set to ::SMPIOCapability::UNSET
985 * </p>
986 * Implementation iterates through below setup from highest security to lowest,
987 * while performing a full connection attempt for each.
988 * <pre>
989 * BTSecurityLevel::ENC_AUTH_FIPS, iocap_auto*
990 * BTSecurityLevel::ENC_AUTH, iocap_auto*
991 * BTSecurityLevel::ENC_ONLY, SMPIOCapability::NO_INPUT_NO_OUTPUT
992 * BTSecurityLevel::NONE, SMPIOCapability::NO_INPUT_NO_OUTPUT
993 *
994 * (*): user SMPIOCapability choice of for authentication IO, skipped if ::SMPIOCapability::NO_INPUT_NO_OUTPUT
995 * </pre>
996 * <p>
997 * Implementation may perform multiple connection and disconnect actions
998 * until successful pairing or failure.
999 * </p>
1000 * <p>
1001 * Intermediate AdapterStatusListener::deviceConnected() and AdapterStatusListener::deviceDisconnected()
1002 * callbacks are not delivered while negotiating. This avoids any interference by the user application.
1003 * </p>
1004 * @param auth_io_cap user SMPIOCapability choice for negotiation
1005 * @see isConnSecurityAutoEnabled()
1006 * @see ::BTSecurityLevel
1007 * @see ::SMPIOCapability
1008 * @see setConnSecurity()
1009 */
1010 bool setConnSecurityAuto(const SMPIOCapability iocap_auto) noexcept;
1011
1012 /**
1013 * Returns true if automatic security negotiation has been enabled via setConnSecurityAuto(),
1014 * otherwise false.
1015 * @see setConnSecurityAuto()
1016 */
1017 bool isConnSecurityAutoEnabled() const noexcept;
1018
1019 HCIStatusCode setPairingPINCode(const std::string& pinCode) noexcept;
1021
1022 /**
1023 * Method sets the given passkey entry, see ::PairingMode::PASSKEY_ENTRY_ini.
1024 * <p>
1025 * Call this method if the device shall be securely paired with ::PairingMode::PASSKEY_ENTRY_ini,
1026 * i.e. when notified via AdapterStatusListener::devicePairingState() in state ::SMPPairingState::PASSKEY_EXPECTED.
1027 * </p>
1028 *
1029 * @param passkey used for ::PairingMode::PASSKEY_ENTRY_ini method.
1030 * Will be encrypted before sending to counter-party.
1031 *
1032 * @return HCIStatusCode::SUCCESS if the command has been accepted, otherwise ::HCIStatusCode may disclose reason for rejection.
1033 * @see PairingMode
1034 * @see SMPPairingState
1035 * @see AdapterStatusListener::devicePairingState()
1036 * @see setPairingPasskey()
1037 * @see setPairingNumericComparison()
1038 * @see getPairingMode()
1039 * @see getPairingState()
1040 */
1041 HCIStatusCode setPairingPasskey(const uint32_t passkey) noexcept;
1042
1043 /**
1044 * Method replies with a negative passkey response, i.e. rejection, see ::PairingMode::PASSKEY_ENTRY_ini.
1045 * <p>
1046 * You may call this method if the device shall be securely paired with ::PairingMode::PASSKEY_ENTRY_ini,
1047 * i.e. when notified via AdapterStatusListener::devicePairingState() in state ::SMPPairingState::PASSKEY_EXPECTED.
1048 * </p>
1049 * <p>
1050 * Current experience exposed a roughly 3s immediate disconnect handshake with certain devices and/or Kernel BlueZ code.
1051 *
1052 * Hence using setPairingPasskey() with `passkey = 0` is recommended, especially when utilizing
1053 * automatic security negotiation via setConnSecurityAuto()!
1054 * </p>
1055 *
1056 * @return HCIStatusCode::SUCCESS if the command has been accepted, otherwise ::HCIStatusCode may disclose reason for rejection.
1057 * @see PairingMode
1058 * @see SMPPairingState
1059 * @see AdapterStatusListener::devicePairingState()
1060 * @see setPairingPasskey()
1061 * @see setPairingNumericComparison()
1062 * @see getPairingMode()
1063 * @see getPairingState()
1064 */
1066
1067 /**
1068 * Method sets the numeric comparison result, see ::PairingMode::NUMERIC_COMPARE_ini.
1069 * <p>
1070 * Call this method if the device shall be securely paired with ::PairingMode::NUMERIC_COMPARE_ini,
1071 * i.e. when notified via AdapterStatusListener::devicePairingState() in state ::SMPPairingState::NUMERIC_COMPARE_EXPECTED.
1072 * </p>
1073 *
1074 * @param equal used for ::PairingMode::NUMERIC_COMPARE_ini method.
1075 * Will be encrypted before sending to counter-party.
1076 *
1077 * @return HCIStatusCode::SUCCESS if the command has been accepted, otherwise ::HCIStatusCode may disclose reason for rejection.
1078 * @see PairingMode
1079 * @see SMPPairingState
1080 * @see AdapterStatusListener::devicePairingState()
1081 * @see setPairingPasskey()
1082 * @see setPairingNumericComparison()
1083 * @see getPairingMode()
1084 * @see getPairingState()
1085 */
1086 HCIStatusCode setPairingNumericComparison(const bool equal) noexcept;
1087
1088 /**
1089 * Returns the current ::PairingMode used by the device.
1090 * <p>
1091 * If the device is not paired, the current mode is ::PairingMode::NONE.
1092 * </p>
1093 * <p>
1094 * If the Pairing Feature Exchange is completed, i.e. ::SMPPairingState::FEATURE_EXCHANGE_COMPLETED,
1095 * as notified by AdapterStatusListener::devicePairingState(),
1096 * the current mode reflects the currently used PairingMode.
1097 * </p>
1098 * <p>
1099 * In case the Pairing Feature Exchange is in progress, the current mode is ::PairingMode::NEGOTIATING.
1100 * </p>
1101 * @return current ::PairingMode.
1102 * @see PairingMode
1103 * @see SMPPairingState
1104 * @see AdapterStatusListener::devicePairingState()
1105 * @see setPairingPasskey()
1106 * @see setPairingNumericComparison()
1107 * @see getPairingMode()
1108 * @see getPairingState()
1109 */
1110 PairingMode getPairingMode() const noexcept;
1111
1112 /**
1113 * Returns the current ::SMPPairingState.
1114 * <p>
1115 * If the device is not paired, the current state is ::SMPPairingState::NONE.
1116 * </p>
1117 * @see PairingMode
1118 * @see SMPPairingState
1119 * @see AdapterStatusListener::devicePairingState()
1120 * @see setPairingPasskey()
1121 * @see setPairingNumericComparison()
1122 * @see getPairingMode()
1123 * @see getPairingState()
1124 */
1125 SMPPairingState getPairingState() const noexcept;
1126
1127 /**
1128 * Disconnects this device via disconnect(..) if getConnected()==true
1129 * and explicitly removes its shared references from the Adapter:
1130 * connected-devices, discovered-devices and shared-devices.
1131 * <p>
1132 * All added AdapterStatusListener associated with this instance
1133 * will be removed via BTAdapter::removeAllStatusListener().
1134 * </p>
1135 * <p>
1136 * This method shall be issued to ensure no device reference will
1137 * be leaked in a long lived adapter,
1138 * as only its reference within connected-devices and discovered-devices are removed at disconnect.
1139 * </p>
1140 * <p>
1141 * After calling this method, this instance is destroyed and shall not be used anymore!
1142 * </p>
1143 * <p>
1144 * This method is an atomic operation.
1145 * </p>
1146 * <p>
1147 * An application using one thread per device and rapid connect, should either use disconnect() or remove(),
1148 * but never issue remove() after disconnect() if the device is in use.
1149 * </p>
1150 * @see BTAdapter::removeAllStatusListener()
1151 */
1152 void remove() noexcept;
1153
1154 /**
1155 * Returns the connected GATTHandler or nullptr, see connectGATT(), getGattServices() and disconnect().
1156 *
1157 * @return
1158 * @see connectGATT()
1159 * @see getGattServices()
1160 * @see disconnect()
1161 */
1162 std::shared_ptr<BTGattHandler> getGattHandler() noexcept;
1163
1165
1166 /**
1167 * Returns a complete list of shared BTGattService available on this device,
1168 * initially retrieved via GATT discovery.
1169 *
1170 * In case of transmission error, zero services or no GattGenericAccessSvc,
1171 * method will return zero services indicating an error.
1172 * In this case, user can assume that the connection is or will be disconnected.
1173 *
1174 * Method is only functional on a remote BTDevice in BTRole::Slave, a GATT server (GATTRole::Server),
1175 * i.e. the local BTAdapter acting as a BTRole::Master GATT client.
1176 *
1177 * The HCI connectLE(..) or connectBREDR(..) must be performed first, see {@link #connectDefault()}.
1178 *
1179 * If this method has been called for the first time:
1180 * - the client MTU exchange will be performed
1181 * - a complete list of BTGattService inclusive their BTGattChar and BTGattDesc will be retrieved
1182 * - the GattGenericAccessSvc is extracted from the services, see getGattGenericAccess().
1183 *
1184 * A GATT connection will be created via connectGATT() if not established yet.
1185 * @see getGattGenericAccess()
1186 */
1188
1189 /**
1190 * Returns the shared GenericAccess instance, retrieved by getGattServices() or nullptr if not available.
1191 *
1192 * @return
1193 * @see getGattServices()
1194 */
1196
1197 /**
1198 * Find a BTGattService by its service_uuid.
1199 *
1200 * It will check objects of a connected device using getGattServices().
1201 *
1202 * It will not turn on discovery or connect to this remote device.
1203 *
1204 * @parameter service_uuid the jau::uuid_t of the desired BTGattService
1205 * @return The matching service or null if not found
1206 * @see findGattChar()
1207 */
1208 BTGattServiceRef findGattService(const jau::uuid_t& service_uuid) noexcept;
1209
1210 /**
1211 * Find a BTGattChar by its service_uuid and char_uuid.
1212 *
1213 * It will check objects of this connected device using getGattServices().
1214 *
1215 * It will not turn on discovery or connect to this remote device.
1216 *
1217 * @parameter service_uuid the jau::uuid_t of the intermediate BTGattService
1218 * @parameter char_uuid the jau::uuid_t of the desired BTGattChar, within the intermediate BTGattService.
1219 * @return The matching characteristic or null if not found
1220 * @since 2.4.0
1221 * @see findGattService()
1222 */
1223 BTGattCharRef findGattChar(const jau::uuid_t& service_uuid, const jau::uuid_t& char_uuid) noexcept;
1224
1225 /**
1226 * Find a BTGattChar by its char_uuid only.
1227 *
1228 * It will check objects of this connected device using getGattServices().
1229 *
1230 * It will not turn on discovery or connect to this remote device.
1231 *
1232 * This variation is less efficient than findGattChar() by service_uuid and char_uuid,
1233 * since it has to traverse through all services.
1234 *
1235 * @parameter char_uuid the jau::uuid_t of the desired BTGattChar, within the intermediate BTGattService.
1236 * @return The matching characteristic or null if not found
1237 * @since 2.4.0
1238 * @see findGattService()
1239 */
1240 BTGattCharRef findGattChar(const jau::uuid_t& char_uuid) noexcept;
1241
1242 /**
1243 * Send a notification event consisting out of the given `value` representing the given characteristic value handle
1244 * to the connected BTRole::Master.
1245 *
1246 * This command is only valid if this BTGattHandler is in role GATTRole::Server.
1247 *
1248 * Implementation is not receiving any reply after sending out the indication and returns immediately.
1249 *
1250 * @param char_value_handle valid characteristic value handle, must be sourced from referenced DBGattServer
1251 * @param value the octets to be send
1252 * @return true if successful, otherwise false
1253 */
1254 bool sendNotification(const uint16_t char_value_handle, const jau::TROOctets & value) noexcept;
1255
1256 /**
1257 * Send an indication event consisting out of the given `value` representing the given characteristic value handle
1258 * to the connected BTRole::Master.
1259 *
1260 * This command is only valid if this BTGattHandler is in role GATTRole::Server.
1261 *
1262 * Implementation awaits the indication reply after sending out the indication.
1263 *
1264 * @param char_value_handle valid characteristic value handle, must be sourced from referenced DBGattServer
1265 * @param value the octets to be send
1266 * @return true if successful, otherwise false
1267 */
1268 bool sendIndication(const uint16_t char_value_handle, const jau::TROOctets & value) noexcept;
1269
1270 /**
1271 * Issues a GATT ping to the device, validating whether it is still reachable.
1272 * <p>
1273 * This method could be periodically utilized to shorten the underlying OS disconnect period
1274 * after turning the device off, which lies within 7-13s.
1275 * </p>
1276 * <p>
1277 * In case the device is no more reachable, the GATTHandler will initiate disconnect due to the occurring IO error.
1278 * A disconnect will finally being issued.
1279 * </p>
1280 * <p>
1281 * GATT services must have been initialized via getGattServices(), otherwise `false` is being returned.
1282 * </p>
1283 * @return `true` if successful, otherwise false in case no GATT services exists or is not connected .. etc.
1284 */
1285 bool pingGATT() noexcept;
1286
1287 /**
1288 * Add the given BTGattCharListener to the listener list if not already present.
1289 * <p>
1290 * Convenience delegation call to GATTHandler
1291 * </p>
1292 * <p>
1293 * To enable the actual BLE notification and/or indication, one needs to call
1294 * BTGattChar::configNotificationIndication(bool, bool, bool[])
1295 * or BTGattChar::enableNotificationOrIndication(bool enabledState[2]).
1296 * </p>
1297 * @param listener A BTGattCharListener instance, listening to all BluetoothGattCharacteristic events of this device
1298 * @return true if the given listener is not element of the list and has been newly added, otherwise false.
1299 * @throws IllegalStateException if the GATTHandler is null, i.e. not connected
1300 */
1301 bool addCharListener(const BTGattCharListenerRef& l) noexcept;
1302
1303 /**
1304 * Please use BTGattChar::addCharListener() for clarity, merely existing here to allow JNI access.
1305 */
1306 bool addCharListener(const BTGattCharListenerRef& l, const BTGattCharRef& d) noexcept;
1307
1308 /**
1309 * Remove the given {@link BTGattCharListener} from the listener list.
1310 * <p>
1311 * If the GATTHandler is null, i.e. not connected, `false` is being returned.
1312 * </p>
1313 * @param listener A {@link BTGattCharListener} instance
1314 * @return true if the given listener is an element of the list and has been removed, otherwise false.
1315 */
1316 bool removeCharListener(const BTGattCharListenerRef& l) noexcept;
1317
1318 /**
1319 * Remove all {@link BTGattCharListener} from the list, which are associated to the given {@link BTGattChar}.
1320 * <p>
1321 * Implementation tests all listener's BTGattCharListener::match(const BTGattChar & characteristic)
1322 * to match with the given associated characteristic.
1323 * </p>
1324 * @param associatedCharacteristic the match criteria to remove any BTGattCharListener from the list
1325 * @return number of removed listener.
1326 */
1327 size_type removeAllAssociatedCharListener(const BTGattCharRef& associatedCharacteristic) noexcept;
1328
1329 size_type removeAllAssociatedCharListener(const BTGattChar * associatedCharacteristic) noexcept;
1330
1331 /**
1332 * Remove all {@link BTGattCharListener} from the list.
1333 * @return number of removed listener.
1334 */
1336 };
1337
1338 inline bool operator==(const BTDevice& lhs, const BTDevice& rhs) noexcept {
1339 return lhs.getAddressAndType() == rhs.getAddressAndType() ||
1340 lhs.getVisibleAddressAndType() == rhs.getVisibleAddressAndType() // FIXME: Evaluate if OK w/o collisions
1341 ;
1342 }
1343
1344 inline bool operator!=(const BTDevice& lhs, const BTDevice& rhs) noexcept
1345 { return !(lhs == rhs); }
1346
1347 typedef std::shared_ptr<BTDevice> BTDeviceRef;
1348
1349 /**@}*/
1350
1351} // namespace direct_bt
1352
1353#endif /* BT_DEVICE_HPP_ */
#define JAVA_DBT_PACKAGE
Definition: BTTypes0.hpp:43
Unique Bluetooth EUI48 address and BDAddressType tuple.
Definition: BTAddress.hpp:175
BTAdapter represents one local Bluetooth Controller.
Definition: BTAdapter.hpp:324
BTDevice represents one remote Bluetooth device.
Definition: BTDevice.hpp:81
BDAddressAndType addressAndType
Device's unique mac address and type tuple, might be its initially reported (resolvable) random addre...
Definition: BTDevice.hpp:311
std::shared_ptr< GattGenericAccessSvc > getGattGenericAccess()
Returns the shared GenericAccess instance, retrieved by getGattServices() or nullptr if not available...
Definition: BTDevice.cpp:2290
HCIStatusCode setPairingPINCodeNegative() noexcept
Definition: BTDevice.cpp:1989
bool removeCharListener(const BTGattCharListenerRef &l) noexcept
Remove the given BTGattCharListener from the listener list.
Definition: BTDevice.cpp:2385
bool setConnSecurity(const BTSecurityLevel sec_level, const SMPIOCapability io_cap=SMPIOCapability::UNSET) noexcept
Sets the given BTSecurityLevel and SMPIOCapability used to connect to this device on the upcoming con...
Definition: BTDevice.cpp:1896
const uint64_t ts_creation
Definition: BTDevice.hpp:307
bool isConnSecurityAutoEnabled() const noexcept
Returns true if automatic security negotiation has been enabled via setConnSecurityAuto(),...
Definition: BTDevice.cpp:1963
SMPLongTermKey getLongTermKey(const bool responder) const noexcept
Returns a copy of the Long Term Key (LTK), valid after connection and SMP pairing has been completed.
Definition: BTDevice.cpp:1726
bool pingGATT() noexcept
Issues a GATT ping to the device, validating whether it is still reachable.
Definition: BTDevice.cpp:2357
uint64_t getCreationTimestamp() const noexcept
Returns the timestamp in monotonic milliseconds when this device instance has been created,...
Definition: BTDevice.hpp:358
void remove() noexcept
Disconnects this device via disconnect(..) if getConnected()==true and explicitly removes its shared ...
Definition: BTDevice.cpp:2588
BTRole getRole() const noexcept
Return the fixed BTRole of this remote BTDevice.
Definition: BTDevice.hpp:343
SMPSignatureResolvingKey getSignatureResolvingKey(const bool responder) const noexcept
Returns a copy of the Signature Resolving Key (CSRK), valid after connection and SMP pairing has been...
Definition: BTDevice.cpp:1775
EInfoReportRef getEIRInd() noexcept
Return the latest advertised EInfoReport AD_IND variant for this remote device.
Definition: BTDevice.cpp:123
LE_PHYs getTxPhys() const noexcept
Return the Tx LE_PHYs as notified via HCIMetaEventType::LE_PHY_UPDATE_COMPLETE or retrieved via getCo...
Definition: BTDevice.hpp:651
constexpr BDAddressAndType const & getAddressAndType() const noexcept
Returns the devices' unique EUI48 address and type tuple, might be its initially reported (resolvable...
Definition: BTDevice.hpp:388
HCIStatusCode setPairingPasskeyNegative() noexcept
Method replies with a negative passkey response, i.e.
Definition: BTDevice.cpp:2031
static void validateSecParam(const BTSecurityLevel sec_level, const SMPIOCapability io_cap, BTSecurityLevel &res_sec_level, SMPIOCapability &res_io_cap) noexcept
Returns the validated security parameter BTSecurityLevel and SMPIOCapability in the designated refere...
Definition: BTDevice.cpp:1864
bool setSMPKeyBin(const SMPKeyBin &bin) noexcept
Copy all keys from the given SMPKeyBin into this BTDevice.
Definition: BTDevice.cpp:1556
uint64_t getLastUpdateAge(const uint64_t ts_now) const noexcept
Definition: BTDevice.hpp:377
HCIStatusCode connectBREDR(const uint16_t pkt_type=HCI_DM1|HCI_DM3|HCI_DM5|HCI_DH1|HCI_DH3|HCI_DH5, const uint16_t clock_offset=0x0000, const uint8_t role_switch=0x01) noexcept
Establish a HCI BDADDR_BREDR connection to this device.
Definition: BTDevice.cpp:523
uint64_t getLastDiscoveryTimestamp() const noexcept
Returns the timestamp in monotonic milliseconds when this device instance has discovered or connected...
Definition: BTDevice.hpp:365
HCIStatusCode unpair() noexcept
Unpair this device from the adapter while staying connected.
Definition: BTDevice.cpp:2572
std::string getResponderSMPPassKeyString() const noexcept
Returns getResponderSMPPassKey() as a canonical string, e.g.
Definition: BTDevice.hpp:732
static std::string java_class() noexcept
Definition: BTDevice.hpp:327
bool removeStatusListener(const AdapterStatusListenerRef &l) noexcept
Remove the given listener from the list.
Definition: BTDevice.cpp:290
SMPPairingState getPairingState() const noexcept
Returns the current SMPPairingState.
Definition: BTDevice.cpp:2078
SMPIdentityResolvingKey getIdentityResolvingKey(const bool responder) const noexcept
Returns a copy of the Identity Resolving Key (IRK), valid after connection and SMP pairing has been c...
Definition: BTDevice.cpp:1744
std::shared_ptr< ConnectionInfo > getConnectionInfo() noexcept
Retrieves the current connection info for this device and returns the ConnectionInfo reference if suc...
Definition: BTDevice.cpp:294
bool setConnSecurityAuto(const SMPIOCapability iocap_auto) noexcept
Set automatic security negotiation of BTSecurityLevel and SMPIOCapability pairing mode.
Definition: BTDevice.cpp:1923
HCIStatusCode connectLE(const uint16_t le_scan_interval=24, const uint16_t le_scan_window=24, const uint16_t conn_interval_min=8, const uint16_t conn_interval_max=12, const uint16_t conn_latency=0, const uint16_t conn_supervision_timeout=getHCIConnSupervisorTimeout(0, 15)) noexcept
Establish a HCI BDADDR_LE_PUBLIC or BDADDR_LE_RANDOM connection to this device.
Definition: BTDevice.cpp:321
uint16_t getConnectionHandle() const noexcept
Return the HCI connection handle to the LE or BREDR peer, zero if not connected.
Definition: BTDevice.hpp:622
PairingMode getPairingMode() const noexcept
Returns the current PairingMode used by the device.
Definition: BTDevice.cpp:2073
LE_PHYs getRxPhys() const noexcept
Return the Rx LE_PHYs as notified via HCIMetaEventType::LE_PHY_UPDATE_COMPLETE or retrieved via getCo...
Definition: BTDevice.hpp:663
BTDevice(const BTDevice &)=delete
BDAddressAndType const & getVisibleAddressAndType() const noexcept
Returns the devices' visible BDAddressAndType, i.e.
Definition: BTDevice.hpp:399
HCIStatusCode setConnectedLE_PHY(const LE_PHYs Tx, const LE_PHYs Rx) noexcept
Sets preference of used LE_PHYs for the given connection.
Definition: BTDevice.cpp:2449
int8_t getTxPower() const noexcept
Return Tx Power Level in dBm with ±6 dB accuracy of device as recognized at discovery and connect.
Definition: BTDevice.hpp:436
std::string const getName() const noexcept
Returns the remote device name.
Definition: BTDevice.cpp:112
uint64_t getLastUpdateTimestamp() const noexcept
Returns the timestamp in monotonic milliseconds when this device instance underlying data has been up...
Definition: BTDevice.hpp:372
EInfoReportRef getEIR() noexcept
Return the merged advertised EInfoReport for this remote device.
Definition: BTDevice.cpp:118
HCIStatusCode getConnectedLE_PHY(LE_PHYs &resTx, LE_PHYs &resRx) noexcept
Request and return LE_PHYs bit for the given connection.
Definition: BTDevice.cpp:2425
void setSignatureResolvingKey(const SMPSignatureResolvingKey &csrk) noexcept
Sets the Signature Resolving Key (CSRK) of this device for pre-paired encryption.
Definition: BTDevice.cpp:1780
size_type removeAllAssociatedCharListener(const BTGattCharRef &associatedCharacteristic) noexcept
Remove all BTGattCharListener from the list, which are associated to the given BTGattChar.
Definition: BTDevice.cpp:2395
EInfoReportRef getEIRScanRsp() noexcept
Return the latest advertised EInfoReport AD_SCAN_RSP for this remote device.
Definition: BTDevice.cpp:128
std::shared_ptr< BTDevice > getSharedInstance() const noexcept
Returns the shared pointer of this instance managed by the adapter.
Definition: BTDevice.cpp:100
bool sendIndication(const uint16_t char_value_handle, const jau::TROOctets &value) noexcept
Send an indication event consisting out of the given value representing the given characteristic valu...
Definition: BTDevice.cpp:2343
BTSecurityLevel getConnSecurityLevel() const noexcept
Return the BTSecurityLevel, determined when the connection is established.
Definition: BTDevice.cpp:1811
SMPKeyType getAvailableSMPKeys(const bool responder) const noexcept
Returns the available SMPKeyType mask for the responder (LL slave) or initiator (LL master).
Definition: BTDevice.cpp:1547
void operator=(const BTDevice &)=delete
GattServiceList_t getGattServices() noexcept
Returns a complete list of shared BTGattService available on this device, initially retrieved via GAT...
Definition: BTDevice.cpp:2240
void setIdentityResolvingKey(const SMPIdentityResolvingKey &irk) noexcept
Sets the Identity Resolving Key (IRK) of this device for pre-paired encryption.
Definition: BTDevice.cpp:1749
void setLinkKey(const SMPLinkKey &lk) noexcept
Sets the Link Key (LK) of this device for pre-paired encryption.
Definition: BTDevice.cpp:1798
~BTDevice() noexcept override
Releases this instance after calling remove().
Definition: BTDevice.cpp:94
HCIStatusCode connectDefault() noexcept
Establish a default HCI connection to this device, using certain default parameter.
Definition: BTDevice.cpp:563
std::uint32_t getResponderSMPPassKey() const noexcept
Returns the responder SMP passkey, ranging from [0..999999].
Definition: BTDevice.cpp:2568
std::shared_ptr< BTGattHandler > getGattHandler() noexcept
Returns the connected GATTHandler or nullptr, see connectGATT(), getGattServices() and disconnect().
Definition: BTDevice.cpp:2235
BTGattServiceRef findGattService(const jau::uuid_t &service_uuid) noexcept
Find a BTGattService by its service_uuid.
Definition: BTDevice.cpp:2299
jau::nsize_t size_type
Definition: BTDevice.hpp:304
BTAdapter & getAdapter() const
Returns the managing adapter.
Definition: BTDevice.hpp:332
HCIStatusCode disconnect(const HCIStatusCode reason=HCIStatusCode::REMOTE_USER_TERMINATED_CONNECTION) noexcept
Disconnect the LE or BREDR peer's GATT and HCI connection.
Definition: BTDevice.cpp:2488
HCIStatusCode uploadKeys(const std::string &smp_key_bin_path, const BTSecurityLevel req_min_level, const bool verbose_) noexcept
Convenient combination of SMPKeyBin::read(), setSMPKeyBin() and uploadKeys() after validating given S...
Definition: BTDevice.hpp:820
bool matches_irk(const BDAddressAndType &rpa) noexcept
Returns true if this remote device's IRK matches the given random private address (rpa)
Definition: BTDevice.cpp:1764
SMPIOCapability getConnIOCapability() const noexcept
Return the set SMPIOCapability value, determined when the connection is established.
Definition: BTDevice.cpp:1816
std::string get_java_class() const noexcept override
Definition: BTDevice.hpp:324
SMPLinkKey getLinkKey(const bool responder) const noexcept
Returns a copy of the Link Key (LK), valid after connection and SMP pairing has been completed.
Definition: BTDevice.cpp:1793
BTDevice(const BTDevice::ctor_cookie &cc, BTAdapter &adapter, EInfoReport const &r)
Private ctor for private BTDevice::make_shared() intended for friends.
Definition: BTDevice.cpp:46
BTGattCharRef findGattChar(const jau::uuid_t &service_uuid, const jau::uuid_t &char_uuid) noexcept
Find a BTGattChar by its service_uuid and char_uuid.
Definition: BTDevice.cpp:2309
bool addCharListener(const BTGattCharListenerRef &l) noexcept
Add the given BTGattCharListener to the listener list if not already present.
Definition: BTDevice.cpp:2367
HCIStatusCode setPairingNumericComparison(const bool equal) noexcept
Method sets the numeric comparison result, see PairingMode::NUMERIC_COMPARE_ini.
Definition: BTDevice.cpp:2052
bool addStatusListener(const AdapterStatusListenerRef &l) noexcept
Add the given AdapterStatusListener to the list if not already present, intended to listen only for e...
Definition: BTDevice.cpp:286
HCIStatusCode uploadKeys() noexcept
Upload all set keys to the adapter for pre-pairing.
Definition: BTDevice.cpp:1649
bool getConnected() noexcept
Return true if the device has been successfully connected, otherwise false.
Definition: BTDevice.hpp:526
BDAddressAndType visibleAddressAndType
Either the remote devices' initially reported (resolvable) random address or its (static) public iden...
Definition: BTDevice.hpp:309
GATTRole getLocalGATTRole() const noexcept
Return the local GATTRole operating for the remote BTDevice.
Definition: BTDevice.cpp:104
jau::snsize_t ssize_type
Definition: BTDevice.hpp:305
int8_t getRSSI() const noexcept
Returns Received Signal Strength Indicator (RSSI) in dBm with ±6 dB accuracy of device as recognized ...
Definition: BTDevice.hpp:421
bool isPrePaired() const noexcept
Returns true if this device has completed SMP pairing or keys are set via uploadKeys()
Definition: BTDevice.hpp:718
void setLongTermKey(const SMPLongTermKey &ltk) noexcept
Sets the Long Term Key (LTK) of this device for pre-paired encryption.
Definition: BTDevice.cpp:1731
std::string toString() const noexcept override
Definition: BTDevice.hpp:470
HCIStatusCode setPairingPasskey(const uint32_t passkey) noexcept
Method sets the given passkey entry, see PairingMode::PASSKEY_ENTRY_ini.
Definition: BTDevice.cpp:2010
bool sendNotification(const uint16_t char_value_handle, const jau::TROOctets &value) noexcept
Send a notification event consisting out of the given value representing the given characteristic val...
Definition: BTDevice.cpp:2330
size_type removeAllCharListener() noexcept
Remove all BTGattCharListener from the list.
Definition: BTDevice.cpp:2415
HCIStatusCode setPairingPINCode(const std::string &pinCode) noexcept
Definition: BTDevice.cpp:1968
Representing a Gatt Characteristic object from the GATTRole::Client perspective.
Definition: BTGattChar.hpp:94
A thread safe GATT handler associated to one device via one L2CAP connection.
Collection of 'Extended Advertising Data' (EAD), 'Advertising Data' (AD) or 'Extended Inquiry Respons...
Definition: BTTypes0.hpp:898
Generic Access Service is a mandatory GATT service all peripherals are required to implement.
uint16_t opcode, uint16_t dev-id, uint16_t param_size
Definition: MgmtTypes.hpp:1402
Storage for SMP keys including required connection parameter per local adapter and remote device.
Definition: SMPKeyBin.hpp:79
static SMPKeyBin read(const std::string &fname, const bool verbose_)
Create a new SMPKeyBin instance based upon stored file denoted by fname.
Definition: SMPKeyBin.hpp:209
Handles the Security Manager Protocol (SMP) using Protocol Data Unit (PDU) encoded messages over L2CA...
Definition: SMPTypes.hpp:842
static const uint16_t le_scan_interval
static const uint16_t le_scan_window
SMPAuthReqs
SMP Authentication Requirements Bits, denotes specific bits or whole protocol uint8_t bit-mask.
Definition: SMPTypes.hpp:283
SMPPairingState
SMP Pairing Process state definition.
Definition: SMPTypes.hpp:107
SMPKeyType
SMP Key Type for Distribution, indicates keys distributed in the Transport Specific Key Distribution ...
Definition: SMPTypes.hpp:415
std::string toPassKeyString(const std::uint32_t passKey) noexcept
Returns given passKey ranging [0..999999] as a canonical string, e.g.
Definition: SMPTypes.cpp:72
SMPOOBDataFlag
Vol 3, Part H, 2.3.3 OOB authentication data.
Definition: SMPTypes.hpp:253
SMPIOCapability
Vol 3, Part H, 2.3.2 IO capabilities.
Definition: SMPTypes.hpp:209
@ UNSET
Denoting unset value, i.e.
std::shared_ptr< AdapterStatusListener > AdapterStatusListenerRef
Definition: BTAdapter.hpp:297
LE_Features
HCI Supported Commands.
Definition: BTTypes0.hpp:162
std::shared_ptr< BTDevice > BTDeviceRef
Definition: BTDevice.hpp:1347
LE_PHYs
LE Transport PHY bit values.
Definition: BTTypes0.hpp:231
std::shared_ptr< EInfoReport > EInfoReportRef
Definition: BTTypes0.hpp:1164
GATTRole
Bluetooth GATT roles.
Definition: BTTypes0.hpp:96
BTRole
Bluetooth roles from the perspective of the link layer (connection initiator).
Definition: BTTypes0.hpp:69
BTSecurityLevel
Bluetooth Security Level.
Definition: BTTypes0.hpp:267
PairingMode
Bluetooth secure pairing mode.
Definition: BTTypes0.hpp:317
bool operator!=(const BTAdapter &lhs, const BTAdapter &rhs) noexcept
Definition: BTAdapter.hpp:1351
constexpr uint16_t getHCIConnSupervisorTimeout(const uint16_t conn_latency, const uint16_t conn_interval_max_ms, const uint16_t min_result_ms=number(HCIConstInt::LE_CONN_MIN_TIMEOUT_MS), const uint16_t multiplier=10) noexcept
Defining the supervising timeout for LE connections to be a multiple of the maximum connection interv...
Definition: HCITypes.hpp:102
HCIStatusCode
BT Core Spec v5.2: Vol 1, Part F Controller Error Codes: 1.3 List of Error Codes.
Definition: HCITypes.hpp:138
EIRDataType
Bit mask of 'Extended Inquiry Response' (EIR) data fields, indicating a set of related data.
Definition: BTTypes0.hpp:838
@ UNSET
Security Level not set, value 0.
std::shared_ptr< BTGattCharListener > BTGattCharListenerRef
Definition: BTGattChar.hpp:70
std::shared_ptr< BTGattChar > BTGattCharRef
Definition: BTGattChar.hpp:410
std::shared_ptr< BTGattService > BTGattServiceRef
Definition: BTGattChar.hpp:67
uint_fast32_t nsize_t
Natural 'size_t' alternative using uint_fast32_t as its natural sized type.
Definition: int_types.hpp:53
int_fast32_t snsize_t
Natural 'ssize_t' alternative using int_fast32_t as its natural sized type.
Definition: int_types.hpp:65
__pack(...): Produces MSVC, clang and gcc compatible lead-in and -out macros.
Definition: backtrace.hpp:32
STL namespace.
Representing ACL Datas' L2CAP Frame.
Definition: HCITypes.hpp:977
SMP Identity Resolving Key, used for platform agnostic persistence.
Definition: SMPTypes.hpp:636
Local SMP Link Key, used for platform agnostic persistence, mapping to platform specific MgmtLoadLink...
Definition: SMPTypes.hpp:824
SMP Long Term Key, used for platform agnostic persistence.
Definition: SMPTypes.hpp:552
SMP Signature Resolving Key, used for platform agnostic persistence.
Definition: SMPTypes.hpp:712
std::atomic<T> type with predefined fixed std::memory_order, not allowing changing the memory model o...