QBluetoothLocalDevice Class Reference
[QtBluetoothModule]

Detailed Description

The QBluetoothLocalDevice class represents a local bluetooth device.

The class can be used to query for device attributes, such as device address, device class, device manufacturer, etc. Changing of certain attributes is also allowed. This class can also be used to query remote devices which are within range and to initiate bluetooth pairing procedures with remote devices.

This class uses a QBluetoothReply template class in order to return method call results. The QBluetoothReply class holds an error condition flag and the actual return value. If the error condition flag is set to true, then the return value is set to the default constructed value. Thus it is recommended to always check the return value by using the QBluetoothReply::isError method like so:

    QBluetoothAddress addr(remoteDevice);
    QBluetoothLocalDevice local;

    QBluetoothReply<QDateTime> result = local.lastSeen(remoteDevice);
    if (result.isError()) {
        // handle error
        return;
    }

    QDateTime realTime = result.value();

Alternatively, if you know the return value will always succeed, you can do:

    QDateTime result = local.lastSeen(remoteDevice);

See also QBluetoothAddress, QBluetoothRemoteDevice, QBluetoothReply, and QBluetoothLocalDeviceManager.

Member Type Documentation

enum QBluetoothLocalDevice::Error

Possible errors that might occur.

enum QBluetoothLocalDevice::State

State of the local adaptor

The device has two scanning types, page scanning and inquiry scanning.

• Page scan - Controls whether other devices can connect to the local device.
• Inquiry scan - Controls whether the device can be discovered by remote devices.

While each scan type can be activated or disabled independently, only three combinations really make sense:

• Page Scan Off, Inquiry Scan Off - Device is in Off state
• Page Scan On, Inquiry Scan On - Device is in Discoverable state
• Page Scan On, Inquiry Scan Off - Device is Connectable state

The Connectable state is entered by using the bringUp() method. The Discoverable state is entered by using the setDiscoverable() method. The Off state is entered by using the bringDown() method.

Member Function Documentation

QBluetoothLocalDevice::QBluetoothLocalDevice ( QObject * parent = 0 )

Constructs a QBluetoothLocalDevice with the default adaptor, obtained from QBluetoothLocalDeviceManager::defaultAdaptor(). This is equivalent to:

    QBluetoothLocalDeviceManager mgr;
    QString device = mgr.defaultDevice();
    QBluetoothLocalDevice localDevice(device);

The parent parameter specifies the QObject parent.

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

Constructs a QBluetoothLocalDevice with address paremeter representing the bluetooth address of the local device. The parent parameter specifies the QObject parent.

See also deviceName().

QBluetoothLocalDevice::QBluetoothLocalDevice ( const QString & devName, QObject * parent = 0 )

Constructs a QBluetoothLocalDevice with devName, which represents a system internal device name for the device, typically hci<0-7>. The parent parameter specifies the QObject parent.

See also deviceName().

QBluetoothLocalDevice::~QBluetoothLocalDevice ()

Deconstructs a QBluetoothLocalDevice object.

QBluetoothAddress QBluetoothLocalDevice::address () const

Returns the Bluetooth address of this device.

See also deviceName().

bool QBluetoothLocalDevice::cancelDiscovery ()   [slot]

Attempts to cancel the discovery of remote devices started by discoverRemoteDevices(). In case of error or if no discovery process is in progress, an error signal will be emitted. In the case of success, a discoveryCancelled() signal will be emitted. Note that only the QBluetoothLocalDevice instance that initiated the discovery can cancel it, and only that instance will receive the discoveryCancelled() signal. All other instances will receive the discoveryCompleted signal.

Returns true if the request could be queued, false otherwise.

See also discoverRemoteDevices() and discoveryCancelled().

bool QBluetoothLocalDevice::cancelPairing ( const QBluetoothAddress & addr )

Attempts to cancel the pairing process. In case of error, an error signal will be emitted. In the case of success, a pairingFailed() signal will be emitted and error() set to QBluetoothLocalDevice::AuthenticationCancelled. The address of the remote device is given by addr.

