QLowEnergyController Class

Documentation des fonctions membres

[virtual noexcept] QLowEnergyController::~QLowEnergyController()

Détruit l'instance QLowEnergyController.

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

Construit et renvoie un objet QLowEnergyService avec parent à partir de service. Le contrôleur doit se trouver dans PeripheralRole et dans UnconnectedState. L'objet service doit être valide.

Voir également stopAdvertising(), disconnectFromDevice() et QLowEnergyServiceData::addIncludedService.

void QLowEnergyController::connectToDevice()

Se connecte à l'appareil Bluetooth Low Energy distant.

Cette fonction ne fait rien si le signal state() du contrôleur n'est pas égal à UnconnectedState. Le signal connected() est émis une fois que la connexion est établie avec succès.

Sur les systèmes Linux/BlueZ, il n'est pas possible de se connecter au même appareil distant en utilisant deux instances de cette classe. Le deuxième appel à cette fonction peut se solder par une erreur. Cette limitation pourrait être supprimée dans les prochaines versions.

Voir également disconnectFromDevice().

[signal] void QLowEnergyController::connected()

Ce signal est émis lorsque le contrôleur se connecte avec succès au dispositif à faible consommation d'énergie à distance (si le contrôleur se trouve sur le site CentralRole) ou si un dispositif à faible consommation d'énergie à distance s'est connecté au contrôleur (si le contrôleur se trouve sur le site PeripheralRole). Sur iOS, macOS et Android, ce signal n'est pas fiable si le contrôleur se trouve dans la zone PeripheralRole. Sur iOS et macOS, le contrôleur suppose seulement qu'une centrale s'est connectée à notre périphérique dès que cette centrale essaie d'écrire/de lire une caractéristique/un descripteur. Sous Android, le contrôleur surveille tous les dispositifs GATT connectés. Sur Linux BlueZ DBus peripheral backend, la télécommande est considérée comme connectée lorsqu'elle lit/écrit pour la première fois une caractéristique ou un descripteur.

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

Ce signal est émis lorsque les paramètres de la connexion changent. Cela peut se produire à la suite de l'appel à requestConnectionUpdate() ou pour d'autres raisons, par exemple parce que l'autre partie de la connexion a demandé de nouveaux paramètres. Les nouvelles valeurs peuvent être récupérées à partir de newParameters.

Voir aussi requestConnectionUpdate().

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

Renvoie un nouvel objet de cette classe qui se trouve dans CentralRole et dont l'objet parent est parent. Le remoteDevice fait référence à l'appareil avec lequel une connexion sera établie ultérieurement.

Le contrôleur utilise l'adaptateur Bluetooth local par défaut pour la gestion de la connexion.

Voir également QLowEnergyController::CentralRole.

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

Renvoie une nouvelle instance de cette classe avec parent.

Le site remoteDevice doit contenir l'adresse de l'appareil Bluetooth Low Energy distant auquel cet objet doit tenter de se connecter ultérieurement.

La connexion est établie via localDevice. Si localDevice n'est pas valide, l'appareil local par défaut est automatiquement sélectionné. Si localDevice spécifie un périphérique local qui n'est pas un adaptateur Bluetooth local, error() est remplacé par InvalidBluetoothAdapterError une fois que connectToDevice() est appelé.

Notez que la spécification du périphérique local à utiliser pour la connexion n'est possible qu'avec BlueZ. Toutes les autres plateformes ne prennent pas en charge cette fonctionnalité.

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

Renvoie un nouvel objet de cette classe qui se trouve dans PeripheralRole et qui a pour objet parent parent. En général, les étapes suivantes consistent à ajouter des services et à appeler startAdvertising() sur l'objet retourné.

Le contrôleur utilise l'adaptateur Bluetooth local par défaut pour la gestion de la connexion.

Voir également QLowEnergyController::PeripheralRole.

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

Renvoie un nouvel objet de cette classe qui se trouve dans la classe PeripheralRole et qui a pour objet parent parent et utilise localDevice. En général, les étapes suivantes consistent à ajouter des services et à appeler startAdvertising() sur l'objet retourné.

