QLowEnergyController Class

멤버 함수 설명서

[virtual noexcept] QLowEnergyController::~QLowEnergyController()

QLowEnergyController 인스턴스를 삭제합니다.

QLowEnergyService *QLowEnergyController::addService(const QLowEnergyServiceData &service, QObject *parent = nullptr)

service 에서 가져온 parent 를 사용하여 QLowEnergyService 객체를 생성하고 반환합니다. 컨트롤러는 PeripheralRole 및 UnconnectedState 에 속해 있어야 합니다. service 객체는 유효해야 합니다.

stopAdvertising(), disconnectFromDevice() 및 QLowEnergyServiceData::addIncludedService도 참조하십시오 .

void QLowEnergyController::connectToDevice()

원격 Bluetooth Low Energy 기기와 연결합니다.

컨트롤러의 ` state()` 값이 ` UnconnectedState`와 다를 경우, 이 함수는 아무 작업도 수행하지 않습니다. 연결이 성공적으로 수립되면 ` connected()` 신호가 한 번 발생합니다.

Linux/BlueZ 시스템에서는 이 클래스의 두 인스턴스를 사용하여 동일한 원격 장치에 연결할 수 없습니다. 이 함수를 두 번째로 호출하면 오류가 발생하여 실패할 수 있습니다. 이 제한 사항은 향후 릴리스에서 제거될 수 있습니다.

disconnectFromDevice()도 참조하십시오 .

[signal] void QLowEnergyController::connected()

이 신호는 컨트롤러가 원격 저에너지 기기와 성공적으로 연결되었을 때(컨트롤러가 ‘ CentralRole ’ 상태인 경우) 또는 컨트롤러에 연결된 원격 저에너지 기기가 있을 때(컨트롤러가 ‘ PeripheralRole ’ 상태인 경우) 전송됩니다. iOS, macOS 및 Android에서 컨트롤러가 PeripheralRole 상태인 경우 이 신호는 신뢰할 수 없습니다. iOS와 macOS에서 컨트롤러는 특정 센트럴이 특성(characteristic)이나 설명자(descriptor)를 읽거나 쓰려고 시도하는 즉시, 해당 센트럴이 우리 주변 기기에 연결되었다고 추정할 뿐입니다. Android에서는 컨트롤러가 연결된 모든 GATT 기기를 모니터링합니다. Linux BlueZ DBus 주변기기 백엔드에서는 리모컨이 특성이나 디스크립터를 처음 읽거나 쓸 때 연결된 것으로 간주됩니다.

[signal] void QLowEnergyController::connectionUpdated(const QLowEnergyConnectionParameters &newParameters)

이 신호는 연결 매개변수가 변경될 때 발생합니다. 이는 requestConnectionUpdate()를 호출한 결과이거나, 예를 들어 연결 상대방이 새로운 매개변수를 요청한 경우 등 다른 이유로 인해 발생할 수 있습니다. 새로운 값은 newParameters 에서 확인할 수 있습니다.

requestConnectionUpdate()도 참조하십시오 .

[static] QLowEnergyController *QLowEnergyController::createCentral(const QBluetoothDeviceInfo &remoteDevice, QObject *parent = nullptr)

CentralRole 에 속하며 부모 객체가 parent 인 이 클래스의 새 객체를 반환합니다. remoteDevice 는 나중에 연결이 설정될 장치를 가리킵니다.

컨트롤러는 연결 관리를 위해 로컬 기본 블루투스 어댑터를 사용합니다.

QLowEnergyController::CentralRole도 참조하십시오 .

[static] QLowEnergyController *QLowEnergyController::createCentral(const QBluetoothDeviceInfo &remoteDevice, const QBluetoothAddress &localDevice, QObject *parent = nullptr)

parent 를 가진 이 클래스의 새 인스턴스를 반환합니다.

remoteDevice 에는 이 객체가 나중에 연결을 시도해야 할 원격 Bluetooth Low Energy 장치의 주소가 포함되어 있어야 합니다.