Returns true if the request could be queued, false otherwise.

See also pairingFailed() and error().

QBluetoothReply<QString> QBluetoothLocalDevice::company () const

Returns the company name of the device (e.g. the brand of the device).

Note that the underlying HCI daemon requires the IEEE standard oui.txt file in order to read the company information correctly. This file can be downloaded from the IEEE site. The HCI daemon expects the file to be placed at /usr/share/misc/oui.txt.

See also manufacturer(), version(), and revision().

QBluetoothReply<bool> QBluetoothLocalDevice::connectable () const

Returns true if other devices can connect to the local device, i.e. page scan is enabled.

See also setConnectable() and discoverable().

QBluetoothReply<QList<QBluetoothAddress> > QBluetoothLocalDevice::connections () const

Returns a list of all remote devices which are currently connected to the local device.

See also isConnected().

QString QBluetoothLocalDevice::deviceName () const

Returns the system device name of this device. This is of the form hciX.

See also address().

bool QBluetoothLocalDevice::disconnectRemoteDevice ( const QBluetoothAddress & addr )

Requests the Bluetooth device to disconnect the underlying low level connection to the remote bluetooth device at address addr. This call will most likely require system administrator privileges. The actual disconnection will happen several seconds later. First the remoteDeviceDisconnectRequested signal will be sent. This method returns true if the disconnectRemoteDevice request succeeded, and false otherwise.

See also remoteDeviceDisconnectRequested().

bool QBluetoothLocalDevice::discoverRemoteDevices ()   [slot]

Requests the local device to scan for all discoverable devices in the vicinity. Returns true if the device is not already discovering and the process was started successfully. Returns false on error, setting error accordingly.

Once discovery process is in process, the discoveryStarted() signal is emitted. When the discovery process completes, the discoveryCompleted() signal is emitted.

The clients can subscribe to the discovery information in one of two ways. If the client wants to receive information about a device as it is received, they should subscribe to the remoteDeviceFound() signal. Note that the clients should be prepared to receive multiple signals with information about the same device, and deal with them accordingly. If the clients wish to receive the information wholesale, they should subscribe to the remoteDevicesFound() signal.

See also remoteDevicesFound(), remoteDeviceFound(), and cancelDiscovery().

QBluetoothReply<bool> QBluetoothLocalDevice::discoverable () const

Returns true if other devices can discover the local device, i.e. inquiry scan is enabled.

Note that if the device is in Discoverable state, it is also in Connectable state.

See also setDiscoverable() and connectable().

QBluetoothReply<uint> QBluetoothLocalDevice::discoverableTimeout () const

Returns the discoverable timeout set for the device. A value of 0 signifies that the timeout is indefinite.

See also discoverable() and setDiscoverable().

void QBluetoothLocalDevice::discoverableTimeoutChanged ( uint timeout )   [signal]

This signal is emitted whenever a discoverable timeout for a device has been changed. The timeout parameter holds the new timeout.

See also discoverableTimeout() and setDiscoverable().

void QBluetoothLocalDevice::discoveryCancelled ()   [signal]

This signal is emitted whenever a discovery scan has been cancelled.

See also cancelDiscovery().

void QBluetoothLocalDevice::discoveryCompleted ()   [signal]

This signal is emitted whenever a discovery scan has been completed.

See also discoverRemoteDevices() and discoveryStarted().

void QBluetoothLocalDevice::discoveryStarted ()   [signal]

This signal is emitted whenever a discovery scan has been initiated. Note that this signal can be triggered by other instances of QBluetoothLocalDevice.

See also discoverRemoteDevices() and discoveryCompleted().

QBluetoothLocalDevice::Error QBluetoothLocalDevice::error () const

Returns the last error that has occurred.

See also errorString().

void QBluetoothLocalDevice::error ( QBluetoothLocalDevice::Error error, const QString & msg )   [signal]

This is an overloaded member function, provided for convenience.

This signal is emitted whenever an error has occurred. The error variable contains the error that has occurred. The msg variable contains the error message.

See also error().

