Document iOS BLE device discovery cache behaviorHEADdev

On iOS the BLE device discovery results seem to be limited to just
actively advertising devices. QBluetoothDeviceDiscoveryAgent uses
scanForPeripheralsWithServices API (with nil services), but this
API only returns actively advertising devices.

CoreBluetooth does provide an additional API for querying the already
connected devices (retrieveConnectedPeripheralsWithServices). However
this API only returns peripherals that are connected to the current
central manager instance, making it unfeasible to use in a general
purpose bluetooth discovery (which has its own central manager
instance).

The original bug report mentions iOS 18 but it's hard to confirm
whether or not something has changed in that iOS version.
The CoreBluetooth documentation hasn't changed and I couldn't find
relevant entries in change logs.

In summary it would seem that on iOS we can only return BLE devices
that are advertising. It is therefore advisable to store the device
UUID when it is first discovered; with this UUID it's then possible
later quickly connect to the device (advertising or not). If the
use case allows it, this can result in a better user experience too
as the discovery phase can be omitted.

Note: this issue was reproduced with few different smart watches.
These watches force a pairing when services and characteristics
are read, and after that they always automatically connect to the
phone.

Task-number: QTBUG-136692
Pick-to: 6.10 6.9 6.8 6.5
Change-Id: If9554a60299734da05461c3009cbd543b0dded88
Reviewed-by: Ivan Solovev <[email protected]>

1 files changed, 11 insertions, 0 deletions

diff --git a/src/bluetooth/qbluetoothdevicediscoveryagent.cpp b/src/bluetooth/qbluetoothdevicediscoveryagent.cpp
index da88f4aa..4ac91060 100644
--- a/src/bluetooth/qbluetoothdevicediscoveryagent.cpp
+++ b/src/bluetooth/qbluetoothdevicediscoveryagent.cpp
@@ -305,6 +305,17 @@ void QBluetoothDeviceDiscoveryAgent::start()
     {LowEnergyMethod} only. This may happen due to previously cached search results
     which may be incorporated into the search results.
 
+    \note Some platforms (e.g. Windows) may also provide cached results for
+    the devices that are not currently advertising. Other platforms
+    (like \c {iOS}) only provide information about currently advertising
+    devices. You can store the received device UUID (or Bluetooth address)
+    upon first discovery, and then use it later to establish a connection
+    directly (see
+    \l {QBluetoothDeviceInfo::QBluetoothDeviceInfo(const QBluetoothUuid &uuid, const QString &name, quint32 classOfDevice)}
+    {QBluetoothDeviceInfo}). This way the applications can omit the
+    later device discovery phases. Using the Bluetooth address requires
+    that the remote device's Bluetooth address does not change.
+
     \since 5.8
 */
 void QBluetoothDeviceDiscoveryAgent::start(DiscoveryMethods methods)