plasma/service.h

   1 /*
   2  *   Copyright 2008 Aaron Seigo <aseigo@kde.org>
   3  *
   4  *   This program is free software; you can redistribute it and/or modify
   5  *   it under the terms of the GNU Library General Public License as
   6  *   published by the Free Software Foundation; either version 2, or
   7  *   (at your option) any later version.
   8  *
   9  *   This program is distributed in the hope that it will be useful,
  10  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  *   GNU General Public License for more details
  13  *
  14  *   You should have received a copy of the GNU Library General Public
  15  *   License along with this program; if not, write to the
  16  *   Free Software Foundation, Inc.,
  17  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  18  */
  19
  20 #ifndef PLASMA_SERVICE_H
  21 #define PLASMA_SERVICE_H
  22
  23 #include <QtCore/QMap>
  24 #include <QtCore/QObject>
  25 #include <QtCore/QVariant>
  26
  27 #include <kconfiggroup.h>
  28
  29 #include <plasma/plasma_export.h>
  30
  31 class QGraphicsWidget;
  32 class QIODevice;
  33 class QWidget;
  34
  35 namespace Plasma
  36 {
  37
  38 class ServiceJob;
  39 class ServicePrivate;
  40
  41 /**
  42  * @class Service plasma/service.h <Plasma/Service>
  43  *
  44  * @short This class provides a generic API for write access to settings or services.
  45  *
  46  * Plasma::Service allows interaction with a "destination", the definition of which
  47  * depends on the Service itself. For a network settings Service this might be a
  48  * profile name ("Home", "Office", "Road Warrior") while a web based Service this
  49  * might be a username ("aseigo", "stranger65").
  50  *
  51  * A Service provides one or more operations, each of which provides some sort
  52  * of interaction with the destination. Operations are described using config
  53  * XML which is used to create a KConfig object with one group per operation.
  54  * The group names are used as the operation names, and the defined items in
  55  * the group are the parameters available to be set when using that operation.
  56  *
  57  * A service is started with a KConfigGroup (representing a ready to be serviced
  58  * operation) and automatically deletes itself after completion and signaling
  59  * success or failure. See KJob for more information on this part of the process.
  60  *
  61  * Services may either be loaded "stand alone" from plugins, or from a DataEngine
  62  * by passing in a source name to be used as the destination.
  63  *
  64  * Sample use might look like:
  65  *
  66  * @code
  67  * Plasma::DataEngine *twitter = dataEngine("twitter");
  68  * Plasma::Service *service = twitter.serviceForSource("aseigo");
  69  * KConfigGroup op = service->operationDescription("update");
  70  * op.writeEntry("tweet", "Hacking on plasma!");
  71  * Plasma::ServiceJob *job = service->startOperationCall(op);
  72  * connect(job, SIGNAL(finished(KJob*)), this, SLOT(jobCompeted()));
  73  * @endcode
  74  */
  75 class PLASMA_EXPORT Service : public QObject
  76 {
  77     Q_OBJECT
  78 public:
  79     /**
  80      * Destructor
  81      */
  82     ~Service();
  83
  84     /**
  85      * Used to load a given service from a plugin.
  86      *
  87      * @param name the plugin name of the service to load
  88      * @param parent the parent object, if any, for the service
  89      *
  90      * @return a Service object, guaranteed to be not null.
  91      */
  92     static Service *load(const QString &name, QObject *parent = 0);
  93
  94     /**
  95      * Sets the destination for this Service to operate on
  96      *
  97      * @arg destination specific to each Service, this sets which
  98      *                  target or address for ServiceJobs to operate on
  99      */
 100     Q_INVOKABLE void setDestination(const QString &destination);
 101
 102     /**
 103      * @return the target destination, if any, that this service is associated with
 104      */
 105     Q_INVOKABLE QString destination() const;
 106
 107     /**
 108      * @return the possible operations for this profile
 109      */
 110     Q_INVOKABLE QStringList operationNames() const;
 111
 112     /**
 113      * Retrieves the parameters for a given operation
 114      *
 115      * @param operationName the operation to retrieve parameters for
 116      * @return KConfigGroup containing the parameters
 117      */
 118     Q_INVOKABLE KConfigGroup operationDescription(const QString &operationName);
 119
 120     /**
 121      * Called to create a ServiceJob which is associated with a given
 122      * operation and parameter set.
 123      *
 124      * @return a started ServiceJob; the consumer may connect to relevant
 125      *         signals before returning to the event loop
 126      */
 127     Q_INVOKABLE ServiceJob *startOperationCall(const KConfigGroup &description, QObject *parent = 0);
 128
 129     /**
 130      * Query to find if an operation is enabled or not.
 131      *
 132      * @param operation the name of the operation to check
 133      * @return true if the operation is enabled, false otherwise
 134      */
 135     Q_INVOKABLE bool isOperationEnabled(const QString &operation) const;
 136
 137     /**
 138      * The name of this service
 139      */
 140     Q_INVOKABLE QString name() const;
 141
 142     /**
 143      * Assoicates a widget with an operation, which allows the service to
 144      * automatically manage, for example, the enabled state of a widget.
 145      *
 146      * This will remove any previous associations the widget had with
 147      * operations on this engine.
 148      *
 149      * @param widget the QWidget to associate with the service
 150      * @param operation the operation to associate the widget with
 151      */
 152     Q_INVOKABLE void associateWidget(QWidget *widget, const QString &operation);
 153
 154     /**
 155      * Disassociates a widget if it has been associated with an operation
 156      * on this service.
 157      *
 158      * This will not change the enabled state of the widget.
 159      *
 160      * @param widget the QWidget to disassociate.
 161      */
 162     Q_INVOKABLE void disassociateWidget(QWidget *widget);
 163
 164     /**
 165      * Assoicates a widget with an operation, which allows the service to
 166      * automatically manage, for example, the enabled state of a widget.
 167      *
 168      * This will remove any previous associations the widget had with
 169      * operations on this engine.
 170      *
 171      * @param widget the QGraphicsItem to associate with the service
 172      * @param operation the operation to associate the widget with
 173      */
 174     Q_INVOKABLE void associateWidget(QGraphicsWidget *widget, const QString &operation);
 175
 176     /**
 177      * Disassociates a widget if it has been associated with an operation
 178      * on this service.
 179      *
 180      * This will not change the enabled state of the widget.
 181      *
 182      * @param widget the QGraphicsWidget to disassociate.
 183      */
 184     Q_INVOKABLE void disassociateWidget(QGraphicsWidget *widget);
 185
 186 Q_SIGNALS:
 187     /**
 188      * Emitted when a job associated with this Service completes its task
 189      */
 190     void finished(Plasma::ServiceJob *job);
 191
 192     /**
 193      * Emitted when the Service's operations change. For example, a
 194      * media player service may change what operations are available
 195      * in response to the state of the player.
 196      */
 197     void operationsChanged();
 198
 199 protected:
 200     /**
 201      * Default constructor
 202      *
 203      * @arg parent the parent object for this service
 204      */
 205     explicit Service(QObject *parent = 0);
 206
 207     /**
 208      * Constructor for plugin loading
 209      */
 210     Service(QObject *parent, const QVariantList &args);
 211
 212     /**
 213      * Called when a job should be created by the Service.
 214      *
 215      * @param operation which operation to work on
 216      * @param parameters the parameters set by the user for the operation
 217      * @return a ServiceJob that can be started and monitored by the consumer
 218      */
 219     virtual ServiceJob *createJob(const QString &operation,
 220                                   QMap<QString, QVariant> &parameters) = 0;
 221
 222     /**
 223      * By default this is based on the file in plasma/services/name.operations, but can be
 224      * reimplented to use a different mechanism.
 225      *
 226      * It should result in a call to setOperationsScheme(QIODevice *);
 227      */
 228     virtual void registerOperationsScheme();
 229
 230     /**
 231      * Sets the XML used to define the operation schema for
 232      * this Service.
 233      */
 234     void setOperationsScheme(QIODevice *xml);
 235
 236     /**
 237      * Sets the name of the Service; useful for Services not loaded from plugins,
 238      * which use the plugin name for this.
 239      *
 240      * @arg name the name to use for this service
 241      */
 242     void setName(const QString &name);
 243
 244     /**
 245      * Enables a given service by name
 246      *
 247      * @param operation the name of the operation to enable or disable
 248      * @param enable true if the operation should be enabld, false if disabled
 249      */
 250     void setOperationEnabled(const QString &operation, bool enable);
 251
 252 private:
 253     Q_PRIVATE_SLOT(d, void jobFinished(KJob *))
 254     Q_PRIVATE_SLOT(d, void associatedWidgetDestroyed(QObject *))
 255     Q_PRIVATE_SLOT(d, void associatedGraphicsWidgetDestroyed(QObject *))
 256
 257     ServicePrivate * const d;
 258
 259     friend class ServicePrivate;
 260 };
 261
 262 } // namespace Plasma
 263
 264 /**
 265  * Register a service when it is contained in a loadable module
 266  */
 267 #define K_EXPORT_PLASMA_SERVICE(libname, classname) \
 268 K_PLUGIN_FACTORY(factory, registerPlugin<classname>();) \
 269 K_EXPORT_PLUGIN(factory("plasma_service_" #libname)) \
 270 K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION)
 271
 272 #endif // multiple inclusion guard
 273