En esta página

QBluetoothDeviceDiscoveryAgent Class

La clase `QBluetoothDeviceDiscoveryAgent` detecta los dispositivos Bluetooth cercanos. Más información...

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

Tipos públicos

enum DiscoveryMethod { NoMethod, ClassicMethod, LowEnergyMethod }
flags DiscoveryMethods
enum Error { NoError, PoweredOffError, InputOutputError, InvalidBluetoothAdapterError, UnsupportedPlatformError, …, UnknownError }

Funciones públicas

QBluetoothDeviceDiscoveryAgent(QObject *parent = nullptr)
QBluetoothDeviceDiscoveryAgent(const QBluetoothAddress &deviceAdapter, QObject *parent = nullptr)
virtual ~QBluetoothDeviceDiscoveryAgent()
QList<QBluetoothDeviceInfo> discoveredDevices() const
QBluetoothDeviceDiscoveryAgent::Error error() const
QString errorString() const
bool isActive() const
int lowEnergyDiscoveryTimeout() const
void setLowEnergyDiscoveryTimeout(int timeout)

Ranuras públicas

void start()
void start(QBluetoothDeviceDiscoveryAgent::DiscoveryMethods methods)
void stop()

Señales

void canceled()
void deviceDiscovered(const QBluetoothDeviceInfo &info)
void deviceUpdated(const QBluetoothDeviceInfo &info, QBluetoothDeviceInfo::Fields updatedFields)
(since 6.2) void errorOccurred(QBluetoothDeviceDiscoveryAgent::Error error)
void finished()

Miembros públicos estáticos

QBluetoothDeviceDiscoveryAgent::DiscoveryMethods supportedDiscoveryMethods()

Descripción detallada

Para detectar los dispositivos Bluetooth cercanos:

void MyClass::startDeviceDiscovery()
{

    // Crear un agente de detección y conectarse a sus señales
    QBluetoothDeviceDiscoveryAgent*discoveryAgent = new QBluetoothDeviceDiscoveryAgent(this);
    connect(discoveryAgent, SIGNAL(deviceDiscovered(QBluetoothDeviceInfo)),
            this, SLOT(deviceDiscovered(QBluetoothDeviceInfo)));

    // Iniciar un proceso de detección
    discoveryAgent->start();

    //...
}

// En tu slot local, lee la información sobre los dispositivos encontrados
void MyClass::deviceDiscovered(const QBluetoothDeviceInfo&device)
{
    qDebug() << "Found new device:" << device.name() << '(' << device.address().toString() << ')';
}

Para recuperar los resultados de forma asíncrona, conéctate a la señal « deviceDiscovered()». Para obtener una lista de todos los dispositivos detectados, llama a « discoveredDevices()» tras la señal « finished()».

Esta clase se puede utilizar para detectar dispositivos Bluetooth clásicos y de baja energía. El tipo concreto de dispositivo se puede determinar mediante el atributo « QBluetoothDeviceInfo::coreConfigurations()». En la mayoría de los casos, la lista devuelta por « discoveredDevices()» contiene ambos tipos de dispositivos. Sin embargo, no todas las plataformas pueden detectar ambos tipos de dispositivos. En las plataformas con esta limitación (por ejemplo, iOS solo admite la detección de dispositivos de baja energía), el proceso de detección limitará la búsqueda al tipo que sea compatible.

Nota: A partir de Android 6.0, la capacidad de detectar dispositivos requiere el permiso ACCESS_COARSE_LOCATION.

Nota: El backend Win32 no admite actualmente el indicador de intensidad de señal recibida (RSSI), ni los datos específicos del fabricante, ni otras actualizaciones de datos anunciadas por los dispositivos Bluetooth LE tras el descubrimiento.

Documentación sobre tipos de miembro

enum QBluetoothDeviceDiscoveryAgent::DiscoveryMethod
flags QBluetoothDeviceDiscoveryAgent::DiscoveryMethods

Esta enumeración describe el tipo de método de detección utilizado por el QBluetoothDeviceDiscoveryAgent.

