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_export.h"
  27
  28 #include "../bluetoothinterface.h"
  29 #include "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      * Returns the name of the remote device, given its mac address (mac).
 179      *
 180      * @return the name of the remote device
 181      */
 182     //virtual QString getRemoteName(const QString & mac) = 0;
 183
 184     /**
 185      * List UBIs of bonded/paired remote bluetooth devices with this bluetooth
 186      * interface/adapter.
 187      *
 188      * @returns UBIs of bonded/paired bluetooth remote devices
 189      */
 190     //virtual QStringList listBondings() const = 0;
 191
 192     /**
 193      * Periodic discovery status of this bluetooth interface/adapter.
 194      *
 195      * @returns true if periodic discovery is already active otherwise false
 196      */
 197     //virtual bool isPeriodicDiscoveryActive() const = 0;
 198
 199     /**
 200      * Name resolving status of periodic discovery routing.
 201      *
 202      * @returns true if name got resolved while periodic discovery of this bluetooth
 203      * interface/adapter
 204      */
 205     //virtual bool isPeriodicDiscoveryNameResolvingActive() const = 0;
 206
 207     /**
 208      * List the Universal Bluetooth Identifier (UBI) of all known remote devices, which are
 209      * seen, used or paired/bonded.
 210      *
 211      * See listConnections()
 212      *
 213      * @returns a QStringList of UBIs of all known remote bluetooth devices
 214      */
 215     //virtual QStringList listRemoteDevices() const = 0;
 216
 217     /**
 218      * List the Universal Bluetooth Identifier (UBI) of all known remote devices since a specific
 219      * datestamp. Known remote  devices means remote bluetooth which are seen, used or
 220      * paired/bonded.
 221      *
 222      * See listConnections(), listRemoteDevices()
 223      *
 224      * @param date the datestamp of the beginning of recent used devices
 225      * @returns a QStringList of UBIs of all known remote bluetooth devices
 226      */
 227   //  virtual QStringList listRecentRemoteDevices(const QDateTime &date) const = 0;
 228
 229     /**
 230      * Returns true if the remote bluetooth device is trusted otherwise false.
 231      *
 232      * @param mac the address of the remote device
 233      */
 234 //    virtual bool isTrusted(const QString &) = 0;
 235
 236     /**
 237      *
 238      *
 239      *
 240      */
 241
 242
 243     virtual void createPairedDevice(const QString &, const QString &, const QString &) const = 0;
 244
 245     virtual QMap< QString, QVariant > getProperties() const = 0;
 246
 247     virtual QStringList listDevices() const = 0;
 248
 249     virtual QString findDevice(const QString &) const = 0;
 250
 251     //virtual QString createDevice(const QString &) const = 0;
 252     virtual void createDevice(const QString &) const = 0;
 253
 254
 255
 256 //public Q_SLOTS:
 257     /**
 258      * Set mode of bluetooth interface/adapter.
 259      * Valid modes, see mode()
 260      *
 261      * @param mode the mode of the bluetooth interface/adapter
 262      */
 263     //virtual void setMode(const Solid::Control::BluetoothInterface::Mode mode) = 0;
 264
 265     /**
 266      * Set discoverable timeout of bluetooth interface/adapter.
 267      *
 268      * @param timeout timeout in seconds
 269      */
 270     //virtual void setDiscoverableTimeout(int timeout) = 0;
 271
 272     /**
 273      * Set minor class of bluetooth interface/adapter.
 274      *
 275      * @param minor set minor class. Valid mode see listAvaliableMinorClasses()
 276      */
 277     //virtual void setMinorClass(const QString &minor) = 0;
 278
 279     /**
 280      * Set name of bluetooth interface/adapter.
 281      *
 282      * @param name the name of bluetooth interface/adapter
 283      */
 284     //virtual void setName(const QString &name) = 0;
 285
 286
 287     /**
 288      * Start discovery of remote bluetooth devices with device name resolving.
 289      */
 290     //virtual void discoverDevices() = 0;
 291     /**
 292      * Start discovery of remote bluetooth devices without device name resolving.
 293      */
 294     //virtual void discoverDevicesWithoutNameResolving() = 0;
 295     /**
 296      * Cancel discovery of remote bluetooth devices.
 297      */
 298     //virtual void cancelDiscovery() = 0;
 299
 300     /**
 301      * Start periodic discovery of remote bluetooth devices.
 302      * See stopPeriodicDiscovery()
 303      */
 304     //virtual void startPeriodicDiscovery() = 0;
 305
 306     /**
 307      * Stop periodic discovery of remote bluetooth devices.
 308      */
 309     //virtual void stopPeriodicDiscovery() = 0;
 310
 311     /**
 312      * Enable/Disable name resolving of remote bluetooth devices in periodic discovery.
 313      *
 314      * @param resolveName true to enable name resolving otherwise false
 315      */
 316     //virtual void setPeriodicDiscoveryNameResolving(bool resolveNames) = 0;
 317
 318     /**
 319      * Instantiates a new BluetoothRemoteDevice object from this backend given its address.
 320      *
 321      * @param ubi the identifier of the bluetooth remote device instantiated
 322      * @returns a new BluetoothRemoteDevice object if there's a device having the given UBI, 0 otherwise
 323      */
 324     virtual QObject *createBluetoothRemoteDevice(const QString &ubi) = 0;
 325
 326     virtual QObject *createBluetoothInputDevice(const QString &ubi) = 0;
 327
 328     /**
 329      * Marks the device as trusted.
 330      *
 331      * @param mac the address of the remote device
 332      */
 333     //virtual void setTrusted(const QString &) = 0;
 334
 335     /**
 336      * Marks the device as not trusted.
 337      *
 338      * @param mac the address of the remote device
 339      */
 340     //virtual void removeTrust(const QString &) = 0;
 341
 342     virtual void registerAgent(const QString &,const QString &) = 0;
 343
 344     virtual void releaseSession() = 0;
 345
 346     virtual void removeDevice(const QString &) = 0;
 347
 348     virtual void requestSession() = 0;
 349
 350     virtual void setProperty(const QString &, const QVariant &) = 0;
 351
 352     virtual void startDiscovery() = 0;
 353
 354     virtual void stopDiscovery() = 0;
 355
 356     virtual void unregisterAgent(const QString &) = 0;
 357
 358     virtual void cancelDeviceCreation(const QString &) = 0;
 359
 360
 361 Q_SIGNALS:
 362
 363     /**
 364      * This signal is emitted if the mode of the bluetooth interface/adapter has changed.
 365      * See mode() for valid modes.
 366      *
 367      * @param mode the changed mode
 368      */
 369     //void modeChanged(Solid::Control::BluetoothInterface::Mode);
 370
 371     /**
 372      * The signal is emitted if the discoverable timeout of the bluetooth interface/adapter
 373      * has changed.
 374      *
 375      * @param timeout the changed timeout in seconds
 376      */
 377     //void discoverableTimeoutChanged(int timeout);
 378
 379     /**
 380      * The signal is emitted if the minor class of the bluetooth interface/adapter has changed.
 381      *
 382      * @param minor the new minor class
 383      */
 384     //void minorClassChanged(const QString &minor);
 385
 386     /**
 387      * The signal is emitted if the name of the bluetooth interface/adapter has changed.
 388      *
 389      * @param name the new name of the device
 390      */
 391     //void nameChanged(const QString &name);
 392
 393     /**
 394      * This signal is emitted if a discovery has started.
 395      */
 396     //void discoveryStarted();
 397
 398     /**
 399      * This signal is emitted if a discovery has completed.
 400      */
 401     //void discoveryCompleted();
 402
 403     /**
 404      * This signal is emitted if the bluetooth interface/adapter detects a new remote bluetooth device.
 405      *
 406      * @todo change arguments types of deviceClass (uint32) and rssi (int16)
 407      *
 408      * @param ubi the new bluetooth identifier
 409      * @param deviceClass the device Class of the remote device
 410      * @param rssi the RSSI link of the remote device
 411      */
 412     //void remoteDeviceFound(const QString &ubi, int deviceClass, int rssi);
 413
 414     /**
 415      * This signal is emitted if the bluetooth interface/adapter detectes a bluetooth device
 416      * disappeared.
 417      *
 418      * @param ubi the ubi of the disappering bluetooth remote device
 419      */
 420     //void remoteDeviceDisappeared(const QString &ubi);
 421
 422     /**
 423      * This signal is emitted if the bluetooth interface/adapter detectes a new name for a
 424      * bluetooth device.
 425      *
 426      * @param address the address of the bluetooth remote device
 427      * @param name the name of the bluetooth remote device
 428      */
 429     //void remoteNameUpdated(const QString &address, const QString &name);
 430
 431     /**
 432      * This signal is emitted if a bluetooth connection has been created.
 433      *
 434      * @param address the address of the connected bluetooth remote device
 435      */
 436     //void remoteDeviceConnected(const QString &address);
 437
 438     /**
 439      * This signal is emitted if a bluetooth connection has been terminated.
 440      *
 441      * @param address the address of the disconnected bluetooth remote device
 442      */
 443     //void remoteDeviceDisconnected(const QString &address);
 444
 445     /**
 446      * This signal is emitted if a bluetooth device was set trusted.
 447      *
 448      * @param address the address of the trusted bluetooth remote device
 449      */
 450     //void trustAdded(const QString &address);
 451
 452     /**
 453      * This signal is emitted if the trust to the bluetooth device was removed.
 454      *
 455      * @param address the address of the bluetooth remote device
 456      */
 457     //void trustRemoved(const QString &address);
 458
 459     /**
 460      * This signal is emitted if a successful bonding has been created.
 461      *
 462      * @param address the address of the bluetooth remote device
 463      */
 464     //void bondingCreated(const QString &address);
 465
 466     /**
 467      * This signal is emitted if the bonding to a bluetooth device has been removed.
 468      *
 469      * @param address the address of the bluetooth remote device
 470      */
 471     //void bondingRemoved(const QString &address);
 472
 473     /**
 474      * This signal is emitted when a remote device is created.
 475      *
 476      * @param ubi the object path of the device on the system bus
 477      */
 478     void deviceCreated(const QString &ubi);
 479
 480     /**
 481      * This signal is emitted when an inquiry session for a periodic discovery finishes and previously found
 482      * devices are no longer in range or visible.
 483      *
 484      * @param address the address of the remote device
 485      */
 486     void deviceDisappeared(const QString &address);
 487
 488     /**
 489      * This signal will be emitted every time an inquiry result has been found by the service daemon.
 490      * In general they only appear during a device discovery.
 491      *
 492      * @param address the address of the remote device
 493      * @param properties the properties of the remote device
 494      */
 495     void deviceFound(const QString &address, const QMap< QString,QVariant > &properties);
 496
 497     /**
 498      * This signal is emitted when a remote device is removed from the system bus.
 499      *
 500      * @param ubi the object path on the system bus from the remote device
 501      */
 502     void deviceRemoved(const QString &ubi);
 503
 504     /**
 505      * This signal is emitted when a property of the adapter is set to a new value.
 506      *
 507      * @param property the named property of the adapter
 508      * @value the new value for the property
 509      */
 510     void propertyChanged(const QString &property, const QVariant &value);
 511
 512
 513 };
 514 } //Ifaces
 515 } //Control
 516 } //Solid
 517
 518 Q_DECLARE_INTERFACE(Solid::Control::Ifaces::BluetoothInterface, "org.kde.Solid.Control.Ifaces.BluetoothInterface/0.1")
 519
 520 #endif