workspace/libs/solid/control/bluetoothinterface.h

   1 /*  This file is part of the KDE project
   2     Copyright (C) 2006 Will Stephenson <wstephenson@kde.org>
   3     Copyright (C) 2007 Daniel Gollub <dgollub@suse.de>
   4
   5
   6     This library is free software; you can redistribute it and/or
   7     modify it under the terms of the GNU Library General Public
   8     License version 2 as published by the Free Software Foundation.
   9
  10     This library is distributed in the hope that it will be useful,
  11     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13     Library General Public License for more details.
  14
  15     You should have received a copy of the GNU Library General Public License
  16     along with this library; see the file COPYING.LIB.  If not, write to
  17     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18     Boston, MA 02110-1301, USA.
  19
  20 */
  21
  22 #ifndef SOLID_BLUETOOTHINTERFACE_H
  23 #define SOLID_BLUETOOTHINTERFACE_H
  24
  25 #include <QtCore/QDateTime>
  26 #include <QtCore/QPair>
  27 #include <QtCore/QObject>
  28
  29 #include <solid/control/bluetoothremotedevice.h>
  30 #include <solid/control/ifaces/bluetoothremotedevice.h>
  31
  32
  33
  34 namespace Solid
  35 {
  36 namespace Control
  37 {
  38 class BluetoothRemoteDevice;
  39 typedef QList<BluetoothRemoteDevice> BluetoothRemoteDeviceList;
  40 class BluetoothInterfacePrivate;
  41
  42 /**
  43  * Represents a bluetooth interface as seen by the bluetooth subsystem.
  44  */
  45 class SOLIDCONTROL_EXPORT BluetoothInterface : public QObject
  46 {
  47     Q_OBJECT
  48
  49 public:
  50     /**
  51      * Describes the operating mode of a bluetooth interface
  52      *
  53      * - Off : The interface's transceiver is turned off
  54      * - Discoverable : The interface may be discovered by other devices and connected to
  55      * - Connectable : The interface may only be connected to but not discovered
  56      */
  57     enum Mode { Off, Discoverable, Connectable };
  58     /**
  59      * Constructs an invalid bluetooth interface
  60      */
  61     BluetoothInterface();
  62
  63     /**
  64      * Constructs a bluetooth interface for a given Unique Bluetooth Identifier (UBI).
  65      * This object will be auto deleted, DON'T delete it.
  66      * @param ubi the ubi of the bluetooth interface to create
  67      */
  68     explicit BluetoothInterface(const QString &ubi);
  69
  70     /**
  71      * Constructs a new bluetooth interface taking its data from a backend.
  72      *
  73      * @param backendObject the object given by the backend
  74      */
  75     explicit BluetoothInterface(QObject *backendObject);
  76
  77     /**
  78      * Constructs a copy of a bluetooth interface.
  79      *
  80      * @param device the bluetooth interface to copy
  81      */
  82     BluetoothInterface(const BluetoothInterface &device);
  83
  84     /**
  85      * Destroys the device.
  86      */
  87     ~BluetoothInterface();
  88
  89
  90     /**
  91      * Assigns a bluetooth interface to this bluetooth interface and returns a reference to it.
  92      *
  93      * @param device the bluetooth interface to assign
  94      * @return a reference to the bluetooth interface
  95      */
  96     BluetoothInterface &operator=(const BluetoothInterface &device);
  97
  98     /**
  99      * Retrieves the Unique Bluetooth Identifier (UBI) of the BluetoothInterface.
 100      * This identifier is ubique for each bluetooth and bluetooth interface in the system.
 101      *
 102      * @returns the Unique Bluetooth Identifier of the current bluetooth interface
 103      */
 104     QString ubi() const;
 105
 106     /**
 107      * Create new BluetoothRemoteDevice object from this interface given its UBI.
 108      *
 109      * @param ubi the identifier of the bluetooth device to instantiate
 110      * @returns a bluetooth object, if a bluetooth device having the given UBI, for this interface exists, 0 otherwise
 111      */
 112     BluetoothRemoteDevice *createBluetoothRemoteDevice(const QString  & ubi);
 113
 114     /**
 115      * Finds a BluetoothRemoteDevice object given its UBI.
 116      *
 117      * @param ubi the identifier of the bluetooth remote device to find from this bluetooth interface
 118      * @returns a valid BluetoothRemoteDevice object if a remote device having the given UBI for this interface exists, an invalid BluetoothRemoteDevice object otherwise.
 119      */
 120     BluetoothRemoteDevice findBluetoothRemoteDevice(const QString &ubi) const;
 121
 122     /**
 123      * Retrieves the MAC address of the bluetooth interface/adapter.
 124      *
 125      * @returns MAC address of bluetooth interface
 126      */
 127     QString address() const;
 128
 129     /**
 130      * Retrieves the version of the chip of the bluetooth interface/adapter.
 131      * Example: "Bluetooth 2.0 + EDR"
 132      *
 133      * @returns bluetooth chip version
 134      */
 135     QString version() const;
 136
 137     /**
 138      * Retrieves the revision of the chip of the bluetooth interface/adapter.
 139      * Example: "HCI 19.2"
 140      *
 141      * @returns bluetooth chip revision
 142      */
 143     QString revision() const;
 144
 145     /**
 146      * Retrieves the name of the bluetooth chip manufacturer.
 147      * Example: "Boston Silicon Radio"
 148      *
 149      * @returns manufacturer string of bluetooth interface/adapter
 150      */
 151     QString manufacturer() const;
 152
 153     /**
 154      * Retrieves the name of the manufacturer of the bluetooth interface,
 155      * using the chip supplied by BluetoothInterface::manufacterer()
 156      * Based on device address.
 157      *
 158      * @returns company string of bluetooth interface/adapter
 159      */
 160     QString company() const;
 161
 162     /**
 163      * Retrieves the current mode of the bluetooth interface/adapter.
 164      *
 165      * @returns the current mode of bluetooth interface/adapter
 166      */
 167     Mode mode() const;
 168
 169     /**
 170      * Retrieves the discoverable timeout of the bluetooth interface/adapter.
 171      * Discoverable timeout of 0 means never disappear.
 172      *
 173      * @returns current discoverable timeout in seconds
 174      */
 175     int discoverableTimeout() const;
 176
 177     /**
 178      * Retrieves the current discoverable staut of the bluetooth interface/adapter.
 179      *
 180      * @returns current discoverable status of bluetooth interface/adapter
 181      */
 182     bool isDiscoverable() const;
 183
 184     /**
 185      * List all UBIs of connected remote bluetooth devices of this handled bluetooth
 186      * interface/adapter.
 187      *
 188      * @returns list UBIs of connected bluetooth remote devices
 189      */
 190     BluetoothRemoteDeviceList listConnections() const;
 191
 192     /**
 193      * Retrieves major class of the bluetooth interface/adapter.
 194      * @todo enum
 195      * @returns current major class of the bluetooth interface/adapter
 196      */
 197     QString majorClass() const;
 198
 199     /**
 200      * List supported minor classes of the bluetooth interface/adapter.
 201      * @todo enum
 202      *
 203      * @returns list of supported minor classes by bluetooth interface/adapter
 204      */
 205     QStringList listAvailableMinorClasses() const;
 206
 207     /**
 208      * Retrieves minor class of the bluetooth interface/adapter.
 209      * Valid classes, see listAvailableMinorClasses()
 210      * @todo enum
 211      *
 212      * @returns minor class of the bluetooth interface/adapter.
 213      */
 214     QString minorClass() const;
 215
 216     /**
 217      * List services class of the bluetooth interface/adapter.
 218      * @todo enum
 219      *
 220      * @returns list of service classes or empty list if no services registered
 221      */
 222     QStringList serviceClasses() const;
 223
 224     /**
 225      * Retrieves name of bluetooth interface/adapter.
 226      * @todo enum
 227      *
 228      * @returns name of bluetooth interface/adapter
 229      */
 230     QString name() const;
 231
 232     /**
 233      * List UBIs of bonded/paired remote bluetooth devices with this bluetooth
 234      * interface/adapter.
 235      *
 236      * @returns UBIs of bonded/paired bluetooth remote devices
 237      */
 238     QStringList listBondings() const;
 239
 240     /**
 241      * Periodic discovery status of this bluetooth interface/adapter.
 242      *
 243      * @returns true if periodic discovery is already active otherwise false
 244      */
 245     bool isPeriodicDiscoveryActive() const;
 246
 247     /**
 248      * Name resolving status of periodic discovery routing.
 249      *
 250      * @returns true if name got resolved while periodic discovery of this bluetooth
 251      * interface/adapter
 252      */
 253     bool isPeriodicDiscoveryNameResolvingActive() const;
 254
 255     /**
 256      * List the Unique Bluetooth Identifier (UBI) of all known remote devices,
 257      * whether they are seen, used or paired/bonded.
 258      *
 259      * See listConnections()
 260      *
 261      * @returns a QStringList of UBIs of all known remote bluetooth devices
 262      */
 263     QStringList listRemoteDevices() const;
 264
 265     /**
 266      * List the Unique Bluetooth Identifier (UBI) of all known remote devices since a specific
 267      * datestamp. Known remote devices means remote bluetooth which are seen, used or
 268      * paired/bonded.
 269      *
 270      * See listConnections(), listRemoteDevices()
 271      *
 272      * @param date the datestamp of the beginning of recent used devices
 273      * @returns a QStringList of UBIs of all known remote bluetooth devices
 274      */
 275     QStringList listRecentRemoteDevices(const QDateTime &date) const;
 276
 277 public Q_SLOTS:
 278     /**
 279      * Set mode of bluetooth interface/adapter.
 280      * Valid modes, see mode()
 281      *
 282      * @param mode the mode of the bluetooth interface/adapter
 283      */
 284     void setMode(const Mode mode);
 285
 286     /**
 287      * Set discoverable timeout of bluetooth interface/adapter.
 288      *
 289      * @param timeout timeout in seconds
 290      */
 291     void setDiscoverableTimeout(int timeout);
 292
 293     /**
 294      * Set minor class of bluetooth interface/adapter.
 295      *
 296      * @param minor set minor class. Valid mode see listAvaliableMinorClasses()
 297      */
 298     void setMinorClass(const QString &minor);
 299
 300     /**
 301      * Set name of bluetooth interface/adapter.
 302      *
 303      * @param name the name of bluetooth interface/adapter
 304      */
 305     void setName(const QString &name);
 306
 307     /**
 308      * Start discovery of remote bluetooth devices with device name resolving.
 309      */
 310     void discoverDevices();
 311     /**
 312      * Start discovery of remote bluetooth devices without device name resolving.
 313      */
 314     void discoverDevicesWithoutNameResolving();
 315     /**
 316      * Cancel discovery of remote bluetooth devices.
 317      */
 318     void cancelDiscovery();
 319
 320     /**
 321      * Start periodic discovery of remote bluetooth devices.
 322      * See stopPeriodicDiscovery()
 323      */
 324     void startPeriodicDiscovery();
 325
 326     /**
 327      * Stop periodic discovery of remote bluetooth devices.
 328      */
 329     void stopPeriodicDiscovery();
 330
 331     /**
 332      * Enable/Disable name resolving of remote bluetooth devices in periodic discovery.
 333      *
 334      * @param resolveName true to enable name resolving otherwise false
 335      */
 336     void setPeriodicDiscoveryNameResolving(bool resolveNames);
 337
 338 Q_SIGNALS:
 339
 340     /**
 341      * This signal is emitted if the mode of the bluetooth interface/adapter has changed.
 342      * See mode() for valid modes.
 343      *
 344      * @param mode the changed mode
 345      */
 346     void modeChanged(Solid::Control::BluetoothInterface::Mode);
 347
 348     /**
 349      * The signal is emitted if the discoverable timeout of the bluetooth interface/adapter
 350      * has changed.
 351      *
 352      * @param timeout the changed timeout in seconds
 353      */
 354     void discoverableTimeoutChanged(int timeout);
 355
 356     /**
 357      * The signal is emitted if the minor class of the bluetooth interface/adapter has changed.
 358      *
 359      * @param minor the new minor class
 360      */
 361     void minorClassChanged(const QString &minor);
 362
 363     /**
 364      * The signal is emitted if the name of the bluetooth interface/adapter has changed.
 365      *
 366      * @param name the new name of the device
 367      */
 368     void nameChanged(const QString &name);
 369
 370     /**
 371      * This signal is emitted if a discovery has started.
 372      */
 373     void discoveryStarted();
 374
 375     /**
 376      * This signal is emitted if a discovery has completed.
 377      */
 378     void discoveryCompleted();
 379
 380     /**
 381      * This signal is emitted if the bluetooth interface/adapter detects a new remote bluetooth device.
 382      *
 383      * @todo change arguments types of deviceClass (uint32) and rssi (int16)
 384      *
 385      * @param ubi the new bluetooth identifier
 386      * @param deviceClass the device class of the remote device
 387      * @param rssi the Received Signal Strength Information (RSSI) of the remote device
 388      */
 389     void remoteDeviceFound(const QString &ubi, int deviceClass, int rssi);
 390
 391     /**
 392      * This signal is emitted if the bluetooth interface/adapter detectes a bluetooth device
 393      * disappeared.
 394      *
 395      * @param ubi the ubi of the disappering bluetooth remote device
 396      */
 397     void remoteDeviceDisappeared(const QString &ubi);
 398
 399 private:
 400     Q_PRIVATE_SLOT(d, void _k_destroyed(QObject *))
 401
 402     BluetoothInterfacePrivate * const d;
 403 };
 404
 405 } //Control
 406 } //Solid
 407
 408 #endif
 409