En esta página

QBluetoothLocalDevice Class

La clase QBluetoothLocalDevice permite acceder al dispositivo Bluetooth local. Más información...

Encabezado: #include <QBluetoothLocalDevice>
CMake: find_package(Qt6 REQUIRED COMPONENTS Bluetooth)
target_link_libraries(mytarget PRIVATE Qt6::Bluetooth)
qmake: QT += bluetooth
Heredado de: QObject

Tipos públicos

enum Error { NoError, PairingError, MissingPermissionsError, UnknownError }
enum HostMode { HostPoweredOff, HostConnectable, HostDiscoverable, HostDiscoverableLimitedInquiry }
enum Pairing { Unpaired, Paired, AuthorizedPaired }

Funciones públicas

QBluetoothLocalDevice(QObject *parent = nullptr)
QBluetoothLocalDevice(const QBluetoothAddress &address, QObject *parent = 0)
virtual ~QBluetoothLocalDevice()
QBluetoothAddress address() const
QList<QBluetoothAddress> connectedDevices() const
QBluetoothLocalDevice::HostMode hostMode() const
bool isValid() const
QString name() const
QBluetoothLocalDevice::Pairing pairingStatus(const QBluetoothAddress &address) const
void powerOn()
void requestPairing(const QBluetoothAddress &address, QBluetoothLocalDevice::Pairing pairing)
void setHostMode(QBluetoothLocalDevice::HostMode mode)

Señales

void deviceConnected(const QBluetoothAddress &address)
void deviceDisconnected(const QBluetoothAddress &address)
(since 6.2) void errorOccurred(QBluetoothLocalDevice::Error error)
void hostModeStateChanged(QBluetoothLocalDevice::HostMode state)
void pairingFinished(const QBluetoothAddress &address, QBluetoothLocalDevice::Pairing pairing)

Miembros públicos estáticos

QList<QBluetoothHostInfo> allDevices()

Descripción detallada

QBluetoothLocalDevice proporciona funciones para obtener y configurar el estado de los dispositivos Bluetooth locales.

En iOS, esta clase no se puede utilizar porque la plataforma no expone ningún dato ni API que pueda proporcionar información sobre el dispositivo Bluetooth local.

Documentación sobre los tipos de miembros

enum QBluetoothLocalDevice::Error

Esta enumeración describe los errores que pueden devolverse

ConstanteValorDescripción
QBluetoothLocalDevice::NoError0No se conoce ningún error
QBluetoothLocalDevice::PairingError1Error en el emparejamiento
QBluetoothLocalDevice::MissingPermissionsError (since Qt 6.4)2El sistema operativo solicita permisos que el usuario no ha concedido.
QBluetoothLocalDevice::UnknownError100Error desconocido

enum QBluetoothLocalDevice::HostMode

Esta enumeración describe la mayor parte de los dispositivos Bluetooth locales.

ConstanteValorDescripción
QBluetoothLocalDevice::HostPoweredOff0Apagar el dispositivo
QBluetoothLocalDevice::HostConnectable1Los dispositivos Bluetooth remotos pueden conectarse al dispositivo Bluetooth local si se han emparejado previamente con él o conocen su dirección. Esto enciende el dispositivo si estaba apagado.
QBluetoothLocalDevice::HostDiscoverable2Los dispositivos Bluetooth remotos pueden detectar la presencia del dispositivo Bluetooth local. El dispositivo también estará disponible para la conexión y encendido. En Android, este modo solo puede permanecer activo durante un máximo de 5 minutos.
QBluetoothLocalDevice::HostDiscoverableLimitedInquiry3Los dispositivos Bluetooth remotos pueden detectar la presencia del dispositivo Bluetooth local al realizar una consulta limitada. Esto debería utilizarse para localizar servicios que solo son detectables durante un periodo de tiempo limitado. Esto puede acelerar la detección entre dispositivos de juego, ya que la detección de servicios puede omitirse en dispositivos que no estén en modo «LimitedInquiry». En este modo, el dispositivo estará listo para conectarse y encendido, si es necesario. Este modo no es compatible con Android.

Nota: En macOS, no es posible configurar el ` hostMode()`. Los modos de host notificados se limitan a `HostPoweredOff` y `HostConnectable`.

Nota: En Windows, no es posible establecer la propiedad « hostMode » () en «HostDiscoverable» o «HostDiscoverableLimitedInquiry». El uso de estos modos equivale a «HostConnectable».

Nota: A partir de Android 13 (nivel de API 33), el estado HostPoweredOff se basa en una API de Android no pública, ya que la pública ha quedado obsoleta; véase (disable()). Esto podría cambiar en una futura versión de Android.