연결은 ` localDevice`을 통해 설정됩니다. ` localDevice `이 유효하지 않은 경우, 로컬 기본 장치가 자동으로 선택됩니다. ` localDevice `이 로컬 블루투스 어댑터가 아닌 로컬 장치를 지정하는 경우, ` connectToDevice()`가 호출되면 ` error()`가 ` InvalidBluetoothAdapterError `로 설정됩니다.

연결에 사용할 로컬 장치를 지정하는 것은 BlueZ를 사용할 때만 가능하다는 점에 유의하십시오. 다른 모든 플랫폼은 이 기능을 지원하지 않습니다.

[static] QLowEnergyController *QLowEnergyController::createPeripheral(QObject *parent = nullptr)

PeripheralRole 에 속하며 부모 객체가 parent 인 이 클래스의 새 객체를 반환합니다. 일반적으로 다음 단계로는 몇 가지 서비스를 추가한 후, 반환된 객체에서 startAdvertising()을 호출합니다.

컨트롤러는 연결 관리를 위해 로컬 기본 블루투스 어댑터를 사용합니다.

QLowEnergyController::PeripheralRole도 참조하십시오 .

[static, since 6.2] QLowEnergyController *QLowEnergyController::createPeripheral(const QBluetoothAddress &localDevice, QObject *parent = nullptr)

PeripheralRole 에 속하고, 부모 객체가 parent 이며, localDevice 를 사용하는 이 클래스의 새 객체를 반환합니다. 일반적으로 다음 단계로는 몇 가지 서비스를 추가한 후, 반환된 객체에 대해 startAdvertising()를 호출합니다.

주변 장치는 localDevice 에서 생성됩니다. localDevice 가 유효하지 않은 경우, 로컬 기본 장치가 자동으로 선택됩니다. localDevice 가 로컬 Bluetooth 어댑터가 아닌 로컬 장치를 지정하는 경우, error()은 InvalidBluetoothAdapterError 로 설정됩니다.

localDevice 의 선택은 Linux에서만 지원됩니다. 다른 플랫폼에서는 이 매개변수가 무시됩니다.

이 함수는 Qt 6.2에서 도입되었습니다.

QLowEnergyController::PeripheralRole도 참조하십시오 .

QLowEnergyService *QLowEnergyController::createServiceObject(const QBluetoothUuid &serviceUuid, QObject *parent = nullptr)

serviceUuid 로 표시되는 서비스의 인스턴스를 생성합니다. serviceUuid 매개변수는 services()를 통해 미리 획득해야 합니다.

호출자는 반환된 포인터에 대한 소유권을 가지며, parent 매개변수를 기본 소유자로 전달할 수 있습니다.

원격 장치에서 serviceUuid 을 가진 서비스를 찾을 수 없거나 컨트롤러가 연결 해제된 경우, 이 함수는 null 포인터를 반환합니다.

이 함수는 보조 서비스에 대한 인스턴스도 반환할 수 있습니다. 서비스 간의 포함 관계는 QLowEnergyService::includedServices()를 통해 표현할 수 있습니다.

동일한 서비스 UUID를 사용하여 이 함수를 여러 번 호출하면, 반환된 QLowEnergyService 인스턴스들은 내부 데이터를 공유합니다. 따라서 인스턴스 중 하나가 서비스 세부 정보 탐색을 시작하면, 다른 인스턴스들도 자동으로 탐색 상태로 전환됩니다.

services()도 참조하십시오 .

void QLowEnergyController::disconnectFromDevice()

원격 장치와의 연결을 끊습니다.

현재 연결을 통해 생성된 모든 QLowEnergyService, QLowEnergyCharacteristic 또는 QLowEnergyDescriptor 인스턴스는 자동으로 무효화됩니다. 이러한 객체 중 하나라도 무효화되면, 이 컨트롤러 객체가 다시 연결되더라도 계속 무효 상태로 유지됩니다.

컨트롤러가 UnconnectedState 상태인 경우 이 함수는 아무 작업도 수행하지 않습니다.

컨트롤러가 주변기기(peripheral) 역할에 있는 경우, 광고를 중지하고 이전에 addService()를 통해 추가된 모든 서비스를 제거합니다. QLowEnergyController 인스턴스를 재사용하려면 애플리케이션에서 서비스를 다시 추가하고 startAdvertising()를 호출하여 광고 모드를 다시 시작해야 합니다.

