QLowEnergyService Class

    //PreCondition: service details already discovered
    QLowEnergyCharacteristic batteryLevel = service->characteristic(
                QBluetoothUuid::CharacteristicType::BatteryLevel);
    if (!batteryLevel.isValid())
        return;

    QLowEnergyDescriptor notification = batteryLevel.descriptor(
                QBluetoothUuid::DescriptorType::ClientCharacteristicConfiguration);
    if (!notification.isValid())
        return;

    // establish hook into notifications
    connect(service, SIGNAL(characteristicChanged(QLowEnergyCharacteristic,QByteArray)),
            this, SLOT(characteristicChanged(QLowEnergyCharacteristic,QByteArray)));

    // enable notification
    service->writeDescriptor(notification, QByteArray::fromHex("0100"));

    // disable notification
    //service->writeDescriptor(notification, QByteArray::fromHex("0000"));

    // wait until descriptorWritten() signal is emitted
    // to confirm successful write

    QLowEnergyService *first, *second;
    QLowEnergyController control(remoteDevice);
    control.connectToDevice();

    // waiting for connection

    first = control.createServiceObject(QBluetoothUuid::ServiceClassUuid::BatteryService);
    second = control.createServiceObject(QBluetoothUuid::ServiceClassUuid::BatteryService);
    Q_ASSERT(first->state() == QLowEnergyService::RemoteService);
    Q_ASSERT(first->state() == second->state());

    first->discoverDetails();

    Q_ASSERT(first->state() == QLowEnergyService::RemoteServiceDiscovering);
    Q_ASSERT(first->state() == second->state());

멤버 함수 문서

[virtual noexcept] QLowEnergyService::~QLowEnergyService()

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

QLowEnergyCharacteristic QLowEnergyService::characteristic(const QBluetoothUuid &uuid) const

uuid 에 해당하는 특성을 반환하며, 해당 조건에 부합하지 않을 경우 유효하지 않은 특성을 반환합니다.

이 서비스 인스턴스의 discoverDetails()가 아직 호출되지 않았거나, 일치하는 uuid 를 가진 특성이 없는 경우 반환된 특성은 유효하지 않습니다.

characteristics()도 참조하십시오 .

[signal] void QLowEnergyService::characteristicChanged(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue)

연관된 컨트롤러 객체가 ‘ central ’ 역할을 맡고 있는 경우, 주변기기/장치 측의 이벤트로 인해 characteristic 의 값이 변경되면 이 신호가 발신됩니다. 이 경우, 신호 발신은 주변기기 측에서 변경 이벤트가 발생하기 전에 해당 특성의 ‘ ClientCharacteristicConfiguration ’ 디스크립터를 통해 변경 알림이 활성화되었음을 의미합니다. 이에 대한 자세한 내용은 above 에서 확인할 수 있습니다.

컨트롤러가 ‘ peripheral ’ 역할을 수행하는 경우, 즉 서비스 객체가 QLowEnergyController::addService 를 통해 생성된 경우, GATT 클라이언트가 쓰기 요청이나 명령을 사용하여 특성 값을 기록하면 신호가 발신됩니다.

newValue 매개변수에는 characteristic 의 업데이트된 값이 포함됩니다.

[signal] void QLowEnergyService::characteristicRead(const QLowEnergyCharacteristic &characteristic, const QByteArray &value)

이 신호는 ` characteristic `에 대한 읽기 요청이 ` value`를 성공적으로 반환했을 때 발생합니다. 이 신호는 `characteristicRead()`를 호출하여 트리거될 수 있습니다. 읽기 작업이 성공하지 못한 경우, ` CharacteristicReadError ` 플래그를 사용하여 ` errorOccurred()` 신호가 발생합니다.

readCharacteristic()도 참조하십시오 .

[signal] void QLowEnergyService::characteristicWritten(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue)

이 신호는 ` characteristic `의 값이 ` newValue`로 성공적으로 변경되었을 때 발생합니다. 이 변경은 ` writeCharacteristic()`를 호출함으로써 트리거되어야 합니다. 쓰기 작업이 성공하지 못한 경우, ` CharacteristicWriteError ` 플래그를 사용하여 ` errorOccurred()` 신호가 발생합니다.

이 ‘written’ 신호의 수신은 대상 장치가 쓰기 대상 값을 수신했으며 쓰기 요청의 상태를 보고했다는 신호로 간주할 수 있습니다.

writeCharacteristic()도 참조하십시오 .

QList<QLowEnergyCharacteristic> QLowEnergyService::characteristics() const