ConstanteValorDescripción
QBluetoothDeviceDiscoveryAgent::NoMethod0x0El descubrimiento no es posible. No se admite ninguno de los métodos disponibles.
QBluetoothDeviceDiscoveryAgent::ClassicMethod0x01El proceso de detección busca dispositivos Bluetooth Classic (BaseRate).
QBluetoothDeviceDiscoveryAgent::LowEnergyMethod0x02El proceso de detección busca dispositivos Bluetooth Low Energy.

El tipo DiscoveryMethods es una definición de tipo para QFlags<DiscoveryMethod>. Almacena una combinación OR de valores de DiscoveryMethod.

Véase también supportedDiscoveryMethods().

enum QBluetoothDeviceDiscoveryAgent::Error

Indica todas las posibles condiciones de error detectadas durante la búsqueda de dispositivos Bluetooth.

ConstanteValorDescripción
QBluetoothDeviceDiscoveryAgent::NoError0No se ha producido ningún error.
QBluetoothDeviceDiscoveryAgent::PoweredOffError2El adaptador Bluetooth está apagado; enciéndelo antes de realizar la búsqueda.
QBluetoothDeviceDiscoveryAgent::InputOutputError1Se ha producido un error al escribir o leer en el dispositivo.
QBluetoothDeviceDiscoveryAgent::InvalidBluetoothAdapterError3La dirección del adaptador local pasada no coincide con la dirección física de ningún dispositivo Bluetooth local.
QBluetoothDeviceDiscoveryAgent::UnsupportedPlatformError (since Qt 5.5)4La búsqueda de dispositivos no es posible o no está implementada en la plataforma actual. El error se produce en respuesta a una llamada a ` start()`. Un ejemplo de estos casos son las versiones de iOS anteriores a la 5.0, que no admiten en absoluto la búsqueda de dispositivos Bluetooth.
QBluetoothDeviceDiscoveryAgent::UnsupportedDiscoveryMethod (since Qt 5.8)5La plataforma actual no admite uno de los métodos de detección solicitados.
QBluetoothDeviceDiscoveryAgent::LocationServiceTurnedOffError (since Qt 6.2)6El servicio de localización está desactivado. No es posible utilizar las API de Bluetooth cuando el servicio de localización está desactivado.
QBluetoothDeviceDiscoveryAgent::MissingPermissionsError (since Qt 6.4)7El sistema operativo solicita permisos que el usuario no ha concedido.
QBluetoothDeviceDiscoveryAgent::UnknownError100Se ha producido un error desconocido.

Documentación de funciones de miembro

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

Crea un nuevo agente de detección de dispositivos Bluetooth con el padre parent.

[explicit] QBluetoothDeviceDiscoveryAgent::QBluetoothDeviceDiscoveryAgent(const QBluetoothAddress &deviceAdapter, QObject *parent = nullptr)

Crea un nuevo agente de detección de dispositivos Bluetooth con ` parent`.

Utiliza deviceAdapter para la búsqueda de dispositivos. Si deviceAdapter se crea de forma predeterminada, el objeto QBluetoothDeviceDiscoveryAgent resultante utilizará el adaptador Bluetooth predeterminado local.

Si se especifica un ` deviceAdapter ` que no sea un adaptador local, ` error()` se establecerá en ` InvalidBluetoothAdapterError`. Por lo tanto, se recomienda comprobar el indicador de error inmediatamente después de utilizar este constructor.

Véase también error().

[virtual noexcept] QBluetoothDeviceDiscoveryAgent::~QBluetoothDeviceDiscoveryAgent()

Destructor para ~QBluetoothDeviceDiscoveryAgent()

[signal] void QBluetoothDeviceDiscoveryAgent::canceled()

Esta señal se emite cuando la detección de dispositivos se interrumpe mediante una llamada a la función ` stop()`.

[signal] void QBluetoothDeviceDiscoveryAgent::deviceDiscovered(const QBluetoothDeviceInfo &info)

Esta señal se emite cuando se detecta el dispositivo Bluetooth descrito en info.

