QLowEnergyController Class

Dokumentation der Mitgliedsfunktionen

[virtual noexcept] QLowEnergyController::~QLowEnergyController()

Zerstört die Instanz QLowEnergyController.

QLowEnergyService *QLowEnergyController::addService(const QLowEnergyServiceData &service, QObject *parent = nullptr)

Konstruiert ein QLowEnergyService -Objekt mit parent aus service und gibt es zurück. Die Steuerung muss sich im PeripheralRole und im UnconnectedState befinden. Das service -Objekt muss gültig sein.

Siehe auch stopAdvertising(), disconnectFromDevice(), und QLowEnergyServiceData::addIncludedService.

void QLowEnergyController::connectToDevice()

Stellt eine Verbindung mit dem entfernten Bluetooth Low Energy Gerät her.

Diese Funktion führt nichts aus, wenn state() des Controllers nicht gleich UnconnectedState ist. Das Signal connected() wird ausgegeben, sobald die Verbindung erfolgreich hergestellt ist.

Auf Linux/BlueZ-Systemen ist es nicht möglich, mit zwei Instanzen dieser Klasse eine Verbindung zu demselben entfernten Gerät herzustellen. Der zweite Aufruf dieser Funktion kann mit einem Fehler fehlschlagen. Diese Einschränkung kann in zukünftigen Versionen aufgehoben werden.

Siehe auch disconnectFromDevice().

[signal] void QLowEnergyController::connected()

Dieses Signal wird ausgegeben, wenn das Steuergerät erfolgreich eine Verbindung zu einem entfernten Low-Energy-Gerät herstellt (wenn sich das Steuergerät im CentralRole befindet) oder wenn ein entferntes Low-Energy-Gerät mit dem Steuergerät verbunden ist (wenn sich das Steuergerät im PeripheralRole befindet). Unter iOS, macOS und Android ist dieses Signal nicht zuverlässig, wenn sich der Controller im PeripheralRole befindet. Unter iOS und macOS vermutet der Controller nur, dass eine Zentrale mit unserem Peripheriegerät verbunden ist, sobald diese Zentrale versucht, ein Merkmal/Deskriptor zu schreiben/lesen. Unter Android überwacht der Controller alle angeschlossenen GATT-Geräte. Unter Linux BlueZ DBus Peripherie-Backend wird die Zentrale als verbunden betrachtet, wenn sie zum ersten Mal ein Merkmal oder einen Deskriptor liest/schreibt.

[signal] void QLowEnergyController::connectionUpdated(const QLowEnergyConnectionParameters &newParameters)

Dieses Signal wird ausgesendet, wenn sich die Verbindungsparameter ändern. Dies kann durch den Aufruf von requestConnectionUpdate() oder aus anderen Gründen geschehen, zum Beispiel weil die andere Seite der Verbindung neue Parameter angefordert hat. Die neuen Werte können über newParameters abgerufen werden.

Siehe auch requestConnectionUpdate().

[static] QLowEnergyController *QLowEnergyController::createCentral(const QBluetoothDeviceInfo &remoteDevice, QObject *parent = nullptr)

Gibt ein neues Objekt dieser Klasse zurück, das sich im CentralRole befindet und das übergeordnete Objekt parent hat. Die Adresse remoteDevice verweist auf das Gerät, zu dem später eine Verbindung hergestellt wird.

Der Controller verwendet den lokalen Standard-Bluetooth-Adapter für das Verbindungsmanagement.

Siehe auch QLowEnergyController::CentralRole.

[static] QLowEnergyController *QLowEnergyController::createCentral(const QBluetoothDeviceInfo &remoteDevice, const QBluetoothAddress &localDevice, QObject *parent = nullptr)

Gibt eine neue Instanz dieser Klasse mit parent zurück.

Die remoteDevice muss die Adresse des entfernten Bluetooth Low Energy Geräts enthalten, mit dem dieses Objekt später versuchen soll, eine Verbindung herzustellen.

