QLowEnergyController Class

Dokumentation zu den Member-Funktionen

[virtual noexcept] QLowEnergyController::~QLowEnergyController()

Löscht die Instanz von „ QLowEnergyController “.

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

Erstellt und gibt ein „ QLowEnergyService “-Objekt mit „ parent “ aus „ service “ zurück. Der Controller 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 zum entfernten Bluetooth-Low-Energy-Gerät her.

Diese Funktion führt keine Aktion aus, wenn der Wert von „ state()“ des Controllers nicht „ UnconnectedState “ ist. Das Signal „ connected()“ wird ausgegeben, sobald die Verbindung erfolgreich hergestellt wurde.

Auf Linux/BlueZ-Systemen ist es nicht möglich, mit zwei Instanzen dieser Klasse eine Verbindung zum selben Remote-Gerät herzustellen. Der zweite Aufruf dieser Funktion schlägt möglicherweise mit einem Fehler fehl. Diese Einschränkung wird möglicherweise in zukünftigen Versionen aufgehoben.

Siehe auch ` disconnectFromDevice()`.

[signal] void QLowEnergyController::connected()

Dieses Signal wird gesendet, wenn der Controller erfolgreich eine Verbindung zu einem entfernten Low-Energy-Gerät herstellt (sofern sich der Controller im Modus „ CentralRole “ befindet) oder wenn ein entferntes Low-Energy-Gerät mit dem Controller verbunden ist (sofern sich der Controller im Modus „ PeripheralRole “ befindet). Unter iOS, macOS und Android ist dieses Signal nicht zuverlässig, wenn sich der Controller im Modus „ PeripheralRole “ befindet. Unter iOS und macOS geht der Controller erst dann davon aus, dass ein Central mit unserem Peripheriegerät verbunden ist, sobald dieses Central versucht, eine Eigenschaft oder einen Deskriptor zu schreiben oder zu lesen. Unter Android überwacht der Controller alle verbundenen GATT-Geräte. Beim Linux-BlueZ-DBus-Peripherie-Backend gilt die Fernbedienung als verbunden, sobald sie zum ersten Mal eine Eigenschaft oder einen Deskriptor liest oder schreibt.

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

Dieses Signal wird ausgelöst, wenn sich die Verbindungsparameter ändern. Dies kann durch den Aufruf von ` requestConnectionUpdate()` oder aus anderen Gründen geschehen, beispielsweise weil die Gegenstelle 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 dessen übergeordnetes Objekt „ parent “ ist. „ remoteDevice “ bezieht sich auf das Gerät, zu dem später eine Verbindung hergestellt wird.

Der Controller verwendet den lokalen Standard-Bluetooth-Adapter für die Verbindungsverwaltung.

Siehe auch „ QLowEnergyController::CentralRole “.

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

Gibt eine neue Instanz dieser Klasse mit dem Parameter „ parent “ zurück.

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

Die Verbindung wird über ` localDevice` hergestellt. Ist ` localDevice ` ungültig, wird automatisch das lokale Standardgerät ausgewählt. Wenn ` localDevice ` ein lokales Gerät angibt, bei dem es sich nicht um einen lokalen Bluetooth-Adapter handelt, wird ` error()` auf ` InvalidBluetoothAdapterError ` gesetzt, sobald ` connectToDevice()` aufgerufen wird.

Beachten Sie, dass die Angabe des für die Verbindung zu verwendenden lokalen Geräts 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 über das übergeordnete Objekt „ parent “ verfügt. In der Regel bestehen die nächsten Schritte darin, einige Dienste hinzuzufügen und schließlich die Methode „ startAdvertising()“ für das zurückgegebene Objekt aufzurufen.

Der Controller verwendet den lokalen Standard-Bluetooth-Adapter für die Verbindungsverwaltung.

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, das „ parent “ als übergeordnetes Objekt hat und „ localDevice “ verwendet. In der Regel bestehen die nächsten Schritte darin, einige Dienste hinzuzufügen und schließlich die Methode „ startAdvertising()“ für das zurückgegebene Objekt aufzurufen.

Das Peripheriegerät wird unter „ localDevice “ angelegt. Ist „ localDevice “ ungültig, wird automatisch das lokale Standardgerät ausgewählt. Wenn „ localDevice “ ein lokales Gerät angibt, bei dem es sich nicht um einen lokalen Bluetooth-Adapter handelt, 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)

Erstellt eine Instanz des Dienstes, der durch „ serviceUuid “ repräsentiert wird. Der Parameter „ serviceUuid “ muss zuvor über „ services()“ abgerufen worden sein.

Der Aufrufer übernimmt die Verantwortung für den zurückgegebenen Zeiger und kann einen „ parent “-Parameter als Standardbesitzer übergeben.

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

