|
Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions | |
The QBluetoothLocalDevice class represents a local bluetooth device. More...
#include <QBluetoothLocalDevice>
Inherits QObject.
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.
Possible errors that might occur.
| Constant | Value | Description |
|---|---|---|
| QBluetoothLocalDevice::NoError | 0 | No error. |
| QBluetoothLocalDevice::InvalidArguments | 1 | Invalid arguments have been provided for the operation. |
| QBluetoothLocalDevice::NotAuthorized | 2 | The client has no permission to perform the action. |
| QBluetoothLocalDevice::OutOfMemory | 3 | Out of memory condition occurred. |
| QBluetoothLocalDevice::NoSuchAdaptor | 4 | Trying to use a device which does not exist. |
| QBluetoothLocalDevice::UnknownAddress | 5 | No such host has been found. |
| QBluetoothLocalDevice::ConnectionAttemptFailed | 6 | Connection attempt has failed. |
| QBluetoothLocalDevice::NotConnected | 7 | No connection exists. |
| QBluetoothLocalDevice::AlreadyExists | 8 | A record or procedure already exists. |
| QBluetoothLocalDevice::DoesNotExist | 9 | A record or procedure does not exist. |
| QBluetoothLocalDevice::InProgress | 10 | A long running operation is in progress. |
| QBluetoothLocalDevice::AuthenticationFailed | 11 | Authentication has failed. |
| QBluetoothLocalDevice::AuthenticationTimeout | 12 | Authentication has timed out. |
| QBluetoothLocalDevice::AuthenticationRejected | 13 | Authentication has been rejected. |
| QBluetoothLocalDevice::AuthenticationCancelled | 14 | Authentication has been canceled. |
| QBluetoothLocalDevice::UnknownError | 15 | Unknown error has occurred. |
State of the local adaptor
| Constant | Value | Description |
|---|---|---|
| QBluetoothLocalDevice::Off | 0 | The device is turned off. |
| QBluetoothLocalDevice::Connectable | 1 | The device can be connected to, but cannot be discovered. |
| QBluetoothLocalDevice::Discoverable | 2 | The device can be connected to and can be discovered by other remote devicess. |
The device has two scanning types, page scanning and inquiry scanning.
While each scan type can be activated or disabled independently, only three combinations really make sense:
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.
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.
Constructs a QBluetoothLocalDevice with address paremeter representing the bluetooth address of the local device. The parent parameter specifies the QObject parent.
See also deviceName().
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().
Deconstructs a QBluetoothLocalDevice object.
Returns the Bluetooth address of this device.
See also deviceName().
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().
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().
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().
Returns true if other devices can connect to the local device, i.e. page scan is enabled.
See also setConnectable() and discoverable().
Returns a list of all remote devices which are currently connected to the local device.
See also isConnected().
Returns the system device name of this device. This is of the form hciX.
See also address().
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().
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().
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().
Returns the discoverable timeout set for the device. A value of 0 signifies that the timeout is indefinite.
See also discoverable() and setDiscoverable().
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().
This signal is emitted whenever a discovery scan has been cancelled.
See also cancelDiscovery().
This signal is emitted whenever a discovery scan has been completed.
See also discoverRemoteDevices() and discoveryStarted().
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().
Returns the last error that has occurred.
See also errorString().
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().
Returns the human readable form of the last error that has occurred.
See also error().
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().
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().
Returns true if the device is currently in Periodic Discovery Mode.
See also setPeriodicDiscoveryEnabled().
Returns true if the local device is currently enabled. This is the same as calling connectable().
See also connectable(), setConnectable(), and turnOff().
Returns whether the instance is valid.
Lists the addresses of all known devices, ones that have paired, seen or used.
See also lastUsed() and lastSeen().
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().
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().
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().
Returns the manufacturer of the device.
See also version(), revision(), and company().
Returns the human readable name of the device.
See also setName() and nameChanged().
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).
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().
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.
This signal is emitted whenever a pairing request has failed. The addr parameter holds the address of the remote device.
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.
Returns the pin code length used when the device was paired to addr. If the device is not paired, an invalid QBluetoothReply is returned.
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().
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.
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.
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.
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.
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().
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().
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.
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().
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().
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().
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().
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().
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().
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.
Returns the device revision. This is generally manufacturer-specific.
See also manufacturer(), version(), and company().
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().
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().
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().
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().
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().
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.
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.
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().
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().
| Copyright © 2009 Nokia | Trademarks | Qt Extended 4.4.3 |