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 의 타임아웃은 시간이 지남에 따라 저전력(Low Energy) 장치의 출현 및 소멸을 모니터링하고자 하는 의도를 나타냅니다. 이 조건 하에서는 마지막 신호 발신 이후 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

블루투스 저에너지(Bluetooth Low Energy) 장치 검색에 적용되는 타임아웃 값을 밀리초 단위로 반환합니다. 값이 ‘ -1 ’인 경우, 플랫폼이 이 속성을 지원하지 않으므로 장치 검색의 타임아웃을 조정할 수 없음을 의미합니다. 반환 값이 ‘ 0 ’인 경우, 검색이 끝없이 진행됨을 의미하며, 이 경우 ‘ stop()’를 통해 수동으로 검색을 중지해야 합니다.

setLowEnergyDiscoveryTimeout()도 참조하십시오 .

void QBluetoothDeviceDiscoveryAgent::setLowEnergyDiscoveryTimeout(int timeout)

블루투스 저에너지(Bluetooth Low Energy) 장치 검색의 최대 검색 시간을 밀리초 단위로 timeout 로 설정합니다. timeout 가 0 인 경우, stop()가 호출될 때까지 검색이 진행됩니다.

이는 블루투스 저에너지(Bluetooth Low Energy) 장치 탐색 과정이 대부분 종료 시점이 정해져 있지 않다는 점을 반영한 것입니다. 플랫폼은 검색이 수동으로 중지될 때까지 계속해서 더 많은 장치를 찾습니다. 타임아웃을 설정하면 timeout 밀리초가 지난 후 검색이 중단됩니다. 물론, stop()를 호출하여 수동으로 탐색을 중단할 수도 있습니다.

새로운 타임아웃 값은 장치 검색이 다시 시작될 때까지 적용되지 않습니다. 또한 이 타임아웃은 기존 블루투스(Classic Bluetooth) 장치 검색에는 영향을 미치지 않습니다. 플랫폼에 따라 기존 검색으로 인해 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()

이 함수는 현재 플랫폼에서 지원하는 검색 방법을 반환합니다. 이 함수를 사용하여 장치 검색 범위를 제한할 수 있습니다.