Le périphérique est créé sur localDevice. Si localDevice n'est pas valide, le périphérique local par défaut est automatiquement sélectionné. Si localDevice spécifie un périphérique local qui n'est pas un adaptateur Bluetooth local, error() est défini sur InvalidBluetoothAdapterError.

La sélection de localDevice n'est possible que sous Linux. Sur les autres plateformes, le paramètre est ignoré.

Cette fonction a été introduite dans Qt 6.2.

Voir aussi QLowEnergyController::PeripheralRole.

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

Crée une instance du service représenté par serviceUuid. Le paramètre serviceUuid doit avoir été obtenu via services().

L'appelant est propriétaire du pointeur retourné et peut passer un paramètre parent comme propriétaire par défaut.

Cette fonction renvoie un pointeur nul si aucun service avec serviceUuid ne peut être trouvé sur le dispositif distant ou si le contrôleur est déconnecté.

Cette fonction peut également renvoyer des instances pour des services secondaires. Les relations d'inclusion entre les services peuvent être exprimées via QLowEnergyService::includedServices().

Si cette fonction est appelée plusieurs fois en utilisant le même UUID de service, les instances QLowEnergyService renvoyées partagent leurs données internes. Par conséquent, si l'une des instances lance la découverte des détails du service, les autres instances passent automatiquement à l'état de découverte.

Voir aussi services().

void QLowEnergyController::disconnectFromDevice()

Se déconnecte de l'appareil distant.

Toute instance QLowEnergyService, QLowEnergyCharacteristic ou QLowEnergyDescriptor résultant de la connexion actuelle est automatiquement invalidée. Une fois que l'un de ces objets devient invalide, il le reste même si l'objet contrôleur se reconnecte.

Cette fonction ne fait rien si le contrôleur est dans le rôle UnconnectedState.

Si le contrôleur joue le rôle de périphérique, il cesse de faire de la publicité et supprime tous les services qui ont été ajoutés précédemment via addService(). Pour réutiliser l'instance QLowEnergyController, l'application doit ajouter à nouveau des services et redémarrer le mode de publicité en appelant startAdvertising().

Voir également connectToDevice().

[signal] void QLowEnergyController::disconnected()

Ce signal est émis lorsque le contrôleur se déconnecte du dispositif à faible consommation d'énergie distant ou vice versa. Sur iOS et macOS, ce signal n'est pas fiable si le contrôleur se trouve sur le site PeripheralRole. Sur Android, le signal est émis lorsque le dernier appareil connecté est déconnecté. Sur le backend BlueZ DBus, le contrôleur est considéré comme déconnecté lorsque le dernier client ayant accédé aux attributs s'est déconnecté.

void QLowEnergyController::discoverServices()

Lance le processus de découverte du service.

La progression de la découverte est indiquée par le signal serviceDiscovered(). Le signal discoveryFinished() est émis lorsque le processus est terminé.

Si l'instance de contrôleur n'est pas connectée ou si le contrôleur a déjà effectué la découverte de services, cette fonction ne fera rien.

[signal] void QLowEnergyController::discoveryFinished()

Ce signal est émis lorsque la découverte du service en cours se termine. Le signal n'est pas émis si le processus de découverte se termine par une erreur.

Ce signal ne peut être émis que si le contrôleur se trouve dans la page CentralRole.

Voir également discoverServices() et error().

QLowEnergyController::Error QLowEnergyController::error() const

Renvoie la dernière erreur survenue ou NoError.

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

Ce signal est émis lorsqu'une erreur se produit. Le paramètre newError décrit l'erreur qui s'est produite.

Cette fonction a été introduite dans Qt 6.2.

Voir aussi error() et errorString().

QString QLowEnergyController::errorString() const

Renvoie une représentation textuelle de la dernière erreur survenue. La chaîne est traduite.

QBluetoothAddress QLowEnergyController::localAddress() const