QString QBluetoothLocalDevice::errorString () const

Returns the human readable form of the last error that has occurred.

See also error().

QBluetoothReply<bool> QBluetoothLocalDevice::isConnected ( const QBluetoothAddress & addr ) const

Returns true if a remote device is connected to the local device. The address of the remote device is given by addr.

See also connections().

QBluetoothReply<bool> QBluetoothLocalDevice::isPaired ( const QBluetoothAddress & addr ) const

Returns true if the local device is paired to a remote device, and false otherwise. In the case of an error, the return value is invalid and the error() is set accordingly. The address of the remote device is given by addr.

See also pairedDevices().

QBluetoothReply<bool> QBluetoothLocalDevice::isPeriodicDiscoveryEnabled () const

Returns true if the device is currently in Periodic Discovery Mode.

See also setPeriodicDiscoveryEnabled().

QBluetoothReply<bool> QBluetoothLocalDevice::isUp ()

Returns true if the local device is currently enabled. This is the same as calling connectable().

See also connectable(), setConnectable(), and turnOff().

bool QBluetoothLocalDevice::isValid () const

Returns whether the instance is valid.

QBluetoothReply<QList<QBluetoothAddress> > QBluetoothLocalDevice::knownDevices () const

Lists the addresses of all known devices, ones that have paired, seen or used.

See also lastUsed() and lastSeen().

QBluetoothReply<QList<QBluetoothAddress> > QBluetoothLocalDevice::knownDevices ( const QDateTime & date ) const

This is an overloaded member function, provided for convenience.

Lists the addresses of all known devices, ones that have paired, seen or used after the given date.

See also lastUsed() and lastSeen().

QBluetoothReply<QDateTime> QBluetoothLocalDevice::lastSeen ( const QBluetoothAddress & addr ) const

Returns the date the remote device with address addr was last seen by the local device adaptor. In the case the device has never been seen, returns an invalid QDateTime. If an error occurs, this method returns an invalid QDateTime and sets the error() accordingly.

See also lastUsed().

QBluetoothReply<QDateTime> QBluetoothLocalDevice::lastUsed ( const QBluetoothAddress & addr ) const

Returns the date the remote device with address addr was last used by the local device adaptor. In the case the device has never been used, returns an invalid QDateTime. If an error occurs, this method returns an invalid QDateTime and sets the error() accordingly.

See also lastSeen().

QBluetoothReply<QString> QBluetoothLocalDevice::manufacturer () const

Returns the manufacturer of the device.

See also version(), revision(), and company().

QBluetoothReply<QString> QBluetoothLocalDevice::name () const

Returns the human readable name of the device.

See also setName() and nameChanged().

void QBluetoothLocalDevice::nameChanged ( const QString & name )   [signal]

This signal is emitted whenever a device name has been changed. The name variable contains the new name. Note that this signal can be triggered by external events (such as another program changing the device name).

QBluetoothReply<QList<QBluetoothAddress> > QBluetoothLocalDevice::pairedDevices () const

Returns a list of Bluetooth device addresses which are currently paired to this device. Pairing establishes a secret key which is used for encryption of all communication between the two devices. The encryption key is based on a PIN which must be entered on both devices.

Note that each device maintains its own list of paired devices and thus it is possible that while the local device trusts the peer, the peer might not trust the local device.

The function will return a list of paired device addresses. If an error occurred during a request, the return value will be an error, and error() will be set accordingly.

See also isPaired().

void QBluetoothLocalDevice::pairingCreated ( const QBluetoothAddress & addr )   [signal]

This signal is emitted whenever a pairing request has completed successfully. The addr parameter holds the address just paired to. Note that this signal could be triggered by external events.

void QBluetoothLocalDevice::pairingFailed ( const QBluetoothAddress & addr )   [signal]

This signal is emitted whenever a pairing request has failed. The addr parameter holds the address of the remote device.

void QBluetoothLocalDevice::pairingRemoved ( const QBluetoothAddress & addr )   [signal]

This signal is emitted whenever a pairing has been removed. The addr parameter holds the address of the remote device. Note that this signal could be triggered by external events.

