En esta página

QBluetoothServiceDiscoveryAgent Class

La clase `QBluetoothServiceDiscoveryAgent` permite buscar servicios Bluetooth. Más información...

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

Tipos públicos

enum DiscoveryMode { MinimalDiscovery, FullDiscovery }
enum Error { NoError, PoweredOffError, InputOutputError, InvalidBluetoothAdapterError, MissingPermissionsError, UnknownError }

Funciones públicas

QBluetoothServiceDiscoveryAgent(QObject *parent = nullptr)
QBluetoothServiceDiscoveryAgent(const QBluetoothAddress &deviceAdapter, QObject *parent = nullptr)
virtual ~QBluetoothServiceDiscoveryAgent()
QList<QBluetoothServiceInfo> discoveredServices() const
QBluetoothServiceDiscoveryAgent::Error error() const
QString errorString() const
bool isActive() const
QBluetoothAddress remoteAddress() const
bool setRemoteAddress(const QBluetoothAddress &address)
void setUuidFilter(const QBluetoothUuid &uuid)
void setUuidFilter(const QList<QBluetoothUuid> &uuids)
QList<QBluetoothUuid> uuidFilter() const

Ranuras públicas

void clear()
void start(QBluetoothServiceDiscoveryAgent::DiscoveryMode mode = MinimalDiscovery)
void stop()

Señales

void canceled()
(since 6.2) void errorOccurred(QBluetoothServiceDiscoveryAgent::Error error)
void finished()
void serviceDiscovered(const QBluetoothServiceInfo &info)

Descripción detallada

El proceso de detección se basa en el proceso de detección de servicios Bluetooth (SDP). Para consultar los servicios que ofrecen todos los dispositivos Bluetooth con los que se puede establecer contacto, es necesario seguir los siguientes pasos:

  • crear una instancia de QBluetoothServiceDiscoveryAgent,
  • conectarse a las señales « serviceDiscovered()» o « finished()»,
  • y llamar a ` start()`.
void MyClass::startServiceDiscovery()
{

    // Crear un agente de descubrimiento y conectarse a sus señales
    QBluetoothServiceDiscoveryAgent*discoveryAgent = new QBluetoothServiceDiscoveryAgent(this);
    connect(discoveryAgent, SIGNAL(serviceDiscovered(QBluetoothServiceInfo)),
            this, SLOT(serviceDiscovered(QBluetoothServiceInfo)));

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

    //...
}

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

De forma predeterminada, se lleva a cabo un descubrimiento mínimo de servicios. En este modo, se garantiza que los objetos QBluetoothServiceInfo devueltos contengan únicamente información sobre el UUID del dispositivo y del servicio. Dependiendo de la plataforma y de las capacidades del dispositivo, también puede estar disponible otra información sobre el servicio. El modo de descubrimiento mínimo de servicios se basa en los datos SDP almacenados en la caché de la plataforma. Por lo tanto, es posible que este descubrimiento no encuentre un dispositivo aunque esté físicamente disponible. En tales casos, se debe realizar una búsqueda completa para forzar una actualización de la caché de la plataforma. Sin embargo, para la mayoría de los casos de uso, una búsqueda mínima es suficiente, ya que es mucho más rápida y otras clases que requieren información actualizada, como ` QBluetoothSocket::connectToService()`, realizarán una búsqueda adicional si es necesario. Si se requiere la información completa del servicio, pasa ` FullDiscovery ` como parámetro `discoveryMode` a ` start()`.

Esta clase puede utilizar internamente QBluetoothDeviceDiscoveryAgent para encontrar dispositivos desconocidos.

El descubrimiento de servicios también puede encontrar servicios Bluetooth Low Energy si el dispositivo de destino es una combinación de un dispositivo clásico y uno Low Energy. Dichos dispositivos deben anunciar sus servicios de baja energía a través de SDP. Si el dispositivo de destino solo admite servicios Bluetooth de baja energía, es probable que no los anuncie a través de SDP. Se debe utilizar la clase QLowEnergyController para realizar el descubrimiento de servicios en dispositivos de baja energía.

En iOS, esta clase no se puede utilizar porque la plataforma no expone una API que permita el acceso a las funciones relacionadas con QBluetoothServiceDiscoveryAgent.

Véase también QBluetoothDeviceDiscoveryAgent y QLowEnergyController.

Documentación sobre los tipos de miembros

enum QBluetoothServiceDiscoveryAgent::DiscoveryMode

Esta enumeración describe el modo de detección de servicios.