Diese Funktion kann auch Instanzen für sekundäre Dienste zurückgeben. Die Einbindungsbeziehungen 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 initiiert, wechseln die anderen Instanzen automatisch ebenfalls in den Ermittlungszustand.

Siehe auch ` services()`.

void QLowEnergyController::disconnectFromDevice()

Trennt die Verbindung zum Remote-Gerät.

Alle Instanzen von ` QLowEnergyService`, ` QLowEnergyCharacteristic ` oder ` QLowEnergyDescriptor `, die aus der aktuellen Verbindung entstanden sind, werden automatisch ungültig. Sobald eines dieser Objekte ungültig wird, bleibt es ungültig, auch wenn dieses Controller-Objekt die Verbindung erneut herstellt.

Diese Funktion hat keine Auswirkung, wenn sich der Controller im Zustand „ UnconnectedState “ befindet.

Befindet sich der Controller in der Peripherie-Rolle, beendet er die Bekanntgabe und entfernt alle Dienste, die zuvor über ` addService()` hinzugefügt wurden. Um die ` QLowEnergyController `-Instanz wiederverwenden zu können, muss die Anwendung die Dienste erneut hinzufügen und den Bekanntgabemodus durch Aufruf von ` startAdvertising()` neu starten.

Siehe auch ` connectToDevice()`.

[signal] void QLowEnergyController::disconnected()

Dieses Signal wird ausgesendet, wenn die Steuerung die Verbindung zum Low-Energy-Fernbedienungsgerät trennt oder umgekehrt. Unter iOS und macOS ist dieses Signal unzuverlässig, wenn sich die Steuerung im „ PeripheralRole “ befindet. Unter Android wird das Signal ausgesendet, wenn die Verbindung zum zuletzt verbundenen Gerät getrennt wird. Beim BlueZ-DBus-Backend gilt die Steuerung als getrennt, wenn der letzte Client, der auf die Attribute zugegriffen hat, die Verbindung getrennt hat.

void QLowEnergyController::discoverServices()

Leitet den Prozess der Dienstermittlung ein.

Der Fortschritt der Erkennung wird über das Signal „ serviceDiscovered()“ angezeigt. Das Signal „ discoveryFinished()“ wird ausgesendet, sobald der Vorgang abgeschlossen ist.

Wenn die Controller-Instanz nicht verbunden ist oder der Controller die Dienstermittlung bereits durchgeführt hat, führt diese Funktion keine Aktion aus.

[signal] void QLowEnergyController::discoveryFinished()

Dieses Signal wird ausgesendet, wenn die laufende Diensterkennung abgeschlossen ist. Das Signal wird nicht ausgesendet, wenn der Erkennungsprozess mit einem Fehler endet.

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

Siehe auch „ discoverServices()“ und „ error()“.

QLowEnergyController::Error QLowEnergyController::error() const

Gibt den zuletzt aufgetretenen Fehler oder „ NoError “ zurück.

[signal, since 6.2] void QLowEnergyController::errorOccurred(QLowEnergyController::Error 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.

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 bei der Erstellung dieser Klasseninstanz die Verwendung des Standardadapters angefordert wurde, zum Zeitpunkt der Erstellung jedoch 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 in bestimmten Situationen zur Optimierung der Paketgrößen verwendet werden. Die maximale Datenmenge, die in einem einzelnen Paket übertragen werden kann, beträgt „mtu-3“ Bytes. 3 Bytes werden für den ATT-Protokoll-Header benötigt.

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

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

Befindet sich der Controller im Modus „ PeripheralRole “, sind möglicherweise mehrere zentrale Geräte mit ihm verbunden. In diesen Fällen gibt diese Funktion die MTU der zuletzt ausgehandelten Verbindung zurück.

Diese Funktion wurde in Qt 6.2 eingeführt.

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

Dieses Signal wird nach einer erfolgreichen MTU-Änderung ausgesendet. „ mtu “ steht für den neuen Wert.

Siehe auch „ mtu()“.

[since 6.5] void QLowEnergyController::readRssi()

readRssi() liest den RSSI-Wert (Received Signal Strength Indicator) eines angeschlossenen Fernbedienungsgeräts aus. War der Lesevorgang erfolgreich, wird der RSSI-Wert anschließend über 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 “ entspricht dieser Wert immer dem Wert, der bei der Erstellung des Controller-Objekts übergeben wurde. Bei einem Controller im „ PeripheralRole “ ist dieser Wert eine der Adressen der derzeit verbundenen Client-Geräte. Diese Adresse ist ungültig, wenn sich der Controller derzeit nicht im „ ConnectedState “ befindet.

QLowEnergyController::RemoteAddressType QLowEnergyController::remoteAddressType() const

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

Siehe auch „ setRemoteAddressType()“.

QBluetoothUuid QLowEnergyController::remoteDeviceUuid() const

Gibt die eindeutige Kennung des entfernten Bluetooth-Low-Energy-Geräts zurück.

Unter macOS/iOS/tvOS stellt CoreBluetooth keine Hardware-Adressen für LE-Geräte bereit bzw. akzeptiert diese nicht; stattdessen sollen Entwickler eindeutige 128-Bit-UUIDs verwenden, die von CoreBluetooth generiert werden. Diese UUIDs bleiben für dasselbe Central-<->Peripheral-Paar konstant, und wir verwenden sie bei der Verbindung mit einem Remote-Gerät. Bei einem Controller im „ CentralRole “ entspricht dieser Wert immer dem Wert, der bei der Erstellung des Controller-Objekts übergeben wurde. Bei einem Controller im „ PeripheralRole “ ist dieser Wert ungültig.

QString QLowEnergyController::remoteName() const

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

void QLowEnergyController::requestConnectionUpdate(const QLowEnergyConnectionParameters &parameters)

Fordert den Controller auf, die Verbindung gemäß parameters zu aktualisieren. Ist die Anforderung 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 ausgewogene Priorität). Jede Kategorie beinhaltet einen vorkonfigurierten Wertesatz für „ QLowEnergyConnectionParameters::minimumInterval()“, „ QLowEnergyConnectionParameters::maximumInterval()“ und „ QLowEnergyConnectionParameters::latency()“. Obwohl die Verbindungsanfrage ein asynchroner Vorgang ist, stellt Android keinen Callback bereit, der das Ergebnis der Anfrage mitteilt. Dies ist ein bekannter 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 beim Erstellen einer Instanz von ` QLowEnergyController ` mithilfe von ` createCentral()` oder ` createPeripheral()` festgelegt.

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

