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

Documentación de las funciones miembro

[virtual noexcept] QLowEnergyService::~QLowEnergyService()

Destruye la instancia QLowEnergyService.

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

Devuelve la característica coincidente para uuid; en caso contrario, una característica inválida.

La característica devuelta no es válida si todavía no se ha llamado a discoverDetails() de esta instancia de servicio o si no hay características que coincidan con uuid.

Véase también characteristics().

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

Si el objeto controlador asociado tiene el rol central, esta señal se emite cuando el valor de characteristic es cambiado por un evento en el lado del periférico/dispositivo. En ese caso, la emisión de la señal implica que las notificaciones de cambio deben haberse activado a través del descriptor ClientCharacteristicConfiguration de la característica antes del evento de cambio en el periférico. Encontrará más detalles sobre cómo hacerlo en above.

Si el controlador desempeña el papel peripheral, es decir, el objeto de servicio se creó a través de QLowEnergyController::addService, la señal se emite cuando un cliente GATT ha escrito el valor de la característica mediante una solicitud o comando de escritura.

El parámetro newValue contiene el valor actualizado de la característica characteristic.

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

Esta señal se emite cuando la petición de lectura de characteristic devuelve con éxito su value. La señal puede activarse llamando a characteristicRead(). Si la operación de lectura no tiene éxito, se emite la señal errorOccurred() utilizando la bandera CharacteristicReadError.

Véase también readCharacteristic().

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

Esta señal se emite cuando el valor de characteristic se cambia con éxito a newValue. El cambio debe haberse desencadenado llamando a writeCharacteristic(). Si la operación de escritura no tiene éxito, se emite la señal errorOccurred() utilizando la bandera CharacteristicWriteError.

La recepción de la señal de escritura puede considerarse como una señal de que el dispositivo de destino ha recibido el valor a escribir e informa del estado de la solicitud de escritura.

Véase también writeCharacteristic().

QList<QLowEnergyCharacteristic> QLowEnergyService::characteristics() const

Devuelve todas las características asociadas a esta instancia QLowEnergyService.

La lista devuelta está vacía si aún no se ha llamado a discoverDetails() de esta instancia de servicio o si no hay características conocidas.

Véase también characteristic(), state() y discoverDetails().

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

Devuelve true si characteristic pertenece a este servicio; en caso contrario false.

Una característica pertenece a un servicio si characteristics() contiene el characteristic.

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

Devuelve true si descriptor pertenece a este servicio; en caso contrario false.

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

Esta señal se emite cuando la petición de lectura de descriptor devuelve con éxito su value. La señal puede activarse llamando a descriptorRead(). Si la operación de lectura no tiene éxito, se emite la señal errorOccurred() utilizando la bandera DescriptorReadError.

Véase también readDescriptor().

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

Esta señal se emite cuando el valor de descriptor se cambia con éxito a newValue. Si el objeto controlador asociado está en el rol central, el cambio debe haber sido causado llamando a writeDescriptor(). En caso contrario, la señal es el resultado de una solicitud o comando de escritura de un cliente GATT en el descriptor correspondiente.

Véase también writeDescriptor().

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

Inicia el descubrimiento de los servicios incluidos en el servicio, las características y sus descriptores asociados.

El proceso de descubrimiento se indica mediante la señal stateChanged(). Tras su creación, el servicio se encuentra en el estado DiscoveryRequired. Al llamar a discoverDetails() transita a DiscoveringService. Una vez finalizado el descubrimiento de detalles, pasa al estado ServiceDiscovered. En cada transición, se emite la señal stateChanged(). En función del argumento mode, se realiza una FullDiscovery o una SkipValueDiscovery. En cualquier caso, se descubren todos los servicios y características. Un FullDiscovery procede y lee todos los valores y descriptores de características. Un SkipValueDiscovery no lee valores de característica y descriptores. Un SkipValueDiscovery tiene dos ventajas. En primer lugar, es más rápido. En segundo lugar, evita los errores de algunos dispositivos que anuncian erróneamente características o descriptores como legibles pero que, sin embargo, no permiten leerlos. Esto puede provocar un comportamiento impredecible. Después de un SkipValueDiscovery, es necesario llamar a readCharacteristic() / readDescriptor() y esperar a que finalicen con éxito antes de acceder al valor de una característica o descriptor.

