QBluetoothDeviceDiscoveryAgent Class

メンバ関数のドキュメント

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

親としてparent を持つ新しいBluetoothデバイス検出エージェントを構築します。

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

parent を使用して、新しい Bluetooth デバイス検出エージェントを生成します。

デバイスの検索にはdeviceAdapter を使用します。deviceAdapter がデフォルトで生成された場合、結果として得られるQBluetoothDeviceDiscoveryAgentオブジェクトは、ローカルのデフォルトBluetoothアダプタを使用します。

deviceAdapter としてローカルアダプタ以外のものが指定された場合、error()はInvalidBluetoothAdapterError に設定されます。したがって、このコンストラクタを使用後は直ちにエラーフラグを確認することを推奨します。

error()も参照してください 。

[virtual noexcept] QBluetoothDeviceDiscoveryAgent::~QBluetoothDeviceDiscoveryAgent()

~QBluetoothDeviceDiscoveryAgent() のデストラクタ

[signal] void QBluetoothDeviceDiscoveryAgent::canceled()

このシグナルは、stop() の呼び出しによってデバイスの検出が中止されたときに発生します。

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

このシグナルは、info で指定されたBluetoothデバイスが検出された際に発せられます。

このシグナルは、最も重要なデバイス情報が収集され次第、直ちに発信されます。ただし、finished() シグナルが発信されるまでは、すでに検出済みのデバイスであっても情報の収集は継続されます。これは特に、信号強度情報（RSSI）やメーカーデータの更新において当てはまります。 ユースケースでメーカーデータやRSSIの継続的な更新が必要な場合は、検出が完了したらdiscoveredDevices()を介してデバイス情報を取得するか、deviceUpdated()シグナルをリッスンすることをお勧めします。

lowEnergyDiscoveryTimeout() が 0 より大きい場合、このシグナルはinfo の属性のうち少なくとも 1 つが変更されたときにのみ発信されます。これは、より正確な情報が利用可能になった時点で更新を受け取りたいという要望を反映したものです。 この動作の例外は、lowEnergyDiscoveryTimeout が0 に設定されている場合です。0 のタイムアウトは、低消費電力（Low Energy）デバイスの出現および消失を長期的に監視したいという意図を表します。この条件下では、前回のシグナル発火以降にinfo が変更されていなくても、deviceDiscovered()シグナルが発火します。

QBluetoothDeviceInfo::rssi() およびlowEnergyDiscoveryTimeout()も参照してください 。

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

このシグナルは、エージェントが `info` で記述されたBluetoothデバイスに関する追加情報を受信した際に発信されます。updatedFields フラグは、どの情報が更新されたかを示します。

ディスカバリ中、signal strength やmanufacturerData などの一部の情報は動的に変化する場合があります。このシグナルは、アプリケーションがこのデータを表示している場合、ディスカバリが完了するまで待つのではなく、データを更新できることを通知するものです。

QBluetoothDeviceInfo::rssi() およびlowEnergyDiscoveryTimeout()も参照してください 。

QList<QBluetoothDeviceInfo> QBluetoothDeviceDiscoveryAgent::discoveredDevices() const

検出されたすべてのBluetoothデバイスの一覧を返します。

QBluetoothDeviceDiscoveryAgent::Error QBluetoothDeviceDiscoveryAgent::error() const

最後のエラーを返します。

ディスカバリを再起動すると、それ以前に発生したエラーはすべてクリアされます。

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

このシグナルは、Bluetoothデバイスの検出中にerror が発生した際に発せられます。error パラメータは、発生したエラーの詳細を示します。

この関数はQt 6.2で導入されました。

error() およびerrorString()も参照してください 。

QString QBluetoothDeviceDiscoveryAgent::errorString() const

直近のエラーについて、人間が理解しやすい説明を返します。

error() およびerrorOccurred()も参照してください 。

[signal] void QBluetoothDeviceDiscoveryAgent::finished()

このシグナルは、Bluetoothデバイスの検出が完了したときに発せられます。デバイスの検出がエラーで終了した場合は、このシグナルは発せられません。

bool QBluetoothDeviceDiscoveryAgent::isActive() const

エージェントが現在Bluetoothデバイスを検出している場合はtrueを返し、そうでない場合はfalseを返します。

int QBluetoothDeviceDiscoveryAgent::lowEnergyDiscoveryTimeout() const

Bluetooth Low Energy デバイスの検索に適用されるタイムアウトをミリ秒単位で返します。-1 という値は、プラットフォームがこのプロパティをサポートしておらず、デバイス検索のタイムアウトを調整できないことを意味します。0 という戻り値は、検索が終了しないことを意味し、stop() を使用して手動で停止する必要があります。

setLowEnergyDiscoveryTimeout()も参照してください 。

void QBluetoothDeviceDiscoveryAgent::setLowEnergyDiscoveryTimeout(int timeout)

Bluetooth Low Energyデバイスの検索にかかる最大時間を、timeout （ミリ秒単位）に設定します。timeout が0 の場合、stop()が呼び出されるまで検出処理が実行されます。

これは、Bluetooth Low Energy デバイスの検出プロセスが、ほとんどの場合、終了時期が定まっていないという事実を反映しています。プラットフォームは、検索が手動で停止されるまで、引き続きデバイスを探し続けます。このタイムアウトにより、timeout ミリ秒経過後に検索が中止されることが保証されます。もちろん、stop() を呼び出すことで、手動で検出を中止することも可能です。

新しいタイムアウト値は、デバイス検索が再開始されるまで有効になりません。また、このタイムアウトは従来のBluetoothデバイス検索には影響しません。プラットフォームによっては、従来の検索により、timeout を超える時間がディスカバリープロセス全体に追加される場合があります。

信頼性の高いBluetooth Low Energyのディスカバリを行うには、少なくとも40000ミリ秒を設定してください。

lowEnergyDiscoveryTimeout()も参照してください 。

[slot] void QBluetoothDeviceDiscoveryAgent::start()

Bluetoothデバイスの検出がまだ開始されていない場合、検出を開始します。

各デバイスが検出されるたびに、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)

Bluetoothデバイスの検出がまだ開始されておらず、指定されたmethods がサポートされている場合、Bluetoothデバイスの検出を開始します。discoverymethods は、デバイス検索の範囲を制限します。たとえば、対象のサービスまたはデバイスがBluetooth Low Energyデバイスである場合、この関数を使用して検索を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()

Bluetoothデバイスの検出を停止します。デバイスの検出がキャンセルされると、cancel()シグナルが発信されます。cancelシグナルを受信する前に、start()が呼び出される場合があります。start()が呼び出されると、以前の検出からのcancelシグナルは破棄されます。

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

この関数は、現在のプラットフォームでサポートされている検出メソッドを返します。これを使用して、デバイス検出の範囲を絞り込むことができます。