이 ` QLowEnergyService ` 인스턴스와 관련된 모든 특성을 반환합니다.

이 서비스 인스턴스의 discoverDetails()가 아직 호출되지 않았거나 알려진 특성이 없는 경우, 반환되는 목록은 비어 있습니다.

characteristic(), state(), discoverDetails()도 참조하십시오 .

bool QLowEnergyService::contains(const QLowEnergyCharacteristic &characteristic) const

characteristic 가 이 서비스에 속하는 경우 true 를 반환하고, 그렇지 않은 경우 false 를 반환합니다.

특성 characteristic 가 characteristics()에 포함되어 있는 경우, 해당 특성은 이 서비스에 속합니다.

bool QLowEnergyService::contains(const QLowEnergyDescriptor &descriptor) const

descriptor 가 이 서비스에 속하는 경우 ` true `를 반환하고, 그렇지 않은 경우 ` false`를 반환합니다.

[signal] void QLowEnergyService::descriptorRead(const QLowEnergyDescriptor &descriptor, const QByteArray &value)

이 신호는 ` descriptor `에 대한 읽기 요청이 ` value`를 성공적으로 반환했을 때 발생합니다. 이 신호는 `descriptorRead()`를 호출하여 트리거될 수 있습니다. 읽기 작업이 성공하지 못한 경우, ` DescriptorReadError ` 플래그를 사용하여 ` errorOccurred()` 신호가 발생합니다.

readDescriptor()도 참조하십시오 .

[signal] void QLowEnergyService::descriptorWritten(const QLowEnergyDescriptor &descriptor, const QByteArray &newValue)

이 신호는 ` descriptor `의 값이 ` newValue`로 성공적으로 변경되었을 때 발생합니다. 관련 컨트롤러 객체가 ` central ` 역할을 수행하는 경우, 이 변경은 ` writeDescriptor()` 호출에 의해 발생해야 합니다. 그렇지 않은 경우, 이 신호는 GATT 클라이언트가 해당 디스크립터에 보낸 쓰기 요청이나 명령의 결과입니다.

writeDescriptor()도 참조하십시오 .

void QLowEnergyService::discoverDetails(QLowEnergyService::DiscoveryMode mode = FullDiscovery)

서비스에 포함된 서비스, 특성 및 관련 설명자의 탐색을 시작합니다.

탐색 과정은 ` stateChanged()` 신호를 통해 표시됩니다. 생성 후, 서비스는 ` DiscoveryRequired ` 상태가 됩니다. `discoverDetails()`를 호출하면 ` DiscoveringService` 상태로 전환됩니다. 세부 정보 탐색이 완료되면 ` ServiceDiscovered ` 상태로 전환됩니다. 각 상태 전환 시마다 ` stateChanged()` 신호가 발생합니다. 인자 ` mode`에 따라 ` FullDiscovery ` 또는 ` SkipValueDiscovery `가 수행됩니다. 어떤 경우든 모든 서비스와 특성이 탐색됩니다. FullDiscovery 는 모든 특성 값과 디스크립터를 읽어 냅니다. SkipValueDiscovery 는 특성 값과 디스크립터를 읽지 않습니다. SkipValueDiscovery 에는 두 가지 장점이 있습니다. 첫째, 속도가 더 빠릅니다. 둘째, 특성을 읽기 가능하다고 잘못 알리면서도 실제로는 읽기를 허용하지 않는 일부 장치의 버그를 우회할 수 있습니다. 이는 예측할 수 없는 동작을 유발할 수 있습니다. SkipValueDiscovery 후에는 readCharacteristic() / readDescriptor()를 호출하고, 이 호출이 성공적으로 완료될 때까지 기다린 후에야 특성이나 디스크립터의 값에 접근할 수 있습니다.

mode 인수는 Qt 6.2에서 도입되었습니다.

state()도 참조하십시오 .

QLowEnergyService::ServiceError QLowEnergyService::error() const

마지막으로 발생한 오류를 반환하거나, ` NoError`를 반환합니다.

[signal, since 6.2] void QLowEnergyService::errorOccurred(QLowEnergyService::ServiceError newError)

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

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

QList<QBluetoothUuid> QLowEnergyService::includedServices() const

현재 서비스에 포함된 모든 서비스의 UUID를 반환합니다.

이 서비스 인스턴스의 ` discoverDetails()`가 아직 호출되지 않았거나 알려진 특성이 없는 경우, 반환된 목록은 비어 있습니다.

포함된 서비스 내에 또 다른 서비스가 포함될 수 있습니다. 이러한 2단계 포함 관계는 해당 1단계 QLowEnergyService 인스턴스를 통해 가져와야 합니다. 기술적으로 이는 순환 의존성을 유발할 수 있습니다.

