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