connectToDevice()도 참조하십시오 .

[signal] void QLowEnergyController::disconnected()

이 신호는 컨트롤러가 원격 저전력(Low Energy) 장치와의 연결이 끊어지거나, 그 반대의 경우 발생합니다. iOS 및 macOS에서는 컨트롤러가 ‘ PeripheralRole ’ 상태에 있을 때 이 신호의 신뢰성이 떨어집니다. Android에서는 마지막으로 연결된 장치가 연결이 끊어지면 이 신호가 발생합니다. BlueZ DBus 백엔드에서는 속성에 마지막으로 접근한 클라이언트가 연결을 끊었을 때 컨트롤러가 연결이 끊어진 것으로 간주됩니다.

void QLowEnergyController::discoverServices()

서비스 검색 프로세스를 시작합니다.

탐색 진행 상황은 ` serviceDiscovered()` 신호를 통해 표시됩니다. 프로세스가 완료되면 ` discoveryFinished()` 신호가 발신됩니다.

컨트롤러 인스턴스가 연결되어 있지 않거나 컨트롤러가 이미 서비스 검색을 수행한 경우, 이 함수는 아무 작업도 수행하지 않습니다.

[signal] void QLowEnergyController::discoveryFinished()

이 신호는 실행 중인 서비스 검색이 완료될 때 발생합니다. 검색 프로세스가 오류로 종료된 경우에는 이 신호가 발생하지 않습니다.

이 신호는 컨트롤러가 CentralRole 상태에 있을 때만 발신될 수 있습니다.

discoverServices() 및 error()도 참조하십시오 .

QLowEnergyController::Error QLowEnergyController::error() const

마지막으로 발생한 오류 또는 ` NoError`를 반환합니다.

[signal, since 6.2] void QLowEnergyController::errorOccurred(QLowEnergyController::Error newError)

오류가 발생하면 이 신호가 발생합니다. ` newError ` 매개변수는 발생한 오류를 설명합니다.

이 함수는 Qt 6.2에서 도입되었습니다.

error() 및 errorString()도 참조하십시오 .

QString QLowEnergyController::errorString() const

가장 최근에 발생한 오류를 텍스트로 변환하여 반환합니다. 이 문자열은 번역된 상태입니다.

QBluetoothAddress QLowEnergyController::localAddress() const

통신에 사용 중인 로컬 블루투스 어댑터의 주소를 반환합니다.

이 클래스 인스턴스에 기본 어댑터 사용이 요청되었으나, 이 클래스 인스턴스를 생성할 당시 기본 어댑터가 없었던 경우, 반환되는 QBluetoothAddress 는 null이 됩니다.

QBluetoothAddress::isNull()도 참조하십시오 .

[since 6.2] int QLowEnergyController::mtu() const

MTU 크기를 반환합니다.

연결 설정 과정에서 ATT MTU 크기가 협상됩니다. 이 메서드는 해당 협상 결과를 반환합니다. 특정 상황에서 패킷 크기를 최적화하는 데 사용할 수 있습니다. 단일 패킷으로 전송할 수 있는 최대 데이터 양은 mtu-3바이트입니다. ATT 프로토콜 헤더에 3바이트가 필요합니다.

연결 설정 및 MTU 협상 이전에는 23 의 기본값이 반환됩니다.

모든 플랫폼이 MTU 값을 노출하는 것은 아닙니다. 해당 플랫폼(예: Linux)에서는 이 함수가 항상 ` -1`를 반환합니다.

컨트롤러가 PeripheralRole 에 있는 경우, 해당 컨트롤러에 여러 중앙 장치가 연결되어 있을 수 있습니다. 이러한 경우 이 함수는 마지막으로 협상된 연결의 MTU를 반환합니다.

이 함수는 Qt 6.2에서 도입되었습니다.

[signal] void QLowEnergyController::mtuChanged(int mtu)

이 신호는 MTU 변경이 성공적으로 완료된 결과로 전송됩니다. ‘ mtu ’는 새로운 값을 나타냅니다.

mtu()항목도 참조하십시오 .

[since 6.5] void QLowEnergyController::readRssi()