QLowEnergyController::createServiceObject각 UUID에 대한 서비스 인스턴스를 얻으려면 ()를 사용해야 합니다.

createServiceObject()도 참조하십시오 .

void QLowEnergyService::readCharacteristic(const QLowEnergyCharacteristic &characteristic)

characteristic 의 값을 읽습니다. 작업이 성공하면 characteristicRead() 신호가 발생하고, 그렇지 않으면 CharacteristicReadError 가 설정됩니다. 일반적으로, characteristic 는 QLowEnergyCharacteristic::Read 속성이 설정되어 있을 때 읽을 수 있습니다.

동일한 원격 장치에 대한 모든 디스크립터 및 특성 요청은 직렬화됩니다. 여러 요청을 동시에 발행할 때는 큐가 사용됩니다. 이 큐는 동일한 특성에 대한 중복된 읽기 요청을 제거하지는 않습니다.

특성은 서비스가 ‘ ServiceDiscovered ’ 상태이고 해당 특성이 해당 서비스에 속해 있을 때만 읽을 수 있습니다. 이 조건 중 하나라도 충족되지 않으면 ‘ QLowEnergyService::OperationError ’가 설정됩니다.

characteristicRead() 및 writeCharacteristic()도 참조하십시오 .

void QLowEnergyService::readDescriptor(const QLowEnergyDescriptor &descriptor)

descriptor 의 값을 읽습니다. 작업이 성공하면 descriptorRead() 신호가 발생하고, 그렇지 않으면 DescriptorReadError 이 설정됩니다.

동일한 원격 장치에 대한 모든 디스크립터 및 특성 요청은 직렬화됩니다. 여러 요청을 동시에 발행할 때는 큐가 사용됩니다. 이 큐는 동일한 디스크립터에 대한 중복된 읽기 요청을 제거하지는 않습니다.

디스크립터는 서비스가 ServiceDiscovered 상태에 있고, 해당 디스크립터가 해당 서비스에 속하는 경우에만 읽을 수 있습니다. 이 조건 중 하나라도 충족되지 않으면 QLowEnergyService::OperationError 가 설정됩니다.

descriptorRead() 및 writeDescriptor()도 참조하십시오 .

QString QLowEnergyService::serviceName() const

서비스의 이름을 반환하며, 그렇지 않은 경우 빈 문자열을 반환합니다.

serviceUuid()가 잘 알려진 UUID인 경우에만 반환된 이름을 가져올 수 있습니다.

QBluetoothUuid QLowEnergyService::serviceUuid() const

서비스의 UUID를 반환하며, 그렇지 않은 경우 null UUID를 반환합니다.

QLowEnergyService::ServiceState QLowEnergyService::state() const

서비스의 현재 상태를 반환합니다.

장치의 서비스가 처음 인스턴스화된 경우, 객체의 상태는 ` DiscoveryRequired`입니다. 주변 장치의 동일한 서비스를 가리키는 모든 서비스 객체의 상태는 항상 동일합니다. 이는 내부 객체 데이터가 공유되는 특성 때문입니다. 따라서 첫 번째 인스턴스 이후에 생성된 모든 서비스 객체 인스턴스는 이미 존재하는 인스턴스와 동일한 상태를 가집니다.

QLowEnergyController 가 원격 장치와의 연결을 끊으면 서비스는 무효 상태가 됩니다. 무효화된 서비스는 연결 해제 시점의 내부 상태를 유지합니다. 이는 서비스 세부 정보가 한 번 탐색되면 무효화된 서비스에서도 해당 정보를 가져올 수 있음을 의미합니다. 이를 통해 장치 연결이 수립되고, 서비스 세부 정보가 가져온 후, 다음 장치가 주변 기기에 연결할 수 있도록 즉시 장치를 분리하는 시나리오가 가능합니다.

그러나 일반적인 상황에서는 서비스 및 그 세부 정보를 반복적으로 검색하는 것을 방지하기 위해 연결을 유지해야 합니다. 검색에는 다소 시간이 소요될 수 있으며, 클라이언트는 진행 중인 변경 알림을 구독할 수 있습니다.

stateChanged()도 참조하십시오 .

[signal] void QLowEnergyService::stateChanged(QLowEnergyService::ServiceState newState)

이 신호는 서비스의 상태가 변경될 때 발생합니다. newState 는 state()를 통해서도 조회할 수 있습니다.

state()도 참조하십시오 .

QLowEnergyService::ServiceTypes QLowEnergyService::type() const

