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

Détruit l'instance 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 fonction 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é joue le rôle de 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 changement doivent avoir été activées via le descripteur ClientCharacteristicConfiguration de la caractéristique avant l'événement de changement sur le périphérique. Pour plus de détails sur la manière de procéder, voir above.

Si le contrôleur joue le rôle de peripheral, c'est-à-dire que 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 demande ou d'une commande d'écriture.

Le paramètre newValue contient la valeur actualisée de la caractéristique characteristic.

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

Ce signal est émis lorsque la demande de lecture de characteristic a renvoyé avec succès son value. Le signal peut être déclenché par l'appel de characteristicRead(). Si l'opération de lecture n'aboutit pas, le signal errorOccurred() est émis en utilisant l'indicateur CharacteristicReadError.

Voir également readCharacteristic().

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

Ce signal est émis lorsque la valeur de characteristic est modifiée avec succès en newValue. La modification doit avoir été déclenchée par l'appel à writeCharacteristic(). Si l'opération d'écriture n'aboutit pas, le signal errorOccurred() est émis en utilisant l'indicateur CharacteristicWriteError.

La réception du signal d'écriture peut être considérée comme un signe que le dispositif cible a reçu la valeur à écrire et renvoie l'état de la demande d'écriture.

Voir aussi writeCharacteristic().

QList<QLowEnergyCharacteristic> QLowEnergyService::characteristics() const

Renvoie toutes les caractéristiques associées à cette instance QLowEnergyService.

La liste renvoyée est vide si la fonction discoverDetails() de cette instance de service n'a pas encore été appelée ou s'il n'y a pas de caractéristiques connues.

Voir aussi characteristic(), state() et discoverDetails().

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

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

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

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

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

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

Ce signal est émis lorsque la demande de lecture de descriptor a renvoyé avec succès son value. Le signal peut être déclenché en appelant le descripteurRead(). Si l'opération de lecture n'aboutit pas, le signal errorOccurred() est émis en utilisant l'indicateur DescriptorReadError.

Voir également readDescriptor().

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

Ce signal est émis lorsque la valeur de descriptor est modifiée avec succès en newValue. Si l'objet contrôleur associé joue le rôle de central, la modification doit avoir été provoquée par l'appel à writeDescriptor(). Sinon, le signal est le résultat d'une demande ou d'une commande d'écriture d'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, des caractéristiques et des descripteurs associés.

Le processus de découverte est indiqué par le signal stateChanged(). Après sa création, le service est dans l'état DiscoveryRequired. Lorsqu'il appelle 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, un FullDiscovery ou un SkipValueDiscovery est exécuté. Dans tous les cas, tous les services et caractéristiques sont découverts. Un FullDiscovery procède à la lecture de toutes les valeurs de caractéristique et de tous les descripteurs. Un SkipValueDiscovery ne lit pas les valeurs de caractéristiques et les descripteurs. Un SkipValueDiscovery présente deux avantages. Premièrement, il est plus rapide. Deuxièmement, il contourne les bogues de certains appareils qui annoncent à tort que les caractéristiques ou les descripteurs sont lisibles, mais qui n'autorisent pas la lecture sur ces derniers. Cela peut entraîner un comportement imprévisible. Après un SkipValueDiscovery, il est nécessaire d'appeler readCharacteristic() / readDescriptor() et d'attendre qu'ils 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 aussi state().

QLowEnergyService::ServiceError QLowEnergyService::error() const

Renvoie la dernière erreur survenue ou 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 qui sont inclus dans le service actuel.

La liste renvoyée est vide si la fonction discoverDetails() de cette instance de service n'a pas encore été appelée ou s'il n'y a pas de caractéristiques connues.

Il est possible qu'un service inclus contienne encore un autre service. Ces inclusions de second niveau doivent être obtenues via l'instance de premier niveau correspondante QLowEnergyService. Techniquement, cela pourrait créer une dépendance circulaire.

QLowEnergyController::createServiceObject() doit être utilisé pour obtenir des instances de service pour chacun des UUID.

Voir également createServiceObject().

void QLowEnergyService::readCharacteristic(const QLowEnergyCharacteristic &characteristic)

Lit la valeur de characteristic. Si l'opération est réussie, le signal characteristicRead() est émis ; sinon, le signal CharacteristicReadError est activé. En général, un characteristic est lisible si sa propriété QLowEnergyCharacteristic::Read est activée.

