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 Member-Funktionen

[virtual noexcept] QLowEnergyService::~QLowEnergyService()

Löscht die Instanz „ QLowEnergyService “.

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

Gibt das passende Merkmal für „ uuid “ zurück; andernfalls ein ungültiges Merkmal.

Das zurückgegebene Merkmal ist ungültig, wenn die Methode ` discoverDetails()` dieser Service-Instanz noch nicht aufgerufen wurde oder es keine Merkmale mit dem passenden ` uuid` gibt.

Siehe auch ` characteristics()`.

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

Befindet sich das zugehörige Controller-Objekt 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 bedeutet die Signalausgabe, dass Änderungsbenachrichtigungen über den Deskriptor „ ClientCharacteristicConfiguration “ der Eigenschaft vor dem Änderungsereignis auf der Peripherie aktiviert worden sein müssen. Weitere Details dazu finden Sie unter above.

Befindet sich der Controller in der Rolle „ peripheral “, d. h., wurde das Serviceobjekt über „ QLowEnergyController::addService “ erstellt, wird das Signal ausgesendet, wenn ein GATT-Client den Wert des Merkmals mithilfe einer Schreibanforderung oder eines Befehls geschrieben hat.

Der Parameter „ newValue “ enthält den aktualisierten Wert von „ characteristic “.

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

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

Siehe auch ` readCharacteristic()`.

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

Dieses Signal wird ausgelöst, wenn der Wert von „ characteristic “ erfolgreich in „ newValue “ geändert wurde. Die Änderung muss durch den Aufruf von „ writeCharacteristic()“ ausgelöst worden sein. Wenn der Schreibvorgang nicht erfolgreich ist, wird das Signal „ errorOccurred()“ unter Verwendung des Flags „ CharacteristicWriteError “ ausgelöst.

Der Empfang des „written“-Signals kann als Zeichen dafür gewertet werden, dass das Zielgerät den zu schreibenden Wert empfangen hat und den Status der Schreibanforderung zurückmeldet.

Siehe auch ` writeCharacteristic()`.

QList<QLowEnergyCharacteristic> QLowEnergyService::characteristics() const

Gibt alle Merkmale zurück, die dieser „ QLowEnergyService “-Instanz zugeordnet sind.

Die zurückgegebene Liste ist leer, wenn die Methode „ discoverDetails()“ dieser Service-Instanz 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 einem Service, 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 ausgelöst, wenn die Leseanforderung für „ descriptor “ erfolgreich den Wert „ value “ zurückgegeben hat. Das Signal kann durch den Aufruf von „descriptorRead()“ ausgelöst werden. Wenn der Lesevorgang nicht erfolgreich ist, wird das Signal „ errorOccurred()“ unter Verwendung des Flags „ DescriptorReadError “ ausgelöst.

Siehe auch ` readDescriptor()`.

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

Dieses Signal wird ausgelöst, wenn der Wert von „ descriptor “ erfolgreich in „ newValue “ geändert wurde. Befindet sich das zugehörige Controller-Objekt in der Rolle „ central “, muss die Änderung durch den Aufruf von „ writeDescriptor()“ verursacht worden sein. Andernfalls ist das Signal das Ergebnis einer Schreibanforderung oder eines Befehls eines GATT-Clients an den jeweiligen Deskriptor.

Siehe auch writeDescriptor().

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

Leitet die Erkennung der im Dienst enthaltenen Dienste, Eigenschaften und der zugehörigen Deskriptoren ein.