Nota: Al menos en Android 12, la configuración de visibilidad de Bluetooth del dispositivo puede determinar el resultado al establecer HostDiscoverable o HostConnectable. Por ejemplo, si la visibilidad está desactivada, puede que no sea posible entrar en el modo HostDiscoverable, sino que se utilizará HostConnectable en su lugar. Esto puede cambiar en futuras versiones de Android.

enum QBluetoothLocalDevice::Pairing

Esta enumeración describe el estado de emparejamiento entre los dos dispositivos Bluetooth.

ConstanteValorDescripción
QBluetoothLocalDevice::Unpaired0Los dispositivos Bluetooth no están emparejados.
QBluetoothLocalDevice::Paired1Los dispositivos Bluetooth están emparejados. El sistema solicitará autorización al usuario cuando el dispositivo remoto inicie una conexión con el dispositivo local.
QBluetoothLocalDevice::AuthorizedPaired2Los dispositivos Bluetooth están emparejados. El sistema no solicitará autorización al usuario cuando el dispositivo remoto inicie una conexión con el dispositivo local.

Documentación de funciones de miembro

[explicit] QBluetoothLocalDevice::QBluetoothLocalDevice(QObject *parent = nullptr)

Crea un objeto `QBluetoothLocalDevice` con ` parent`.

Nota: A partir de Android 12 (nivel de API 31), la creación de esta clase requiere permisos de tiempo de ejecución de Bluetooth (BLUETOOTH_SCAN y BLUETOOTH_CONNECT). Si no se conceden los permisos, el dispositivo no será válido.

Véase también isValid().

[explicit] QBluetoothLocalDevice::QBluetoothLocalDevice(const QBluetoothAddress &address, QObject *parent = 0)

Crea un nuevo objeto `QBluetoothLocalDevice` para ` address`. Si se crea un objeto ` address ` mediante la construcción por defecto, el dispositivo local resultante seleccionará el dispositivo local por defecto.

Nota: A partir de Android 12 (nivel de API 31), la creación de esta clase requiere permisos de tiempo de ejecución de Bluetooth (BLUETOOTH_SCAN y BLUETOOTH_CONNECT). Si no se conceden los permisos, el dispositivo no será válido.

Véase también isValid().

[virtual noexcept] QBluetoothLocalDevice::~QBluetoothLocalDevice()

Destruye el « QBluetoothLocalDevice ».

QBluetoothAddress QBluetoothLocalDevice::address() const

Devuelve la dirección MAC de este dispositivo Bluetooth.

Nota: En Android, a partir de la versión 6.0, esta función siempre devuelve el valor constante 02:00:00:00:00:00 como dirección local. Se ha eliminado el acceso programático a la dirección MAC local del dispositivo.

[static] QList<QBluetoothHostInfo> QBluetoothLocalDevice::allDevices()

Devuelve una lista de todos los dispositivos Bluetooth locales disponibles. En macOS, solo existe el dispositivo local «predeterminado».

QList<QBluetoothAddress> QBluetoothLocalDevice::connectedDevices() const

Devuelve la lista de dispositivos conectados. Esta lista es diferente de la lista de dispositivos emparejados actualmente.

En Android y macOS, no es posible obtener una lista de dispositivos conectados. Solo es posible detectar los cambios de conexión y desconexión. Para mayor comodidad, esta clase supervisa todos los eventos de conexión y desconexión desde su instanciación y devuelve la lista actual al llamar a esta función. Por lo tanto, es posible que esta función devuelva una lista vacía poco después de crear una instancia.

Véanse también deviceConnected() y deviceDisconnected().

[signal] void QBluetoothLocalDevice::deviceConnected(const QBluetoothAddress &address)

Esta señal se emite cuando el dispositivo local establece una conexión con un dispositivo remoto mediante address.

Véase también deviceDisconnected() y connectedDevices().

[signal] void QBluetoothLocalDevice::deviceDisconnected(const QBluetoothAddress &address)

Esta señal se emite cuando el dispositivo local se desconecta de un dispositivo Bluetooth remoto con el estado « address ».

Véase también deviceConnected() y connectedDevices().

[signal, since 6.2] void QBluetoothLocalDevice::errorOccurred(QBluetoothLocalDevice::Error error)

Se emite una señal si se produce un error excepcional de « error » durante el emparejamiento.

Esta función se introdujo en Qt 6.2.

QBluetoothLocalDevice::HostMode QBluetoothLocalDevice::hostMode() const

Devuelve el modo de host actual de este dispositivo Bluetooth local. En macOS, puede ser « HostPoweredOff » o « HostConnectable ».

Véase también setHostMode().

