QLowEnergyController Class

Documentation sur les fonctions membres

[virtual noexcept] QLowEnergyController::~QLowEnergyController()

Supprime l'instance de ` QLowEnergyController `.

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

Crée et renvoie un objet ` QLowEnergyService ` avec l’ parent provenant de service. Le contrôleur doit se trouver dans le répertoire PeripheralRole et dans le répertoire 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 la valeur de la méthode ` state()` du contrôleur n'est pas égale à ` UnconnectedState`. Le signal ` connected()` est émis une fois la connexion établie avec succès.

Sur les systèmes Linux/BlueZ, il n’est pas possible de se connecter au même périphérique distant à l’aide de deux instances de cette classe. Le deuxième appel à cette fonction peut échouer et générer une erreur. Cette limitation pourrait être supprimée dans de futures versions.

Voir également disconnectFromDevice().

[signal] void QLowEnergyController::connected()

Ce signal est émis lorsque le contrôleur se connecte avec succès à un périphérique LoE distant (si le contrôleur se trouve en mode « CentralRole ») ou lorsqu’un périphérique LoE distant se connecte au contrôleur (si le contrôleur se trouve en mode « PeripheralRole »). Sous iOS, macOS et Android, ce signal n’est pas fiable si le contrôleur se trouve en mode « PeripheralRole ». Sous iOS et macOS, le contrôleur suppose simplement qu’un périphérique central est connecté à notre périphérique dès que ce périphérique central tente d’écrire ou de lire une caractéristique ou un descripteur. Sous Android, le contrôleur surveille tous les périphériques GATT connectés. Sur le backend périphérique DBus BlueZ sous Linux, la télécommande est considérée comme connectée dès qu’elle lit ou é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 connexion changent. Cela peut se produire à la suite de l'appel de la fonction ` requestConnectionUpdate()` ou pour d'autres raisons, par exemple parce que l'autre extrémité de la connexion a demandé de nouveaux paramètres. Les nouvelles valeurs peuvent être récupérées via ` newParameters`.

Voir également requestConnectionUpdate().

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

Renvoie un nouvel objet de cette classe qui se trouve dans l'CentralRole et dont l'objet parent est parent. L'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 l'parent.

L'remoteDevice doit contenir l'adresse du périphérique 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, 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 ` 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. Les autres plateformes ne prennent pas en charge cette fonctionnalité.

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

Renvoie un nouvel objet de cette classe appartenant à l'PeripheralRole et dont l'objet parent est parent. En général, les étapes suivantes consistent à ajouter des services, puis à appeler la méthode startAdvertising() sur l'objet renvoyé.

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 l'PeripheralRole, dont l'objet parent est parent et qui utilise localDevice. En général, les étapes suivantes consistent à ajouter des services, puis à appeler startAdvertising() sur l'objet renvoyé.

Le périphérique est créé via ` 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 prise en charge que sous Linux. Sur les autres plateformes, ce paramètre est ignoré.

Cette fonction a été introduite dans Qt 6.2.

Voir également 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 la fonction services().

L'appelant prend possession du pointeur renvoyé et peut transmettre un paramètre parent en tant que propriétaire par défaut.

Cette fonction renvoie un pointeur nul si aucun service associé à serviceUuid n’est trouvé sur le périphérique distant ou si le contrôleur est déconnecté.

Cette fonction peut également renvoyer des instances de 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 elles aussi.

Voir également services().

void QLowEnergyController::disconnectFromDevice()

Se déconnecte de l'appareil distant.

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

Cette fonction n'a aucun effet si le contrôleur se trouve dans l'état « UnconnectedState ».

Si le contrôleur occupe le rôle de périphérique, il cesse de diffuser et supprime tous les services qui avaient été précédemment ajoutés via addService(). Pour réutiliser l’instance QLowEnergyController, l’application doit rajouter les services et relancer le mode de diffusion en appelant startAdvertising().

Voir également connectToDevice().

[signal] void QLowEnergyController::disconnected()

Ce signal est émis lorsque le contrôleur se déconnecte de l'appareil LoE distant, ou inversement. Sous iOS et macOS, ce signal n'est pas fiable si le contrôleur se trouve en mode « PeripheralRole ». Sous Android, le signal est émis lorsque le dernier appareil connecté se déconnecte. Sur le backend BlueZ DBus, le contrôleur est considéré comme déconnecté lorsque le dernier client ayant accédé à ses attributs s'est déconnecté.

void QLowEnergyController::discoverServices()

Lance le processus de découverte des services.

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

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

[signal] void QLowEnergyController::discoveryFinished()

Ce signal est émis lorsque la découverte des services en cours s'achève. 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 l'état « CentralRole ».

Voir également discoverServices() et error().

QLowEnergyController::Error QLowEnergyController::error() const

Renvoie la dernière erreur survenue ou la valeur « 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 également error() et errorString().

QString QLowEnergyController::errorString() const

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

QBluetoothAddress QLowEnergyController::localAddress() const

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

Si cette instance de classe a reçu pour instruction d’utiliser l’adaptateur par défaut, mais qu’aucun adaptateur par défaut n’était disponible lors de la création de cette instance, la valeur renvoyée par QBluetoothAddress sera nulle.

Voir également QBluetoothAddress::isNull().

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

Renvoie la taille de la MTU.

Lors de l'établissement de la connexion, la taille de la 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ée dans un seul paquet est de 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 de la MTU, la valeur par défaut 23 est renvoyée.

Toutes les plateformes n’exposent pas la valeur MTU. Sur ces plateformes (par exemple Linux), cette fonction renvoie toujours -1.