서비스의 유형을 반환합니다.

void QLowEnergyService::writeCharacteristic(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue, QLowEnergyService::WriteMode mode = WriteWithResponse)

characteristic 의 값으로 newValue 을 기록합니다. 정확한 의미는 연관된 컨트롤러 객체가 수행하는 역할에 따라 달라집니다.

중앙 역할

이 호출은 원격 주변 장치에 대한 쓰기 요청 또는 명령을 발생시킵니다. 작업이 성공하면 ` characteristicWritten()` 신호가 발신되고, 그렇지 않으면 ` CharacteristicWriteError `가 설정됩니다. 이 함수를 호출한다고 해서 ` characteristicChanged()` 신호가 트리거되지는 않으며, 현재 쓰기 요청 이후 주변 장치 자체가 값을 다시 변경하는 경우에만 해당 신호가 트리거됩니다.

mode 매개변수는 원격 장치가 쓰기 확인을 전송해야 하는지 여부를 결정합니다. 쓰기 대상인 characteristic 는 해당 쓰기 모드를 지원해야 합니다. 특성(characteristic)이 지원하는 쓰기 모드는 QLowEnergyCharacteristic::Write 및 QLowEnergyCharacteristic::WriteNoResponse 속성으로 표시됩니다.

동일한 원격 장치에 대한 모든 디스크립터 및 특성 쓰기 요청은 직렬화됩니다. 여러 쓰기 요청을 동시에 발행할 때는 큐가 사용됩니다. 이 큐는 동일한 특성에 대한 중복된 쓰기 요청을 제거하지는 않습니다. 예를 들어, 동일한 디스크립터가 값 A로 설정된 직후 값 B로 설정되는 경우, 두 쓰기 요청은 주어진 순서대로 실행됩니다.

특성은 이 서비스가 ‘ ServiceDiscovered ’ 상태에 있고 해당 서비스에 속해 있을 때만 쓰기가 가능합니다. 이 조건 중 하나라도 충족되지 않으면 ‘ QLowEnergyService::OperationError ’가 설정됩니다.

주변기기 역할

이 호출의 결과로, 해당 특성 값이 로컬 데이터베이스에 업데이트됩니다.

현재 클라이언트가 연결되어 있고 해당 특성(characteristic)에 대한 알림 또는 표시 기능을 활성화한 경우, 해당 정보가 전송됩니다. 기기가 해당 특성에 대한 알림 또는 표시 기능을 활성화한 상태이고, 현재 연결되어 있지 않지만 로컬 기기와 본드(bond)가 형성되어 있는 경우, 다음 재연결 시 알림 또는 표시가 전송됩니다.

특성 값의 길이에 제약이 있고 newValue 가 해당 제약을 준수하지 않는 경우, 동작은 정의되지 않습니다.

QLowEnergyService::characteristicWritten() 및 QLowEnergyService::readCharacteristic()도 참조하십시오 .

void QLowEnergyService::writeDescriptor(const QLowEnergyDescriptor &descriptor, const QByteArray &newValue)

descriptor 의 값으로 newValue 를 기록합니다. 정확한 의미는 관련 컨트롤러 객체가 수행하는 역할에 따라 달라집니다.

중앙 역할

이 함수를 호출하면 원격 장치에 대한 쓰기 요청이 발생합니다. 작업이 성공하면 descriptorWritten() 신호가 발생하고, 그렇지 않으면 DescriptorWriteError 신호가 발생합니다.

동일한 원격 장치에 대한 모든 디스크립터 및 특성 요청은 순차적으로 처리됩니다. 여러 쓰기 요청을 동시에 발행할 때는 큐가 사용됩니다. 이 큐는 동일한 디스크립터에 대한 중복된 쓰기 요청을 제거하지는 않습니다. 예를 들어, 동일한 디스크립터가 값 A로 설정된 직후 B로 설정되는 경우, 두 쓰기 요청은 주어진 순서대로 실행됩니다.

디스크립터에 쓰기 작업은 해당 서비스가 ‘ ServiceDiscovered ’ 상태일 때만 가능하며, 해당 디스크립터가 해당 서비스에 속해야 합니다. 이 조건 중 하나라도 충족되지 않으면 ‘ QLowEnergyService::OperationError ’가 설정됩니다.

주변 장치 역할

값은 로컬 서비스 데이터베이스에 기록됩니다. newValue 의 내용이 descriptor 에 대해 유효하지 않은 경우, 동작은 정의되지 않습니다.

descriptorWritten() 및 readDescriptor()도 참조하십시오 .