knode/knjobdata.h

   1 /*
   2     KNode, the KDE newsreader
   3     Copyright (c) 1999-2006 the KNode authors.
   4     See file AUTHORS for details
   5
   6     This program is free software; you can redistribute it and/or modify
   7     it under the terms of the GNU General Public License as published by
   8     the Free Software Foundation; either version 2 of the License, or
   9     (at your option) any later version.
  10     You should have received a copy of the GNU General Public License
  11     along with this program; if not, write to the Free Software Foundation,
  12     Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, US
  13 */
  14
  15 #ifndef KNJOBDATA_H
  16 #define KNJOBDATA_H
  17
  18 #include <kurl.h>
  19 #include <kio/global.h>
  20
  21 #include <QObject>
  22 #include <QList>
  23
  24 #include <libkdepim/progressmanager.h>
  25
  26 class KJob;
  27
  28 namespace KIO {
  29 class Job;
  30 }
  31
  32 class KNJobItem;
  33 class KNJobData;
  34 class KNServerInfo;
  35
  36
  37 /** Base class for classes that want to create and schedule jobs. */
  38 class KNJobConsumer {
  39
  40   public:
  41     KNJobConsumer();
  42     virtual ~KNJobConsumer();
  43
  44     /** Send the job to the scheduler and append it to the
  45      *  job queue.
  46      */
  47     void emitJob(KNJobData *j);
  48
  49     /** Remove the job from the joblist and process it by
  50      *  calling @ref processJob
  51      */
  52     void jobDone(KNJobData *j);
  53
  54     /** Returns true if we are waiting for at least one job
  55      *  to be completed
  56      */
  57     bool jobsPending() const { return !mJobs.isEmpty(); }
  58
  59     /** Find any job related to a job item and cancel it.
  60      */
  61     void cancelJobs( KNJobItem *item );
  62
  63   protected:
  64     /** The actual work is done here */
  65     virtual void processJob(KNJobData *j);
  66     /** List of all active jobs. */
  67     QList<KNJobData*> mJobs;
  68
  69 };
  70
  71
  72 /** Base class for data structures used in jobs. */
  73 class KNJobItem {
  74
  75   public:
  76     KNJobItem()           {}
  77     virtual ~KNJobItem()  {}
  78
  79     virtual bool isLocked()         { return false; }
  80     virtual void setLocked(bool)    { }
  81
  82     virtual QString prepareForExecution() { return QString(); }
  83
  84 };
  85
  86
  87 /** Abstract base class for all KNode internal jobs.
  88  *  This class takes care of:
  89  *  - progress/status reporting and user interaction (cancellation).
  90  *  - error handling/reporting.
  91  *  - easy handling of associated KIO jobs.
  92  *  To imlpement a new job class, you need to sub-class this class and
  93  *  implement the execute() method.
  94  */
  95 class KNJobData : public QObject
  96 {
  97   Q_OBJECT
  98
  99   public:
 100
 101     friend class KNJobConsumer;
 102
 103     enum jobType {  JTLoadGroups=1,
 104                     JTFetchGroups,
 105                     JTfetchNewHeaders,
 106                     JTfetchArticle,
 107                     JTpostArticle,
 108                     JTmail,
 109                     JTfetchSource   };
 110
 111     KNJobData(jobType t, KNJobConsumer *c, KNServerInfo *a, KNJobItem *i);
 112     ~KNJobData();
 113
 114     jobType type() const                  { return t_ype; }
 115
 116     KNServerInfo* account() const         { return a_ccount; }
 117     KNJobItem* data() const               { return d_ata; }
 118
 119     /** Returns the error code (see KIO::Error). */
 120     int error() const { return mError; }
 121     /** Returns the error message. */
 122     QString errorString() const { return mErrorString; }
 123     /** Returns true if the job finished successfully. */
 124     bool success() const { return mErrorString.isEmpty() && mError == 0; }
 125     /** Returns true if the job has been canceled by the user. */
 126     bool canceled() const { return mCanceled; }
 127
 128     /** Cancels this job.
 129      *  If the job is currently active, this cancels the associated KIO job and
 130      *  emits the finished signal.
 131      */
 132     void cancel();
 133
 134     /** Set job error information.
 135      *  @param err The error code (see KIO::Error).
 136      *  @param errMsg A translated error message.
 137      */
 138     void setError( int err, const QString &errMsg );
 139
 140     void prepareForExecution()           { mErrorString = d_ata->prepareForExecution(); }
 141     void notifyConsumer();
 142
 143     /** Performs the actual operation of a job, needs to be reimplemented for
 144      *  every job.
 145      *  Note that a job might be executed multiple times e.g. in case of an
 146      *  authentication error.
 147      */
 148     virtual void execute() = 0;
 149
 150     /** Returns the progress item for this job. */
 151     KPIM::ProgressItem* progressItem() const { return mProgressItem; }
 152     /** Creates a KPIM::ProgressItem for this job. */
 153     void createProgressItem();
 154
 155     /** Set the status message of the progress item if available.
 156      *  @param msg The new status message.
 157      */
 158     void setStatus( const QString &msg ) { if ( mProgressItem ) mProgressItem->setStatus( msg ); }
 159     /** Set the progress value of the progress item if available.
 160      *  @param progress The new progress value.
 161      */
 162     void setProgress( unsigned int progress ) { if ( mProgressItem ) mProgressItem->setProgress( progress ); }
 163     /** Tells the progress item to indicate that the job has finished if
 164      *  available. This causes the destruction of the progress item.
 165      */
 166     void setComplete() { if ( mProgressItem ) { mProgressItem->setComplete(); mProgressItem = 0; } }
 167
 168   signals:
 169     /** Emitted when a job has been finished.
 170      *  It's recommended to to emit it via emitFinished().
 171      */
 172     void finished( KNJobData* );
 173
 174   protected:
 175     /** Emits the finished() signal via a single-shot timer. */
 176     void emitFinished();
 177
 178     /** Returns a correctly set up KUrl according to the encryption and
 179      *  authentication settings for KIO slave operations.
 180      */
 181     KUrl baseUrl() const;
 182
 183     /**
 184       Connects progress signals.
 185       @param job The KJob to setup.
 186     */
 187     void setupKJob( KJob *job );
 188
 189     /** Sets TLS metadata and connects the given KIO job to the progress item.
 190      *  @param job The KIO job to setup.
 191      */
 192     void setupKIOJob( KIO::Job *job );
 193
 194   protected:
 195     jobType t_ype;
 196     KNJobItem *d_ata;
 197     KNServerInfo *a_ccount;
 198     /** The job error code (see KIO::Error). */
 199     int mError;
 200     /** The error message. */
 201     QString mErrorString;
 202     /** Cancel status flag. */
 203     bool mCanceled;
 204     KNJobConsumer *c_onsumer;
 205     /** An associated KJob. */
 206     KJob *mJob;
 207     /** The progress item representing this job to the user. */
 208     KPIM::ProgressItem *mProgressItem;
 209
 210   private slots:
 211     /** Connected to the progress signal of mJob to update the progress item. */
 212     void slotJobPercent( KJob *job, unsigned long percent );
 213     /** Connected to the info message signal if mJob to update the progress item. */
 214     void slotJobInfoMessage( KJob *job, const QString &msg );
 215     /** Emits the finished signal. @see emitFinished() */
 216     void slotEmitFinished();
 217
 218 };
 219
 220
 221 #endif