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() 신호가 전송됩니다.

쓰기 신호의 수신은 대상 장치가 쓰기할 값을 수신하고 쓰기 요청 상태를 다시 보고한다는 신호로 간주할 수 있습니다.

writeCharacteristic()도 참조하세요 .

QList<QLowEnergyCharacteristic> QLowEnergyService::characteristics() const

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

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

characteristic(), state() 및 discoverDetails()도 참조하세요 .

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

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

characteristics()에 characteristic 이 포함된 경우 특성은 서비스에 속합니다.

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()가 아직 호출되지 않았거나 알려진 특성이 없는 경우 반환된 목록은 비어 있습니다.

포함된 서비스에 또 다른 서비스가 포함되어 있을 수 있습니다. 이러한 두 번째 레벨 포함은 관련 첫 번째 레벨 QLowEnergyService 인스턴스를 통해 가져와야 합니다. 기술적으로 이는 순환 종속성을 생성할 수 있습니다.

QLowEnergyController::createServiceObject()를 사용하여 각 UUID에 대한 서비스 인스턴스를 가져와야 합니다.

createServiceObject()도 참조하세요 .

void QLowEnergyService::readCharacteristic(const QLowEnergyCharacteristic &characteristic)

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

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

특성은 서비스가 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)

이 신호는 서비스 상태가 변경될 때 발신됩니다. state ()을 통해서도 newState 를 검색할 수 있습니다.

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 은 관련 쓰기 모드를 지원해야 합니다. 특성의 지원되는 쓰기 모드는 QLowEnergyCharacteristic::Write 및 QLowEnergyCharacteristic::WriteNoResponse 속성으로 표시됩니다.

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

이 서비스가 ServiceDiscovered 상태이고 해당 서비스에 속하는 경우에만 특성을 쓸 수 있습니다. 이러한 조건 중 하나가 사실이 아닌 경우 QLowEnergyService::OperationError 이 설정됩니다.

주변 역할

이 호출로 인해 특성 값이 로컬 데이터베이스에서 업데이트됩니다.

클라이언트가 현재 연결되어 있고 해당 특성에 대한 알림이나 표시를 사용 설정한 경우 해당 정보가 전송됩니다. 디바이스가 특성에 대한 알림 또는 표시를 사용 설정했고 해당 디바이스가 현재 연결되어 있지 않지만 로컬 디바이스 사이에 본드가 존재하면 다음에 다시 연결될 때 알림 또는 표시가 전송됩니다.

특성 값의 길이에 대한 제약 조건이 있고 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()도 참조하세요 .