Die Verbindung wird über localDevice hergestellt. Wenn localDevice ungültig ist, wird automatisch das lokale Standardgerät ausgewählt. Wenn localDevice ein lokales Gerät angibt, das kein lokaler Bluetooth-Adapter ist, wird error() auf InvalidBluetoothAdapterError gesetzt, sobald connectToDevice() aufgerufen wird.

Beachten Sie, dass die Angabe des lokalen Geräts, das für die Verbindung verwendet werden soll, nur bei Verwendung von BlueZ möglich ist. Alle anderen Plattformen unterstützen diese Funktion nicht.

[static] QLowEnergyController *QLowEnergyController::createPeripheral(QObject *parent = nullptr)

Gibt ein neues Objekt dieser Klasse zurück, das sich im PeripheralRole befindet und das übergeordnete Objekt parent hat. Die nächsten Schritte bestehen in der Regel darin, einige Dienste hinzuzufügen und schließlich startAdvertising() für das zurückgegebene Objekt aufzurufen.

Der Controller verwendet den lokalen Standard-Bluetooth-Adapter für das Verbindungsmanagement.

Siehe auch QLowEnergyController::PeripheralRole.

[static, since 6.2] QLowEnergyController *QLowEnergyController::createPeripheral(const QBluetoothAddress &localDevice, QObject *parent = nullptr)

Gibt ein neues Objekt dieser Klasse zurück, das sich im PeripheralRole befindet und das übergeordnete Objekt parent hat und localDevice verwendet. Normalerweise sind die nächsten Schritte das Hinzufügen einiger Dienste und schließlich der Aufruf von startAdvertising() für das zurückgegebene Objekt.

Das Peripheriegerät wird auf localDevice erstellt. Wenn localDevice ungültig ist, wird automatisch das lokale Standardgerät ausgewählt. Wenn localDevice ein lokales Gerät angibt, das kein lokaler Bluetooth-Adapter ist, wird error() auf InvalidBluetoothAdapterError gesetzt.

Die Auswahl von localDevice wird nur unter Linux unterstützt. Auf anderen Plattformen wird der Parameter ignoriert.

Diese Funktion wurde in Qt 6.2 eingeführt.

Siehe auch QLowEnergyController::PeripheralRole.

QLowEnergyService *QLowEnergyController::createServiceObject(const QBluetoothUuid &serviceUuid, QObject *parent = nullptr)

Erzeugt eine Instanz des durch serviceUuid dargestellten Dienstes. Der Parameter serviceUuid muss über services() bezogen worden sein.

Der Aufrufer ist Eigentümer des zurückgegebenen Zeigers und kann einen Parameter parent als Standard-Eigentümer übergeben.

Diese Funktion gibt einen Nullzeiger zurück, wenn auf dem entfernten Gerät kein Dienst mit serviceUuid gefunden werden kann oder die Verbindung zum Steuergerät unterbrochen ist.

Diese Funktion kann auch Instanzen für sekundäre Dienste zurückgeben. Die Include-Beziehungen zwischen Diensten können über QLowEnergyService::includedServices() ausgedrückt werden.

Wird diese Funktion mehrfach mit derselben Dienst-UUID aufgerufen, teilen sich die zurückgegebenen QLowEnergyService -Instanzen ihre internen Daten. Wenn also eine der Instanzen die Ermittlung der Dienstdetails einleitet, gehen die anderen Instanzen automatisch ebenfalls in den Ermittlungszustand über.

Siehe auch services().

void QLowEnergyController::disconnectFromDevice()

Trennt die Verbindung mit dem entfernten Gerät.

Alle QLowEnergyService, QLowEnergyCharacteristic oder QLowEnergyDescriptor Instanzen, die aus der aktuellen Verbindung hervorgegangen sind, werden automatisch ungültig. Sobald eines dieser Objekte ungültig wird, bleibt es ungültig, auch wenn dieses Steuerungsobjekt erneut eine Verbindung herstellt.

Diese Funktion ist wirkungslos, wenn sich die Steuerung in der UnconnectedState befindet.

