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()

원격 블루투스 저에너지 장치에 연결합니다.

컨트롤러의 state()가 UnconnectedState 과 같지 않으면 이 함수는 아무 일도 하지 않습니다. 연결이 성공적으로 설정되면 connected() 신호가 방출됩니다.

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

disconnectFromDevice()도 참조하세요 .

[signal] void QLowEnergyController::connected()

이 신호는 컨트롤러가 원격 저에너지 장치(컨트롤러가 CentralRole)에 있는 경우 또는 원격 저에너지 장치가 컨트롤러에 연결된 경우(컨트롤러가 PeripheralRole)에 있는 경우 성공적으로 연결되면 방출됩니다. iOS, macOS 및 Android에서 컨트롤러가 PeripheralRole 에 있는 경우 이 신호는 신뢰할 수 없습니다. iOS 및 macOS에서 컨트롤러는 이 중앙에서 특성/설명자를 쓰거나 읽으려고 시도하는 즉시 주변 장치에 연결된 중앙을 추측할 뿐입니다. 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 저에너지 장치의 주소가 포함되어야 합니다.

연결은 localDevice 을 통해 설정됩니다. localDevice 이 유효하지 않으면 로컬 기본 장치가 자동으로 선택됩니다. localDevice 이 로컬 Bluetooth 어댑터가 아닌 로컬 장치를 지정하는 경우 error()은 connectToDevice()이 호출되면 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 에 있는 경우 이 함수는 아무 작업도 수행하지 않습니다.

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

connectToDevice()도 참조하세요 .

[signal] void QLowEnergyController::disconnected()

이 신호는 컨트롤러가 원격 저에너지 장치와 연결이 끊어지거나 그 반대로 연결이 끊어질 때 방출됩니다. 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

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

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

QLowEnergyController::RemoteAddressType QLowEnergyController::remoteAddressType() const

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

setRemoteAddressType()도 참조하세요 .

QBluetoothUuid QLowEnergyController::remoteDeviceUuid() const

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

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

QString QLowEnergyController::remoteName() const

컨트롤러가 CentralRole 에 있는 경우 원격 Bluetooth 저에너지 장치의 이름을 반환합니다. 그렇지 않으면 결과가 지정되지 않습니다.

void QLowEnergyController::requestConnectionUpdate(const QLowEnergyConnectionParameters &parameters)

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

안드로이드는 이 파라미터 세트의 조정을 간접적으로만 허용합니다. 연결 매개변수는 세 가지 카테고리(높음, 낮음 및 균형 우선순위)로 구분됩니다. 각 카테고리는 QLowEnergyConnectionParameters::minimumInterval(), QLowEnergyConnectionParameters::maximumInterval() 및 QLowEnergyConnectionParameters::latency()에 대해 미리 구성된 값 집합을 의미합니다. 연결 요청은 비동기 작업이지만 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 저에너지 장치에 연결하는 데 필요합니다.

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

remoteAddressType()도 참조하세요 .

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

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

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

블루즈 DBus 백엔드에서 블루즈는 스캔 응답에 어떤 데이터를 사용할지 여부를 결정합니다. 따라서 모든 광고 데이터는 기본 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()도 참조하세요 .