QBluetoothReply<uchar> QBluetoothLocalDevice::pinCodeLength ( const QBluetoothAddress & addr ) const

Returns the pin code length used when the device was paired to addr. If the device is not paired, an invalid QBluetoothReply is returned.

QBluetoothReply<QString> QBluetoothLocalDevice::remoteAlias ( const QBluetoothAddress & addr ) const

Returns the alias for a remote device. If the alias is set, it should be used in preference to the device display name. On success, returns the alias as a string. The address of the remote device is given by addr.

See also setRemoteAlias() and removeRemoteAlias().

void QBluetoothLocalDevice::remoteAliasChanged ( const QBluetoothAddress & addr, const QString & alias )   [signal]

This signal is emitted whenever a remote device's alias has been changed. The addr contains the address of the remote device, and alias contains the new alias. This signal can be triggered externally.

void QBluetoothLocalDevice::remoteAliasRemoved ( const QBluetoothAddress & addr )   [signal]

This signal is emitted whenever a remote device's alias has been removed. The addr contains the address of the remote device. This signal can be triggered externally.

void QBluetoothLocalDevice::remoteClassUpdated ( const QBluetoothAddress & addr, QBluetooth::DeviceMajor major, quint8 minor, QBluetooth::ServiceClasses serviceClasses )   [signal]

This signal is emitted whenever a remote device's class has changed. The addr parameter holds the address of the device, the major, minor and serviceClasses parameters hold the Device Major, Device Minor and Device Service Classes information, respectively.

void QBluetoothLocalDevice::remoteDeviceConnected ( const QBluetoothAddress & addr )   [signal]

This signal is emitted whenever a remote device has connected to the local device. The addr parameter holds the address of the remote device. Note that this signal can be triggered externally.

void QBluetoothLocalDevice::remoteDeviceDisappeared ( const QBluetoothAddress & addr )   [signal]

This signal is emitted whenever a periodic discovery cycle has completed, and a previously detected device is no longer in range or invisible. The addr parameter holds the address of the remote device.

See also setPeriodicDiscoveryEnabled().

void QBluetoothLocalDevice::remoteDeviceDisconnectRequested ( const QBluetoothAddress & addr )   [signal]

This signal is emitted whenever a disconnectRemoteDevice request has been issued to the Bluetooth system. Services can act upon this signal in order to shut down the connection gracefully to the particular device before the underlying low-level connection is terminated. The actual disconnection will happen several seconds later. The addr parameter holds the address of the device being disconnected.

See also disconnectRemoteDevice().

void QBluetoothLocalDevice::remoteDeviceDisconnected ( const QBluetoothAddress & addr )   [signal]

This signal is emitted whenever a remote device has disconnected from the local device. The addr parameter holds the address of the remote device. Note that this signal can be triggered externally.

void QBluetoothLocalDevice::remoteDeviceFound ( const QBluetoothRemoteDevice & device )   [signal]

This signal is emitted whenever a device is discovered. The device parameter contains the remote device discovered. Note that this signal can be triggered by other instances of QBluetoothLocalDevice.

See also remoteDevicesFound().

void QBluetoothLocalDevice::remoteDevicesFound ( const QList<QBluetoothRemoteDevice> & list )   [signal]

This signal is emitted whenever a discovery procedure has finished. It returns all devices discovered by the procedure. The list contains the list of all remote devices found.

See also remoteDeviceFound().

void QBluetoothLocalDevice::remoteNameFailed ( const QBluetoothAddress & addr )   [signal]

This signal is emitted whenever a request for a remote device's name has failed. The addr parameter holds the address of the device.

See also remoteNameUpdated().

void QBluetoothLocalDevice::remoteNameUpdated ( const QBluetoothAddress & addr, const QString & name )   [signal]

This signal is emitted whenever the remote device's name has been changed. This can occur when a never seen device has been discovered and the name was obtained (in this case its bluetooth address should be used for display purposes until this signal is emitted), or if the device name has changed since last communication. The addr parameter holds the address of the Bluetooth device. The name contains the new name.

