QBluetoothDeviceDiscoveryAgent Class

成员函数文档

[explicit] QBluetoothDeviceDiscoveryAgent::QBluetoothDeviceDiscoveryAgent(QObject *parent = nullptr)

使用父对象parent 构建一个新的蓝牙设备发现代理。

[explicit] QBluetoothDeviceDiscoveryAgent::QBluetoothDeviceDiscoveryAgent(const QBluetoothAddress &deviceAdapter, QObject *parent = nullptr)

使用parent 构建一个新的蓝牙设备发现代理。

它使用deviceAdapter 进行设备搜索。如果deviceAdapter 采用默认构造，生成的QBluetoothDeviceDiscoveryAgent对象将使用本地默认蓝牙适配器。

如果指定的 `deviceAdapter ` 不是本地适配器，则 `error()` 将被设置为 `InvalidBluetoothAdapterError`。因此，建议在使用此构造函数后立即检查错误标志。

另请参阅 error()。

[virtual noexcept] QBluetoothDeviceDiscoveryAgent::~QBluetoothDeviceDiscoveryAgent()

~QBluetoothDeviceDiscoveryAgent() 的析构函数

[signal] void QBluetoothDeviceDiscoveryAgent::canceled()

当通过调用stop() 终止设备发现时，会发出此信号。

[signal] void QBluetoothDeviceDiscoveryAgent::deviceDiscovered(const QBluetoothDeviceInfo &info)

当发现由info 描述的蓝牙设备时，会发出此信号。

一旦收集到最重要的设备信息，该信号即会触发。但是，只要finished()信号尚未触发，即使对于已发现的设备，信息收集仍会继续。这一点在信号强度信息（RSSI）和制造商数据的更新方面尤为明显。 如果用例需要持续更新制造商数据或RSSI，建议在发现过程完成后通过discoveredDevices()获取设备信息，或者监听deviceUpdated()信号。

如果 `lowEnergyDiscoveryTimeout()` 大于 0，则该信号仅在 `info ` 的至少一个属性发生变化时才会发出。这反映了在获得更精确信息时才接收更新的需求。 此行为的例外情况是当lowEnergyDiscoveryTimeout 被设置为0 时。超时值0 表示希望随时间推移监控低功耗设备的出现与消失。在此条件下，即使自上次信号发出以来info 未发生变化，仍会发出deviceDiscovered()信号。

另请参阅 QBluetoothDeviceInfo::rssi() 和lowEnergyDiscoveryTimeout()。

[signal] void QBluetoothDeviceDiscoveryAgent::deviceUpdated(const QBluetoothDeviceInfo &info, QBluetoothDeviceInfo::Fields updatedFields)

当代理收到关于由info 描述的蓝牙设备的额外信息时，会发出此信号。updatedFields 标志用于指示哪些信息已被更新。

在发现过程中，某些信息可能会动态变化，例如signal strength 和manufacturerData 。该信号通知您：如果您的应用程序正在显示这些数据，则可以立即更新，而无需等待发现过程结束。

另请参阅 QBluetoothDeviceInfo::rssi() 和lowEnergyDiscoveryTimeout()。

QList<QBluetoothDeviceInfo> QBluetoothDeviceDiscoveryAgent::discoveredDevices() const

返回一个包含所有已发现的蓝牙设备的列表。

QBluetoothDeviceDiscoveryAgent::Error QBluetoothDeviceDiscoveryAgent::error() const

返回最后一个错误。

重新启动发现过程时，任何先前可能存在的错误都会被清除。

[signal, since 6.2] void QBluetoothDeviceDiscoveryAgent::errorOccurred(QBluetoothDeviceDiscoveryAgent::Error error)

当在蓝牙设备发现过程中发生error 时，会发出此信号。error 参数描述了发生的错误。

该函数在 Qt 6.2 中引入。

另请参阅 error() 和errorString()。

