QLowEnergyService Class
La clase QLowEnergyService representa un servicio concreto en un dispositivo Bluetooth Low Energy. Más información...
| Encabezado: | #include <QLowEnergyService> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Bluetooth) target_link_libraries(mytarget PRIVATE Qt6::Bluetooth) |
| qmake: | QT += bluetooth |
| Heredado de: | QObject |
Tipos públicos
(since 6.2) enum | DiscoveryMode { FullDiscovery, SkipValueDiscovery } |
| enum | ServiceError { NoError, OperationError, CharacteristicReadError, CharacteristicWriteError, DescriptorReadError, …, UnknownError } |
| enum | ServiceState { InvalidService, RemoteService, RemoteServiceDiscovering, RemoteServiceDiscovered, LocalService, …, ServiceDiscovered } |
| enum | ServiceType { PrimaryService, IncludedService } |
| flags | ServiceTypes |
| enum | WriteMode { WriteWithResponse, WriteWithoutResponse, WriteSigned } |
Funciones públicas
| virtual | ~QLowEnergyService() |
| QLowEnergyCharacteristic | characteristic(const QBluetoothUuid &uuid) const |
| QList<QLowEnergyCharacteristic> | characteristics() const |
| bool | contains(const QLowEnergyCharacteristic &characteristic) const |
| bool | contains(const QLowEnergyDescriptor &descriptor) const |
| void | discoverDetails(QLowEnergyService::DiscoveryMode mode = FullDiscovery) |
| QLowEnergyService::ServiceError | error() const |
| QList<QBluetoothUuid> | includedServices() const |
| void | readCharacteristic(const QLowEnergyCharacteristic &characteristic) |
| void | readDescriptor(const QLowEnergyDescriptor &descriptor) |
| QString | serviceName() const |
| QBluetoothUuid | serviceUuid() const |
| QLowEnergyService::ServiceState | state() const |
| QLowEnergyService::ServiceTypes | type() const |
| void | writeCharacteristic(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue, QLowEnergyService::WriteMode mode = WriteWithResponse) |
| void | writeDescriptor(const QLowEnergyDescriptor &descriptor, const QByteArray &newValue) |
Señales
| void | characteristicChanged(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue) |
| void | characteristicRead(const QLowEnergyCharacteristic &characteristic, const QByteArray &value) |
| void | characteristicWritten(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue) |
| void | descriptorRead(const QLowEnergyDescriptor &descriptor, const QByteArray &value) |
| void | descriptorWritten(const QLowEnergyDescriptor &descriptor, const QByteArray &newValue) |
(since 6.2) void | errorOccurred(QLowEnergyService::ServiceError newError) |
| void | stateChanged(QLowEnergyService::ServiceState newState) |
Descripción detallada
QLowEnergyService permite acceder a los detalles de los servicios Bluetooth Low Energy. La clase facilita el descubrimiento y la publicación de los detalles de los servicios, permite leer y escribir los datos que contienen y notifica los cambios en los datos.
Estructura del servicio
Un dispositivo periférico Bluetooth Low Energy puede contener varios servicios. A su vez, cada servicio puede incluir otros servicios. Esta clase representa un único servicio del dispositivo periférico y se crea mediante ` QLowEnergyController::createServiceObject()`. El parámetro ` type()` indica si este servicio es un servicio primario (de nivel superior) o si forma parte de otro servicio. Cada servicio puede contener una o más características y cada característica puede contener descriptores. La estructura resultante puede tener el aspecto que se muestra en el siguiente diagrama:

