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

Dokumentation der Mitgliedsfunktionen

[virtual noexcept] QLowEnergyService::~QLowEnergyService()

Zerstört die Instanz QLowEnergyService.

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

Gibt das passende Merkmal für uuid zurück, ansonsten ein ungültiges Merkmal.

Das zurückgegebene Merkmal ist ungültig, wenn die Funktion discoverDetails() dieser Serviceinstanz noch nicht aufgerufen wurde oder es keine Merkmale mit einem passenden uuid gibt.

Siehe auch characteristics().

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

Befindet sich das zugehörige Steuerungsobjekt in der Rolle central, wird dieses Signal ausgegeben, wenn der Wert von characteristic durch ein Ereignis auf der Peripherie-/Geräteseite geändert wird. In diesem Fall impliziert die Ausgabe des Signals, dass Änderungsmeldungen über den ClientCharacteristicConfiguration Deskriptor des Merkmals vor dem Änderungsereignis auf der Peripherieseite aktiviert worden sein müssen. Weitere Einzelheiten darüber, wie dies geschehen kann, sind unter above zu finden.

Befindet sich der Controller in der Rolle peripheral, d.h. das Serviceobjekt wurde über QLowEnergyController::addService erstellt, wird das Signal ausgegeben, wenn ein GATT-Client den Wert des Merkmals über eine Schreibanforderung oder einen Schreibbefehl geschrieben hat.

Der Parameter newValue enthält den aktualisierten Wert des characteristic.

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

Dieses Signal wird ausgegeben, wenn die Leseabfrage für characteristic erfolgreich dessen value zurückgegeben hat. Das Signal kann durch den Aufruf von characteristicRead() ausgelöst werden. Wenn der Lesevorgang nicht erfolgreich war, wird das Signal errorOccurred() unter Verwendung des Flags CharacteristicReadError ausgegeben.

Siehe auch readCharacteristic().

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

Dieses Signal wird ausgegeben, wenn der Wert von characteristic erfolgreich in newValue geändert wurde. Die Änderung muss durch den Aufruf von writeCharacteristic() ausgelöst worden sein. Ist der Schreibvorgang nicht erfolgreich, wird das Signal errorOccurred() über das Flag CharacteristicWriteError ausgegeben.

Der Empfang des Schreibsignals kann als Zeichen dafür gewertet werden, dass das Zielgerät den zu schreibenden Wert erhalten hat und den Status der Schreibanforderung zurückmeldet.

Siehe auch writeCharacteristic().

QList<QLowEnergyCharacteristic> QLowEnergyService::characteristics() const

Gibt alle Merkmale zurück, die mit dieser QLowEnergyService Instanz verbunden sind.

Die zurückgegebene Liste ist leer, wenn discoverDetails() für diese Dienstinstanz noch nicht aufgerufen wurde oder keine Merkmale bekannt sind.

Siehe auch characteristic(), state(), und discoverDetails().

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

Gibt true zurück, wenn characteristic zu diesem Dienst gehört; andernfalls false.

Ein Merkmal gehört zu einer Dienstleistung, wenn characteristics() die characteristic enthält.

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

Gibt true zurück, wenn descriptor zu diesem Dienst gehört; andernfalls false.

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

Dieses Signal wird ausgegeben, wenn die Leseanfrage für descriptor erfolgreich dessen value zurückgegeben hat. Das Signal kann durch den Aufruf von descriptorRead() ausgelöst werden. Wenn der Lesevorgang nicht erfolgreich war, wird das Signal errorOccurred() unter Verwendung des Flags DescriptorReadError ausgegeben.

Siehe auch readDescriptor().

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

Dieses Signal wird ausgegeben, wenn der Wert von descriptor erfolgreich in newValue geändert wurde. Wenn sich das zugehörige Controller-Objekt in der Rolle central befindet, muss die Änderung durch den Aufruf von writeDescriptor() verursacht worden sein. Andernfalls ist das Signal das Ergebnis einer Schreibanforderung oder eines Schreibbefehls von einem GATT-Client an den entsprechenden Deskriptor.

