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());

Documentation des fonctions membres

[virtual noexcept] QLowEnergyService::~QLowEnergyService()

Supprime l'instance de ` QLowEnergyService `.

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

Renvoie la caractéristique correspondante pour uuid; sinon, une caractéristique non valide.

La caractéristique renvoyée n'est pas valide si la méthode discoverDetails() de cette instance de service n'a pas encore été appelée ou s'il n'existe aucune caractéristique correspondant à uuid.

Voir également characteristics().

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

Si l'objet contrôleur associé occupe le rôle « central », ce signal est émis lorsque la valeur de « characteristic » est modifiée par un événement du côté du périphérique. Dans ce cas, l'émission du signal implique que les notifications de modification doivent avoir été activées via le descripteur « ClientCharacteristicConfiguration » de la caractéristique avant l'événement de modification sur le périphérique. Vous trouverez plus de détails sur la manière de procéder à l’ above.

Si le contrôleur occupe le rôle d’ peripheral, c’est-à-dire si l’objet de service a été créé via QLowEnergyController::addService, le signal est émis lorsqu’un client GATT a écrit la valeur de la caractéristique à l’aide d’une requête d’écriture ou d’une commande.

Le paramètre « newValue » contient la valeur mise à jour de la caractéristique characteristic.

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

Ce signal est émis lorsque la requête de lecture concernant characteristic a renvoyé avec succès son value. Le signal peut être déclenché par l'appel de la fonction characteristicRead(). Si l'opération de lecture échoue, le signal errorOccurred() est émis à l'aide du drapeau CharacteristicReadError.

Voir également readCharacteristic().

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

Ce signal est émis lorsque la valeur de ` characteristic ` a été modifiée avec succès pour passer à ` newValue`. La modification doit avoir été déclenchée par l'appel de la fonction ` writeCharacteristic()`. Si l'opération d'écriture échoue, le signal ` errorOccurred()` est émis à l'aide du drapeau ` CharacteristicWriteError `.

La réception du signal « written » peut être considérée comme un signe indiquant que le périphérique cible a bien reçu la valeur à écrire et renvoie l’état de la requête d’écriture.

Voir également writeCharacteristic().

QList<QLowEnergyCharacteristic> QLowEnergyService::characteristics() const

Renvoie toutes les caractéristiques associées à cette instance de service « QLowEnergyService ».

La liste renvoyée est vide si la méthode ` discoverDetails()` de cette instance de service n'a pas encore été appelée ou s'il n'existe aucune caractéristique connue.

Voir également characteristic(), state() et discoverDetails().

bool QLowEnergyService::contains(const QLowEnergyCharacteristic &characteristic) const

Renvoie ` true ` si ` characteristic ` appartient à ce service ; sinon, renvoie ` false`.

Une caractéristique appartient à un service si characteristics() contient characteristic.

bool QLowEnergyService::contains(const QLowEnergyDescriptor &descriptor) const

Renvoie ` true ` si ` descriptor ` appartient à ce service ; sinon, renvoie ` false`.

[signal] void QLowEnergyService::descriptorRead(const QLowEnergyDescriptor &descriptor, const QByteArray &value)

Ce signal est émis lorsque la requête de lecture concernant descriptor a renvoyé avec succès son value. Le signal peut être déclenché par l'appel à la fonction descriptorRead(). Si l'opération de lecture échoue, le signal errorOccurred() est émis à l'aide du drapeau DescriptorReadError.

Voir également readDescriptor().

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

Ce signal est émis lorsque la valeur de ` descriptor ` a été modifiée avec succès et remplace désormais ` newValue`. Si l'objet contrôleur associé occupe le rôle « central », cette modification doit avoir été provoquée par l'appel de la fonction ` writeDescriptor()`. Dans le cas contraire, le signal résulte d'une requête d'écriture ou d'une commande émise par un client GATT vers le descripteur correspondant.

Voir également writeDescriptor().

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

Lance la découverte des services inclus dans le service, de leurs caractéristiques et des descripteurs qui leur sont associés.