Una característica es el principal portador de información. Cuenta con un « value » () y un « properties » () que describen los permisos de acceso al valor. El objetivo general del descriptor incluido es definir con mayor detalle la naturaleza de la característica. Por ejemplo, podría especificar cómo debe interpretarse el valor o si puede notificar al consumidor del valor los cambios que se produzcan en este.
Interacción entre servicios
Una vez creado un objeto de servicio por primera vez, sus detalles aún no se conocen. Esto se indica mediante su state() actual, que es DiscoveryRequired. Solo es posible recuperar el serviceUuid() y el serviceName().
El descubrimiento de sus servicios incluidos, características y descriptores se activa al llamar a discoverDetails(). Durante el descubrimiento, el state() pasa de DiscoveryRequired a DiscoveringService y, finalmente, a su estado final ServiceDiscovered. Esta transición se notifica mediante la señal stateChanged(). Una vez que se conocen los detalles, se conocen todas las características, descriptores y servicios incluidos, y se pueden leer o escribir.
Los valores de las características y los descriptores pueden recuperarse mediante QLowEnergyCharacteristic y QLowEnergyDescriptor, respectivamente. Sin embargo, la lectura o escritura directa de estos atributos requiere el objeto de servicio. La función readCharacteristic() intenta volver a leer el valor de una característica. Aunque el descubrimiento inicial del servicio pueda haber obtenido ya un valor, esta llamada puede ser necesaria en casos en los que el valor de la característica cambie constantemente sin que se proporcionen notificaciones. Un ejemplo podría ser una característica de tiempo que proporciona un valor continuo. Si el intento de lectura tiene éxito, se emite la señal characteristicRead(). Si falla la lectura del valor, se activa la señal CharacteristicReadError. La función writeCharacteristic() intenta escribir un nuevo valor en la característica indicada. Si el intento de escritura tiene éxito, se emite la señal characteristicWritten(). Si la escritura falla, se activa el evento CharacteristicWriteError. La lectura y la escritura de descriptores siguen el mismo patrón.
Se realiza todo intento de leer o escribir el valor de un descriptor o una característica en el hardware. Esto significa que la metainformación, como QLowEnergyCharacteristic::properties(), suele ignorarse al leer y escribir. A modo de ejemplo, es posible llamar a writeCharacteristic() a pesar de que la característica sea de solo lectura según la descripción de sus metadatos. La solicitud de escritura resultante se reenvía al dispositivo conectado y corresponde a este responder a la solicitud potencialmente inválida. En este caso, el resultado es la emisión del CharacteristicWriteError en respuesta al error devuelto por el dispositivo. Este comportamiento simplifica la interacción con dispositivos que informan de metainformación errónea. Si no fuera posible reenviar la solicitud al dispositivo remoto, se establece el OperationError. Una posible razón podría ser que el objeto de característica que se va a escribir ni siquiera pertenezca al servicio actual. En resumen, los dos tipos de errores permiten distinguir rápidamente entre casos de error local y remoto.
Todas las solicitudes se serializan según el principio «primero en entrar, primero en salir» (FIFO). Por ejemplo, el envío de una segunda solicitud de escritura, antes de que haya finalizado la solicitud de escritura anterior, se retrasa hasta que haya finalizado la primera solicitud de escritura.
Nota: Actualmente , no es posible enviar solicitudes de escritura firmadas ni de escritura fiable.
En algunos casos, el periférico genera actualizaciones de valores que la unidad central está interesada en recibir. Para que una característica admita dichas notificaciones, debe tener la propiedad « QLowEnergyCharacteristic::Notify » o « QLowEnergyCharacteristic::Indicate » y un descriptor de tipo « QBluetoothUuid::DescriptorType::ClientCharacteristicConfiguration ». Siempre que se cumplan estas condiciones, las notificaciones se pueden habilitar tal y como se muestra en el siguiente fragmento de código:
//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 writeEl ejemplo muestra una característica de nivel de batería que informa a la unidad central cada vez que cambia el valor. Las notificaciones se envían a través de la señal characteristicChanged(). En la especificación de Bluetooth se ofrecen más detalles sobre este mecanismo.
Compartición de datos de servicio
Cada instancia de `QLowEnergyService` comparte sus estados internos y su información con otras instancias de `QLowEnergyService` del mismo servicio. Si una instancia inicia la detección de los detalles del servicio, todas las demás instancias la siguen automáticamente. Por lo tanto, el siguiente fragmento de código siempre funciona:
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());Otras operaciones, como las llamadas a readCharacteristic(), readDescriptor(), writeCharacteristic(), writeDescriptor() o la invalidación del servicio debido a que el QLowEnergyController relacionado se desconecta del dispositivo, se comparten de la misma manera.
Véase también QLowEnergyController, QLowEnergyCharacteristic y QLowEnergyDescriptor.
Documentación sobre los tipos de miembros
[since 6.2] enum QLowEnergyService::DiscoveryMode
Esta enumeración enumera los modos de detección de servicios. Todos los modos detectan las características del servicio y los descriptores de dichas características. Los modos se diferencian en si se leen los valores de las características y los descriptores.
| Constante | Valor | Descripción |
|---|---|---|
QLowEnergyService::FullDiscovery | 0 | Durante un descubrimiento completo, se detectan todas las características. Se leen todos los valores de las características y todos los descriptores. |
QLowEnergyService::SkipValueDiscovery | 1 | Durante un descubrimiento mínimo, se detectan todas las características. No se leen ni los valores de las características ni los descriptores. |
Esta enumeración se introdujo en Qt 6.2.
Véase también discoverDetails().
enum QLowEnergyService::ServiceError
Esta enumeración describe todas las condiciones de error posibles durante el funcionamiento del servicio. La función error() devuelve el último error que se ha producido.
| Constante | Valor | Descripción |
|---|---|---|
QLowEnergyService::NoError | 0 | No se ha producido ningún error. |
QLowEnergyService::OperationError | 1 | Se ha intentado realizar una operación mientras el servicio no estaba listo. Un ejemplo podría ser el intento de escribir en el servicio mientras aún no se encontraba en el estado « ServiceDiscovered » ( state) o el servicio no es válido debido a una pérdida de conexión con el dispositivo periférico. |
QLowEnergyService::CharacteristicReadError (since Qt 5.5) | 5 | Ha fallado un intento de leer un valor de característica. Por ejemplo, podría activarse en respuesta a una llamada a readCharacteristic(). |
QLowEnergyService::CharacteristicWriteError | 2 | Ha fallado un intento de escribir un nuevo valor en una característica. Por ejemplo, podría activarse al intentar escribir en una característica de solo lectura. |
QLowEnergyService::DescriptorReadError (since Qt 5.5) | 6 | Ha fallado un intento de leer el valor de un descriptor. Por ejemplo, podría activarse en respuesta a una llamada a readDescriptor(). |
QLowEnergyService::DescriptorWriteError | 3 | Ha fallado un intento de escribir un nuevo valor en un descriptor. Por ejemplo, puede activarse al intentar escribir en un descriptor de solo lectura. |
QLowEnergyService::UnknownError (since Qt 5.5) | 4 | Se ha producido un error desconocido al interactuar con el servicio. |
enum QLowEnergyService::ServiceState
Esta enumeración describe la función « state()» del objeto de servicio.
| Constante | Valor | Descripción |
|---|---|---|
QLowEnergyService::InvalidService | 0 | Un servicio puede pasar a ser inválido cuando pierde la conexión con el dispositivo subyacente. Aunque se pierda la conexión, conserva su última información. Un servicio inválido no puede volver a ser válido aunque se restablezca la conexión con el dispositivo. |
QLowEnergyService::RemoteService | 1 | Los detalles del servicio aún deben obtenerse llamando a discoverDetails(). Los únicos datos fiables son su serviceUuid() y su serviceName(). |
QLowEnergyService::RemoteServiceDiscovering | 2 | Se están obteniendo los detalles del servicio. |
QLowEnergyService::RemoteServiceDiscovered | 3 | Se han obtenido los detalles del servicio. |
QLowEnergyService::LocalService (since Qt 5.7) | 4 | El servicio está asociado a un objeto controlador en peripheral role. Estos objetos de servicio no cambian de estado. |
QLowEnergyService::DiscoveryRequired | RemoteService | Obsoleto. Se ha renombrado como RemoteService. |
QLowEnergyService::DiscoveringService | RemoteServiceDiscovering | Obsoleto. Se ha renombrado como RemoteServiceDiscovering. |
QLowEnergyService::ServiceDiscovered | RemoteServiceDiscovered | Obsoleto. Se ha renombrado como RemoteServiceDiscovered. |
enum QLowEnergyService::ServiceType
flags QLowEnergyService::ServiceTypes
Esta enumeración describe el tipo de servicio.
| Constante | Valor | Descripción |
|---|---|---|
QLowEnergyService::PrimaryService | 0x0001 | El servicio es un servicio de nivel superior o primario. Si no se establece este indicador de tipo, el servicio se considera un servicio secundario. Cada servicio puede estar incluido en otro servicio, lo cual se indica mediante IncludedService. |
QLowEnergyService::IncludedService | 0x0002 | El servicio está incluido en otro servicio. En algunas plataformas, este indicador no se puede determinar hasta que se haya detectado el servicio que incluye al servicio actual. |
El tipo ServiceTypes es una definición de tipo (typedef) para QFlags<ServiceType>. Almacena una combinación OR de valores de ServiceType.
enum QLowEnergyService::WriteMode
Esta enumeración describe el modo que se debe utilizar al escribir un valor de característica. La característica indica los modos de escritura que admite a través de su propiedad ` properties`.
| Constante | Valor | Descripción |
|---|---|---|
QLowEnergyService::WriteWithResponse | 0 | Si se escribe una característica utilizando este modo, el periférico deberá enviar una confirmación de escritura. Si la operación se realiza con éxito, la confirmación se emite a través de la señal characteristicWritten(). En caso contrario, se emite el CharacteristicWriteError. Una característica debe tener configurada la propiedad QLowEnergyCharacteristic::Write para admitir este modo de escritura. |
QLowEnergyService::WriteWithoutResponse | 1 | Si se escribe una característica utilizando este modo, el periférico remoto no deberá enviar una confirmación de escritura. No se puede determinar si la operación se ha realizado con éxito y la carga útil no debe superar los 20 bytes. Una característica debe tener configurada la propiedad QLowEnergyCharacteristic::WriteNoResponse para admitir este modo de escritura. Su ventaja es una operación de escritura más rápida, ya que puede realizarse entre otras interacciones del dispositivo. |
QLowEnergyService::WriteSigned (since Qt 5.7) | 2 | Si se escribe una característica utilizando este modo, el periférico remoto no enviará una confirmación de escritura. No se puede determinar si la operación se ha realizado con éxito y la carga útil no debe superar los 8 bytes. Debe existir un enlace entre los dos dispositivos y este no debe estar cifrado. Una característica debe tener configurada la propiedad « QLowEnergyCharacteristic::WriteSigned » para admitir este modo de escritura. Actualmente, este valor solo es compatible con Android y con Linux con BlueZ 5 y una versión del núcleo 3.7 o posterior. |
Documentación de funciones miembro
[virtual noexcept] QLowEnergyService::~QLowEnergyService()
Elimina la instancia de « QLowEnergyService ».
QLowEnergyCharacteristic QLowEnergyService::characteristic(const QBluetoothUuid &uuid) const
Devuelve la característica coincidente para uuid; en caso contrario, devuelve una característica no válida.
La característica devuelta no es válida si aún no se ha llamado a la función discoverDetails() de esta instancia del servicio o si no hay características con un uuid que coincida.
Véase también ` characteristics()`.
[signal] void QLowEnergyService::characteristicChanged(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue)
Si el objeto controlador asociado ocupa el rol « central », esta señal se emite cuando el valor de « characteristic » se modifica debido a un evento en el lado del periférico o del dispositivo. En ese caso, la emisión de la señal implica que las notificaciones de cambio deben haberse activado mediante el descriptor « ClientCharacteristicConfiguration » de la característica antes de que se produzca el evento de cambio en el periférico. Se puede encontrar más información sobre cómo hacerlo en above.
Si el controlador desempeña la función de « peripheral », es decir, si el objeto de servicio se ha creado mediante QLowEnergyController::addService, la señal se emite cuando un cliente GATT ha escrito el valor de la característica mediante una solicitud de escritura o un comando.
El parámetro « newValue » contiene el valor actualizado de characteristic.
[signal] void QLowEnergyService::characteristicRead(const QLowEnergyCharacteristic &characteristic, const QByteArray &value)
Esta señal se emite cuando la solicitud de lectura de « characteristic » ha devuelto correctamente su « value ». La señal puede activarse al llamar a «characteristicRead()». Si la operación de lectura no se realiza correctamente, se emite la señal « errorOccurred()» utilizando el indicador « CharacteristicReadError ».
Nota: Esta señal solo se emite para casos de uso relacionados con la función Central.
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 modifica correctamente a ` newValue`. El cambio debe haberse activado mediante la llamada a ` writeCharacteristic()`. Si la operación de escritura no se realiza correctamente, se emite la señal ` errorOccurred()` utilizando el indicador ` CharacteristicWriteError `.
La recepción de la señal de escritura puede considerarse una indicación de que el dispositivo de destino ha recibido el valor que se iba a escribir y notifica el estado de la solicitud de escritura.
Nota: Si se llama a « writeCharacteristic()» utilizando el modo « WriteWithoutResponse », esta señal y la de « errorOccurred()» nunca se emiten.
Nota: Esta señal solo se emite para casos de uso relacionados con la función central.
Véase también writeCharacteristic().
QList<QLowEnergyCharacteristic> QLowEnergyService::characteristics() const
Devuelve todas las características asociadas a esta instancia de « QLowEnergyService ».
La lista devuelta estará vacía si aún no se ha llamado a la función discoverDetails() de esta instancia del 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, devuelve ` 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, devuelve « false ».
[signal] void QLowEnergyService::descriptorRead(const QLowEnergyDescriptor &descriptor, const QByteArray &value)
Esta señal se emite cuando la solicitud de lectura de un ` descriptor ` devuelve correctamente su ` value`. La señal puede activarse al llamar a `descriptorRead()`. Si la operación de lectura no se realiza correctamente, se emite la señal ` errorOccurred()` utilizando el indicador ` DescriptorReadError `.
Nota: Esta señal solo se emite para casos de uso relacionados con la función central.
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 modifica correctamente a « newValue ». Si el objeto controlador asociado desempeña la función de « central », la modificación debe haber sido provocada por la llamada a « writeDescriptor()». En caso contrario, la señal es el resultado de una solicitud de escritura o de un comando de un cliente GATT dirigido al descriptor correspondiente.
Véase también writeDescriptor().
void QLowEnergyService::discoverDetails(QLowEnergyService::DiscoveryMode mode = FullDiscovery)
Inicia el proceso de descubrimiento de los servicios incluidos en el servicio, sus características y los descriptores asociados a ellos.
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()», pasa al estado « DiscoveringService ». Una vez finalizado el descubrimiento de detalles, pasa al estado « ServiceDiscovered ». En cada transición, se emite la señal « stateChanged()». Dependiendo del argumento « mode », se realiza un « FullDiscovery » o un « SkipValueDiscovery ». En cualquier caso, se descubren todos los servicios y características. Un FullDiscovery continúa y lee todos los valores de las características y los descriptores. Un SkipValueDiscovery no lee los valores de las características ni los descriptores. Un SkipValueDiscovery tiene dos ventajas. En primer lugar, es más rápido. En segundo lugar, evita errores en algunos dispositivos que anuncian erróneamente características o descriptores como legibles, pero que, sin embargo, no permiten su lectura. Esto puede provocar un comportamiento impredecible. Tras 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 un descriptor.
El argumento mode se introdujo en Qt 6.2.
Véase también state().
QLowEnergyService::ServiceError QLowEnergyService::error() const
Devuelve el último error producido o un objeto de tipo « 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 estará vacía si aún no se ha llamado a la función ` discoverDetails()` de esta instancia de servicio o si no hay características conocidas.
Es posible que un servicio incluido contenga a su vez otro servicio. Dichas inclusiones de segundo nivel deben obtenerse a través de su instancia correspondiente de ` QLowEnergyService ` de primer nivel. Técnicamente, esto podría crear una dependencia circular.
QLowEnergyController::createServiceObjectSe debe utilizar () 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 se realiza correctamente, se emite la señal « characteristicRead()»; en caso contrario, se activa la señal « CharacteristicReadError ». En general, un « characteristic » es legible si su propiedad « QLowEnergyCharacteristic::Read » está activada.
Todas las solicitudes de descriptores y características dirigidas al mismo dispositivo remoto se serializan. Se utiliza una cola cuando se envían varias solicitudes al mismo tiempo. La cola no elimina las solicitudes de lectura duplicadas para la misma característica.
Una característica solo se puede leer si el servicio se encuentra en el estado « ServiceDiscovered » y pertenece al servicio. Si alguna de estas condiciones no se cumple, se establece el valor « QLowEnergyService::OperationError ».
Nota: Al llamar a esta función, aunque ` QLowEnergyCharacteristic::properties()` indique que una propiedad no es legible, siempre se intenta leer el valor de la característica en el hardware. Si el hardware devuelve un error, se establece el indicador ` CharacteristicReadError `.
Véanse también characteristicRead() y writeCharacteristic().
void QLowEnergyService::readDescriptor(const QLowEnergyDescriptor &descriptor)
Lee el valor de ` descriptor`. Si la operación se realiza correctamente, se emite la señal ` descriptorRead()`; en caso contrario, se activa la señal ` DescriptorReadError `.
Todas las solicitudes de descriptores y características dirigidas al mismo dispositivo remoto se serializan. Se utiliza una cola cuando se envían varias solicitudes al mismo tiempo. La cola no elimina las solicitudes de lectura duplicadas para un mismo descriptor.
Un descriptor solo se puede leer si el servicio se encuentra en el estado « ServiceDiscovered » y el descriptor pertenece a dicho servicio. Si alguna de estas condiciones no se cumple, se establece el valor « QLowEnergyService::OperationError ».
Véanse también descriptorRead() y writeDescriptor().
QString QLowEnergyService::serviceName() const
Devuelve el nombre del servicio; en caso contrario, devuelve una cadena vacía.
El nombre devuelto solo 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 es siempre el mismo. Esto se debe a que los datos internos del objeto son compartidos. Por lo tanto, cualquier instancia de objeto de servicio creada después de la primera tiene un estado igual al de las instancias ya existentes.
Un servicio deja de ser válido si el QLowEnergyController se desconecta del dispositivo remoto. Un servicio no válido conserva su estado interno en el momento en que se produce la desconexión. Esto implica que, una vez descubiertos los detalles del servicio, estos pueden recuperarse incluso de un servicio no válido. Esto permite situaciones en las que se establece la conexión con el 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 debería mantenerse para evitar el descubrimiento repetido de servicios y sus detalles. El descubrimiento puede tardar 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. El ` newState ` también se puede obtener mediante ` state()`.
Véase también state().
QLowEnergyService::ServiceTypes QLowEnergyService::type() const
Devuelve el tipo del servicio.
Nota: No se puede confiar enel atributo «type» hasta que el servicio haya alcanzado el estado « ServiceDiscovered ». Este campo se inicializa con « PrimaryService ».
Nota: En Android, no es posible determinar si un servicio es primario o secundario. Por lo tanto, todos los servicios tienen activado el indicador « PrimaryService ».
void QLowEnergyService::writeCharacteristic(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue, QLowEnergyService::WriteMode mode = WriteWithResponse)
Establece ` newValue ` como valor de ` characteristic`. La semántica exacta depende del rol que tenga el objeto controlador asociado.
Papel central
La llamada da lugar a una solicitud de escritura o un comando dirigido a un periférico remoto. Si la operación se realiza con éxito, se emite la señal « characteristicWritten()»; en caso contrario, se establece el valor « CharacteristicWriteError ». La llamada a esta función no activa la señal « characteristicChanged()» a menos que el propio periférico vuelva a cambiar el valor tras la solicitud de escritura actual.
El parámetro mode determina si el dispositivo remoto debe enviar una confirmación de escritura. La characteristic en la que se va a escribir debe admitir 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 utiliza una cola cuando se envían varias solicitudes de escritura al mismo tiempo. La cola no elimina las solicitudes de escritura duplicadas para una misma característica. Por ejemplo, si un mismo descriptor se establece en el valor A e inmediatamente después en B, las dos solicitudes de escritura se ejecutan en el orden indicado.
Nota: Actualmente , no es posible utilizar escrituras firmadas o fiables tal y como se definen en la especificación de Bluetooth.
Solo se puede escribir en una característica si este servicio se encuentra en el estado « ServiceDiscovered » y pertenece al servicio. Si alguna de estas condiciones no se cumple, se establece el valor « QLowEnergyService::OperationError ».
Nota: Al llamar a esta función, aunque ` QLowEnergyCharacteristic::properties()` indique que una propiedad no es escribible, siempre se intenta escribir en el hardware. Del mismo modo, también se envía un ` WriteWithoutResponse ` al hardware, aunque la característica solo admita ` WriteWithResponse`. Si el hardware devuelve un error, se establece el ` CharacteristicWriteError `.
Función del periférico
La llamada da lugar a la actualización del valor de la característica en la base de datos local.
Si hay un cliente conectado en ese momento y tiene habilitadas las notificaciones o indicaciones para la característica, se enviará la información correspondiente. Si un dispositivo tiene habilitadas las notificaciones o indicaciones para la característica y dicho 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 siguiente reconexión.
Si existe una restricción sobre la longitud del valor de la característica y ` newValue ` no cumple dicha restricción, el comportamiento no está especificado.
Nota: El argumento ` mode ` se ignora en el modo periférico.
Véase también QLowEnergyService::characteristicWritten() y QLowEnergyService::readCharacteristic().
void QLowEnergyService::writeDescriptor(const QLowEnergyDescriptor &descriptor, const QByteArray &newValue)
Establece ` newValue ` como valor de ` descriptor`. La semántica exacta depende del rol que tenga el objeto controlador asociado.
Rol central
Una llamada a esta función da lugar a una solicitud de escritura al dispositivo remoto. Si la operación se realiza correctamente, se emite la señal descriptorWritten(); en caso contrario, se emite la señal DescriptorWriteError.
Todas las solicitudes de descriptores y características dirigidas al mismo dispositivo remoto se serializan. Se utiliza una cola cuando se envían varias solicitudes de escritura al mismo tiempo. La cola no elimina las solicitudes de escritura duplicadas para un mismo descriptor. Por ejemplo, si un mismo descriptor se establece en el valor A e inmediatamente después en B, las dos solicitudes de escritura se ejecutan en el orden indicado.
Solo se puede escribir en un descriptor si este servicio se encuentra en el estado « ServiceDiscovered » y pertenece al servicio. Si alguna de estas condiciones no se cumple, se establece el QLowEnergyService::OperationError.
Función del periférico
El valor se escribe en la base de datos de servicios local. Si el contenido de « newValue » no es válido para « descriptor », el comportamiento no está especificado.
Véase también descriptorWritten() y readDescriptor().
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.