ConstanteValorDescripción
QBluetoothServiceDiscoveryAgent::MinimalDiscovery0Realiza un descubrimiento mínimo de servicios. Los objetos ` QBluetoothServiceInfo ` devueltos pueden estar incompletos y solo se garantiza que contengan información sobre el UUID del dispositivo y del servicio. Dado que un descubrimiento mínimo se basa en datos SDP almacenados en caché, es posible que no encuentre un dispositivo físicamente existente hasta que se realice un descubrimiento completo de servicios ( FullDiscovery ).
QBluetoothServiceDiscoveryAgent::FullDiscovery1Realiza un descubrimiento completo de servicios.

enum QBluetoothServiceDiscoveryAgent::Error

Esta enumeración describe los errores que pueden producirse durante la detección de servicios.

ConstanteValorDescripción
QBluetoothServiceDiscoveryAgent::NoErrorQBluetoothDeviceDiscoveryAgent::NoErrorNo se ha producido ningún error.
QBluetoothServiceDiscoveryAgent::PoweredOffErrorQBluetoothDeviceDiscoveryAgent::PoweredOffErrorEl adaptador Bluetooth está apagado; enciéndelo antes de realizar la detección.
QBluetoothServiceDiscoveryAgent::InputOutputErrorQBluetoothDeviceDiscoveryAgent::InputOutputErrorSe ha producido un error al escribir o leer en el dispositivo.
QBluetoothServiceDiscoveryAgent::InvalidBluetoothAdapterError (since Qt 5.3)QBluetoothDeviceDiscoveryAgent::InvalidBluetoothAdapterErrorLa dirección del adaptador local facilitada no coincide con la dirección física de ningún dispositivo Bluetooth local.
QBluetoothServiceDiscoveryAgent::MissingPermissionsError (since Qt 6.4)QBluetoothDeviceDiscoveryAgent::MissingPermissionsErrorEl sistema operativo solicita permisos que el usuario no ha concedido.
QBluetoothServiceDiscoveryAgent::UnknownErrorQBluetoothDeviceDiscoveryAgent::UnknownErrorSe ha producido un error desconocido.

Documentación de funciones de miembro

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

Crea un nuevo objeto `QBluetoothServiceDiscoveryAgent` con ` parent`. La búsqueda se realiza a través del adaptador Bluetooth predeterminado local.

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

Crea un nuevo QBluetoothServiceDiscoveryAgent para deviceAdapter y con parent.

Utiliza deviceAdapter para la búsqueda de servicios. Si deviceAdapter se crea de forma predeterminada, el objeto QBluetoothServiceDiscoveryAgent 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.

Nota: En WinRT se ignorará la dirección del adaptador pasada como parámetro.

Nota: En Android, pasar cualquier dirección deviceAdapter no tiene sentido, ya que Android 6.0 o versiones posteriores ya no publican la dirección Bluetooth local. Por consiguiente, la dirección del adaptador pasada nunca podrá coincidir con la dirección del adaptador local. Por lo tanto, la llamada posterior a start() siempre provocará InvalidBluetoothAdapterError.

Véase también error().

[virtual noexcept] QBluetoothServiceDiscoveryAgent::~QBluetoothServiceDiscoveryAgent()

Destructor para QBluetoothServiceDiscoveryAgent

[signal] void QBluetoothServiceDiscoveryAgent::canceled()

Esta señal se activa cuando se cancela la detección de servicios mediante una llamada a ` stop()`.

[slot] void QBluetoothServiceDiscoveryAgent::clear()

Borra los resultados de las búsquedas de servicios anteriores y restablece uuidFilter(). Esta función no realiza ninguna acción mientras se está llevando a cabo una búsqueda de servicios (véase isActive()).

Véase también discoveredServices().

QList<QBluetoothServiceInfo> QBluetoothServiceDiscoveryAgent::discoveredServices() const

Devuelve la lista de todos los servicios detectados.

Esta lista de servicios acumula los servicios recién detectados a partir de múltiples llamadas a ` start()`. A menos que se llame a ` clear()`, el tamaño de la lista no puede reducirse. Esto implica que, si un dispositivo Bluetooth remoto se sale del alcance entre dos llamadas consecutivas a ` start()`, la lista puede contener entradas obsoletas.

Nota: La lista de servicios siempre debe borrarse antes de cambiar el modo de detección.

Véase también clear().

QBluetoothServiceDiscoveryAgent::Error QBluetoothServiceDiscoveryAgent::error() const

