kio/kio/forwardingslavebase.h

   1 /* This file is part of the KDE project
   2    Copyright (c) 2004 Kevin Ottens <ervin@ipsquad.net>
   3
   4    This library is free software; you can redistribute it and/or
   5    modify it under the terms of the GNU Library General Public
   6    License as published by the Free Software Foundation; either
   7    version 2 of the License, or (at your option) any later version.
   8
   9    This library 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 GNU
  12    Library General Public License for more details.
  13
  14    You should have received a copy of the GNU Library General Public License
  15    along with this library; see the file COPYING.LIB.  If not, write to
  16    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17    Boston, MA 02110-1301, USA.
  18 */
  19
  20 #ifndef _FORWARDING_SLAVE_BASE_H_
  21 #define _FORWARDING_SLAVE_BASE_H_
  22
  23 #include <kio/slavebase.h>
  24 #include <kio/jobclasses.h>
  25
  26 #include <QtCore/QObject>
  27 #include <QtCore/QEventLoop>
  28
  29 namespace KIO
  30 {
  31
  32 class ForwardingSlaveBasePrivate;
  33
  34 /**
  35  * This class should be used as a base for ioslaves acting as a
  36  * forwarder to other ioslaves. It has been designed to support only
  37  * local filesystem like ioslaves.
  38  *
  39  * If the resulting ioslave should be a simple proxy, you only need
  40  * to implement the ForwardingSlaveBase::rewriteUrl() method.
  41  *
  42  * For more advanced behavior, the classic ioslave methods should
  43  * be reimplemented, because their default behavior in this class
  44  * is to forward using the ForwardingSlaveBase::rewriteUrl() method.
  45  *
  46  * A possible code snippet for an advanced stat() behavior would look
  47  * like this in the child class:
  48  *
  49  * \code
  50  *     void ChildProtocol::stat(const KUrl &url)
  51  *     {
  52  *         bool is_special = false;
  53  *
  54  *         // Process the URL to see if it should have
  55  *         // a special treatment
  56  *
  57  *         if ( is_special )
  58  *         {
  59  *             // Handle the URL ourselves
  60  *             KIO::UDSEntry entry;
  61  *             // Fill entry with UDSAtom instances
  62  *             statEntry(entry);
  63  *             finished();
  64  *         }
  65  *         else
  66  *         {
  67  *             // Setup the ioslave internal state if
  68  *             // required by ChildProtocol::rewriteUrl()
  69  *             ForwardingSlaveBase::stat(url);
  70  *         }
  71  *     }
  72  * \endcode
  73  *
  74  * Of course in this case, you surely need to reimplement listDir()
  75  * and get() accordingly.
  76  *
  77  * If you want view on directories to be correctly refreshed when
  78  * something changes on a forwarded URL, you'll need a companion kded
  79  * module to emit the KDirNotify Files*() D-Bus signals.
  80  *
  81  * This class was initially used for media:/ ioslave. This ioslave code
  82  * and the MediaDirNotify class of its companion kded module can be a
  83  * good source of inspiration.
  84  *
  85  * @see ForwardingSlaveBase::rewriteUrl()
  86  * @author Kevin Ottens <ervin@ipsquad.net>
  87  */
  88 class KIO_EXPORT ForwardingSlaveBase : public QObject, public SlaveBase
  89 {
  90 Q_OBJECT
  91 public:
  92     ForwardingSlaveBase(const QByteArray &protocol,
  93                         const QByteArray &poolSocket,
  94                         const QByteArray &appSocket);
  95     virtual ~ForwardingSlaveBase();
  96
  97     virtual void get(const KUrl &url);
  98
  99     virtual void put(const KUrl &url, int permissions,
 100                      JobFlags flags);
 101
 102     virtual void stat(const KUrl &url);
 103
 104     virtual void mimetype(const KUrl &url);
 105
 106     virtual void listDir(const KUrl &url);
 107
 108     virtual void mkdir(const KUrl &url, int permissions);
 109
 110     virtual void rename(const KUrl &src, const KUrl &dest, JobFlags flags);
 111
 112     virtual void symlink(const QString &target, const KUrl &dest,
 113                          JobFlags flags);
 114
 115     virtual void chmod(const KUrl &url, int permissions);
 116
 117     virtual void setModificationTime(const KUrl& url, const QDateTime& mtime);
 118
 119     virtual void copy(const KUrl &src, const KUrl &dest,
 120                       int permissions, JobFlags flags);
 121
 122     virtual void del(const KUrl &url, bool isfile);
 123
 124 protected:
 125     /**
 126      * Rewrite an url to its forwarded counterpart. It should return
 127      * true if everything was ok, and false otherwise.
 128      *
 129      * If a problem is detected it's up to this method to trigger error()
 130      * before returning. Returning false silently cancel the current
 131      * slave operation.
 132      *
 133      * @param url The URL as given during the slave call
 134      * @param newURL The new URL to forward the slave call to
 135      * @return true if the given url could be correctly rewritten
 136      */
 137     virtual bool rewriteUrl(const KUrl &url, KUrl &newURL)=0;
 138
 139     /**
 140      * Allow to modify a UDSEntry before it's sent to the ioslave enpoint.
 141      * This is the default implementation working in most case, but sometimes
 142      * you could make use of more forwarding black magic (for example
 143      * dynamically transform any desktop file into a fake directory...)
 144      *
 145      * @param entry the UDSEntry to post-process
 146      * @param listing indicate if this entry it created during a listDir
 147      *                operation
 148      */
 149     virtual void prepareUDSEntry(KIO::UDSEntry &entry,
 150                                  bool listing=false) const;
 151
 152     /**
 153      * Return the URL being processed by the ioslave
 154      * Only access it inside prepareUDSEntry()
 155      */
 156     KUrl processedUrl() const;
 157
 158     /**
 159      * Return the URL asked to the ioslave
 160      * Only access it inside prepareUDSEntry()
 161      */
 162     KUrl requestedUrl() const;
 163
 164 private:
 165     // KIO::Job
 166     Q_PRIVATE_SLOT(d, void _k_slotResult(KJob *job))
 167     Q_PRIVATE_SLOT(d, void _k_slotWarning(KJob *job, const QString &msg))
 168     Q_PRIVATE_SLOT(d, void _k_slotInfoMessage(KJob *job, const QString &msg))
 169     Q_PRIVATE_SLOT(d, void _k_slotTotalSize(KJob *job, qulonglong size))
 170     Q_PRIVATE_SLOT(d, void _k_slotProcessedSize(KJob *job, qulonglong size))
 171     Q_PRIVATE_SLOT(d, void _k_slotSpeed(KJob *job, unsigned long bytesPerSecond))
 172
 173     // KIO::SimpleJob subclasses
 174     Q_PRIVATE_SLOT(d, void _k_slotRedirection(KIO::Job *job, const KUrl &url))
 175
 176     // KIO::ListJob
 177     Q_PRIVATE_SLOT(d, void _k_slotEntries(KIO::Job *job, const KIO::UDSEntryList &entries))
 178
 179     // KIO::TransferJob
 180     Q_PRIVATE_SLOT(d, void _k_slotData(KIO::Job *job, const QByteArray &data))
 181     Q_PRIVATE_SLOT(d, void _k_slotDataReq(KIO::Job *job, QByteArray &data))
 182     Q_PRIVATE_SLOT(d, void _k_slotMimetype (KIO::Job *job, const QString &type))
 183     Q_PRIVATE_SLOT(d, void _k_slotCanResume (KIO::Job *job, KIO::filesize_t offset))
 184
 185     friend class ForwardingSlaveBasePrivate;
 186     ForwardingSlaveBasePrivate *const d;
 187 };
 188
 189 }
 190
 191 #endif