[signal] void QBluetoothLocalDevice::hostModeStateChanged(QBluetoothLocalDevice::HostMode state)

La dirección state del servidor ha cambiado a HostMode.

bool QBluetoothLocalDevice::isValid() const

Devuelve ` true ` si el objeto ` QBluetoothLocalDevice ` representa un dispositivo Bluetooth local disponible; en caso contrario, devuelve `false`.

Si el adaptador Bluetooth local representado por una instancia de esta clase se retira del sistema (por ejemplo, al retirar el adaptador Bluetooth subyacente), dicha instancia dejará de ser válida. Una instancia de ` QBluetoothLocalDevice ` que ya sea inválida seguirá siéndolo incluso si se vuelve a conectar el mismo adaptador Bluetooth al sistema.

Nota: A partir de Android 12 (nivel de API 31), la creación de esta clase requiere permisos de tiempo de ejecución de Bluetooth (BLUETOOTH_SCAN y BLUETOOTH_CONNECT). Si no se conceden los permisos, el dispositivo no será válido.

Véase también allDevices().

QString QBluetoothLocalDevice::name() const

Devuelve el nombre que el usuario ha asignado a este dispositivo Bluetooth.

[signal] void QBluetoothLocalDevice::pairingFinished(const QBluetoothAddress &address, QBluetoothLocalDevice::Pairing pairing)

El emparejamiento o desemparejamiento se ha completado con address. El estado actual del emparejamiento se encuentra en pairing. Si la solicitud de emparejamiento no se ha realizado correctamente, no se emitirá esta señal. La señal errorOccurred() se emite si la solicitud de emparejamiento ha fallado. La señal solo se emite para aquellas solicitudes de emparejamiento que se hayan solicitado previamente llamando a requestPairing() de la instancia actual del objeto.

QBluetoothLocalDevice::Pairing QBluetoothLocalDevice::pairingStatus(const QBluetoothAddress &address) const

Devuelve el estado actual de emparejamiento por Bluetooth de address: si no está emparejado, si está emparejado o si está emparejado y autorizado.

void QBluetoothLocalDevice::powerOn()

Enciende el dispositivo tras devolverlo al estado « hostMode » (), si estaba apagado.

Nota: Debido a las diferentes políticas de seguridad de las plataformas compatibles, este método puede comportarse de forma distinta en cada una de ellas. Por ejemplo, el sistema puede solicitar al usuario que confirme antes de activar o desactivar el Bluetooth. En macOS no es posible activar ni desactivar el Bluetooth. Consulta la documentación específica de Bluetooth de cada plataforma para obtener más detalles.

void QBluetoothLocalDevice::requestPairing(const QBluetoothAddress &address, QBluetoothLocalDevice::Pairing pairing)

Establece el estado « pairing » con ` address`. Los resultados se devuelven mediante la señal ` pairingFinished()`.

En Android y macOS, el estado « AuthorizedPaired » no es posible y tendrá el mismo comportamiento que «Paired». En Windows, la decisión sobre el modo de emparejamiento exacto depende del sistema operativo.

En macOS, no es posible desemparejar un dispositivo. Si se solicita Unpaired, se emite inmediatamente pairingFinished(), aunque el dispositivo permanece emparejado. Es posible solicitar el emparejamiento de un dispositivo que haya estado desemparejado anteriormente. Además, AuthorizedPaired tiene el mismo comportamiento que Paired.

Precaución: establecer un emparejamiento puede tardar varios minutos y puede requerir la confirmación del usuario.

void QBluetoothLocalDevice::setHostMode(QBluetoothLocalDevice::HostMode mode)

Establece el modo de host de este dispositivo Bluetooth local en « mode ».

Algunas transiciones, como encender o apagar el dispositivo, pueden tardar un tiempo. Por lo tanto, las llamadas posteriores solo deben realizarse una vez que la señal hostModeStateChanged() haya concluido la solicitud anterior. Si se ignora esto, el resultado de dicha serie de llamadas no está bien definido.

Nota: Debido a las diferentes políticas de seguridad de las plataformas compatibles, este método puede comportarse de forma distinta en cada una de ellas. Por ejemplo, el sistema puede solicitar al usuario una confirmación antes de activar o desactivar el Bluetooth, y es posible que no todos los modos de host sean compatibles. En macOS, no es posible cambiar mediante programación el valor de hostMode(). El usuario solo puede activar o desactivar el Bluetooth en las Preferencias del Sistema. En Windows, este método debe llamarse desde el hilo de la interfaz de usuario, ya que podría requerir la confirmación del usuario. Consulta la documentación específica de Bluetooth de cada plataforma para obtener más detalles.

Véase también ` hostMode()`.

© 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.