workspace/libs/solid/control/bluetoothsecurity.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     Copyright (C) 2007 Juan González <jaguilera@opsiland.info>
   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_BLUETOOTHSECURITY_H
  23 #define SOLID_BLUETOOTHSECURITY_H
  24
  25 #include <QtCore/QObject>
  26 #include <QtCore/QPair>
  27
  28 #include <solid/control/singletondefs.h>
  29 #include <solid/control/solid_control_export.h>
  30
  31 namespace Solid
  32 {
  33 namespace Control
  34 {
  35     /**
  36      * This is the interface a class must implement to act as a Passkey Agent.
  37      * A class that acts as a PassKeyAgent will handle the process of pairing
  38      * (stablish a trusted connection) with a remote device.
  39      */
  40     class SOLIDCONTROL_EXPORT BluetoothPasskeyAgent : public QObject
  41     {
  42         Q_OBJECT
  43         Q_PROPERTY(QString remote READ remote)
  44         public:
  45             /**
  46              * Initializes the passkey agent
  47              * @param parent pointer to the parent object for auto deletion
  48              * @param remote address of the remote device for this agent in 00:00:00:00:00:00 format. If empty the agent will act as the default passkey agent for all devices.
  49              */
  50             BluetoothPasskeyAgent(QObject *parent = 0,const QString &remote="");
  51             //FIXME This method shouldn't be virtual, but the linker complains (and halts) if it isn't
  52             /**
  53              * Gets the UBI of the remote device this agent authenticates.
  54              * @return Universal Bluetooth Identifier of the associated agent. If empty the agent authenticates any remote device that requires it.
  55              */
  56             virtual QString remote();
  57         public Q_SLOTS:
  58             /**
  59              * This method gets called when the bluetooth system needs to get the passkey for a remote authentication.
  60              * @param ubi Universal Bluetooth Identifier of the remote device
  61              * @param isNumeric Indicates whether a numerical passkey is expected.
  62              * @return The passkey to be used in this authentication, or an empty string if the request has been rejected/canceled
  63              */
  64             virtual QString requestPasskey(const QString &ubi, bool isNumeric);
  65             /**
  66              * This method gets called when the bluetooth system needs to verify a passkey. The verification is
  67              * done by showing the value to the passkey agent.
  68              * @param ubi Universal Bluetooth Identifier of the remote device
  69              * @param passkey The passkey to confirm.
  70              * @return Whether the passkey accepts or not the remote passkey
  71              */
  72             virtual bool confirmPasskey(const QString &ubi, const QString &passkey);
  73             /**
  74              * Gets called when the bluetooth system needs to show a passkey. No answer is
  75              * expected from the agent.
  76              * @param ubi Universal Bluetooth Identifier of the remote device
  77              * @param passkey The passkey to show
  78              */
  79             virtual void displayPasskey(const QString &ubi, const QString &passkey);
  80             /**
  81              * Indicates keypresses from a remote device,this can happen, for example, when pairing with a keyboard.
  82              * @param ubi Universal Bluetooth Identifier of the remote device that emitted the keypress
  83              */
  84             virtual void keypress(const QString &ubi);
  85             /**
  86              * Indicates to the agent that the authentication has been completed.
  87              * @param ubi Universal Bluetooth Identifier of the remote device that has been authenticated
  88              */
  89             virtual void completedAuthentication(const QString &ubi);
  90             /**
  91              * Indicates to the agent that the authentication has been canceled before completion.
  92              * @param ubi Universal Bluetooth Identifier of the remote device which authentication was
  93              */
  94             virtual void cancelAuthentication(const QString &ubi);
  95         private:
  96             /// UBI of the remote device this passkey agent handles authentication for.
  97             QString m_remote;
  98     };
  99
 100     /**
 101      * This is the interface a class must implement to act as an Authorization Agent.
 102      * An Authorization Agent handles requests to access local services from a remote
 103      * device.
 104      */
 105     class SOLIDCONTROL_EXPORT BluetoothAuthorizationAgent: public QObject
 106     {
 107         Q_OBJECT
 108         public:
 109             /**
 110              * Used to keep the QObject deletion chain working.
 111              * @param parent The parent of this object that will take care of deletion.
 112              */
 113             BluetoothAuthorizationAgent(QObject *parent);
 114         public Q_SLOTS:
 115             /**
 116              * This method gets called when the bluetooth system wants to get an authorization for accessing a local service.
 117              * @param localUbi Universal Bluetooth Identifier of the local device providing the service
 118              * @param remoteAddress of the remote device that wants to use our services
 119              * @param serviceUuid Universal unique identifier for the local service
 120              * @return whether the remote device is authorized to use the local service.
 121              */
 122             virtual bool authorize(const QString &localUbi,const QString &remoteAddress,const QString& serviceUuid)=0;
 123             /**
 124              * Cancels the currently active authorization request for the given local/remote device.
 125              * @param localUbi Universal Bluetooth Identifier of the local device providing the service
 126              * @param remoteAddress of the remote device that wanted to use our services but canceled before completion.
 127              * @param serviceUuid Universal unique identifier for the local service
 128              */
 129             virtual void cancel(const QString &localUbi,const QString &remoteAddress,const QString& serviceUuid)=0;
 130     };
 131
 132     class BluetoothSecurityPrivate;
 133     /**
 134      * Represents a bluetooth security interface which handles passkey request by the backend.
 135      * To get an instance of this class use Solid::Control::BluetoothManager::security().
 136      */
 137     class SOLIDCONTROL_EXPORT BluetoothSecurity : public QObject
 138     {
 139     Q_OBJECT
 140     public:
 141         /**
 142          * Constructs an invalid bluetooth security object
 143          */
 144         BluetoothSecurity();
 145
 146         /**
 147          * Constructs a new bluetooth security object taking its data from a backend.
 148          *
 149          * @param backendObject the object given by the backend
 150          */
 151         explicit BluetoothSecurity(QObject *backendObject);
 152
 153         /**
 154          * Destroys the device.
 155          */
 156         ~BluetoothSecurity();
 157
 158         /**
 159          * Assigns a bluetooth security object to this bluetooth security object and returns a reference to it.
 160          *
 161          * @param device the bluetooth security object to assign
 162          * @return a reference to the bluetooth security object
 163                      */
 164         BluetoothSecurity &operator=(const BluetoothSecurity &object);
 165     public Q_SLOTS:
 166         /**
 167          * Sets the passkeyagent that will handle authentication (for pairing) requests in this process
 168          * @param agent The PasskeyAgent for this process. If there is a previously registered agent it WON'T be deleted, track/parent your objects.
 169          */
 170         void setPasskeyAgent(Solid::Control::BluetoothPasskeyAgent *agent);
 171         /**
 172          * Sets the authorizationagent that will handle service usage authorization requests in this process.
 173          * @param agent The AuthorizationAgent for this process.If there is a previously registered agent it WON'T be deleted, track/parent your objects.
 174          */
 175         void setAuthorizationAgent(Solid::Control::BluetoothAuthorizationAgent *agent);
 176     private:
 177         Q_PRIVATE_SLOT(d, void _k_destroyed(QObject *))
 178
 179         BluetoothSecurityPrivate * const d;
 180     };
 181 } //Control
 182 } //Solid
 183
 184 #endif