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_CONTROL_BLUETOOTHINTERFACE_H
  23 #define SOLID_CONTROL_BLUETOOTHINTERFACE_H
  24
  25 #include <QtCore/QDateTime>
  26 #include <QtCore/QPair>
  27 #include <QtCore/QObject>
  28 #include <QtCore/QMap>
  29
  30 #include "bluetoothremotedevice.h"
  31 #include "bluetoothinputdevice.h"
  32 #include "ifaces/bluetoothremotedevice.h"
  33 #include "ifaces/bluetoothinputdevice.h"
  34
  35
  36
  37 namespace Solid
  38 {
  39 namespace Control
  40 {
  41 class BluetoothRemoteDevice;
  42 typedef QList<BluetoothRemoteDevice*> BluetoothRemoteDeviceList;
  43 class BluetoothInterfacePrivate;
  44
  45 /**
  46  * Represents a bluetooth interface as seen by the bluetooth subsystem.
  47  */
  48 class SOLIDCONTROL_EXPORT BluetoothInterface : public QObject
  49 {
  50     Q_OBJECT
  51
  52
  53 public:
  54     /**
  55      * Describes the operating mode of a bluetooth interface
  56      *
  57      * - Off : The interface's transceiver is turned off
  58      * - Discoverable : The interface may be discovered by other devices and connected to
  59      * - Connectable : The interface may only be connected to but not discovered
  60      */
  61     //enum Mode { Off, Discoverable, Connectable };
  62
  63
  64     /**
  65      * Constructs an invalid bluetooth interface
  66      */
  67     BluetoothInterface();
  68
  69
  70
  71     /**
  72      * Constructs a bluetooth interface for a given Unique Bluetooth Identifier (UBI).
  73      * This object will be auto deleted, DON'T delete it.
  74      * @param ubi the ubi of the bluetooth interface to create
  75      */
  76     explicit BluetoothInterface(const QString &ubi);
  77
  78     /**
  79      * Constructs a new bluetooth interface taking its data from a backend.
  80      *
  81      * @param backendObject the object given by the backend
  82      */
  83     explicit BluetoothInterface(QObject *backendObject);
  84
  85     /**
  86      * Constructs a copy of a bluetooth interface.
  87      *
  88      * @param device the bluetooth interface to copy
  89      */
  90     BluetoothInterface(const BluetoothInterface &device);
  91
  92     /**
  93      * Destroys the device.
  94      */
  95     ~BluetoothInterface();
  96
  97
  98     /**
  99      * Assigns a bluetooth interface to this bluetooth interface and returns a reference to it.
 100      *
 101      * @param device the bluetooth interface to assign
 102      * @return a reference to the bluetooth interface
 103      */
 104     BluetoothInterface &operator=(const BluetoothInterface &device);
 105
 106     /**
 107      * Retrieves the Unique Bluetooth Identifier (UBI) of the BluetoothInterface.
 108      * This identifier is ubique for each bluetooth and bluetooth interface in the system.
 109      *
 110      * @returns the Unique Bluetooth Identifier of the current bluetooth interface
 111      */
 112     QString ubi() const;
 113
 114     /**
 115      * Create new BluetoothRemoteDevice object from this interface given its address.
 116      *
 117      * @param ubi the identifier of the bluetooth device to instantiate
 118      * @returns a bluetooth object, if a bluetooth device having the given UBI, for this interface exists, 0 otherwise
 119      */
 120     //Solid::Control::BluetoothRemoteDevice* createBluetoothRemoteDevice(const QString &address);
 121     void createBluetoothRemoteDevice(const QString &address);
 122
 123     /**
 124      * Finds a BluetoothRemoteDevice object given its UBI.
 125      *
 126      * @param ubi the identifier of the bluetooth remote device to find from this bluetooth interface
 127      * @returns a valid BluetoothRemoteDevice object if a remote device having the given UBI for this interface exists, an invalid BluetoothRemoteDevice object otherwise.
 128      */
 129     const QString getBluetoothRemoteDeviceUBI(const QString &address) const;
 130
 131     Solid::Control::BluetoothRemoteDevice findBluetoothRemoteDeviceAddr(const QString &addr) const;
 132
 133     Solid::Control::BluetoothRemoteDevice* findBluetoothRemoteDeviceUBI(const QString &ubi) const;
 134
 135     Solid::Control::BluetoothInputDevice* findBluetoothInputDeviceUBI(const QString &ubi) const;
 136
 137     /**
 138      * Retrieves the MAC address of the bluetooth interface/adapter.
 139      *
 140      * @returns MAC address of bluetooth interface
 141      */
 142     QString address() const;
 143
 144     /**
 145      * Retrieves the version of the chip of the bluetooth interface/adapter.
 146      * Example: "Bluetooth 2.0 + EDR"
 147      *
 148      * @returns bluetooth chip version
 149      */
 150     //QString version() const;
 151
 152     /**
 153      * Retrieves the revision of the chip of the bluetooth interface/adapter.
 154      * Example: "HCI 19.2"
 155      *
 156      * @returns bluetooth chip revision
 157      */
 158     //QString revision() const;
 159
 160     /**
 161      * Retrieves the name of the bluetooth chip manufacturer.
 162      * Example: "Boston Silicon Radio"
 163      *
 164      * @returns manufacturer string of bluetooth interface/adapter
 165      */
 166     //QString manufacturer() const;
 167
 168     /**
 169      * Retrieves the name of the manufacturer of the bluetooth interface,
 170      * using the chip supplied by BluetoothInterface::manufacterer()
 171      * Based on device address.
 172      *
 173      * @returns company string of bluetooth interface/adapter
 174      */
 175     //QString company() const;
 176
 177     /**
 178      * Retrieves the discoverable timeout of the bluetooth interface/adapter.
 179      * Discoverable timeout of 0 means never disappear.
 180      *
 181      * @returns current discoverable timeout in seconds
 182      */
 183     int discoverableTimeout() const;
 184
 185     /**
 186      * Retrieves the current discoverable staut of the bluetooth interface/adapter.
 187      *
 188      * @returns current discoverable status of bluetooth interface/adapter
 189      */
 190     bool isDiscoverable() const;
 191
 192     /**
 193      * Retrieves the current status of a discovering session for the adapter.
 194      *
 195      * @returns true if a discovering session is running for the adapter
 196      */
 197     bool isDiscovering() const;
 198
 199
 200     /**
 201      * List all UBIs of connected remote bluetooth devices of this handled bluetooth
 202      * interface/adapter.
 203      *
 204      * @returns list UBIs of connected bluetooth remote devices
 205      */
 206     //BluetoothRemoteDeviceList listConnections() const;
 207
 208     /**
 209      * Retrieves major class of the bluetooth interface/adapter.
 210      * @todo enum
 211      * @returns current major class of the bluetooth interface/adapter
 212      */
 213     //QString majorClass() const;
 214
 215     /**
 216      * List supported minor classes of the bluetooth interface/adapter.
 217      * @todo enum
 218      *
 219      * @returns list of supported minor classes by bluetooth interface/adapter
 220      */
 221     //QStringList listAvailableMinorClasses() const;
 222
 223     /**
 224      * Retrieves minor class of the bluetooth interface/adapter.
 225      * Valid classes, see listAvailableMinorClasses()
 226      * @todo enum
 227      *
 228      * @returns minor class of the bluetooth interface/adapter.
 229      */
 230     //QString minorClass() const;
 231
 232     /**
 233      * List services class of the bluetooth interface/adapter.
 234      * @todo enum
 235      *
 236      * @returns list of service classes or empty list if no services registered
 237      */
 238     //QStringList serviceClasses() const;
 239
 240     /**
 241      * Retrieves name of bluetooth interface/adapter.
 242      * @todo enum
 243      *
 244      * @returns name of bluetooth interface/adapter
 245      */
 246     QString name() const;
 247
 248     /**
 249      * Returns the name of the remote device, given its mac address (mac).
 250      *
 251      * @return the name of the remote device
 252      */
 253     //QString getRemoteName(const QString & mac);
 254
 255     /**
 256      * List UBIs of bonded/paired remote bluetooth devices with this bluetooth
 257      * interface/adapter.
 258      *
 259      * @returns UBIs of bonded/paired bluetooth remote devices
 260      */
 261     //QStringList listBondings() const;
 262
 263     /**
 264      * Periodic discovery status of this bluetooth interface/adapter.
 265      *
 266      * @returns true if periodic discovery is already active otherwise false
 267      */
 268    // bool isPeriodicDiscoveryActive() const;
 269
 270     /**
 271      * Name resolving status of periodic discovery routing.
 272      *
 273      * @returns true if name got resolved while periodic discovery of this bluetooth
 274      * interface/adapter
 275      */
 276     //bool isPeriodicDiscoveryNameResolvingActive() const;
 277
 278     /**
 279      * List the Unique Bluetooth Identifier (UBI) of all known remote devices,
 280      * whether they are seen, used or paired/bonded.
 281      *
 282      * See listConnections()
 283      *
 284      * @returns a QStringList of UBIs of all known remote bluetooth devices
 285      */
 286     //QStringList listRemoteDevices() const;
 287
 288     /**
 289      * List the Unique Bluetooth Identifier (UBI) of all known remote devices since a specific
 290      * datestamp. Known remote devices means remote bluetooth which are seen, used or
 291      * paired/bonded.
 292      *
 293      * See listConnections(), listRemoteDevices()
 294      *
 295      * @param date the datestamp of the beginning of recent used devices
 296      * @returns a QStringList of UBIs of all known remote bluetooth devices
 297      */
 298   //  QStringList listRecentRemoteDevices(const QDateTime &date) const;
 299
 300     /**
 301      * Returns true if the remote bluetooth device is trusted otherwise false.
 302      *
 303      * @param mac the address of the remote device
 304      */
 305 //    bool isTrusted(const QString &);
 306
 307
 308     void createPairedDevice(const QString &, const QString &, const QString &) const;
 309
 310     QMap< QString, QVariant > getProperties() const;
 311
 312     BluetoothRemoteDeviceList listDevices() const;
 313
 314
 315
 316
 317 public Q_SLOTS:
 318     /**
 319      * Set the discoverable state of the interface/adapter.
 320      *
 321      * @param status the discoverable state of the bluetooth interface/adapter
 322      */
 323     void setDiscoverable(bool status);
 324
 325     /**
 326      * Set discoverable timeout of bluetooth interface/adapter.
 327      *
 328      * @param timeout timeout in seconds
 329      */
 330     void setDiscoverableTimeout(int timeout);
 331
 332     /**
 333      * Set minor class of bluetooth interface/adapter.
 334      *
 335      * @param minor set minor class. Valid mode see listAvaliableMinorClasses()
 336      */
 337     //void setMinorClass(const QString &minor);
 338
 339     /**
 340      * Set name of bluetooth interface/adapter.
 341      *
 342      * @param name the name of bluetooth interface/adapter
 343      */
 344     void setName(const QString &name);
 345
 346     /**
 347      * Start discovery of remote bluetooth devices with device name resolving.
 348      */
 349     //void discoverDevices();
 350     /**
 351      * Start discovery of remote bluetooth devices without device name resolving.
 352      */
 353     //void discoverDevicesWithoutNameResolving();
 354     /**
 355      * Cancel discovery of remote bluetooth devices.
 356      */
 357     //void cancelDiscovery();
 358
 359     /**
 360      * Start periodic discovery of remote bluetooth devices.
 361      * See stopPeriodicDiscovery()
 362      */
 363     //void startPeriodicDiscovery();
 364
 365     /**
 366      * Stop periodic discovery of remote bluetooth devices.
 367      */
 368     //void stopPeriodicDiscovery();
 369
 370     /**
 371      * Enable/Disable name resolving of remote bluetooth devices in periodic discovery.
 372      *
 373      * @param resolveName true to enable name resolving otherwise false
 374      */
 375     //void setPeriodicDiscoveryNameResolving(bool resolveNames);
 376
 377     /**
 378      * Marks the device as trusted.
 379      *
 380      * @param mac the address of the remote device
 381      */
 382     //void setTrusted(const QString &);
 383
 384     /**
 385      * Marks the device as not trusted.
 386      *
 387      * @param mac the address of the remote device
 388      */
 389     //void removeTrust(const QString &);
 390
 391     void registerAgent(const QString &,const QString &) const;
 392
 393     void releaseSession() const;
 394
 395     void removeDevice(const QString &) const;
 396
 397     void requestSession() const;
 398
 399     void setProperty(const QString &, const QVariant &) const;
 400
 401     void startDiscovery() const;
 402
 403     void stopDiscovery() const;
 404
 405     void unregisterAgent(const QString &) const;
 406
 407     void cancelDeviceCreation(const QString &) const;
 408
 409
 410 Q_SIGNALS:
 411
 412     /**
 413      * This signal is emitted if the mode of the bluetooth interface/adapter has changed.
 414      * See mode() for valid modes.
 415      *
 416      * @param mode the changed mode
 417      */
 418     //void modeChanged(Solid::Control::BluetoothInterface::Mode);
 419
 420     /**
 421      * The signal is emitted if the discoverable timeout of the bluetooth interface/adapter
 422      * has changed.
 423      *
 424      * @param timeout the changed timeout in seconds
 425      */
 426     //void discoverableTimeoutChanged(int timeout);
 427
 428     /**
 429      * The signal is emitted if the minor class of the bluetooth interface/adapter has changed.
 430      *
 431      * @param minor the new minor class
 432      */
 433     //void minorClassChanged(const QString &minor);
 434
 435     /**
 436      * The signal is emitted if the name of the bluetooth interface/adapter has changed.
 437      *
 438      * @param name the new name of the device
 439      */
 440     //void nameChanged(const QString &name);
 441
 442     /**
 443      * This signal is emitted if a discovery has started.
 444      */
 445     //void discoveryStarted();
 446
 447     /**
 448      * This signal is emitted if a discovery has completed.
 449      */
 450     //void discoveryCompleted();
 451
 452     /**
 453      * This signal is emitted if the bluetooth interface/adapter detects a new remote bluetooth device.
 454      *
 455      * @todo change arguments types of deviceClass (uint32) and rssi (int16)
 456      *
 457      * @param ubi the new bluetooth identifier
 458      * @param deviceClass the device class of the remote device
 459      * @param rssi the Received Signal Strength Information (RSSI) of the remote device
 460      */
 461     //void remoteDeviceFound(const QString &ubi, int deviceClass, int rssi);
 462
 463     /**
 464      * This signal is emitted if the bluetooth interface/adapter detectes a bluetooth device
 465      * disappeared.
 466      *
 467      * @param ubi the ubi of the disappering bluetooth remote device
 468      */
 469     //void remoteDeviceDisappeared(const QString &ubi);
 470
 471     /**
 472      * This signal is emitted if the bluetooth interface/adapter detectes a new name for a
 473      * bluetooth device.
 474      *
 475      * @param address the address of the bluetooth remote device
 476      * @param name the name of the bluetooth remote device
 477      */
 478     //void remoteNameUpdated(const QString &address, const QString &name);
 479
 480     /**
 481      * This signal is emitted if a bluetooth connection has been created.
 482      *
 483      * @param address the address of the connected bluetooth remote device
 484      */
 485     //void remoteDeviceConnected(const QString &address);
 486
 487     /**
 488      * This signal is emitted if a bluetooth connection has been terminated.
 489      *
 490      * @param address the address of the disconnected bluetooth remote device
 491      */
 492     //void remoteDeviceDisconnected(const QString &address);
 493
 494     /**
 495      * This signal is emitted if a bluetooth device was set trusted.
 496      *
 497      * @param address the address of the trusted bluetooth remote device
 498      */
 499     //void trustAdded(const QString &address);
 500
 501     /**
 502      * This signal is emitted if the trust to the bluetooth device was removed.
 503      *
 504      * @param address the address of the bluetooth remote device
 505      */
 506     //void trustRemoved(const QString &address);
 507
 508     /**
 509      * This signal is emitted if a successful bonding has been created.
 510      *
 511      * @param address the address of the bluetooth remote device
 512      */
 513     //void bondingCreated(const QString &address);
 514
 515     /**
 516      * This signal is emitted if the bonding to a bluetooth device has been removed.
 517      *
 518      * @param address the address of the bluetooth remote device
 519      */
 520     //void bondingRemoved(const QString &address);
 521 /**
 522      * This signal is emitted when a remote device is created.
 523      *
 524      * @param ubi the object path of the device on the system bus
 525      */
 526     void deviceCreated(const QString &ubi);
 527
 528     /**
 529      * This signal is emitted when an inquiry session for a periodic discovery finishes and previously found
 530      * devices are no longer in range or visible.
 531      *
 532      * @param address the address of the remote device
 533      */
 534     void deviceDisappeared(const QString &address);
 535
 536     /**
 537      * This signal will be emitted every time an inquiry result has been found by the service daemon.
 538      * In general they only appear during a device discovery.
 539      *
 540      * @param address the address of the remote device
 541      * @param properties the properties of the remote device
 542      */
 543     void deviceFound(const QString &address, const QMap< QString, QVariant > &properties);
 544
 545     /**
 546      * This signal is emitted when a remote device is removed from the system bus.
 547      *
 548      * @param ubi the object path on the system bus from the remote device
 549      */
 550     void deviceRemoved(const QString &ubi);
 551
 552     /**
 553      * This signal is emitted when a property of the adapter is set to a new value.
 554      *
 555      * @param property the named property of the adapter
 556      * @value the new value for the property
 557      */
 558     void propertyChanged(const QString &property, const QVariant &value);
 559
 560
 561
 562
 563 private:
 564     Q_PRIVATE_SLOT(d, void _k_destroyed(QObject *))
 565
 566     QVariant getProperty(const QString&) const;
 567     BluetoothInterfacePrivate * const d;
 568
 569 private Q_SLOTS:
 570     void slotDeviceCreated(const QString& ubi);
 571
 572 };
 573
 574 } //Control
 575 } //Solid
 576
 577
 578 #endif
 579