QLowEnergyController Class

Documentación de las funciones miembro

[virtual noexcept] QLowEnergyController::~QLowEnergyController()

Destruye la instancia QLowEnergyController.

QLowEnergyService *QLowEnergyController::addService(const QLowEnergyServiceData &service, QObject *parent = nullptr)

Construye y devuelve un objeto QLowEnergyService con parent desde service. El controlador debe estar en PeripheralRole y en UnconnectedState. El objeto service debe ser válido.

Véase también stopAdvertising(), disconnectFromDevice() y QLowEnergyServiceData::addIncludedService.

void QLowEnergyController::connectToDevice()

Se conecta al dispositivo Bluetooth Low Energy remoto.

Esta función no hace nada si la señal state() del controlador no es igual a UnconnectedState. La señal connected() se emite una vez que la conexión se ha establecido correctamente.

En sistemas Linux/BlueZ, no es posible conectarse al mismo dispositivo remoto utilizando dos instancias de esta clase. La segunda llamada a esta función puede fallar con un error. Es posible que esta limitación se elimine en futuras versiones.

Véase también disconnectFromDevice().

[signal] void QLowEnergyController::connected()

Esta señal se emite cuando el controlador se conecta con éxito al dispositivo remoto de baja energía (si el controlador está en CentralRole) o si un dispositivo remoto de baja energía se conectó al controlador (si el controlador está en PeripheralRole). En iOS, macOS y Android esta señal no es fiable si el controlador está en PeripheralRole. En iOS y macOS el controlador sólo adivina que alguna central se conectó a nuestro periférico en cuanto esta central intenta escribir/leer una característica/descriptor. En Android el controlador monitoriza todos los dispositivos GATT conectados. En Linux BlueZ DBus peripheral backend la central se considera conectada cuando lee/escribe por primera vez una característica o un descriptor.

[signal] void QLowEnergyController::connectionUpdated(const QLowEnergyConnectionParameters &newParameters)

Esta señal se emite cuando cambian los parámetros de la conexión. Esto puede ocurrir como resultado de llamar a requestConnectionUpdate() o por otras razones, por ejemplo porque el otro lado de la conexión solicitó nuevos parámetros. Los nuevos valores pueden recuperarse desde newParameters.

Véase también requestConnectionUpdate().

[static] QLowEnergyController *QLowEnergyController::createCentral(const QBluetoothDeviceInfo &remoteDevice, QObject *parent = nullptr)

Devuelve un nuevo objeto de esta clase que está en CentralRole y tiene como objeto padre parent. El remoteDevice se refiere al dispositivo con el que se establecerá una conexión posteriormente.

El controlador utiliza el adaptador Bluetooth local por defecto para la gestión de la conexión.

Véase también QLowEnergyController::CentralRole.

[static] QLowEnergyController *QLowEnergyController::createCentral(const QBluetoothDeviceInfo &remoteDevice, const QBluetoothAddress &localDevice, QObject *parent = nullptr)

Devuelve una nueva instancia de esta clase con parent.

remoteDevice debe contener la dirección del dispositivo Bluetooth Low Energy remoto al que este objeto debe intentar conectarse posteriormente.

La conexión se establece a través de localDevice. Si localDevice no es válido, se selecciona automáticamente el dispositivo local por defecto. Si localDevice especifica un dispositivo local que no es un adaptador Bluetooth local, error() se convierte en InvalidBluetoothAdapterError una vez que se llama a connectToDevice().

Tenga en cuenta que especificar el dispositivo local que se utilizará para la conexión sólo es posible cuando se utiliza BlueZ. El resto de plataformas no admiten esta función.

[static] QLowEnergyController *QLowEnergyController::createPeripheral(QObject *parent = nullptr)

Devuelve un nuevo objeto de esta clase que está en PeripheralRole y tiene el objeto padre parent. Normalmente, los siguientes pasos son añadir algunos servicios y finalmente llamar a startAdvertising() sobre el objeto devuelto.

El controlador utiliza el adaptador Bluetooth local por defecto para la gestión de la conexión.