readRssi()는 연결된 원격 장치의 RSSI(수신 신호 강도 지표)를 읽습니다. 읽기가 성공하면, RSSI 값은 rssiRead() 신호를 통해 보고됩니다.

이 함수는 Qt 6.5에서 도입되었습니다.

rssiRead(), connectToDevice(), state(), createCentral() 및 errorOccurred()도 참조하십시오 .

QBluetoothAddress QLowEnergyController::remoteAddress() const

원격 블루투스 저에너지(BLE) 장치의 주소를 반환합니다.

CentralRole 에 있는 컨트롤러의 경우, 이 값은 항상 컨트롤러 객체가 생성될 때 전달된 값과 동일합니다. PeripheralRole 에 있는 컨트롤러의 경우, 이 값은 현재 연결된 클라이언트 장치 주소 중 하나입니다. 컨트롤러가 현재 ConnectedState 에 속해 있지 않은 경우, 이 주소는 유효하지 않습니다.

QLowEnergyController::RemoteAddressType QLowEnergyController::remoteAddressType() const

remoteAddress()의 반환 유형을 반환합니다. 기본적으로 이 값은 PublicAddress 로 초기화됩니다.

setRemoteAddressType()도 참조하십시오 .

QBluetoothUuid QLowEnergyController::remoteDeviceUuid() const

원격 블루투스 저에너지(Bluetooth Low Energy) 장치의 고유 식별자를 반환합니다.

macOS/iOS/tvOS에서 CoreBluetooth는 LE 기기의 하드웨어 주소를 노출하거나 수락하지 않으며, 대신 개발자는 CoreBluetooth에서 생성한 고유한 128비트 UUID를 사용해야 합니다. 이러한 UUID는 동일한 센트럴 <-> 페리페럴 쌍에 대해 변하지 않으며, 원격 기기에 연결할 때 이를 사용합니다. CentralRole 의 컨트롤러에 대해서는, 이 값은 항상 컨트롤러 객체가 생성될 때 전달된 값과 동일합니다. PeripheralRole 의 컨트롤러에 대해서는 이 값이 유효하지 않습니다.

QString QLowEnergyController::remoteName() const

컨트롤러가 ‘ CentralRole ’ 상태에 있는 경우, 원격 블루투스 저에너지(Bluetooth Low Energy) 장치의 이름을 반환합니다. 그렇지 않은 경우 결과는 정의되지 않습니다.

void QLowEnergyController::requestConnectionUpdate(const QLowEnergyConnectionParameters &parameters)

컨트롤러에 parameters 에 따라 연결을 업데이트하도록 요청합니다. 요청이 성공하면, 실제 새로운 매개변수와 함께 connectionUpdated() 신호가 발신됩니다. 연결 매개변수에 대한 자세한 내용은 QLowEnergyConnectionParameters 클래스를 참조하십시오.

Android에서는 이 매개변수 세트의 조정을 간접적으로만 허용합니다. 연결 매개변수는 세 가지 범주(높은 우선순위, 낮은 우선순위, 균형 잡힌 우선순위)로 구분됩니다. 각 범주는 QLowEnergyConnectionParameters::minimumInterval(), QLowEnergyConnectionParameters::maximumInterval() 및 QLowEnergyConnectionParameters::latency()에 대해 미리 구성된 값 세트를 의미합니다. 연결 요청은 비동기 작업이지만, Android는 요청 결과를 알려주는 콜백을 제공하지 않습니다. 이는 Android에서 공식적으로 인정된 버그입니다. 이 버그로 인해 Android는 connectionUpdated() 신호를 발생시키지 않습니다.

connectionUpdated()도 참조하십시오 .

QLowEnergyController::Role QLowEnergyController::role() const

이 컨트롤러 객체가 속한 역할을 반환합니다.

이 역할은 createCentral() 또는 createPeripheral()를 사용하여 QLowEnergyController 인스턴스를 생성할 때 결정됩니다.

[signal, since 6.5] void QLowEnergyController::rssiRead(qint16 rssi)

이 신호는 연결된 원격 장치의 RSSI(수신 신호 강도 표시기)를 성공적으로 읽은 후에 발생합니다. ` rssi ` 매개변수는 새로운 값을 나타냅니다.