Devuelve el tipo de error que se ha producido por última vez. Si la detección de servicios se realiza para un único dispositivo (` remoteAddress()`), devolverá los errores que se hayan producido al intentar detectar servicios en ese dispositivo. Si no se ha establecido la opción ` remoteAddress()` y los dispositivos se detectan mediante un escaneo, los errores que se produzcan durante la detección de servicios en dispositivos individuales no se guardan y no se emiten señales. En este caso, los errores son bastante habituales, ya que es posible que algunos dispositivos no respondan al proceso de detección o que ya no se encuentren dentro del alcance. Dichos errores se ocultan. Si no se devuelve ningún servicio, se puede suponer que no se ha podido detectar ningún servicio.

Cualquier posible error anterior se borra al reiniciar la detección.

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

Esta señal se emite cuando se produce un error de « error ». El parámetro « error » describe el error que se ha producido.

Esta función se introdujo en Qt 6.2.

QString QBluetoothServiceDiscoveryAgent::errorString() const

Devuelve una descripción comprensible para el usuario del último error que se produjo durante la detección de servicios.

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

[signal] void QBluetoothServiceDiscoveryAgent::finished()

Esta señal se emite cuando finaliza la detección de servicios Bluetooth.

A diferencia de la señal ` QBluetoothDeviceDiscoveryAgent::finished()`, esta señal se emitirá incluso si se ha producido un error durante la búsqueda de servicios. Por lo tanto, se recomienda comprobar la señal ` errorOccurred()` para evaluar si la búsqueda de servicios se ha realizado con éxito.

bool QBluetoothServiceDiscoveryAgent::isActive() const

Devuelve « true » si la detección de servicios está activa en ese momento; en caso contrario, devuelve « false ». La detección activa se puede detener llamando a la función « stop()».

QBluetoothAddress QBluetoothServiceDiscoveryAgent::remoteAddress() const

Devuelve la dirección del dispositivo remoto. Si no se llama a ` setRemoteAddress()``, la función devolverá un objeto ` QBluetoothAddress` creado por defecto.

Véase también setRemoteAddress().

[signal] void QBluetoothServiceDiscoveryAgent::serviceDiscovered(const QBluetoothServiceInfo &info)

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

Nota: El parámetro QBluetoothServiceInfo pasado puede contener un servicio Bluetooth de baja energía si el dispositivo de destino anuncia dicho servicio a través de SDP. Esto es obligatorio en los dispositivos que admiten tanto el Bluetooth clásico (BaseRate) como los servicios de baja energía.

Véase también QBluetoothDeviceInfo::coreConfigurations().

bool QBluetoothServiceDiscoveryAgent::setRemoteAddress(const QBluetoothAddress &address)

Establece la dirección del dispositivo remoto en address. Si se utiliza la construcción por defecto address, se detectarán los servicios en todos los dispositivos Bluetooth con los que se pueda establecer contacto. Solo se puede establecer una nueva dirección remota cuando no haya ninguna detección de servicios en curso; de lo contrario, esta función devuelve «false».

En algunas plataformas, la detección de servicios puede dar lugar a solicitudes de emparejamiento. Por lo tanto, no se recomienda realizar búsquedas de servicios en todos los dispositivos. Esta función se puede utilizar para restringir la detección de servicios a un dispositivo concreto.

Véase también remoteAddress().

void QBluetoothServiceDiscoveryAgent::setUuidFilter(const QBluetoothUuid &uuid)

Se trata de una función miembro sobrecargada, que se ofrece para mayor comodidad.

Establece el filtro UUID en una lista que contiene un único elemento: uuid. La coincidencia se aplica a los atributos ServiceId y ServiceClassIds del servicio.

Véase también uuidFilter().

void QBluetoothServiceDiscoveryAgent::setUuidFilter(const QList<QBluetoothUuid> &uuids)

Establece el filtro UUID en uuids. Solo se devolverán los servicios que coincidan con los UUID de uuids. La coincidencia se aplica a los atributos ServiceId y ServiceClassIds del servicio.

Una lista de UUID vacía equivale a una lista que contiene únicamente QBluetoothUuid::ServiceClassUuid::PublicBrowseGroup.

Véase también uuidFilter().

[slot] void QBluetoothServiceDiscoveryAgent::start(QBluetoothServiceDiscoveryAgent::DiscoveryMode mode = MinimalDiscovery)

Inicia la detección de servicios. El parámetro « mode » especifica el tipo de detección de servicios que se va a realizar.

En algunas plataformas, la detección de dispositivos puede dar lugar a solicitudes de emparejamiento.

Véase también DiscoveryMode.

[slot] void QBluetoothServiceDiscoveryAgent::stop()

Detiene el proceso de detección de servicios. Se emitirá la señal « canceled()» una vez que la búsqueda se haya detenido.

QList<QBluetoothUuid> QBluetoothServiceDiscoveryAgent::uuidFilter() const

Devuelve el filtro UUID.

Véase también setUuidFilter().

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