Véase también QLowEnergyController::PeripheralRole.

[static, since 6.2] QLowEnergyController *QLowEnergyController::createPeripheral(const QBluetoothAddress &localDevice, QObject *parent = nullptr)

Devuelve un nuevo objeto de esta clase que está en PeripheralRole y tiene el objeto padre parent y está usando localDevice. Típicamente, los siguientes pasos son añadir algunos servicios y finalmente llamar a startAdvertising() sobre el objeto devuelto.

El periférico se crea en localDevice. Si localDevice no es válido, se selecciona automáticamente el dispositivo local por defecto. Si localDevice especifica un dispositivo local que no es un adaptador Bluetooth local, error() se establece en InvalidBluetoothAdapterError.

La selección de localDevice sólo se admite en Linux. En otras plataformas, el parámetro se ignora.

Esta función se introdujo en Qt 6.2.

Véase también QLowEnergyController::PeripheralRole.

QLowEnergyService *QLowEnergyController::createServiceObject(const QBluetoothUuid &serviceUuid, QObject *parent = nullptr)

Crea una instancia del servicio representado por serviceUuid. El parámetro serviceUuid debe haberse obtenido a través de services().

La persona que llama toma la propiedad del puntero devuelto y puede pasar un parámetro parent como propietario por defecto.

Esta función devuelve un puntero nulo si no se encuentra ningún servicio con serviceUuid en el dispositivo remoto o si el controlador está desconectado.

Esta función también puede devolver instancias para servicios secundarios. Las relaciones de inclusión entre servicios pueden expresarse mediante QLowEnergyService::includedServices().

Si se llama a esta función varias veces utilizando el mismo UUID de servicio, las instancias QLowEnergyService devueltas comparten sus datos internos. Por lo tanto, si una de las instancias inicia el descubrimiento de los detalles del servicio, las demás instancias también pasan automáticamente al estado de descubrimiento.

Véase también services().

void QLowEnergyController::disconnectFromDevice()

Se desconecta del dispositivo remoto.

Cualquier instancia de QLowEnergyService, QLowEnergyCharacteristic o QLowEnergyDescriptor resultante de la conexión actual se invalida automáticamente. Una vez que cualquiera de esos objetos se invalida, permanecen inválidos incluso si este objeto controlador se vuelve a conectar.

Esta función no hace nada si el controlador está en UnconnectedState.

Si el controlador está en el rol periférico, detiene la publicidad y elimina todos los servicios que hayan sido añadidos previamente a través de addService(). Para reutilizar la instancia QLowEnergyController, la aplicación debe volver a añadir servicios y reiniciar el modo de publicidad llamando a startAdvertising().

Véase también connectToDevice().

[signal] void QLowEnergyController::disconnected()

Esta señal se emite cuando el controlador se desconecta del dispositivo remoto de baja energía o viceversa. En iOS y macOS esta señal no es fiable si el controlador está en PeripheralRole. En Android la señal se emite cuando el último dispositivo conectado se desconecta. En BlueZ DBus backend el controlador se considera desconectado cuando el último cliente que ha accedido a los atributos se ha desconectado.

void QLowEnergyController::discoverServices()

Inicia el proceso de descubrimiento del servicio.

El progreso del descubrimiento se indica mediante la señal serviceDiscovered(). La señal discoveryFinished() se emite cuando el proceso ha finalizado.

Si la instancia del controlador no está conectada o el controlador ya ha realizado el descubrimiento de servicios, esta función no hará nada.

[signal] void QLowEnergyController::discoveryFinished()

Esta señal se emite cuando finaliza el descubrimiento del servicio en ejecución. La señal no se emite si el proceso de descubrimiento finaliza con un error.

Esta señal sólo puede emitirse si el controlador se encuentra en CentralRole.

Véase también discoverServices() y error().

QLowEnergyController::Error QLowEnergyController::error() const

Devuelve el último error ocurrido o NoError.

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

Véase también error() y errorString().

QString QLowEnergyController::errorString() const

Devuelve una representación textual del último error ocurrido. La cadena se traduce.

QBluetoothAddress QLowEnergyController::localAddress() const