Renvoie l'adresse de l'adaptateur Bluetooth local utilisé pour la communication.

Si l'on a demandé à cette instance de classe d'utiliser l'adaptateur par défaut mais qu'il n'y avait pas d'adaptateur par défaut lors de la création de cette instance de classe, l'adresse QBluetoothAddress renvoyée sera nulle.

Voir aussi QBluetoothAddress::isNull().

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

Renvoie la taille du MTU.

Lors de l'établissement de la connexion, la taille du MTU ATT est négociée. Cette méthode fournit le résultat de cette négociation. Elle peut être utilisée pour optimiser la taille des paquets dans certaines situations. La quantité maximale de données pouvant être transférées dans un seul paquet est mtu-3 octets. 3 octets sont nécessaires pour l'en-tête du protocole ATT.

Avant l'établissement de la connexion et la négociation du MTU, la valeur par défaut de 23 sera renvoyée.

Toutes les plateformes n'affichent pas la valeur du MTU. Sur ces plates-formes (par exemple Linux), cette fonction renvoie toujours -1.

Si le contrôleur se trouve sur le site PeripheralRole, il se peut que plusieurs dispositifs centraux y soient connectés. Dans ce cas, cette fonction renvoie le MTU de la dernière connexion négociée.

Cette fonction a été introduite dans Qt 6.2.

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

Ce signal est émis à la suite d'une modification réussie du MTU. mtu représente la nouvelle valeur.

Voir également mtu().

[since 6.5] void QLowEnergyController::readRssi()

readRssi() lit le RSSI (indicateur de puissance du signal reçu) d'un appareil distant connecté. Si la lecture a réussi, le RSSI est alors signalé par le signal rssiRead().

Cette fonction a été introduite dans Qt 6.5.

Voir aussi rssiRead(), connectToDevice(), state(), createCentral() et errorOccurred().

QBluetoothAddress QLowEnergyController::remoteAddress() const

Renvoie l'adresse du dispositif Bluetooth Low Energy distant.

Pour un contrôleur dans CentralRole, cette valeur sera toujours celle qui a été transmise lors de la création de l'objet contrôleur. Pour un contrôleur sur le site PeripheralRole, cette valeur est l'une des adresses des appareils clients actuellement connectés. Cette adresse n'est pas valide si le contrôleur ne se trouve pas actuellement sur le site ConnectedState.

QLowEnergyController::RemoteAddressType QLowEnergyController::remoteAddressType() const

Renvoie le type de remoteAddress(). Par défaut, cette valeur est initialisée à PublicAddress.

Voir aussi setRemoteAddressType().

QBluetoothUuid QLowEnergyController::remoteDeviceUuid() const

Renvoie l'identifiant unique du périphérique Bluetooth Low Energy distant.

Sur macOS/iOS/tvOS CoreBluetooth n'expose pas/accepte les adresses matérielles pour les périphériques LE ; à la place les développeurs sont supposés utiliser des UUIDs uniques de 128 bits, générés par CoreBluetooth. Ces UUIDS resteront constants pour la même paire centrale <-> périphérique et nous les utilisons lorsque nous nous connectons à un périphérique distant. Pour un contrôleur dans le site CentralRole, cette valeur sera toujours celle passée lors de la création de l'objet contrôleur. Pour un contrôleur dans PeripheralRole, cette valeur est invalide.

QString QLowEnergyController::remoteName() const

Renvoie le nom de l'appareil Bluetooth Low Energy distant, si le contrôleur se trouve sur le site CentralRole. Dans le cas contraire, le résultat n'est pas spécifié.

void QLowEnergyController::requestConnectionUpdate(const QLowEnergyConnectionParameters &parameters)

Demande au contrôleur de mettre à jour la connexion conformément à parameters. Si la demande aboutit, le signal connectionUpdated() est émis avec les nouveaux paramètres actuels. Voir la classe QLowEnergyConnectionParameters pour plus d'informations sur les paramètres de connexion.