See also remoteNameFailed().

bool QBluetoothLocalDevice::removePairing ( const QBluetoothAddress & addr )

Requests the local device to remove its pairing to a remote device with address addr. Returns true if the removal request could be queued successfully, false otherwise. The signal pairingRemoved() will be sent if the pairing could be removed successfully. An error() signal will be emitted if the pairing could not be removed.

See also pairingRemoved().

bool QBluetoothLocalDevice::removeRemoteAlias ( const QBluetoothAddress & addr )

Removes the alias for a remote device given by addr. Returns true if the alias could be removed, and false otherwise.

See also setRemoteAlias() and remoteAlias().

bool QBluetoothLocalDevice::requestPairing ( const QBluetoothAddress & addr )

Requests the local device to pair to a remote device found at address addr. This method returns true if the pairing request could be started and false otherwise.

See also pairedDevices(), pairingCreated(), pairingFailed(), and QBluetoothPasskeyAgent.

QBluetoothReply<QString> QBluetoothLocalDevice::revision () const

Returns the device revision. This is generally manufacturer-specific.

See also manufacturer(), version(), and company().

bool QBluetoothLocalDevice::setConnectable ()

Sets the device into Connectable state. Other devices can connect to the local device, but not discover its existence.

Returns true if the request could be queued, and false otherwise. The stateChanged() signal will be sent once the device has changed state. An error() signal will be sent if the state change failed.

See also connectable() and stateChanged().

bool QBluetoothLocalDevice::setDiscoverable ( uint timeout = 0 )

Sets the device into Discoverable state. The timeout value is used to specify how long the device will remain discoverable. If the timeout value of 0 is specified, the device will remain discoverable indefinitely.

Returns true if the request could be queued, and false otherwise. The stateChanged() signal will be sent once the device has changed state. An error() signal will be sent if the state change failed.

See also discoverableTimeout(), discoverable(), and stateChanged().

bool QBluetoothLocalDevice::setName ( const QString & name )

Sets the human readable name of this device to name. Returns true if the call succeeded, and false otherwise. In addition, nameChanged signal will be sent once the name has been changed.

See also name() and nameChanged().

bool QBluetoothLocalDevice::setPeriodicDiscoveryEnabled ( bool enabled )

Enables or Disables the Periodic Discovery Mode according to enabled. When in Periodic Discovery Mode the device will periodically run a device inquiry and report the results. Returns true if the mode change operation succeeded, and false otherwise.

See also isPeriodicDiscoveryEnabled().

bool QBluetoothLocalDevice::setRemoteAlias ( const QBluetoothAddress & addr, const QString & alias )

Sets the alias for a remote device given by addr to alias alias. Returns true if the alias could be set, and false otherwise.

See also remoteAlias() and removeRemoteAlias().

void QBluetoothLocalDevice::stateChanged ( QBluetoothLocalDevice::State state )   [signal]

This signal is emitted whenever a device has entered a new state. The state variable contains the new state. Note that this signal can be triggered externally.

bool QBluetoothLocalDevice::turnOff ()

Turns off the device.

Returns true if the request could be queued, and false otherwise. The stateChanged() signal will be sent once the device has changed state. An error() signal will be sent if the state change failed.

Use setConnectable() or setDiscoverable() to turn the device back on.

See also connectable() and State.

bool QBluetoothLocalDevice::updateRemoteDevice ( QBluetoothRemoteDevice & device ) const

Updates the information about the remote device, based on the local device cache. Some information is generally not provided by the local adaptor until a low-level connection is made to the remote device. Thus devices which are found by discoverRemoteDevices() will not contain the full information about the device. The remote device is given by device.

Returns true on successful completion of the request; otherwise returns false.

See also discoverRemoteDevices() and remoteDevicesFound().

QBluetoothReply<QString> QBluetoothLocalDevice::version () const

Returns the Bluetooth protocol version this device supports. This can for instance be 1.0, 1.1, 1.2, 2.0...

See also manufacturer(), revision(), and company().