El argumento mode se introdujo en Qt 6.2.

Véase también state().

QLowEnergyService::ServiceError QLowEnergyService::error() const

Devuelve el último error ocurrido o NoError.

[signal, since 6.2] void QLowEnergyService::errorOccurred(QLowEnergyService::ServiceError newError)

Esta señal se emite cuando se produce un error. El parámetro newError describe el error que se ha producido.

Esta función se introdujo en Qt 6.2.

QList<QBluetoothUuid> QLowEnergyService::includedServices() const

Devuelve los UUID de todos los servicios incluidos en el servicio actual.

La lista devuelta está vacía si aún no se ha llamado a discoverDetails() de esta instancia de servicio o no hay características conocidas.

Es posible que un servicio incluido contenga otro servicio. Estos servicios incluidos de segundo nivel deben obtenerse a través de su instancia de primer nivel QLowEnergyService. Técnicamente, esto podría crear una dependencia circular.

QLowEnergyController::createServiceObject() debe utilizarse para obtener instancias de servicio para cada uno de los UUID.

Véase también createServiceObject().

void QLowEnergyService::readCharacteristic(const QLowEnergyCharacteristic &characteristic)

Lee el valor de characteristic. Si la operación tiene éxito, se emite la señal characteristicRead(); en caso contrario, se establece CharacteristicReadError. En general, un characteristic es legible, si su propiedad QLowEnergyCharacteristic::Read está establecida.

Todas las solicitudes de descriptor y de característica dirigidas al mismo dispositivo remoto se serializan. Se emplea una cola cuando se emiten varias solicitudes al mismo tiempo. La cola no elimina las solicitudes de lectura duplicadas para la misma característica.

Una característica sólo puede leerse si el servicio se encuentra en el estado ServiceDiscovered y pertenece al servicio. Si una de estas condiciones no es cierta, se activa QLowEnergyService::OperationError.

Véase también characteristicRead() y writeCharacteristic().

void QLowEnergyService::readDescriptor(const QLowEnergyDescriptor &descriptor)

Lee el valor de descriptor. Si la operación tiene éxito, se emite la señal descriptorRead(); en caso contrario, se establece DescriptorReadError.

Se serializan todas las solicitudes de descriptor y característica dirigidas al mismo dispositivo remoto. Se emplea una cola cuando se emiten varias solicitudes al mismo tiempo. La cola no elimina las solicitudes de lectura duplicadas para el mismo descriptor.

Un descriptor sólo puede leerse si el servicio se encuentra en el estado ServiceDiscovered y el descriptor pertenece al servicio. Si una de estas condiciones no es cierta, se activa QLowEnergyService::OperationError.

Véase también descriptorRead() y writeDescriptor().

QString QLowEnergyService::serviceName() const

Devuelve el nombre del servicio; en caso contrario, una cadena vacía.

El nombre devuelto sólo se puede recuperar si serviceUuid() es un UUID conocido.

QBluetoothUuid QLowEnergyService::serviceUuid() const

Devuelve el UUID del servicio; en caso contrario, un UUID nulo.

QLowEnergyService::ServiceState QLowEnergyService::state() const

Devuelve el estado actual del servicio.

Si el servicio del dispositivo se ha instanciado por primera vez, el estado del objeto es DiscoveryRequired. El estado de todos los objetos de servicio que apuntan al mismo servicio en el dispositivo periférico son siempre iguales. Esto se debe a la naturaleza compartida de los datos internos del objeto. Por lo tanto, cualquier instancia de objeto de servicio creada después de la primera tiene un estado igual a las instancias ya existentes.