Le processus de découverte est signalé par le signal « stateChanged » (). Une fois créé, le service se trouve dans l’état « DiscoveryRequired ». Lors de l’appel de la méthode discoverDetails(), il passe à l’état « DiscoveringService ». Une fois la découverte des détails terminée, il passe à l’état « ServiceDiscovered ». À chaque transition, le signal « stateChanged » () est émis. En fonction de l’argument « mode », une « FullDiscovery » ou une « SkipValueDiscovery » est effectuée. Dans tous les cas, l’ensemble des services et des caractéristiques est découvert. Une « FullDiscovery » procède à la lecture de toutes les valeurs de caractéristiques et de tous les descripteurs. Une « SkipValueDiscovery » ne lit ni les valeurs de caractéristiques ni les descripteurs. Une « SkipValueDiscovery » présente deux avantages. Premièrement, elle est plus rapide. Deuxièmement, elle contourne les bogues présents sur certains appareils qui signalent à tort que des caractéristiques ou des descripteurs sont lisibles, mais qui n’autorisent pourtant pas leur lecture. Cela peut entraîner un comportement imprévisible. Après une opération « SkipValueDiscovery », il est nécessaire d’appeler « readCharacteristic() » / « readDescriptor() » et d’attendre qu’elles se terminent avec succès avant d’accéder à la valeur d’une caractéristique ou d’un descripteur.

L’argument mode a été introduit dans Qt 6.2.

Voir également state().

QLowEnergyService::ServiceError QLowEnergyService::error() const

Renvoie la dernière erreur survenue ou l'NoError.

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

QList<QBluetoothUuid> QLowEnergyService::includedServices() const

Renvoie les UUID de tous les services inclus par le service actuel.

La liste renvoyée est vide si la méthode discoverDetails() de cette instance de service n'a pas encore été appelée ou s'il n'existe aucune caractéristique connue.

Il est possible qu’un service inclus contienne lui-même un autre service. Ces inclusions de deuxième niveau doivent être obtenues via l’instance correspondante de la méthode ` QLowEnergyService ` de premier niveau. Techniquement, cela pourrait créer une dépendance circulaire.

QLowEnergyController::createServiceObjectLa méthode () doit être utilisée pour obtenir les instances de service correspondant à chacun des UUID.

Voir également createServiceObject().

void QLowEnergyService::readCharacteristic(const QLowEnergyCharacteristic &characteristic)

Lit la valeur de l’ characteristic. Si l’opération aboutit, le signal characteristicRead() est émis ; dans le cas contraire, le signal CharacteristicReadError est activé. En général, un characteristic est accessible en lecture si sa propriété QLowEnergyCharacteristic::Read est activée.

Toutes les requêtes de descripteurs et de caractéristiques adressées au même périphérique distant sont sérialisées. Une file d’attente est utilisée lors de l’émission de plusieurs requêtes simultanées. La file d’attente n’élimine pas les requêtes de lecture en double pour une même caractéristique.

Une caractéristique ne peut être lue que si le service est à l’état « ServiceDiscovered » et si elle appartient à ce service. Si l’une de ces conditions n’est pas remplie, la valeur « QLowEnergyService::OperationError » est définie.

Voir également characteristicRead() et writeCharacteristic().

void QLowEnergyService::readDescriptor(const QLowEnergyDescriptor &descriptor)

Lit la valeur d'descriptor. Si l'opération aboutit, le signal descriptorRead() est émis ; dans le cas contraire, l'DescriptorReadError est activée.

Toutes les requêtes de descripteurs et de caractéristiques adressées au même périphérique distant sont sérialisées. Une file d’attente est utilisée lorsque plusieurs requêtes sont émises simultanément. La file d’attente n’élimine pas les requêtes de lecture en double pour un même descripteur.

Un descripteur ne peut être lu que si le service est dans l’état « ServiceDiscovered » et si le descripteur appartient à ce service. Si l’une de ces conditions n’est pas remplie, l’ QLowEnergyService::OperationError est activé.

Voir également descriptorRead() et writeDescriptor().

QString QLowEnergyService::serviceName() const

Renvoie le nom du service ; sinon, une chaîne vide.

Le nom renvoyé ne peut être récupéré que si serviceUuid() est un UUID bien connu.

QBluetoothUuid QLowEnergyService::serviceUuid() const

Renvoie l'UUID du service ; sinon, un UUID nul.

QLowEnergyService::ServiceState QLowEnergyService::state() const

Renvoie l'état actuel du service.

Si le service de l'appareil a été instancié pour la première fois, l'état de l'objet est « DiscoveryRequired ». L'état de tous les objets de service qui pointent vers le même service sur le périphérique est toujours identique. Cela est dû à la nature partagée des données internes de l'objet. Par conséquent, toute instance d'objet de service créée après la première a un état identique à celui des instances déjà existantes.

Un service devient invalide si l’ QLowEnergyController se déconnecte du périphérique distant. Un service invalide conserve son état interne au moment de la déconnexion. Cela implique qu’une fois les détails du service découverts, ceux-ci peuvent même être récupérés à partir d’un service invalide. Cela permet des scénarios dans lesquels la connexion au périphérique est établie, les détails du service sont récupérés, puis le périphérique est immédiatement déconnecté pour permettre au périphérique suivant de se connecter.