이 함수는 Qt 6.5에서 도입되었습니다.

readRssi()도 참조하십시오 .

[signal] void QLowEnergyController::serviceDiscovered(const QBluetoothUuid &newService)

이 신호는 새로운 서비스가 발견될 때마다 전송됩니다. ` newService ` 매개변수에는 발견된 서비스의 UUID가 포함됩니다.

이 신호는 컨트롤러가 CentralRole 상태일 때만 발생될 수 있습니다.

discoverServices() 및 discoveryFinished()도 참조하십시오 .

QList<QBluetoothUuid> QLowEnergyController::services() const

컨트롤러가 ‘ CentralRole ’ 상태에 있는 경우, 원격 장치가 제공하는 서비스 목록을 반환합니다. 그렇지 않은 경우, 결과는 정의되지 않습니다.

이 목록에는 모든 주 서비스와 보조 서비스가 포함됩니다.

createServiceObject()도 참조하십시오 .

void QLowEnergyController::setRemoteAddressType(QLowEnergyController::RemoteAddressType type)

원격 주소 type 을 설정합니다. 원격 Bluetooth Low Energy 장치에 연결하려면 이 유형을 지정해야 합니다.

이 속성은 구형 리눅스 커널(v3.3 이하)을 사용하는 리눅스/BlueZ 시스템에서, 또는 실행 파일에 CAP_NET_ADMIN이 설정되지 않은 경우에만 설정해야 합니다. 이 속성의 기본값은 RandomAddress 입니다.

remoteAddressType()도 참조하십시오 .

void QLowEnergyController::startAdvertising(const QLowEnergyAdvertisingParameters &parameters, const QLowEnergyAdvertisingData &advertisingData, const QLowEnergyAdvertisingData &scanResponseData = QLowEnergyAdvertisingData())

parameters 에 설정된 매개변수를 사용하여 advertisingData 및 scanResponseData 에 명시된 데이터를 광고하기 시작합니다. 컨트롤러는 PeripheralRole 에 위치해야 합니다. parameters 가 광고가 연결 가능해야 함을 나타내는 경우, 이 함수는 들어오는 클라이언트 연결에 대한 수신 대기도 시작합니다.

scanResponseData 를 제공할 필요는 없습니다. 이는 parameters 의 특정 구성에서는 적용되지 않기 때문입니다. advertisingData 와 scanResponseData 는 31바이트의 사용자 데이터로 제한됩니다. 예를 들어, advertisingData 에 여러 개의 128비트 UUID가 추가된 경우, 광고된 패킷에 모든 UUID가 포함되지 않을 수 있습니다. 기존의 제한으로 인해 UUID가 잘릴 수 있습니다. 이러한 경우 추가 정보를 얻기 위해 scanResponseData 를 사용할 수 있습니다.

BlueZ DBus 백엔드에서는 BlueZ가 스캔 응답에 데이터를 사용할지 여부와 어떤 데이터를 사용할지 결정합니다. 따라서 모든 광고 데이터는 main advertisingData 매개변수에 설정하는 것이 권장됩니다. 광고 데이터와 스캔 응답 데이터가 모두 설정된 경우, 스캔 응답 데이터가 우선적으로 적용됩니다.

이 객체가 현재 UnconnectedState 에 포함되어 있지 않은 경우, 아무런 동작도 발생하지 않습니다.

stopAdvertising()도 참조하십시오 .

QLowEnergyController::ControllerState QLowEnergyController::state() const

컨트롤러의 현재 상태를 반환합니다.

stateChanged()도 참조하십시오 .

[signal] void QLowEnergyController::stateChanged(QLowEnergyController::ControllerState state)

이 신호는 컨트롤러의 상태가 변경될 때 발생합니다. 새로운 state 는 state()를 통해서도 가져올 수 있습니다.

state()도 참조하십시오 .

void QLowEnergyController::stopAdvertising()

이 객체가 현재 광고 상태인 경우, 광고를 중지합니다.

이 함수가 작동하려면 컨트롤러가 PeripheralRole 에 있어야 합니다. 이 함수는 addService()를 통해 이전에 추가된 서비스를 무효화하지 않습니다.

startAdvertising()도 참조하십시오 .