Android ne permet qu'indirectement d'ajuster cet ensemble de paramètres. Les paramètres de connexion sont répartis en trois catégories (priorité élevée, faible et équilibrée). Chaque catégorie implique un ensemble préconfiguré de valeurs pour QLowEnergyConnectionParameters::minimumInterval(), QLowEnergyConnectionParameters::maximumInterval() et QLowEnergyConnectionParameters::latency(). Bien que la demande de connexion soit une opération asynchrone, Android ne fournit pas de rappel indiquant le résultat de la demande. Il s'agit d'un bogue reconnu d'Android. En raison de ce bogue, Android n'émet pas le signal connectionUpdated().

Voir aussi connectionUpdated().

QLowEnergyController::Role QLowEnergyController::role() const

Renvoie le rôle de cet objet contrôleur.

Le rôle est déterminé lors de la construction d'une instance QLowEnergyController à l'aide de createCentral() ou createPeripheral().

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

Ce signal est émis après la lecture réussie du RSSI (indicateur de puissance du signal reçu) pour un appareil distant connecté. Le paramètre rssi représente la nouvelle valeur.

Cette fonction a été introduite dans Qt 6.5.

Voir aussi readRssi().

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

Ce signal est émis chaque fois qu'un nouveau service est découvert. Le paramètre newService contient l'UUID du service découvert.

Ce signal ne peut être émis que si le contrôleur se trouve dans la zone CentralRole.

Voir également discoverServices() et discoveryFinished().

QList<QBluetoothUuid> QLowEnergyController::services() const

Renvoie la liste des services offerts par le dispositif distant, si le contrôleur se trouve sur le site CentralRole. Dans le cas contraire, le résultat n'est pas spécifié.

La liste contient tous les services primaires et secondaires.

Voir également createServiceObject().

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

Définit l'adresse distante type. Le type est nécessaire pour se connecter à l'appareil Bluetooth Low Energy distant.

Cet attribut ne doit être défini que sur les systèmes Linux/BlueZ dotés d'anciens noyaux Linux (v3.3 ou inférieurs), ou si CAP_NET_ADMIN n'est pas défini pour l'exécutable. La valeur par défaut de l'attribut est RandomAddress.

Voir aussi remoteAddressType().

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

Démarre la publicité des données fournies dans advertisingData et scanResponseData, en utilisant les paramètres définis dans parameters. Le contrôleur doit se trouver sur le site PeripheralRole. Si parameters indique que l'annonce doit être connectable, cette fonction commence également à écouter les connexions entrantes des clients.

Il n'est pas nécessaire de fournir scanResponseData, car cela ne s'applique pas à certaines configurations de parameters. advertisingData et scanResponseData sont limités à 31 octets de données utilisateur. Si, par exemple, plusieurs uuids de 128 bits sont ajoutés à advertisingData, les paquets annoncés peuvent ne pas contenir tous les uuids. La limite existante peut avoir causé la troncature des uuids. Dans ce cas, scanResponseData peut être utilisé pour obtenir des informations supplémentaires.

Sur le backend BlueZ DBus, BlueZ décide si, et quelles données, il faut utiliser dans une réponse de balayage. Par conséquent, il est recommandé de définir toutes les données d'annonce dans le paramètre principal advertisingData. Si des données d'annonce et de réponse au balayage sont définies, les données de réponse au balayage sont prioritaires.

Si cet objet ne se trouve pas actuellement dans UnconnectedState, rien ne se produit.

Voir également stopAdvertising().

QLowEnergyController::ControllerState QLowEnergyController::state() const

Renvoie l'état actuel du contrôleur.

Voir aussi stateChanged().

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

Ce signal est émis lorsque l'état du contrôleur change. Le nouveau state peut également être récupéré via state().

Voir aussi state().

void QLowEnergyController::stopAdvertising()

Arrête la publicité si cet objet est actuellement dans l'état de publicité.

Le contrôleur doit se trouver sur le site PeripheralRole pour que cette fonction fonctionne. Elle n'invalide pas les services qui ont été ajoutés précédemment via addService().

Voir également startAdvertising().