workspace/libs/solid/control/ifaces/bluetoothinterface.h

   1 /*  This file is part of the KDE project
   2     Copyright (C) 2007 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_IFACES_BLUETOOTHINTERFACE_H
  23 #define SOLID_IFACES_BLUETOOTHINTERFACE_H
  24
  25 #include <QtCore/QList>
  26 #include <solid/control/solid_control_export.h>
  27
  28 #include <solid/control/bluetoothinterface.h>
  29 #include <solid/control/ifaces/bluetoothremotedevice.h>
  30
  31 #include <QtCore/QObject>
  32
  33 namespace Solid
  34 {
  35 namespace Control
  36 {
  37 namespace Ifaces
  38 {
  39 /**
  40  * Represents a bluetooth interface as seen by the bluetooth subsystem.
  41  */
  42 class SOLIDCONTROLIFACES_EXPORT BluetoothInterface : public QObject
  43 {
  44     Q_OBJECT
  45 public:
  46     /**
  47      * Create a BluetoothInterface.
  48      *
  49      * @param parent the parent object
  50      */
  51     BluetoothInterface(QObject *parent = 0);
  52
  53     /**
  54      * Destructs a BluetoothInterface object.
  55      */
  56     virtual ~BluetoothInterface();
  57
  58     /**
  59      * Retrieves the Universal Bluetooth Identifier (UBI) of the BluetoothInterface.
  60      * This identifier is unique for each bluetooth remote device and bluetooth interface in the system.
  61      *
  62      * @returns the Universal Bluetooth Identifier of the current bluetooth interface
  63      */
  64     virtual QString ubi() const = 0;
  65
  66     /**
  67      * Retrieves the MAC address of the bluetooth interface/adapter.
  68      *
  69      * @returns MAC address of bluetooth interface
  70      */
  71     virtual QString address() const = 0;
  72
  73     /**
  74      * Retrieves the version of the chip of the bluetooth interface/adapter.
  75      * Example: "Bluetooth 2.0 + EDR"
  76      *
  77      * @returns bluetooth chip version
  78      */
  79     virtual QString version() const = 0;
  80
  81     /**
  82      * Retrieves the revision of the chip of the bluetooth interface/adapter.
  83      * Example: "HCI 19.2"
  84      *
  85      * @returns bluetooth chip revision
  86      */
  87     virtual QString revision() const = 0;
  88
  89     /**
  90      * Retrieves the name of the bluetooth chip manufacturer.
  91      * Example: "Cambdirge Silicon Radio"
  92      *
  93      * @returns manufacturer string of bluetooth interface/adapter
  94      */
  95     virtual QString manufacturer() const = 0;
  96
  97     /**
  98      * Retrieves the name of the bluetooth chip company.
  99      * Based on device address.
 100      *
 101      * @returns company string of bluetooth interface/adapter
 102      */
 103     virtual QString company() const = 0;
 104
 105
 106     /**
 107      * Retrieves the current mode of the bluetooth interface/adapter.
 108      * Valid modes: "off", "connectable", "discoverable"
 109      *
 110      * @todo determine unify type for valid modes.. enum?! what about other bluetooth APIs?
 111      * three modes?
 112      *
 113      * @returns current mode of bluetooth interface/adaoter
 114      */
 115     virtual Solid::Control::BluetoothInterface::Mode mode() const = 0;
 116
 117     /**
 118      * Retrieves the discoverable timeout of the bluetooth interface/adapter.
 119      * Discoverable timeout of 0 means never disappear.
 120      *
 121      * @returns current discoverable timeout in seconds
 122      */
 123     virtual int discoverableTimeout() const = 0;
 124
 125     /**
 126      * Retrieves the current discoverable staut of the bluetooth interface/adapter.
 127      *
 128      * @returns current discoverable status of bluetooth interface/adapter
 129      */
 130     virtual bool isDiscoverable() const = 0;
 131
 132
 133     /**
 134      * List all UBIs of connected remote bluetooth devices of this handled bluetooth
 135      * interface/adapter.
 136      *
 137      * @returns list UBIs of connected bluetooth remote devices
 138      */
 139     virtual QStringList listConnections() const = 0;
 140
 141
 142     /**
 143      * Retrieves major class of the bluetooth interface/adapter.
 144      *
 145      * @returns current major class of the bluetooth interface/adapter
 146      */
 147     virtual QString majorClass() const = 0;
 148
 149     /**
 150      * List supported minor classes of the bluetooth interface/adapter.
 151      *
 152      * @returns list of supported minor classes by bluetooth interface/adapter
 153      */
 154     virtual QStringList listAvailableMinorClasses() const = 0;
 155
 156     /**
 157      * Retrievies minor class of the bluetooth interface/adapter.
 158      * Valid classes, see listAvailableMinorClasses()
 159      *
 160      * @returns minor class of the bluetooth interface/adapter.
 161      */
 162     virtual QString minorClass() const = 0;
 163
 164     /**
 165      * List services class of the bluetooth interface/adapter.
 166      *
 167      * @returns list of service classes or empty list if no services registered
 168      */
 169     virtual QStringList serviceClasses() const = 0;
 170     /**
 171      * Retrieves name of bluetooth interface/adapter.
 172      *
 173      * @returns name of bluetooth interface/adapter
 174      */
 175     virtual QString name() const = 0;
 176
 177     /**
 178      * List UBIs of bonded/paired remote bluetooth devices with this bluetooth
 179      * interface/adapter.
 180      *
 181      * @returns UBIs of bonded/paired bluetooth remote devices
 182      */
 183     virtual QStringList listBondings() const = 0;
 184
 185     /**
 186      * Periodic discovery status of this bluetooth interface/adapter.
 187      *
 188      * @returns true if periodic discovery is already active otherwise false
 189      */
 190     virtual bool isPeriodicDiscoveryActive() const = 0;
 191
 192     /**
 193      * Name resolving status of periodic discovery routing.
 194      *
 195      * @returns true if name got resolved while periodic discovery of this bluetooth
 196      * interface/adapter
 197      */
 198     virtual bool isPeriodicDiscoveryNameResolvingActive() const = 0;
 199
 200     /**
 201      * List the Universal Bluetooth Identifier (UBI) of all known remote devices, which are
 202      * seen, used or paired/bonded.
 203      *
 204      * See listConnections()
 205      *
 206      * @returns a QStringList of UBIs of all known remote bluetooth devices
 207      */
 208     virtual QStringList listRemoteDevices() const = 0;
 209
 210     /**
 211      * List the Universal Bluetooth Identifier (UBI) of all known remote devices since a specific
 212      * datestamp. Known remote  devices means remote bluetooth which are seen, used or
 213      * paired/bonded.
 214      *
 215      * See listConnections(), listRemoteDevices()
 216      *
 217      * @param date the datestamp of the beginning of recent used devices
 218      * @returns a QStringList of UBIs of all known remote bluetooth devices
 219      */
 220     virtual QStringList listRecentRemoteDevices(const QDateTime &date) const = 0;
 221
 222 public Q_SLOTS:
 223     /**
 224      * Set mode of bluetooth interface/adapter.
 225      * Valid modes, see mode()
 226      *
 227      * @param mode the mode of the bluetooth interface/adapter
 228      */
 229     virtual void setMode(const Solid::Control::BluetoothInterface::Mode mode) = 0;
 230
 231     /**
 232      * Set discoverable timeout of bluetooth interface/adapter.
 233      *
 234      * @param timeout timeout in seconds
 235      */
 236     virtual void setDiscoverableTimeout(int timeout) = 0;
 237
 238     /**
 239      * Set minor class of bluetooth interface/adapter.
 240      *
 241      * @param minor set minor class. Valid mode see listAvaliableMinorClasses()
 242      */
 243     virtual void setMinorClass(const QString &minor) = 0;
 244
 245     /**
 246      * Set name of bluetooth interface/adapter.
 247      *
 248      * @param name the name of bluetooth interface/adapter
 249      */
 250     virtual void setName(const QString &name) = 0;
 251
 252
 253     /**
 254      * Start discovery of remote bluetooth devices with device name resolving.
 255      */
 256     virtual void discoverDevices() = 0;
 257     /**
 258      * Start discovery of remote bluetooth devices without device name resolving.
 259      */
 260     virtual void discoverDevicesWithoutNameResolving() = 0;
 261     /**
 262      * Cancel discovery of remote bluetooth devices.
 263      */
 264     virtual void cancelDiscovery() = 0;
 265
 266     /**
 267      * Start periodic discovery of remote bluetooth devices.
 268      * See stopPeriodicDiscovery()
 269      */
 270     virtual void startPeriodicDiscovery() = 0;
 271
 272     /**
 273      * Stop periodic discovery of remote bluetooth devices.
 274      */
 275     virtual void stopPeriodicDiscovery() = 0;
 276
 277     /**
 278      * Enable/Disable name resolving of remote bluetooth devices in periodic discovery.
 279      *
 280      * @param resolveName true to enable name resolving otherwise false
 281      */
 282     virtual void setPeriodicDiscoveryNameResolving(bool resolveNames) = 0;
 283
 284     /**
 285      * Instantiates a new BluetoothRemoteDevice object from this backend given its UBI.
 286      *
 287      * @param ubi the identifier of the bluetooth remote device instantiated
 288      * @returns a new BluetoothRemoteDevice object if there's a device having the given UBI, 0 otherwise
 289      */
 290     virtual QObject *createBluetoothRemoteDevice(const QString &ubi) = 0;
 291
 292 Q_SIGNALS:
 293
 294     /**
 295      * This signal is emitted if the mode of the bluetooth interface/adapter has changed.
 296      * See mode() for valid modes.
 297      *
 298      * @param mode the changed mode
 299      */
 300     void modeChanged(Solid::Control::BluetoothInterface::Mode);
 301
 302     /**
 303      * The signal is emitted if the discoverable timeout of the bluetooth interface/adapter
 304      * has changed.
 305      *
 306      * @param timeout the changed timeout in seconds
 307      */
 308     void discoverableTimeoutChanged(int timeout);
 309
 310     /**
 311      * The signal is emitted if the minor class of the bluetooth interface/adapter has changed.
 312      *
 313      * @param minor the new minor class
 314      */
 315     void minorClassChanged(const QString &minor);
 316
 317     /**
 318      * The signal is emitted if the name of the bluetooth interface/adapter has changed.
 319      *
 320      * @param name the new name of the device
 321      */
 322     void nameChanged(const QString &name);
 323
 324     /**
 325      * This signal is emitted if a discovery has started.
 326      */
 327     void discoveryStarted();
 328
 329     /**
 330      * This signal is emitted if a discovery has completed.
 331      */
 332     void discoveryCompleted();
 333
 334     /**
 335      * This signal is emitted if the bluetooth interface/adapter detects a new remote bluetooth device.
 336      *
 337      * @todo change arguments types of deviceClass (uint32) and rssi (int16)
 338      *
 339      * @param ubi the new bluetooth identifier
 340      * @param deviceClass the device Class of the remote device
 341      * @param rssi the RSSI link of the remote device
 342      */
 343     void remoteDeviceFound(const QString &ubi, int deviceClass, int rssi);
 344
 345     /**
 346      * This signal is emitted if the bluetooth interface/adapter detectes a bluetooth device
 347      * disappeared.
 348      *
 349      * @param ubi the ubi of the disappering bluetooth remote device
 350      */
 351     void remoteDeviceDisappeared(const QString &ubi);
 352
 353 };
 354 } //Ifaces
 355 } //Control
 356 } //Solid
 357
 358 Q_DECLARE_INTERFACE(Solid::Control::Ifaces::BluetoothInterface, "org.kde.Solid.Control.Ifaces.BluetoothInterface/0.1")
 359
 360 #endif