QString QBluetoothDeviceDiscoveryAgent::errorString() const

返回上次错误的通俗易懂的描述。

另请参阅 error() 和errorOccurred()。

[signal] void QBluetoothDeviceDiscoveryAgent::finished()

当蓝牙设备发现过程完成时，将触发此信号。如果设备发现过程因错误而终止，则不会触发此信号。

bool QBluetoothDeviceDiscoveryAgent::isActive() const

如果代理当前正在发现蓝牙设备，则返回 true；否则返回 false。

int QBluetoothDeviceDiscoveryAgent::lowEnergyDiscoveryTimeout() const

返回应用于蓝牙低功耗（BLE）设备搜索的超时时间（单位为毫秒）。若返回值为-1 ，则表示平台不支持此属性，且无法调整设备搜索的超时时间。若返回值为0 ，则表示搜索将无限期进行，必须通过stop()手动停止。

另请参阅 setLowEnergyDiscoveryTimeout()。

void QBluetoothDeviceDiscoveryAgent::setLowEnergyDiscoveryTimeout(int timeout)

将蓝牙低功耗设备搜索的最大搜索时间设置为timeout 毫秒。如果timeout 的值为0 ，则发现过程将持续运行，直到调用stop()为止。

这反映了蓝牙低功耗设备发现过程通常是开放式的这一事实。平台会持续搜索更多设备，直到搜索被手动停止。超时设置确保搜索在timeout 毫秒后终止。当然，仍可通过调用stop()手动中止发现过程。

新的超时值只有在重新启动设备搜索后才会生效。此外，该超时设置不会影响经典蓝牙设备的搜索。根据平台的不同，经典搜索可能会使整个发现过程的总时间超过timeout 。

为了确保蓝牙低功耗（BLE）发现过程的可靠性，请将超时值设置为至少 40000 毫秒。

另请参阅 lowEnergyDiscoveryTimeout()。

[slot] void QBluetoothDeviceDiscoveryAgent::start()

如果尚未启动，则启动蓝牙设备发现功能。

每发现一个设备，都会触发deviceDiscovered()信号。设备发现完成后，会触发finished()信号。该发现过程将使用该平台支持的最大数量的发现方法。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        bluetoothDeviceDiscoveryAgent, qOverload<>(&QBluetoothDeviceDiscoveryAgent::start));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        bluetoothDeviceDiscoveryAgent, [receiver = bluetoothDeviceDiscoveryAgent]() { receiver->start(); });

另请参阅 supportedDiscoveryMethods()。

[slot] void QBluetoothDeviceDiscoveryAgent::start(QBluetoothDeviceDiscoveryAgent::DiscoveryMethods methods)

如果蓝牙设备发现功能尚未启动，且所提供的methods 受支持，则启动蓝牙设备发现。发现methods 会限制设备搜索的范围。例如，如果目标服务或设备是蓝牙低功耗（Bluetooth Low Energy）设备，则可使用此功能将搜索范围限定为蓝牙低功耗设备，从而显著缩短发现时间。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        bluetoothDeviceDiscoveryAgent, qOverload(&QBluetoothDeviceDiscoveryAgent::start));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        bluetoothDeviceDiscoveryAgent, [receiver = bluetoothDeviceDiscoveryAgent](QBluetoothDeviceDiscoveryAgent::DiscoveryMethods methods) { receiver->start(methods); });

[slot] void QBluetoothDeviceDiscoveryAgent::stop()

停止蓝牙设备发现。一旦设备发现被取消，将发出 cancel() 信号。在接收到 cancel 信号之前，可能会调用start()。一旦调用start()，来自先前发现操作的 cancel 信号将被丢弃。

[static] QBluetoothDeviceDiscoveryAgent::DiscoveryMethods QBluetoothDeviceDiscoveryAgent::supportedDiscoveryMethods()

该函数返回当前平台支持的设备发现方法。可用于限制设备发现的范围。