Toutefois, dans des circonstances normales, la connexion doit rester active afin d’éviter une découverte répétée des services et de leurs détails. La découverte peut prendre un certain temps et le client peut s’abonner à des notifications de modification en continu.

Voir également stateChanged().

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

Ce signal est émis lorsque l'état du service change. L'newState e peut également être récupérée via la fonction state().

Voir également state().

QLowEnergyService::ServiceTypes QLowEnergyService::type() const

Renvoie le type du service.

void QLowEnergyService::writeCharacteristic(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue, QLowEnergyService::WriteMode mode = WriteWithResponse)

Écrit « newValue » comme valeur de l'characteristic. La sémantique exacte dépend du rôle dans lequel se trouve l'objet contrôleur associé.

Rôle central

L'appel entraîne une requête d'écriture ou une commande vers un périphérique distant. Si l'opération aboutit, le signal « characteristicWritten » () est émis ; dans le cas contraire, le paramètre « CharacteristicWriteError » est défini. L'appel de cette fonction ne déclenche pas le signal « characteristicChanged » () à moins que le périphérique lui-même ne modifie à nouveau la valeur après la requête d'écriture en cours.

Le paramètre ` mode ` détermine si le périphérique distant doit envoyer une confirmation d’écriture. La caractéristique ` characteristic ` à écrire doit prendre en charge le mode d’écriture concerné. Les modes d’écriture pris en charge par la caractéristique sont indiqués par ses propriétés ` QLowEnergyCharacteristic::Write ` et ` QLowEnergyCharacteristic::WriteNoResponse `.

Toutes les requêtes d’écriture de descripteurs et de caractéristiques destinées au même périphérique distant sont sérialisées. Une file d’attente est utilisée lorsque plusieurs requêtes d’écriture sont émises simultanément. La file d’attente n’élimine pas les requêtes d’écriture en double pour une même caractéristique. Par exemple, si un même descripteur est défini sur la valeur A puis immédiatement après sur la valeur B, les deux requêtes d’écriture sont exécutées dans l’ordre indiqué.

Une caractéristique ne peut être écrite que si ce service est à l’état « ServiceDiscovered » et appartient au service. Si l’une de ces conditions n’est pas remplie, l’ QLowEnergyService::OperationError est défini.

Rôle du périphérique

L’appel entraîne la mise à jour de la valeur de la caractéristique dans la base de données locale.

Si un client est actuellement connecté et qu’il a activé les notifications ou les indications pour cette caractéristique, les informations correspondantes seront envoyées. Si un appareil a activé les notifications ou les indications pour cette caractéristique et que cet appareil n’est actuellement pas connecté, mais qu’une liaison existe entre lui et l’appareil local, alors la notification ou l’indication sera envoyée lors de la prochaine reconnexion.

S’il existe une contrainte sur la longueur de la valeur de la caractéristique et que l’ newValue e ne respecte pas cette contrainte, le comportement n’est pas spécifié.

Voir également ` QLowEnergyService::characteristicWritten()` et ` QLowEnergyService::readCharacteristic()`.

void QLowEnergyService::writeDescriptor(const QLowEnergyDescriptor &descriptor, const QByteArray &newValue)

Écrit « newValue » comme valeur de « descriptor ». La sémantique exacte dépend du rôle dans lequel se trouve l'objet contrôleur associé.

Rôle central

Un appel à cette fonction entraîne une requête d’écriture vers le périphérique distant. Si l’opération aboutit, le signal descriptorWritten() est émis ; dans le cas contraire, le signal DescriptorWriteError est émis.

Toutes les requêtes de descripteurs et de caractéristiques adressées au même périphérique distant sont sérialisées. Une file d’attente est utilisée lors de l’émission simultanée de plusieurs requêtes d’écriture. La file d’attente n’élimine pas les requêtes d’écriture en double pour un même descripteur. Par exemple, si un même descripteur est défini sur la valeur A puis immédiatement après sur la valeur B, les deux requêtes d’écriture sont exécutées dans l’ordre indiqué.

Un descripteur ne peut être modifié que si ce service est à l’état « ServiceDiscovered » et appartient au service. Si l’une de ces conditions n’est pas remplie, l’ QLowEnergyService::OperationError est activé.

Rôle du périphérique

La valeur est écrite dans la base de données locale du service. Si le contenu de ` newValue ` n’est pas valide pour ` descriptor`, le comportement n’est pas spécifié.

Voir également descriptorWritten() et readDescriptor().