Toutes les demandes de descripteurs et de caractéristiques vers le même dispositif distant sont sérialisées. Une file d'attente est utilisée lorsque plusieurs demandes sont émises simultanément. La file d'attente n'élimine pas les demandes de lecture en double pour la même caractéristique.

Une caractéristique ne peut être lue que si le service est dans l'état ServiceDiscovered et appartient au service. Si l'une de ces conditions n'est pas vraie, QLowEnergyService::OperationError est activé.

Voir également characteristicRead() et writeCharacteristic().

void QLowEnergyService::readDescriptor(const QLowEnergyDescriptor &descriptor)

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

Toutes les demandes de descripteurs et de caractéristiques vers le même dispositif distant sont sérialisées. Une file d'attente est utilisée lorsque plusieurs demandes sont émises en même temps. La file d'attente n'élimine pas les demandes de lecture en double pour le même descripteur.

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

Voir aussi descriptorRead() et writeDescriptor().

QString QLowEnergyService::serviceName() const

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

Le nom retourné ne peut être récupéré que si serviceUuid() est un UUID 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 du périphérique 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 égal à celui des instances déjà existantes.

Un service devient invalide si le site QLowEnergyController se déconnecte de l'appareil distant. Un service non valide conserve son état interne au moment de l'événement de déconnexion. Cela signifie qu'une fois que les détails du service sont découverts, ils peuvent même être récupérés à partir d'un service non valide. Cela permet des scénarios dans lesquels la connexion du dispositif est établie, les détails du service sont récupérés et le dispositif est immédiatement déconnecté pour permettre au dispositif suivant de se connecter au dispositif périphérique.

Toutefois, dans des circonstances normales, la connexion doit être maintenue pour éviter la 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 aux notifications de changement en cours.

Voir aussi stateChanged().

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

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

Voir aussi 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 pour le champ characteristic. La sémantique exacte dépend du rôle de l'objet contrôleur associé.

Rôle central

L'appel se traduit par une demande ou une commande d'écriture à un périphérique distant. Si l'opération réussit, le signal characteristicWritten() est émis ; sinon, le signal CharacteristicWriteError est activé. L'appel de cette fonction ne déclenche pas le signal characteristicChanged(), sauf si le périphérique lui-même modifie à nouveau la valeur après la demande d'écriture en cours.

Le paramètre mode détermine si le périphérique doit envoyer une confirmation d'écriture. Le périphérique à écrire characteristic doit prendre en charge le mode d'écriture correspondant. 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 demandes d'écriture de descripteurs et de caractéristiques vers le même dispositif distant sont sérialisées. Une file d'attente est utilisée lorsque plusieurs demandes d'écriture sont émises simultanément. La file d'attente n'élimine pas les demandes d'écriture en double pour la même caractéristique. Par exemple, si le même descripteur est défini sur la valeur A et immédiatement après sur B, les deux demandes d'écriture sont exécutées dans l'ordre donné.

Une caractéristique ne peut être écrite que si ce service est dans l'état ServiceDiscovered et appartient au service. Si l'une de ces conditions n'est pas vraie, l'adresse QLowEnergyService::OperationError est définie.

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é des notifications ou des indications pour la caractéristique, les informations correspondantes seront envoyées. Si un dispositif a activé les notifications ou les indications pour la caractéristique et que ce dispositif n'est pas actuellement connecté, mais qu'un lien existe entre lui et le dispositif local, 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 newValue 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 pour descriptor. La sémantique exacte dépend du rôle de l'objet contrôleur associé.

Rôle central

Un appel à cette fonction entraîne une demande d'écriture au dispositif distant. Si l'opération réussit, le signal descriptorWritten() est émis ; sinon, le signal DescriptorWriteError est émis.

Toutes les demandes de descripteurs et de caractéristiques vers le même dispositif distant sont sérialisées. Une file d'attente est utilisée lorsque plusieurs demandes d'écriture sont émises simultanément. La file d'attente n'élimine pas les demandes d'écriture en double pour le même descripteur. Par exemple, si le même descripteur est mis à la valeur A et immédiatement après à la valeur B, les deux demandes d'écriture sont exécutées dans l'ordre donné.

Un descripteur ne peut être écrit que si ce service est dans l'état ServiceDiscovered, appartient au service. Si l'une de ces conditions n'est pas remplie, l'adresse QLowEnergyService::OperationError est définie.

Rôle périphérique

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

Voir également descriptorWritten() et readDescriptor().