Devuelve la dirección del adaptador Bluetooth local que se está utilizando para la comunicación.

Si se solicitó que esta instancia de clase utilizara el adaptador predeterminado, pero no había ningún adaptador predeterminado cuando se creó esta instancia de clase, el QBluetoothAddress devuelto será null.

Véase también QBluetoothAddress::isNull().

[since 6.2] int QLowEnergyController::mtu() const

Devuelve el tamaño de la MTU.

Durante la configuración de la conexión, se negocia el tamaño de la MTU de ATT. Este método proporciona el resultado de esta negociación. Puede utilizarse para optimizar el tamaño de los paquetes en algunas situaciones. La cantidad máxima de datos que se pueden transferir en un solo paquete es mtu-3 bytes. Se necesitan 3 bytes para la cabecera del protocolo ATT.

Antes de la configuración de la conexión y la negociación de MTU, se devolverá el valor por defecto de 23.

No todas las plataformas exponen el valor MTU. En esas plataformas (por ejemplo, Linux) esta función siempre devuelve -1.

Si el controlador está en PeripheralRole, puede haber varios dispositivos centrales conectados a él. En esos casos esta función devuelve la MTU de la última conexión que se negoció.

Esta función se introdujo en Qt 6.2.

[signal] void QLowEnergyController::mtuChanged(int mtu)

Esta señal se emite como resultado de un cambio exitoso de MTU. mtu representa el nuevo valor.

Véase también mtu().

[since 6.5] void QLowEnergyController::readRssi()

readRssi() lee el RSSI (indicador de intensidad de señal recibida) de un dispositivo remoto conectado. Si la lectura se ha realizado correctamente, el RSSI se notifica mediante la señal rssiRead().

Esta función se introdujo en Qt 6.5.

Véase también rssiRead(), connectToDevice(), state(), createCentral() y errorOccurred().

QBluetoothAddress QLowEnergyController::remoteAddress() const

Devuelve la dirección del dispositivo Bluetooth Low Energy remoto.

Para un controlador en CentralRole, este valor siempre será el que se pasó cuando se creó el objeto controlador. Para un controlador en PeripheralRole, este valor es una de las direcciones del dispositivo cliente conectado actualmente. Esta dirección no será válida si el controlador no se encuentra actualmente en ConnectedState.

QLowEnergyController::RemoteAddressType QLowEnergyController::remoteAddressType() const

Devuelve el tipo de remoteAddress(). Por defecto, este valor se inicializa a PublicAddress.

Véase también setRemoteAddressType().

QBluetoothUuid QLowEnergyController::remoteDeviceUuid() const

Devuelve el identificador único del dispositivo Bluetooth Low Energy remoto.

En macOS/iOS/tvOS CoreBluetooth no expone/acepta direcciones hardware para dispositivos LE; en su lugar los desarrolladores deben usar UUIDs únicos de 128 bits, generados por CoreBluetooth. Estos UUIDS permanecerán constantes para el mismo par central <-> periférico y los utilizaremos cuando nos conectemos a un dispositivo remoto. Para un controlador en CentralRole, este valor será siempre el que se pasó cuando se creó el objeto controlador. Para un controlador en PeripheralRole, este valor no es válido.

QString QLowEnergyController::remoteName() const

Devuelve el nombre del dispositivo Bluetooth Low Energy remoto, si el controlador se encuentra en CentralRole. De lo contrario, el resultado no se especifica.

void QLowEnergyController::requestConnectionUpdate(const QLowEnergyConnectionParameters &parameters)

Solicita al controlador que actualice la conexión según parameters. Si la solicitud tiene éxito, se emitirá la señal connectionUpdated() con los nuevos parámetros reales. Consulte la clase QLowEnergyConnectionParameters para obtener más información sobre los parámetros de conexión.