Siehe auch writeDescriptor().

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

Initiiert die Ermittlung der in den Dienst einbezogenen Dienste, Merkmale und der zugehörigen Deskriptoren.

Der Erkennungsprozess wird durch das Signal stateChanged() angezeigt. Nach der Erstellung befindet sich der Dienst im Zustand DiscoveryRequired. Beim Aufruf von discoverDetails() geht er in den Zustand DiscoveringService über. Nach Abschluss der Detailermittlung geht er in den Zustand ServiceDiscovered über. Bei jedem Übergang wird das Signal stateChanged() ausgegeben. Je nach dem Argument mode wird ein FullDiscovery oder ein SkipValueDiscovery ausgeführt. In jedem Fall werden alle Dienste und Merkmale ermittelt. Ein FullDiscovery liest alle Merkmalswerte und Deskriptoren aus. Ein SkipValueDiscovery liest keine Merkmalswerte und Deskriptoren. Ein SkipValueDiscovery hat zwei Vorteile. Erstens ist es schneller. Zweitens umgeht es Fehler in einigen Geräten, die fälschlicherweise Merkmale oder Deskriptoren als lesbar ankündigen, aber dennoch kein Lesen auf ihnen erlauben. Dies kann zu unvorhersehbarem Verhalten führen. Nach einem SkipValueDiscovery ist es notwendig, readCharacteristic() / readDescriptor() aufzurufen und auf deren erfolgreichen Abschluss zu warten, bevor auf den Wert eines Merkmals oder Deskriptors zugegriffen wird.

Das Argument mode wurde in Qt 6.2 eingeführt.

Siehe auch state().

QLowEnergyService::ServiceError QLowEnergyService::error() const

Gibt den zuletzt aufgetretenen Fehler zurück oder NoError.

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

Dieses Signal wird ausgegeben, wenn ein Fehler aufgetreten ist. Der Parameter newError beschreibt den aufgetretenen Fehler.

Diese Funktion wurde in Qt 6.2 eingeführt.

QList<QBluetoothUuid> QLowEnergyService::includedServices() const

Gibt die UUIDs aller Dienste zurück, die vom aktuellen Dienst umfasst sind.

Die zurückgegebene Liste ist leer, wenn discoverDetails() dieser Dienstinstanz noch nicht aufgerufen wurde oder es keine bekannten Merkmale gibt.

Es ist möglich, dass ein inkludierter Dienst noch einen weiteren Dienst enthält. Solche Second-Level-Includes müssen über ihre entsprechende First-Level-Instanz QLowEnergyService bezogen werden. Technisch gesehen könnte dies eine zirkuläre Abhängigkeit erzeugen.

QLowEnergyController::createServiceObject() sollte verwendet werden, um Dienstinstanzen für jede der UUIDs zu erhalten.

Siehe auch createServiceObject().

void QLowEnergyService::readCharacteristic(const QLowEnergyCharacteristic &characteristic)

Liest den Wert von characteristic. Ist der Vorgang erfolgreich, wird das Signal characteristicRead() ausgegeben; andernfalls wird CharacteristicReadError gesetzt. Im Allgemeinen ist ein characteristic lesbar, wenn seine QLowEnergyCharacteristic::Read Eigenschaft gesetzt ist.

Alle Deskriptor- und Merkmalsanforderungen an ein und dasselbe entfernte Gerät werden serialisiert. Eine Warteschlange wird verwendet, wenn mehrere Anfragen gleichzeitig gestellt werden. Die Warteschlange verhindert nicht, dass doppelte Leseanforderungen für dasselbe Merkmal gestellt werden.