Der Erkennungsprozess wird über das Signal „ stateChanged()“ angezeigt. Nach der Erstellung befindet sich der Dienst im Zustand „ DiscoveryRequired “. Beim Aufruf von „discoverDetails()“ wechselt er in den Zustand „ DiscoveringService “. Nach Abschluss der Detailerkennung wechselt er in den Zustand „ ServiceDiscovered “. Bei jedem Übergang wird das Signal „ stateChanged()“ ausgegeben. Je nach dem Argument „ mode “ wird eine „ FullDiscovery “ oder eine „ SkipValueDiscovery “ durchgeführt. In jedem Fall werden alle Dienste und Merkmale erkannt. Ein „ FullDiscovery “ wird ausgeführt und liest alle Merkmalswerte und Deskriptoren ein. Ein „ SkipValueDiscovery “ liest keine Merkmalswerte und Deskriptoren ein. Ein „ SkipValueDiscovery “ hat zwei Vorteile. Erstens ist er schneller. Zweitens umgeht er Fehler bei einigen Geräten, die Eigenschaften oder Deskriptoren fälschlicherweise als lesbar kennzeichnen, das Lesen dieser Werte jedoch nicht zulassen. Dies kann zu unvorhersehbarem Verhalten führen. Nach einem „ SkipValueDiscovery “ ist es erforderlich, „ readCharacteristic()“ bzw. „ readDescriptor()“ aufzurufen und abzuwarten, bis diese erfolgreich abgeschlossen sind, bevor auf den Wert einer Eigenschaft oder eines 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 oder „ NoError “ zurück.

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

Dieses Signal wird ausgelöst, wenn ein Fehler auftritt. 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 einbezogen werden.

Die zurückgegebene Liste ist leer, wenn die Methode ` discoverDetails()` dieser Dienstinstanz noch nicht aufgerufen wurde oder keine Merkmale bekannt sind.

Es ist möglich, dass ein eingebundener Dienst einen weiteren Dienst enthält. Solche Einbindungen der zweiten Ebene müssen über die entsprechende ` QLowEnergyService `-Instanz der ersten Ebene abgerufen werden. Technisch gesehen könnte dies zu einer zirkulären Abhängigkeit führen.

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

Siehe auch ` createServiceObject()`.

void QLowEnergyService::readCharacteristic(const QLowEnergyCharacteristic &characteristic)

Liest den Wert von „ characteristic “. Bei erfolgreichem Abschluss des Vorgangs wird das Signal „ characteristicRead()“ ausgesendet; andernfalls wird das Signal „ CharacteristicReadError “ gesetzt. Im Allgemeinen ist ein „ characteristic “ lesbar, wenn seine Eigenschaft „ QLowEnergyCharacteristic::Read “ gesetzt ist.

Alle Deskriptor- und Merkmalsanfragen an dasselbe Remote-Gerät werden serialisiert. Bei der gleichzeitigen Ausgabe mehrerer Anfragen wird eine Warteschlange verwendet. Die Warteschlange verhindert keine doppelten Leseanfragen für dasselbe Merkmal.

Eine Eigenschaft kann nur gelesen werden, wenn sich der Dienst im Status „ ServiceDiscovered “ befindet und zu diesem Dienst gehört. Ist eine dieser Bedingungen nicht erfüllt, wird „ QLowEnergyService::OperationError “ gesetzt.

Siehe auch „ characteristicRead()“ und „ writeCharacteristic()“.

void QLowEnergyService::readDescriptor(const QLowEnergyDescriptor &descriptor)

Liest den Wert von „ descriptor “. Bei erfolgreichem Ablauf wird das Signal „ descriptorRead()“ ausgelöst; andernfalls wird „ DescriptorReadError “ gesetzt.

Alle Deskriptor- und Merkmalsanfragen an dasselbe Remote-Gerät werden serialisiert. Bei der gleichzeitigen Ausgabe mehrerer Anfragen kommt eine Warteschlange zum Einsatz. Die Warteschlange verhindert keine doppelten Leseanfragen für denselben Deskriptor.

Ein Deskriptor kann nur gelesen werden, wenn sich der Dienst im Zustand „ ServiceDiscovered “ befindet und der Deskriptor zu diesem Dienst gehört. Ist eine dieser Bedingungen nicht erfüllt, 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.

Wurde der Dienst des Geräts zum ersten Mal instanziiert, lautet der Status des Objekts „ DiscoveryRequired “. Der Status aller Dienstobjekte, die auf denselben Dienst auf dem Peripheriegerät verweisen, ist stets identisch. Dies ist auf die gemeinsame Nutzung der internen Objektdaten zurückzuführen. Daher hat jede nach der ersten erstellte Dienstobjektinstanz denselben Status wie bereits vorhandene Instanzen.