La señal se emite tan pronto como se ha recopilado la información más importante del dispositivo. Sin embargo, mientras no se haya emitido la señal finished(), la recopilación de información continúa incluso para los dispositivos ya detectados. Esto es especialmente cierto en el caso de la información sobre la intensidad de la señal (RSSI) y las actualizaciones de los datos del fabricante. Si el caso de uso requiere actualizaciones continuas de los datos del fabricante o del RSSI, es recomendable recuperar la información del dispositivo mediante discoveredDevices() una vez finalizada la detección o escuchar la señal deviceUpdated().

Si lowEnergyDiscoveryTimeout() es mayor que 0, la señal solo se emite cuando cambia al menos un atributo de info. Esto refleja el deseo de recibir actualizaciones a medida que se dispone de información más precisa. La excepción a este comportamiento se da cuando ` lowEnergyDiscoveryTimeout ` se establece en ` 0`. Un tiempo de espera de ` 0 ` indica el deseo de supervisar la aparición y desaparición de dispositivos de baja energía a lo largo del tiempo. En esta condición, la señal `deviceDiscovered()` se emite incluso si ` info ` no ha cambiado desde la última emisión de la señal.

Véase también QBluetoothDeviceInfo::rssi() y lowEnergyDiscoveryTimeout().

[signal] void QBluetoothDeviceDiscoveryAgent::deviceUpdated(const QBluetoothDeviceInfo &info, QBluetoothDeviceInfo::Fields updatedFields)

Esta señal se emite cuando el agente recibe información adicional sobre el dispositivo Bluetooth descrito en info. Los indicadores updatedFields indican qué información se ha actualizado.

Durante el proceso de detección, algunos datos pueden cambiar dinámicamente, como signal strength y manufacturerData. Esta señal te indica que, si tu aplicación está mostrando estos datos, puede actualizarlos en lugar de esperar a que finalice el proceso de detección.

Véase también QBluetoothDeviceInfo::rssi() y lowEnergyDiscoveryTimeout().

QList<QBluetoothDeviceInfo> QBluetoothDeviceDiscoveryAgent::discoveredDevices() const

Devuelve una lista de todos los dispositivos Bluetooth detectados.

QBluetoothDeviceDiscoveryAgent::Error QBluetoothDeviceDiscoveryAgent::error() const

Devuelve el último error.

Cualquier posible error anterior se borra al reiniciar el proceso de detección.

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

Esta señal se emite cuando se produce un error de « error » durante la detección de dispositivos Bluetooth. El parámetro « error » describe el error que se ha producido.

Esta función se introdujo en Qt 6.2.

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

QString QBluetoothDeviceDiscoveryAgent::errorString() const

Devuelve una descripción comprensible para el usuario del último error.

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

[signal] void QBluetoothDeviceDiscoveryAgent::finished()

Esta señal se emite cuando finaliza la búsqueda de dispositivos Bluetooth. La señal no se emitirá si la búsqueda de dispositivos finaliza con un error.

bool QBluetoothDeviceDiscoveryAgent::isActive() const

Devuelve «true» si el agente está buscando dispositivos Bluetooth en ese momento; en caso contrario, devuelve «false».

int QBluetoothDeviceDiscoveryAgent::lowEnergyDiscoveryTimeout() const

Devuelve un tiempo de espera, expresado en milisegundos, que se aplica a la búsqueda de dispositivos Bluetooth Low Energy. Un valor de -1 implica que la plataforma no admite esta propiedad y que el tiempo de espera para la búsqueda de dispositivos no se puede ajustar. Un valor de retorno de 0 implica una búsqueda sin fin que debe detenerse manualmente mediante stop().

Véase también setLowEnergyDiscoveryTimeout().

void QBluetoothDeviceDiscoveryAgent::setLowEnergyDiscoveryTimeout(int timeout)

Establece el tiempo máximo de búsqueda de dispositivos Bluetooth Low Energy en timeout, expresado en milisegundos. Si timeout es 0, el proceso de detección continúa hasta que se llama a stop().

Esto refleja el hecho de que el proceso de detección de dispositivos Bluetooth Low Energy suele ser de duración indefinida. La plataforma sigue buscando más dispositivos hasta que la búsqueda se detiene manualmente. El tiempo de espera garantiza que la búsqueda se interrumpa tras timeout milisegundos. Por supuesto, sigue siendo posible interrumpir manualmente la detección llamando a stop().