Ein Merkmal kann nur gelesen werden, wenn sich der Dienst im Zustand ServiceDiscovered befindet und zum Dienst gehört. Wenn eine dieser Bedingungen nicht erfüllt ist, wird QLowEnergyService::OperationError gesetzt.

Siehe auch characteristicRead() und writeCharacteristic().

void QLowEnergyService::readDescriptor(const QLowEnergyDescriptor &descriptor)

Liest den Wert von descriptor. Ist der Vorgang erfolgreich, wird das Signal descriptorRead() ausgegeben; andernfalls wird DescriptorReadError gesetzt.

Alle Deskriptor- und Merkmalsanfragen an dasselbe entfernte Gerät werden serialisiert. Eine Warteschlange wird verwendet, wenn mehrere Anfragen gleichzeitig gestellt werden. Die Warteschlange verhindert nicht, dass doppelte Leseanforderungen für denselben Deskriptor gestellt werden.

Ein Deskriptor kann nur gelesen werden, wenn sich der Dienst im Zustand ServiceDiscovered befindet und der Deskriptor zu diesem Dienst gehört. Wenn eine dieser Bedingungen nicht erfüllt ist, wird QLowEnergyService::OperationError gesetzt.

Siehe auch descriptorRead() und writeDescriptor().

QString QLowEnergyService::serviceName() const

Gibt den Namen des Dienstes zurück, andernfalls eine leere Zeichenkette.

Der zurückgegebene Name kann nur abgerufen werden, wenn serviceUuid() eine bekannte UUID ist.

QBluetoothUuid QLowEnergyService::serviceUuid() const

Gibt die UUID des Dienstes zurück; andernfalls eine Null-UUID.

QLowEnergyService::ServiceState QLowEnergyService::state() const

Gibt den aktuellen Zustand des Dienstes zurück.

Wenn der Dienst des Geräts zum ersten Mal instanziiert wurde, lautet der Zustand des Objekts DiscoveryRequired. Der Zustand aller Dienstobjekte, die auf denselben Dienst des Peripheriegeräts verweisen, ist immer gleich. Dies ist auf die gemeinsame Nutzung der internen Objektdaten zurückzuführen. Daher hat jede Instanz eines Dienstobjekts, die nach der ersten erstellt wird, den gleichen Status wie die bereits vorhandenen Instanzen.

Ein Dienst wird ungültig, wenn die QLowEnergyController die Verbindung zum entfernten Gerät trennt. Ein ungültiger Dienst behält seinen internen Zustand zum Zeitpunkt der Verbindungstrennung bei. Dies bedeutet, dass die Details eines Dienstes auch von einem ungültigen Dienst abgerufen werden können, sobald sie entdeckt wurden. Dies ermöglicht Szenarien, in denen die Geräteverbindung hergestellt wird, die Dienstdetails abgerufen werden und das Gerät sofort getrennt wird, damit das nächste Gerät die Verbindung zum Peripheriegerät herstellen kann.

Unter normalen Umständen sollte die Verbindung jedoch bestehen bleiben, um eine wiederholte Ermittlung der Dienste und ihrer Details zu vermeiden. Die Ermittlung kann eine Weile dauern, und der Client kann sich für laufende Änderungsmeldungen anmelden.

Siehe auch stateChanged().

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

Dieses Signal wird ausgesendet, wenn sich der Zustand des Dienstes ändert. Die newState kann auch über state() abgerufen werden.

Siehe auch state().

QLowEnergyService::ServiceTypes QLowEnergyService::type() const

Gibt den Typ des Dienstes zurück.

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

Schreibt newValue als Wert für die characteristic. Die genaue Semantik hängt von der Rolle ab, in der sich das zugehörige Controller-Objekt befindet.

Zentrale Rolle

Der Aufruf führt zu einer Schreibanforderung oder einem Schreibbefehl an ein entferntes Peripheriegerät. Ist der Vorgang erfolgreich, wird das Signal characteristicWritten() ausgegeben, andernfalls wird CharacteristicWriteError gesetzt. Der Aufruf dieser Funktion löst nur dann das Signal characteristicChanged() aus, wenn das Peripheriegerät selbst den Wert nach der aktuellen Schreibanforderung erneut ändert.