Befindet sich der Controller in der Peripherie-Rolle, stoppt er die Werbung und entfernt alle Dienste, die zuvor über addService() hinzugefügt wurden. Um die Instanz QLowEnergyController wieder zu verwenden, muss die Anwendung erneut Dienste hinzufügen und den Werbemodus durch Aufruf von startAdvertising() neu starten.

Siehe auch connectToDevice().

[signal] void QLowEnergyController::disconnected()

Dieses Signal wird ausgegeben, wenn das Steuergerät die Verbindung zum entfernten Low-Energy-Gerät trennt oder andersherum. Unter iOS und macOS ist dieses Signal unzuverlässig, wenn sich der Controller im PeripheralRole befindet. Unter Android wird das Signal ausgegeben, wenn das letzte verbundene Gerät getrennt wird. Auf dem BlueZ DBus Backend wird der Controller als getrennt betrachtet, wenn der letzte Client, der auf die Attribute zugegriffen hat, die Verbindung getrennt hat.

void QLowEnergyController::discoverServices()

Leitet den Prozess der Dienstsuche ein.

Der Fortschritt der Suche wird über das Signal serviceDiscovered() angezeigt. Das Signal discoveryFinished() wird ausgegeben, wenn der Prozess beendet ist.

Wenn die Steuerungsinstanz nicht verbunden ist oder die Steuerung die Dienstsuche bereits durchgeführt hat, bewirkt diese Funktion nichts.

[signal] void QLowEnergyController::discoveryFinished()

Dieses Signal wird ausgegeben, wenn die laufende Dienstsuche beendet ist. Das Signal wird nicht ausgegeben, wenn der Erkennungsprozess mit einem Fehler beendet wird.

Dieses Signal kann nur ausgegeben werden, wenn sich der Controller im CentralRole befindet.

Siehe auch discoverServices() und error().

QLowEnergyController::Error QLowEnergyController::error() const

Gibt den zuletzt aufgetretenen Fehler zurück oder NoError.

[signal, since 6.2] void QLowEnergyController::errorOccurred(QLowEnergyController::Error newError)

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

Diese Funktion wurde in Qt 6.2 eingeführt.

Siehe auch error() und errorString().

QString QLowEnergyController::errorString() const

Gibt eine textuelle Darstellung des zuletzt aufgetretenen Fehlers zurück. Die Zeichenkette wird übersetzt.

QBluetoothAddress QLowEnergyController::localAddress() const

Gibt die Adresse des lokalen Bluetooth-Adapters zurück, der für die Kommunikation verwendet wird.

Wenn diese Klasseninstanz angefordert wurde, um den Standardadapter zu verwenden, aber bei der Erstellung dieser Klasseninstanz kein Standardadapter vorhanden war, ist der zurückgegebene Wert QBluetoothAddress null.

Siehe auch QBluetoothAddress::isNull().

[since 6.2] int QLowEnergyController::mtu() const

Gibt die MTU-Größe zurück.

Während des Verbindungsaufbaus wird die ATT-MTU-Größe ausgehandelt. Diese Methode liefert das Ergebnis dieser Aushandlung. Sie kann verwendet werden, um die Paketgröße in bestimmten Situationen zu optimieren. Die maximale Datenmenge, die in einem einzigen Paket übertragen werden kann, beträgt mtu-3 Bytes. 3 Bytes werden für den ATT-Protokollkopf benötigt.

Vor dem Verbindungsaufbau und der MTU-Aushandlung wird der Standardwert von 23 zurückgegeben.

Nicht jede Plattform stellt den MTU-Wert zur Verfügung. Auf diesen Plattformen (z. B. Linux) gibt diese Funktion immer -1 zurück.

Wenn sich der Controller im PeripheralRole befindet, können mehrere zentrale Geräte mit ihm verbunden sein. In solchen Fällen gibt diese Funktion die MTU der letzten ausgehandelten Verbindung zurück.

Diese Funktion wurde in Qt 6.2 eingeführt.

