QBluetoothServiceDiscoveryAgent Class

The QBluetoothServiceDiscoveryAgent class enables you to query for Bluetooth services. More...

Header: #include <QBluetoothServiceDiscoveryAgent>
qmake: QT += bluetooth

Public Types

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

Public Functions

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

Public Slots

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

Signals

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

Detailed Description

The QBluetoothServiceDiscoveryAgent class enables you to query for Bluetooth services.

To query the services provided by all contactable Bluetooth devices:

// Create a discovery agent and connect to its signals
QBluetoothDiscoveryAgent *discoveryAgent = new QBluetoothDiscoveryAgent(this);
connect(discoveryAgent, SIGNAL(deviceDiscovered(const QBluetoothDeviceInfo&)),
        this, SLOT(deviceDiscovered(const QBluetoothDeviceInfo&)));

// Start a discovery
discoveryAgent->start();

...

// In your local slot, read information about the found devices
void MyClass::deviceDiscovered(const QBluetoothDeviceInfo &device)
{
    qDebug() << "Found new device:" << device.name() << '(' << device.address().toString() << ')';
}

By default a minimal service discovery is performed. In this mode, the QBluetotohServiceInfo objects returned are guaranteed to contain only device and service UUID information. Depending on platform and device capabilities, other service information may also be available. For most use cases this is adequate as QBluetoothSocket::connectToService() will perform additional discovery if required. If full service information is required, pass FullDiscovery as the discoveryMode parameter to start().

Member Type Documentation

enum QBluetoothServiceDiscoveryAgent::DiscoveryMode

This enum describes the service discovery mode.

ConstantValueDescription
QBluetoothServiceDiscoveryAgent::MinimalDiscovery0Performs a minimal service discovery. The QBluetoothServiceInfo objects returned may be incomplete and are only guaranteed to contain device and service UUID information.
QBluetoothServiceDiscoveryAgent::FullDiscovery1Performs a full service discovery.

enum QBluetoothServiceDiscoveryAgent::Error

This enum describes errors that can occur during service discovery.

ConstantValueDescription
QBluetoothServiceDiscoveryAgent::NoErrorQBluetoothDeviceDiscoveryAgent::NoErrorNo error has occurred.
QBluetoothServiceDiscoveryAgent::PoweredOffErrorQBluetoothDeviceDiscoveryAgent::PoweredOffErrorThe Bluetooth adaptor is powered off, power it on before doing discovery.
QBluetoothServiceDiscoveryAgent::InputOutputErrorQBluetoothDeviceDiscoveryAgent::InputOutputErrorWriting or reading from the device resulted in an error.
QBluetoothServiceDiscoveryAgent::UnknownErrorQBluetoothDeviceDiscoveryAgent::UnknownErrorAn unknown error has occurred.

Member Function Documentation

QBluetoothServiceDiscoveryAgent::QBluetoothServiceDiscoveryAgent(QObject * parent = 0)

Constructs a new QBluetoothServiceDiscoveryAgent with parent. Services will be discovered on all contactable devices.

QBluetoothServiceDiscoveryAgent::QBluetoothServiceDiscoveryAgent(const QBluetoothAddress & deviceAdapter, QObject * parent = 0)

Constructs a new QBluetoothServiceDiscoveryAgent for deviceAdapter and with parent.

If deviceAdapter is null, the default adapter will be used.

QBluetoothServiceDiscoveryAgent::~QBluetoothServiceDiscoveryAgent()

Destructor for QBluetoothServiceDiscoveryAgent

void QBluetoothServiceDiscoveryAgent::canceled() [signal]

Signals the cancellation of the service discovery.

void QBluetoothServiceDiscoveryAgent::clear() [slot]

Clears the results of a previous service discovery.

QList<QBluetoothServiceInfo> QBluetoothServiceDiscoveryAgent::discoveredServices() const

Returns the list of all discovered services.

Error QBluetoothServiceDiscoveryAgent::error() const

Returns the type of error that last occurred. If service discovery is done on a signle address it will return errors that occured while trying to discover services on that device. If the alternate constructor is used and devices are discovered by a scan, errors during service discovery on individual devices are not saved and no signals are emitted. In this case, errors are fairly normal as some devices may not respond to discovery or may no longer be in range. Such errors are surpressed. If no services are returned, it can be assumed no services could be discovered.

void QBluetoothServiceDiscoveryAgent::error(QBluetoothServiceDiscoveryAgent::Error error) [signal]

This signal is emitted when an error occurs. The error parameter describes the error that occurred.

QString QBluetoothServiceDiscoveryAgent::errorString() const

Returns a human-readable description of the last error that occurred during service discovery on a single device.

void QBluetoothServiceDiscoveryAgent::finished() [signal]

This signal is emitted when Bluetooth service discovery completes. This signal will even be emitted when an error occurred during the service discovery.

bool QBluetoothServiceDiscoveryAgent::isActive() const

Returns true if service discovery is currently active, otherwise returns false.

QBluetoothAddress QBluetoothServiceDiscoveryAgent::remoteAddress() const

Returns the remote device address. If setRemoteAddress is not called, the function will return default QBluetoothAddress.

See also setRemoteAddress().

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

This signal is emitted when the Bluetooth service described by info is discovered.

bool QBluetoothServiceDiscoveryAgent::setRemoteAddress(const QBluetoothAddress & address)

Sets remote device address to address. If address is null, services will be discovered on all contactable Bluetooth devices. A new remote address can only be set while there is no service discovery in progress; otherwise this function returns false.

See also remoteAddress().

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

Sets the UUID filter to uuids. Only services matching the UUIDs in uuids will be returned.

An empty UUID list is equivalent to a list containing only QBluetoothUuid::PublicBrowseGroup.

See also uuidFilter().

void QBluetoothServiceDiscoveryAgent::setUuidFilter(const QBluetoothUuid & uuid)

This is an overloaded member function, provided for convenience.

Sets the UUID filter to a list containing the single element uuid.

See also uuidFilter().

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

Starts service discovery. mode specifies the type of service discovery to perform.

On BlackBerry devices, device discovery may lead to pairing requests.

See also DiscoveryMode.

void QBluetoothServiceDiscoveryAgent::stop() [slot]

Stops service discovery.

QList<QBluetoothUuid> QBluetoothServiceDiscoveryAgent::uuidFilter() const

Returns the UUID filter.

See also setUuidFilter().