Der Parameter mode bestimmt, ob das entfernte Gerät eine Schreibbestätigung senden soll. Das zu beschreibende characteristic muss den entsprechenden Schreibmodus unterstützen. Die unterstützten Schreibmodi des Merkmals werden durch seine Eigenschaften QLowEnergyCharacteristic::Write und QLowEnergyCharacteristic::WriteNoResponse angegeben.

Alle Schreibanforderungen von Deskriptoren und Merkmalen an ein und dasselbe entfernte Gerät werden serialisiert. Eine Warteschlange wird verwendet, wenn mehrere Schreibanforderungen gleichzeitig gestellt werden. Die Warteschlange verhindert nicht, dass doppelte Schreibanforderungen für dasselbe Merkmal gestellt werden. Wenn beispielsweise derselbe Deskriptor auf den Wert A und unmittelbar danach auf B gesetzt wird, werden die beiden Schreibaufträge in der angegebenen Reihenfolge ausgeführt.

Ein Merkmal kann nur geschrieben werden, wenn sich dieser Dienst im Zustand ServiceDiscovered befindet und zum Dienst gehört. Wenn eine dieser Bedingungen nicht erfüllt ist, wird QLowEnergyService::OperationError gesetzt.

Rolle der Peripherie

Der Aufruf führt dazu, dass der Wert des Merkmals in der lokalen Datenbank aktualisiert wird.

Ist ein Client gerade verbunden und hat er Benachrichtigungen oder Hinweise für das Merkmal aktiviert, werden die entsprechenden Informationen gesendet. Wenn ein Gerät Benachrichtigungen oder Hinweise für das Merkmal aktiviert hat und dieses Gerät derzeit nicht verbunden ist, aber eine Verbindung zwischen ihm und dem lokalen Gerät besteht, wird die Benachrichtigung oder der Hinweis bei der nächsten Wiederverbindung gesendet.

Wenn es eine Beschränkung für die Länge des Merkmalswertes gibt und newValue sich nicht an diese Beschränkung hält, ist das Verhalten nicht spezifiziert.

Siehe auch QLowEnergyService::characteristicWritten() und QLowEnergyService::readCharacteristic().

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

Schreibt newValue als Wert für descriptor. Die genaue Semantik hängt von der Rolle ab, in der sich das zugehörige Controller-Objekt befindet.

Zentrale Rolle

Ein Aufruf dieser Funktion führt zu einer Schreibanforderung an das entfernte Gerät. Ist der Vorgang erfolgreich, wird das Signal descriptorWritten() ausgegeben; andernfalls wird DescriptorWriteError ausgegeben.

Alle Deskriptor- und Merkmalsanforderungen an dasselbe entfernte Gerät werden serialisiert. Eine Warteschlange wird verwendet, wenn mehrere Schreibanforderungen gleichzeitig gestellt werden. Die Warteschlange verhindert nicht, dass doppelte Schreibanforderungen für denselben Deskriptor gestellt werden. Wird beispielsweise derselbe Deskriptor auf den Wert A und unmittelbar danach auf B gesetzt, werden die beiden Schreibaufträge in der angegebenen Reihenfolge ausgeführt.

Ein Deskriptor kann nur geschrieben werden, wenn sich dieser Dienst im Zustand ServiceDiscovered befindet und zum Dienst gehört. Wenn eine dieser Bedingungen nicht erfüllt ist, wird QLowEnergyService::OperationError gesetzt.

Peripherie-Rolle

Der Wert wird in die lokale Dienstdatenbank geschrieben. Wenn der Inhalt von newValue nicht für descriptor gültig ist, ist das Verhalten nicht spezifiziert.

Siehe auch descriptorWritten() und readDescriptor().