[signal] void QLowEnergyController::mtuChanged(int mtu)

Dieses Signal wird als Ergebnis einer erfolgreichen MTU-Änderung ausgegeben. mtu stellt den neuen Wert dar.

Siehe auch mtu().

[since 6.5] void QLowEnergyController::readRssi()

readRssi() liest RSSI (received signal strength indicator) für ein verbundenes entferntes Gerät. Wenn der Lesevorgang erfolgreich war, wird die RSSI durch das Signal rssiRead() gemeldet.

Diese Funktion wurde in Qt 6.5 eingeführt.

Siehe auch rssiRead(), connectToDevice(), state(), createCentral(), und errorOccurred().

QBluetoothAddress QLowEnergyController::remoteAddress() const

Gibt die Adresse des entfernten Bluetooth Low Energy Geräts zurück.

Bei einem Controller im CentralRole ist dieser Wert immer derjenige, der bei der Erstellung des Controller-Objekts übergeben wurde. Bei einer Steuerung im PeripheralRole ist dieser Wert eine der Adressen der aktuell verbundenen Client-Geräte. Diese Adresse ist ungültig, wenn sich die Steuereinheit nicht im ConnectedState befindet.

QLowEnergyController::RemoteAddressType QLowEnergyController::remoteAddressType() const

Gibt den Typ von remoteAddress() zurück. Standardmäßig ist dieser Wert auf PublicAddress initialisiert.

Siehe auch setRemoteAddressType().

QBluetoothUuid QLowEnergyController::remoteDeviceUuid() const

Gibt den eindeutigen Bezeichner des entfernten Bluetooth Low Energy Geräts zurück.

Unter macOS/iOS/tvOS stellt CoreBluetooth keine Hardware-Adressen für LE-Geräte zur Verfügung bzw. akzeptiert diese nicht; stattdessen sollen Entwickler eindeutige 128-Bit-UUIDs verwenden, die von CoreBluetooth generiert werden. Diese UUIDS bleiben für dasselbe Zentral- <-> Peripheriegerät-Paar konstant und wir verwenden sie, wenn wir uns mit einem entfernten Gerät verbinden. Für einen Controller in der CentralRole wird dieser Wert immer derjenige sein, der bei der Erstellung des Controller-Objekts übergeben wurde. Für eine Steuerung in der PeripheralRole ist dieser Wert ungültig.

QString QLowEnergyController::remoteName() const

Gibt den Namen des entfernten Bluetooth-Low-Energy-Geräts zurück, wenn sich der Controller im CentralRole befindet. Andernfalls ist das Ergebnis nicht spezifiziert.

void QLowEnergyController::requestConnectionUpdate(const QLowEnergyConnectionParameters &parameters)

Fordert den Controller auf, die Verbindung gemäß parameters zu aktualisieren. Ist die Anfrage erfolgreich, wird das Signal connectionUpdated() mit den aktuellen neuen Parametern ausgegeben. Weitere Informationen zu den Verbindungsparametern finden Sie in der Klasse QLowEnergyConnectionParameters.

Android erlaubt die Anpassung dieses Parametersatzes nur indirekt. Die Verbindungsparameter sind in drei Kategorien unterteilt (hohe, niedrige und ausgeglichene Priorität). Jede Kategorie impliziert einen vorkonfigurierten Satz von Werten für QLowEnergyConnectionParameters::minimumInterval(), QLowEnergyConnectionParameters::maximumInterval() und QLowEnergyConnectionParameters::latency(). Obwohl die Verbindungsanfrage eine asynchrone Operation ist, bietet Android keinen Callback, der das Ergebnis der Anfrage angibt. Dies ist ein anerkannter Android-Fehler. Aufgrund dieses Fehlers gibt Android das Signal connectionUpdated() nicht aus.

Siehe auch connectionUpdated().

QLowEnergyController::Role QLowEnergyController::role() const

Gibt die Rolle zurück, in der sich dieses Controller-Objekt befindet.