Ein Dienst wird ungültig, wenn das „ QLowEnergyController “ die Verbindung zum Remote-Gerät trennt. Ein ungültiger Dienst behält seinen internen Zustand zum Zeitpunkt des Trennungsereignisses bei. Dies bedeutet, dass die Dienstdetails, sobald sie einmal ermittelt wurden, sogar von einem ungültigen Dienst abgerufen werden können. Dies ermöglicht Szenarien, in denen die Geräteverbindung hergestellt wird, die Dienstdetails abgerufen werden und das Gerät sofort getrennt wird, damit sich das nächste Gerät mit dem Peripheriegerät verbinden kann.

Unter normalen Umständen sollte die Verbindung jedoch bestehen bleiben, um eine wiederholte Erkennung von Diensten und deren Details zu vermeiden. Die Erkennung kann eine Weile dauern, und der Client kann Benachrichtigungen über laufende Änderungen abonnieren.

Siehe auch stateChanged().

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

Dieses Signal wird ausgelöst, wenn sich der Status des Dienstes ändert. Der Status des Dienstes („ newState “) kann auch über die Methode „ 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 „ 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()“ ausgelöst; andernfalls wird „ CharacteristicWriteError “ gesetzt. Der Aufruf dieser Funktion löst das Signal „ characteristicChanged()“ nicht aus, es sei denn, das Peripheriegerät selbst ändert den Wert nach der aktuellen Schreibanforderung erneut.

Der Parameter „ mode “ legt fest, ob das Remote-Gerät eine Schreibbestätigung senden soll. Das zu beschreibende Merkmal „ characteristic “ muss den entsprechenden Schreibmodus unterstützen. Die vom Merkmal unterstützten Schreibmodi werden durch die Eigenschaften „ QLowEnergyCharacteristic::Write “ und „ QLowEnergyCharacteristic::WriteNoResponse “ angegeben.

Alle Schreibanforderungen für Deskriptoren und Merkmale an dasselbe Remote-Gerät werden serialisiert. Bei der gleichzeitigen Ausgabe mehrerer Schreibanforderungen kommt eine Warteschlange zum Einsatz. Die Warteschlange verhindert keine doppelten Schreibanforderungen für dasselbe Merkmal. Wird beispielsweise derselbe Deskriptor zunächst auf den Wert A und unmittelbar danach auf den Wert B gesetzt, werden die beiden Schreibanforderungen in der angegebenen Reihenfolge ausgeführt.

Ein Merkmal kann nur geschrieben werden, wenn sich dieser Dienst im Status „ ServiceDiscovered “ befindet und zu dem Dienst gehört. Ist eine dieser Bedingungen nicht erfüllt, wird der Status „ QLowEnergyService::OperationError “ gesetzt.

Peripherie-Rolle

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

Ist derzeit ein Client verbunden und hat dieser Benachrichtigungen oder Anzeigen für das Merkmal aktiviert, werden die entsprechenden Informationen gesendet. Hat ein Gerät Benachrichtigungen oder Anzeigen für das Merkmal aktiviert und ist dieses Gerät derzeit nicht verbunden, besteht jedoch eine Verbindung zwischen ihm und dem lokalen Gerät, wird die Benachrichtigung oder Anzeige bei der nächsten Wiederverbindung gesendet.

Wenn eine Beschränkung hinsichtlich der Länge des Merkmalswerts besteht und „ newValue “ diese Beschränkung nicht einhä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 Remote-Gerät. Ist der Vorgang erfolgreich, wird das Signal „ descriptorWritten()“ ausgelöst; andernfalls wird das Signal „ DescriptorWriteError “ ausgelöst.

Alle Deskriptor- und Merkmalsanfragen an dasselbe Remote-Gerät werden serialisiert. Bei der gleichzeitigen Ausgabe mehrerer Schreibanfragen wird eine Warteschlange verwendet. Die Warteschlange verhindert keine doppelten Schreibanfragen für denselben Deskriptor. Wird beispielsweise derselbe Deskriptor zunächst auf den Wert A und unmittelbar danach auf B gesetzt, werden die beiden Schreibanfragen in der angegebenen Reihenfolge ausgeführt.

Ein Deskriptor kann nur beschrieben werden, wenn sich dieser Dienst im Status „ ServiceDiscovered “ befindet und zum Dienst gehört. Ist eine dieser Bedingungen nicht erfüllt, wird der Status „ QLowEnergyService::OperationError “ gesetzt.

Rolle der Peripherie

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

Siehe auch descriptorWritten() und readDescriptor().