Un servicio deja de ser válido si QLowEnergyController se desconecta del dispositivo remoto. Un servicio inválido conserva su estado interno en el momento del evento de desconexión. Esto implica que, una vez descubiertos los detalles del servicio, pueden recuperarse incluso de un servicio no válido. Esto permite escenarios en los que se establece la conexión del dispositivo, se recuperan los detalles del servicio y el dispositivo se desconecta inmediatamente para permitir que el siguiente dispositivo se conecte al dispositivo periférico.

Sin embargo, en circunstancias normales la conexión debe permanecer para evitar el descubrimiento repetido de servicios y sus detalles. El descubrimiento puede llevar un tiempo y el cliente puede suscribirse a notificaciones de cambios en curso.

Véase también stateChanged().

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

Esta señal se emite cuando cambia el estado del servicio. newState también puede recuperarse a través de state().

Véase también state().

QLowEnergyService::ServiceTypes QLowEnergyService::type() const

Devuelve el tipo del servicio.

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

Escribe newValue como valor para characteristic. La semántica exacta depende del rol en el que se encuentre el objeto controlador asociado.

Rol central

La llamada da lugar a una solicitud o comando de escritura en un periférico remoto. Si la operación tiene éxito, se emite la señal characteristicWritten(); en caso contrario, se establece CharacteristicWriteError. La llamada a esta función no emite la señal characteristicChanged() a menos que el propio periférico vuelva a cambiar el valor después de la solicitud de escritura en curso.

El parámetro mode determina si el dispositivo remoto debe enviar una confirmación de escritura. El characteristic a escribir debe soportar el modo de escritura correspondiente. Los modos de escritura admitidos por la característica se indican mediante sus propiedades QLowEnergyCharacteristic::Write y QLowEnergyCharacteristic::WriteNoResponse.

Todas las solicitudes de escritura de descriptores y características dirigidas al mismo dispositivo remoto se serializan. Se emplea una cola cuando se emiten varias solicitudes de escritura al mismo tiempo. La cola no elimina las solicitudes de escritura duplicadas para la misma característica. Por ejemplo, si el mismo descriptor se establece en el valor A e inmediatamente después en B, las dos solicitudes de escritura se ejecutan en el orden dado.

Una característica sólo puede escribirse si este servicio se encuentra en el estado ServiceDiscovered y pertenece al servicio. Si una de estas condiciones no es cierta, se establece QLowEnergyService::OperationError.

Función periférica

La llamada tiene como resultado la actualización del valor de la característica en la base de datos local.

Si un cliente está conectado en ese momento y ha habilitado notificaciones o indicaciones para la característica, se enviará la información correspondiente. Si un dispositivo ha habilitado notificaciones o indicaciones para la característica y ese dispositivo no está conectado en ese momento, pero existe un vínculo entre él y el dispositivo local, la notificación o indicación se enviará en la próxima reconexión.

Si existe una restricción sobre la longitud del valor de la característica y newValue no respeta dicha restricción, el comportamiento es indeterminado.

Véase también QLowEnergyService::characteristicWritten() y QLowEnergyService::readCharacteristic().

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

Escribe newValue como valor para descriptor. La semántica exacta depende del rol en el que se encuentre el objeto controlador asociado.

Función central

Una llamada a esta función resulta en una petición de escritura al dispositivo remoto. Si la operación tiene éxito, se emite la señal descriptorWritten(); en caso contrario, se emite la señal DescriptorWriteError.

Se serializan todas las peticiones de descriptor y característica hacia el mismo dispositivo remoto. Se emplea una cola cuando se emiten varias solicitudes de escritura al mismo tiempo. La cola no elimina las solicitudes de escritura duplicadas para el mismo descriptor. Por ejemplo, si el mismo descriptor se establece en el valor A e inmediatamente después en B, las dos solicitudes de escritura se ejecutan en el orden dado.

Un descriptor sólo puede escribirse si este servicio está en el estado ServiceDiscovered, pertenece al servicio. Si una de estas condiciones no es cierta, se establece QLowEnergyService::OperationError.

Función periférica

El valor se escribe en la base de datos del servicio local. Si el contenido de newValue no es válido para descriptor, el comportamiento es indeterminado.

Véase también descriptorWritten() y readDescriptor().