Die Rolle wird bei der Erstellung einer QLowEnergyController -Instanz mit createCentral() oder createPeripheral() ermittelt.

[signal, since 6.5] void QLowEnergyController::rssiRead(qint16 rssi)

Dieses Signal wird nach erfolgreichem Lesen des RSSI (Received Signal Strength Indicator) für ein verbundenes entferntes Gerät ausgegeben. Der Parameter rssi repräsentiert den neuen Wert.

Diese Funktion wurde in Qt 6.5 eingeführt.

Siehe auch readRssi().

[signal] void QLowEnergyController::serviceDiscovered(const QBluetoothUuid &newService)

Dieses Signal wird jedes Mal ausgegeben, wenn ein neuer Dienst entdeckt wird. Der Parameter newService enthält die UUID des gefundenen Dienstes.

Dieses Signal kann nur ausgesendet werden, wenn sich der Controller im CentralRole befindet.

Siehe auch discoverServices() und discoveryFinished().

QList<QBluetoothUuid> QLowEnergyController::services() const

Gibt die Liste der vom entfernten Gerät angebotenen Dienste zurück, wenn sich die Steuerung im CentralRole befindet. Andernfalls ist das Ergebnis nicht spezifiziert.

Die Liste enthält alle primären und sekundären Dienste.

Siehe auch createServiceObject().

void QLowEnergyController::setRemoteAddressType(QLowEnergyController::RemoteAddressType type)

Legt die Remote-Adresse type fest. Der Typ ist erforderlich, um eine Verbindung mit dem entfernten Bluetooth Low Energy Gerät herzustellen.

Dieses Attribut muss nur auf Linux/BlueZ-Systemen mit älteren Linux-Kerneln (v3.3 oder niedriger) gesetzt werden, oder wenn CAP_NET_ADMIN für die ausführbare Datei nicht gesetzt ist. Der Standardwert des Attributs ist RandomAddress.

Siehe auch remoteAddressType().

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

Startet die Anzeige der in advertisingData und scanResponseData angegebenen Daten unter Verwendung der in parameters eingestellten Parameter. Der Controller muss sich im PeripheralRole befinden. Wenn parameters angibt, dass die Anzeige verbindbar sein soll, dann beginnt diese Funktion auch, auf eingehende Client-Verbindungen zu warten.

Die Bereitstellung von scanResponseData ist nicht erforderlich, da sie für bestimmte Konfigurationen von parameters nicht anwendbar ist. advertisingData und scanResponseData sind auf 31 Byte Nutzdaten beschränkt. Wenn z. B. mehrere 128-Bit-UUIDs zu advertisingData hinzugefügt werden, enthalten die angekündigten Pakete möglicherweise nicht alle UUIDs. Die bestehende Begrenzung kann dazu geführt haben, dass die uuids abgeschnitten wurden. In solchen Fällen kann scanResponseData für zusätzliche Informationen verwendet werden.

Im BlueZ DBus-Backend entscheidet BlueZ, ob und welche Daten in einer Scan-Antwort verwendet werden sollen. Daher wird empfohlen, alle Advertisement-Daten im Hauptparameter advertisingData zu setzen. Wenn sowohl Advertisement- als auch Scan-Response-Daten gesetzt sind, haben die Scan-Response-Daten Vorrang.

Befindet sich dieses Objekt derzeit nicht im UnconnectedState, geschieht nichts.

Siehe auch stopAdvertising().

QLowEnergyController::ControllerState QLowEnergyController::state() const

Gibt den aktuellen Zustand des Controllers zurück.

Siehe auch stateChanged().

[signal] void QLowEnergyController::stateChanged(QLowEnergyController::ControllerState state)

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

Siehe auch state().

void QLowEnergyController::stopAdvertising()

Stoppt die Werbung, wenn sich das Objekt gerade im Werbezustand befindet.

Der Controller muss sich im PeripheralRole befinden, damit diese Funktion funktioniert. Sie macht keine Dienste ungültig, die zuvor über addService() hinzugefügt wurden.

Siehe auch startAdvertising().