Dieses Signal wird nach erfolgreichem Auslesen des RSSI (Received Signal Strength Indicator) für ein verbundenes Remote-Gerät ausgegeben. Der Parameter „ rssi “ gibt den neuen Wert an.

Diese Funktion wurde in Qt 6.5 eingeführt.

Siehe auch ` readRssi()`.

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

Dieses Signal wird jedes Mal gesendet, wenn ein neuer Dienst erkannt wird. Der Parameter „ newService “ enthält die UUID des gefundenen Dienstes.

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

Siehe auch „ discoverServices()“ und „ discoveryFinished()“.

QList<QBluetoothUuid> QLowEnergyController::services() const

Gibt die Liste der vom Remote-Gerät angebotenen Dienste zurück, sofern sich der Controller im Modus „ CentralRole “ befindet. Andernfalls ist das Ergebnis nicht definiert.

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 zum 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 lautet RandomAddress.

Siehe auch remoteAddressType().

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

Startet die Veröffentlichung der unter advertisingData und scanResponseData angegebenen Daten unter Verwendung der unter parameters festgelegten Parameter. Der Controller muss sich unter PeripheralRole befinden. Wenn unter parameters angegeben ist, dass die Veröffentlichung verbindungsfähig sein soll, beginnt diese Funktion außerdem, auf eingehende Client-Verbindungen zu warten.

Die Angabe von scanResponseData ist nicht erforderlich, da sie für bestimmte Konfigurationen von parameters nicht zutrifft. advertisingData und scanResponseData sind auf 31 Byte Nutzdaten begrenzt. Werden beispielsweise mehrere 128-Bit-UUIDs zu advertisingData hinzugefügt, enthalten die gesendeten Pakete möglicherweise nicht alle UUIDs. Die bestehende Beschränkung könnte zur Verkürzung von UUIDs geführt haben. In solchen Fällen kann scanResponseData für zusätzliche Informationen genutzt werden.

Beim BlueZ-DBus-Backend entscheidet BlueZ, ob und welche Daten in einer Scan-Antwort verwendet werden. Daher wird empfohlen, alle Advertisement-Daten im Hauptparameter „ advertisingData “ festzulegen. Sind sowohl Advertisement- als auch Scan-Antwortdaten festgelegt, haben die Scan-Antwortdaten Vorrang.

Befindet sich dieses Objekt derzeit nicht in der „ UnconnectedState “, geschieht nichts.

Siehe auch ` stopAdvertising()`.

QLowEnergyController::ControllerState QLowEnergyController::state() const

Gibt den aktuellen Status des Controllers zurück.

Siehe auch „ stateChanged()“.

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

Dieses Signal wird ausgelöst, wenn sich der Zustand des Controllers ändert. Der neue „ state “ kann auch über „ state()“ abgerufen werden.

Siehe auch state().

void QLowEnergyController::stopAdvertising()

Beendet die Anzeige, falls sich dieses Objekt derzeit im Anzeigestatus befindet.

Damit diese Funktion funktioniert, muss sich der Controller im „ PeripheralRole “ befinden. Sie macht Dienste, die zuvor über ` addService()` hinzugefügt wurden, nicht ungültig.

Siehe auch „ startAdvertising()“.