plasma/servicejob.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_SERVICEJOB_H
  21 #define PLASMA_SERVICEJOB_H
  22
  23 #include <QtCore/QVariant>
  24
  25 #include <kjob.h>
  26 #include <kservice.h>
  27
  28 #include <plasma/plasma_export.h>
  29
  30 namespace Plasma
  31 {
  32
  33 class ServiceJobPrivate;
  34
  35 /**
  36  * @class ServiceJob plasma/servicejob.h <Plasma/ServiceJob>
  37  *
  38  * @short This class provides jobs for use with Plasma::Service
  39  *
  40  * Unlike KJob, you can do the work in start(), since Plasma::Service already
  41  * delays the call to start() until the event loop is reached.
  42  *
  43  * If the job is quick enough that it is not worth reporting the progress,
  44  * you just need to implement start() to do the task, then call emitResult()
  45  * at the end of it.  If the task does not complete successfully, you should
  46  * set a non-zero error code with setError(int) and an error message with
  47  * setErrorText(QString).
  48  *
  49  * If the job is longer (involving network access, for instance), you should
  50  * report the progress at regular intervals.  See the KJob documentation for
  51  * information on how to do this.
  52  */
  53 class PLASMA_EXPORT ServiceJob : public KJob
  54 {
  55     Q_OBJECT
  56
  57 public:
  58     /**
  59      * Default constructor
  60      *
  61      * @arg destination the subject that the job is acting on
  62      * @arg operation   the action that the job is performing on the @p destination
  63      * @arg parameters  the parameters of the @p action
  64      * @arg parent      the parent object for this service
  65      */
  66     ServiceJob(const QString &destination, const QString &operation,
  67                const QMap<QString, QVariant> &parameters, QObject *parent = 0);
  68
  69     /**
  70      * Destructor
  71      */
  72     ~ServiceJob();
  73
  74     /**
  75      * @return the subject that the job is acting on
  76      */
  77     QString destination() const;
  78
  79     /**
  80      * @return the operation the job is performing on the destination
  81      */
  82     QString operationName() const;
  83
  84     /**
  85      * @return the parameters for the operation
  86      */
  87     QMap<QString, QVariant> parameters() const;
  88
  89     /**
  90      * Returns the result of the operation
  91      *
  92      * The result will be invalid if the job has not completed yet, or
  93      * if the job does not have a meaningful result.
  94      *
  95      * Note that this should not be used to find out whether the operation
  96      * was successful.  Instead, you should check the value of error().
  97      *
  98      * @return the result of the operation
  99      */
 100     QVariant result() const;
 101
 102     /**
 103      * Default implementation of start, which simply sets the results to false.
 104      * This makes it easy to create a "failure" job.
 105      */
 106     virtual void start();
 107
 108 protected:
 109     /**
 110      * Sets the result for an operation.
 111      */
 112     void setResult(const QVariant &result);
 113
 114 private:
 115     Q_PRIVATE_SLOT(d, void slotStart())
 116
 117     ServiceJobPrivate * const d;
 118 };
 119
 120 } // namespace Plasma
 121
 122 #endif // multiple inclusion guard
 123