Android sólo permite indirectamente el ajuste de este conjunto de parámetros. Los parámetros de conexión están separados en tres categorías (prioridad alta, baja y equilibrada). Cada categoría implica un conjunto preconfigurado de valores para QLowEnergyConnectionParameters::minimumInterval(), QLowEnergyConnectionParameters::maximumInterval() y QLowEnergyConnectionParameters::latency(). Aunque la solicitud de conexión es una operación asíncrona, Android no proporciona una llamada de retorno que indique el resultado de la solicitud. Se trata de un error reconocido de Android. Debido a este bug Android no emite la señal connectionUpdated().

Véase también connectionUpdated().

QLowEnergyController::Role QLowEnergyController::role() const

Devuelve el rol en el que se encuentra este objeto controlador.

El rol se determina al construir una instancia de QLowEnergyController utilizando createCentral() o createPeripheral().

[signal, since 6.5] void QLowEnergyController::rssiRead(qint16 rssi)

Esta señal se emite tras la lectura correcta del RSSI (indicador de intensidad de señal recibida) de un dispositivo remoto conectado. El parámetro rssi representa el nuevo valor.

Esta función se introdujo en Qt 6.5.

Véase también readRssi().

[signal] void QLowEnergyController::serviceDiscovered(const QBluetoothUuid &newService)

Esta señal se emite cada vez que se descubre un nuevo servicio. El parámetro newService contiene el UUID del servicio encontrado.

Esta señal sólo puede emitirse si el controlador se encuentra en CentralRole.

Véase también discoverServices() y discoveryFinished().

QList<QBluetoothUuid> QLowEnergyController::services() const

Devuelve la lista de servicios ofrecidos por el dispositivo remoto, si el controlador se encuentra en CentralRole. De lo contrario, el resultado no se especifica.

La lista contiene todos los servicios primarios y secundarios.

Véase también createServiceObject().

void QLowEnergyController::setRemoteAddressType(QLowEnergyController::RemoteAddressType type)

Establece la dirección remota type. El tipo es necesario para conectar con el dispositivo Bluetooth Low Energy remoto.

Sólo es necesario establecer este atributo en sistemas Linux/BlueZ con kernels Linux antiguos (v3.3 o inferior), o si CAP_NET_ADMIN no está establecido para el ejecutable. El valor por defecto del atributo es RandomAddress.

Véase también remoteAddressType().

void QLowEnergyController::startAdvertising(const QLowEnergyAdvertisingParameters &parameters, const QLowEnergyAdvertisingData &advertisingData, const QLowEnergyAdvertisingData &scanResponseData = QLowEnergyAdvertisingData())

Inicia la publicidad de los datos indicados en advertisingData y scanResponseData, utilizando los parámetros establecidos en parameters. PeripheralRole Si parameters indica que el anuncio debe ser conectable, entonces esta función también comienza a escuchar las conexiones entrantes de los clientes.

Proporcionar scanResponseData no es necesario, ya que no es aplicable para ciertas configuraciones de parameters. advertisingData y scanResponseData están limitados a datos de usuario de 31 bytes. Si, por ejemplo, se añaden varios uuids de 128 bits a advertisingData, es posible que los paquetes anunciados no contengan todos los uuids. El límite existente puede haber provocado el truncamiento de los uuids. En tales casos, puede utilizarse scanResponseData para obtener información adicional.

En BlueZ DBus backend BlueZ decide si, y qué datos, utilizar en una respuesta de escaneo. Por lo tanto, se recomienda establecer todos los datos de publicidad en el parámetro principal advertisingData. Si se definen tanto los datos de publicidad como los de respuesta de escaneo, tendrán prioridad los datos de respuesta de escaneo.

Si este objeto no está actualmente en UnconnectedState, no ocurre nada.

Véase también stopAdvertising().

QLowEnergyController::ControllerState QLowEnergyController::state() const

Devuelve el estado actual del controlador.

Véase también stateChanged().

[signal] void QLowEnergyController::stateChanged(QLowEnergyController::ControllerState state)

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

Véase también state().

void QLowEnergyController::stopAdvertising()

Detiene la publicidad, si este objeto se encuentra actualmente en estado de publicidad.

El controlador debe estar en PeripheralRole para que esta función funcione. No invalida los servicios que se hayan añadido previamente mediante addService().

Véase también startAdvertising().