Si le contrôleur se trouve dans l’ PeripheralRole, plusieurs périphériques centraux peuvent y être connectés. Dans ce cas, cette fonction renvoie la 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 de la MTU. « mtu » correspond à la nouvelle valeur.

Voir également mtu().

[since 6.5] void QLowEnergyController::readRssi()

La fonction readRssi() lit la valeur RSSI (indicateur d'intensité du signal reçu) d'un périphérique distant connecté. Si la lecture a réussi, la valeur RSSI est ensuite renvoyée par le signal rssiRead().

Cette fonction a été introduite dans Qt 6.5.

Voir également rssiRead(), connectToDevice(), state(), createCentral() et errorOccurred().

QBluetoothAddress QLowEnergyController::remoteAddress() const

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

Pour un contrôleur de l’ CentralRole, cette valeur sera toujours celle transmise lors de la création de l’objet contrôleur. Pour un contrôleur de l’ PeripheralRole, cette valeur correspond à l’une des adresses des périphériques clients actuellement connectés. Cette adresse sera invalide si le contrôleur ne se trouve pas actuellement dans l’ ConnectedState.

QLowEnergyController::RemoteAddressType QLowEnergyController::remoteAddressType() const

Renvoie le type de la fonction ` 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.

Sous macOS/iOS/tvOS, CoreBluetooth n'expose ni n'accepte les adresses matérielles des périphériques LE ; les développeurs sont plutôt censés utiliser des UUID uniques de 128 bits, générés par CoreBluetooth. Ces UUID restent constants pour une même paire centrale <-> périphérique et nous les utilisons lors de la connexion à un périphérique distant. Pour un contrôleur de type « CentralRole », cette valeur sera toujours celle transmise lors de la création de l’objet contrôleur. Pour un contrôleur de type « PeripheralRole », cette valeur n’est pas valide.

QString QLowEnergyController::remoteName() const

Renvoie le nom du périphérique Bluetooth Low Energy distant, si le contrôleur se trouve dans l’ CentralRole. Dans le cas contraire, le résultat n’est pas défini.

void QLowEnergyController::requestConnectionUpdate(const QLowEnergyConnectionParameters &parameters)

Demande au contrôleur de mettre à jour la connexion conformément à parameters. Si la requête aboutit, le signal connectionUpdated() sera émis avec les nouveaux paramètres effectifs. Consultez la classe QLowEnergyConnectionParameters pour plus d'informations sur les paramètres de connexion.

Android n'autorise qu'indirectement la modification de 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 de valeurs préconfigurées pour les méthodes ` QLowEnergyConnectionParameters::minimumInterval()`, ` QLowEnergyConnectionParameters::maximumInterval()` et ` QLowEnergyConnectionParameters::latency()`. Bien que la requête de connexion soit une opération asynchrone, Android ne fournit pas de rappel indiquant le résultat de la requête. Il s’agit d’un bug reconnu d’Android. En raison de ce bug, Android n’émet pas le signal ` connectionUpdated()`.

Voir également ` connectionUpdated()`.

QLowEnergyController::Role QLowEnergyController::role() const

Renvoie le rôle associé à cet objet contrôleur.

Le rôle est déterminé lors de la création d'une instance de ` 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 de la valeur RSSI (indicateur d'intensité du signal reçu) d'un périphérique distant connecté. Le paramètre ` rssi ` représente la nouvelle valeur.

Cette fonction a été introduite dans Qt 6.5.

Voir également readRssi().

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

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

Ce signal ne peut être émis que si le contrôleur se trouve dans l'état « CentralRole ».

Voir également discoverServices() et discoveryFinished().

QList<QBluetoothUuid> QLowEnergyController::services() const

Renvoie la liste des services proposés par le périphérique distant, si le contrôleur se trouve dans l'CentralRole. Dans le cas contraire, le résultat n'est pas défini.

La liste contient tous les services principaux et secondaires.

Voir également createServiceObject().

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

Définit l'adresse distante type. Ce type est obligatoire pour se connecter au périphérique Bluetooth Low Energy distant.

Cet attribut ne doit être défini que sur les systèmes Linux/BlueZ équipés de noyaux Linux plus anciens (v3.3 ou antérieure), ou si le droit CAP_NET_ADMIN n’est pas attribué à l’exécutable. La valeur par défaut de cet attribut est RandomAddress.

Voir également remoteAddressType().

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

Lance la diffusion des données fournies dans advertisingData et scanResponseData, en utilisant les paramètres définis dans parameters. Le contrôleur doit se trouver dans le répertoire PeripheralRole. Si parameters indique que la diffusion doit être accessible, cette fonction se met é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 UUID de 128 bits sont ajoutés à advertisingData, les paquets diffusés peuvent ne pas contenir tous les UUID. La limite existante a peut-être entraîné la troncature des UUID. Dans ce cas, scanResponseData peut être utilisé pour obtenir des informations supplémentaires.

Sur le backend DBus de BlueZ, c’est BlueZ qui décide si des données doivent être utilisées dans une réponse de scan, et lesquelles. Il est donc recommandé de définir toutes les données de publication dans le paramètre principal advertisingData. Si des données de publication et de réponse de scan sont toutes deux définies, la priorité est donnée aux données de réponse de scan.

Si cet objet ne figure pas actuellement dans l’ UnconnectedState, rien ne se passe.

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. La nouvelle state peut également être récupérée via la fonction state().

Voir également state().

void QLowEnergyController::stopAdvertising()

Arrête la diffusion, si cet objet est actuellement en état de diffusion.

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

Voir également startAdvertising().