QLowEnergyCharacteristic Class
La clase `QLowEnergyCharacteristic` almacena información sobre una característica de servicio de Bluetooth Low Energy. Más información...
| Cabecera: | #include <QLowEnergyCharacteristic> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Bluetooth) target_link_libraries(mytarget PRIVATE Qt6::Bluetooth) |
| qmake: | QT += bluetooth |
Tipos públicos
| enum | PropertyType { Unknown, Broadcasting, Read, WriteNoResponse, Write, …, ExtendedProperty } |
| flags | PropertyTypes |
Funciones públicas
| QLowEnergyCharacteristic() | |
| QLowEnergyCharacteristic(const QLowEnergyCharacteristic &other) | |
| ~QLowEnergyCharacteristic() | |
(since 6.2) QLowEnergyDescriptor | clientCharacteristicConfiguration() const |
| QLowEnergyDescriptor | descriptor(const QBluetoothUuid &uuid) const |
| QList<QLowEnergyDescriptor> | descriptors() const |
| bool | isValid() const |
| QString | name() const |
| QLowEnergyCharacteristic::PropertyTypes | properties() const |
| QBluetoothUuid | uuid() const |
| QByteArray | value() const |
| QLowEnergyCharacteristic & | operator=(const QLowEnergyCharacteristic &other) |
Miembros públicos estáticos
(since 6.2) const QByteArray | CCCDDisable |
(since 6.2) const QByteArray | CCCDEnableIndication |
(since 6.2) const QByteArray | CCCDEnableNotification |
Elementos no miembros relacionados
| bool | operator!=(const QLowEnergyCharacteristic &a, const QLowEnergyCharacteristic &b) |
| bool | operator==(const QLowEnergyCharacteristic &a, const QLowEnergyCharacteristic &b) |
Descripción detallada
QLowEnergyCharacteristic proporciona información sobre las características de un servicio Bluetooth Low Energy: « name()», « uuid()», « value()», « properties()» y « descriptors()». Para obtener la especificación y la información de la característica, es necesario conectarse al dispositivo mediante las clases « QLowEnergyService » y « QLowEnergyController ».
El valor de la característica puede escribirse a través de la instancia QLowEnergyService que gestiona el servicio al que pertenece dicha característica. La función QLowEnergyService::writeCharacteristic() escribe el nuevo valor. La señal QLowEnergyService::characteristicWritten() se emite cuando la operación se realiza con éxito. El método value() de este objeto se actualiza automáticamente en consecuencia.
Las características pueden contener ninguno, uno o varios descriptores. Se pueden recuperar individualmente mediante la función descriptor(). La función descriptors() devuelve todos los descriptores en forma de lista. La finalidad general de un descriptor es añadir información contextual a la característica. Por ejemplo, el descriptor podría proporcionar información sobre el formato o el rango, especificando cómo debe interpretarse el valor de la característica.
Véase también QLowEnergyService y QLowEnergyDescriptor.
Documentación sobre tipos de miembros
enum QLowEnergyCharacteristic::PropertyType
flags QLowEnergyCharacteristic::PropertyTypes
Esta enumeración describe las propiedades de una característica.
| Constante | Valor | Descripción |
|---|---|---|
QLowEnergyCharacteristic::Unknown | 0x00 | Se desconoce el tipo. |
QLowEnergyCharacteristic::Broadcasting | 0x01 | Permite la difusión de valores de características de atributos genéricos (GATT). |
QLowEnergyCharacteristic::Read | 0x02 | Permite la lectura de los valores de las características. |
QLowEnergyCharacteristic::WriteNoResponse | 0x04 | Permite escribir valores de característica sin respuestas. |
QLowEnergyCharacteristic::Write | 0x08 | Permite escribir valores de características. |
QLowEnergyCharacteristic::Notify | 0x10 | Permite la notificación de valores de característica. |
QLowEnergyCharacteristic::Indicate | 0x20 | Permite indicar los valores de las características. |
QLowEnergyCharacteristic::WriteSigned | 0x40 | Permite la escritura firmada de los valores de característica GATT. |
QLowEnergyCharacteristic::ExtendedProperty | 0x80 | Las propiedades adicionales de las características se definen en el descriptor de propiedades extendidas de la característica. |
No se recomienda establecer las propiedades «Notify» e «Indicate» en la misma característica, ya que el comportamiento de la pila Bluetooth subyacente varía de una plataforma a otra. Consulte QLowEnergyCharacteristic::clientCharacteristicConfiguration
El tipo PropertyTypes es un typedef para QFlags<PropertyType>. Almacena una combinación OR de valores de PropertyType.
Véase también properties().
Documentación de funciones miembro
QLowEnergyCharacteristic::QLowEnergyCharacteristic()
Crea un nuevo objeto de clase `QLowEnergyCharacteristic`. Una instancia de esta clase creada mediante la construcción por defecto siempre es inválida.
Véase también isValid().
QLowEnergyCharacteristic::QLowEnergyCharacteristic(const QLowEnergyCharacteristic &other)
Crea un nuevo objeto `QLowEnergyCharacteristic` que sea una copia de ` other`.
Las dos copias siguen compartiendo los mismos datos subyacentes, que no se separan al escribir.
[noexcept] QLowEnergyCharacteristic::~QLowEnergyCharacteristic()
Elimina el objeto ` QLowEnergyCharacteristic `.
[since 6.2] QLowEnergyDescriptor QLowEnergyCharacteristic::clientCharacteristicConfiguration() const
Devuelve el descriptor de configuración de características del cliente o una instancia no válida de ` QLowEnergyDescriptor ` si no existe dicho descriptor.
Las características BTLE pueden admitir notificaciones y/o indicaciones. En ambos casos, el periférico informará a la central de cada cambio en el valor de la característica. En el protocolo de atributos BTLE, la central no confirma los mensajes de notificación, mientras que sí confirma las indicaciones. Las notificaciones se consideran más rápidas, pero poco fiables, mientras que las indicaciones son más lentas y más fiables.
Si una característica admite notificaciones o indicaciones, estas pueden habilitarse escribiendo patrones de bits especiales en el descriptor de configuración de características del cliente. Para mayor comodidad, estos patrones de bits se proporcionan como « QLowEnergyCharacteristic::CCCDDisable », « QLowEnergyCharacteristic::CCCDEnableNotification » y « QLowEnergyCharacteristic::CCCDEnableIndication ».
La activación, por ejemplo, de la notificación para una característica denominada mycharacteristic en un servicio llamado myservice podría realizarse utilizando el siguiente código.
auto cccd = mycharacteristic.clientCharacteristicConfiguration();
if (!cccd.isValid()) {
// your error handling
return error;
}
myservice->writeDescriptor(cccd, QLowEnergyCharacteristic::CCCDEnableNotification);Nota: Llamar a « characteristic.clientCharacteristicConfiguration() » equivale a llamar a « characteristic.descriptor(QBluetoothUuid::DescriptorType::ClientCharacteristicConfiguration) ».
Nota: Nose recomienda utilizar tanto notificaciones como indicaciones en la misma característica. Esto se aplica tanto al lado del servidor, al configurar las características, como al lado del cliente, al habilitarlas. El comportamiento de la pila de Bluetooth varía de una plataforma a otra y es probable que el comportamiento multiplataforma sea inconsistente. Por ejemplo, un cliente Bluez de Linux podría intentar habilitar incondicionalmente ambos mecanismos si ambos son compatibles, mientras que un cliente de macOS podría habilitar incondicionalmente solo las notificaciones. Si se necesitan ambos, considera la posibilidad de crear dos características independientes.
Esta función se introdujo en Qt 6.2.
Véase también descriptor().
QLowEnergyDescriptor QLowEnergyCharacteristic::descriptor(const QBluetoothUuid &uuid) const
Devuelve el descriptor de uuid o de una instancia no válida de QLowEnergyDescriptor.
Véase también descriptors().
QList<QLowEnergyDescriptor> QLowEnergyCharacteristic::descriptors() const
Devuelve la lista de descriptores pertenecientes a esta característica; en caso contrario, devuelve una lista vacía.
Véase también descriptor().
bool QLowEnergyCharacteristic::isValid() const
Devuelve « true » si el objeto « QLowEnergyCharacteristic » es válido; en caso contrario, devuelve « false ».
Un objeto de característica no válido no está asociado a ningún servicio (construido por defecto) o el servicio asociado ya no es válido debido, por ejemplo, a una desconexión del dispositivo Bluetooth Low Energy subyacente. Una vez que el objeto deja de ser válido, ya no puede volver a serlo.
Nota: Si una instancia de ` QLowEnergyCharacteristic ` deja de ser válida debido a una desconexión del dispositivo subyacente, la información encapsulada por la instancia actual permanece tal y como estaba en el momento de la desconexión. Por lo tanto, puede recuperarse tras el evento de desconexión.
QString QLowEnergyCharacteristic::name() const
Devuelve el nombre legible para el usuario de la característica.
El nombre se basa en el identificador de la característica ( uuid()), que debe haber sido estandarizado. La lista completa de tipos de características se puede consultar en «Características» de Bluetooth.org.
La cadena devuelta está vacía si se desconoce el valor de uuid().
Véase también QBluetoothUuid::characteristicToString().
QLowEnergyCharacteristic::PropertyTypes QLowEnergyCharacteristic::properties() const
Devuelve las propiedades de la característica.
Las propiedades definen los permisos de acceso a la característica.
QBluetoothUuid QLowEnergyCharacteristic::uuid() const
Devuelve el UUID de la característica si isValid() devuelve true; en caso contrario, devuelve un UUID de tipo null.
QByteArray QLowEnergyCharacteristic::value() const
Devuelve el valor almacenado en caché de la característica.
Si el método properties() de la característica permite escribir nuevos valores, el valor se puede actualizar mediante QLowEnergyService::writeCharacteristic().
La caché se actualiza durante el ` detail discovery` del servicio asociado, tras una operación correcta de ` read` o `write `, o cuando se recibe una notificación de actualización.
El objeto QByteArray devuelto siempre permanece vacío si la característica no dispone de read permission. En tales casos, solo QLowEnergyService::characteristicChanged() o QLowEnergyService::characteristicWritten() pueden proporcionar información sobre el valor de esta característica.
QLowEnergyCharacteristic &QLowEnergyCharacteristic::operator=(const QLowEnergyCharacteristic &other)
Crea una copia de other y la asigna a este objeto QLowEnergyCharacteristic. Las dos copias siguen compartiendo los mismos datos del servicio y del controlador.
Documentación sobre variables de miembro
[since 6.2] const QByteArray QLowEnergyCharacteristic::CCCDDisable
Patrón de bits que se debe escribir en el descriptor de configuración de características del cliente para desactivar tanto la notificación como la indicación.
Esta variable se introdujo en Qt 6.2.
Véase también QLowEnergyCharacteristic::clientCharacteristicConfiguration.
[since 6.2] const QByteArray QLowEnergyCharacteristic::CCCDEnableIndication
Patrón de bits que se debe escribir en el descriptor de configuración de características del cliente para habilitar la indicación.
Esta variable se introdujo en Qt 6.2.
Véase también QLowEnergyCharacteristic::clientCharacteristicConfiguration.
[since 6.2] const QByteArray QLowEnergyCharacteristic::CCCDEnableNotification
Patrón de bits que se debe escribir en el descriptor de configuración de características del cliente para habilitar la notificación.
Esta variable se introdujo en Qt 6.2.
Véase también QLowEnergyCharacteristic::clientCharacteristicConfiguration.
Elementos no miembros relacionados
bool operator!=(const QLowEnergyCharacteristic &a, const QLowEnergyCharacteristic &b)
Devuelve « true » si « a » y « b » no son iguales; en caso contrario, devuelve « false ».
Se considera que dos instancias de QLowEnergyCharacteristic son iguales si hacen referencia a la misma característica en el mismo dispositivo Bluetooth Low Energy remoto o si ambas instancias se han creado de forma predeterminada.
bool operator==(const QLowEnergyCharacteristic &a, const QLowEnergyCharacteristic &b)
Devuelve ` true ` si ` a ` es igual a ` b`; en caso contrario, devuelve ` false`.
Se considera que dos instancias de ` QLowEnergyCharacteristic ` son iguales si hacen referencia a la misma característica en el mismo dispositivo Bluetooth Low Energy remoto o si ambas instancias se han creado de forma predeterminada.
© 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.