El nuevo valor de tiempo de espera no surtirá efecto hasta que se reinicie la búsqueda de dispositivos. Además, el tiempo de espera no afecta a la búsqueda clásica de dispositivos Bluetooth. Dependiendo de la plataforma, la búsqueda clásica puede alargar la duración total del proceso de detección más allá de timeout.

Para un descubrimiento fiable de Bluetooth Low Energy, utiliza al menos 40 000 milisegundos.

Véase también lowEnergyDiscoveryTimeout().

[slot] void QBluetoothDeviceDiscoveryAgent::start()

Inicia la detección de dispositivos Bluetooth, si aún no se ha iniciado.

Se emite la señal « deviceDiscovered()» cada vez que se detecta un dispositivo. La señal « finished()» se emite una vez finalizada la detección de dispositivos. La detección utiliza el conjunto máximo de métodos de detección compatibles con la plataforma.

Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        bluetoothDeviceDiscoveryAgent, qOverload<>(&QBluetoothDeviceDiscoveryAgent::start));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        bluetoothDeviceDiscoveryAgent, [receiver = bluetoothDeviceDiscoveryAgent]() { receiver->start(); });
Para ver más ejemplos y enfoques, consulta «Conexión a ranuras sobrecargadas».

Véase también supportedDiscoveryMethods().

[slot] void QBluetoothDeviceDiscoveryAgent::start(QBluetoothDeviceDiscoveryAgent::DiscoveryMethods methods)

Inicia la detección de dispositivos Bluetooth, si aún no se ha iniciado y si los parámetros « methods » proporcionados son compatibles. Los parámetros « methods » limitan el alcance de la búsqueda de dispositivos. Por ejemplo, si el servicio o dispositivo de destino es un dispositivo Bluetooth Low Energy, esta función podría utilizarse para limitar la búsqueda a dispositivos Bluetooth Low Energy y, de este modo, reducir significativamente el tiempo de detección.

Nota: methods solo determina el tipo de búsqueda y no implica el filtrado de los resultados. Por ejemplo, la búsqueda puede seguir incluyendo dispositivos Bluetooth clásicos a pesar de que methods esté configurado únicamente en LowEnergyMethod. Esto puede deberse a resultados de búsqueda almacenados previamente en la caché que pueden incorporarse a los resultados de la búsqueda.

Nota: Algunas plataformas (por ejemplo, Windows) también pueden proporcionar resultados almacenados en caché de dispositivos que no están anunciándose en ese momento. Otras plataformas (como iOS) solo proporcionan información sobre los dispositivos que se están anunciando actualmente. Puedes almacenar el UUID del dispositivo recibido (o la dirección Bluetooth) tras el primer descubrimiento y, posteriormente, utilizarlo para establecer una conexión directamente (véase QBluetoothDeviceInfo). De esta forma, las aplicaciones pueden omitir las fases posteriores de descubrimiento de dispositivos. El uso de la dirección Bluetooth requiere que la dirección Bluetooth del dispositivo remoto no cambie.

Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        bluetoothDeviceDiscoveryAgent, qOverload(&QBluetoothDeviceDiscoveryAgent::start));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        bluetoothDeviceDiscoveryAgent, [receiver = bluetoothDeviceDiscoveryAgent](QBluetoothDeviceDiscoveryAgent::DiscoveryMethods methods) { receiver->start(methods); });
Para ver más ejemplos y enfoques, consulta «Conexión a ranuras sobrecargadas».

[slot] void QBluetoothDeviceDiscoveryAgent::stop()

Detiene la búsqueda de dispositivos Bluetooth. La señal `cancel()` se emite una vez que se cancela la búsqueda de dispositivos. Se puede llamar a ` start()` antes de que se reciba la señal `cancel()`. Una vez que se haya llamado a ` start()`, la señal `cancel()` de la búsqueda anterior se descartará.

[static] QBluetoothDeviceDiscoveryAgent::DiscoveryMethods QBluetoothDeviceDiscoveryAgent::supportedDiscoveryMethods()

Esta función devuelve los métodos de detección compatibles con la plataforma actual. Se puede utilizar para limitar el alcance de la detección de dispositivos.

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