kio/kio/slave.h

   1 // -*- c++ -*-
   2 /*
   3  *  This file is part of the KDE libraries
   4  *  Copyright (c) 2000 Waldo Bastian <bastian@kde.org>
   5  *                2000 Stephan Kulow <coolo@kde.org>
   6  *
   7  *  This library is free software; you can redistribute it and/or
   8  *  modify it under the terms of the GNU Library General Public
   9  *  License version 2 as published by the Free Software Foundation.
  10  *
  11  *  This library is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  *  Library General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU Library General Public License
  17  *  along with this library; see the file COPYING.LIB.  If not, write to
  18  *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19  *  Boston, MA 02110-1301, USA.
  20  **/
  21
  22 #ifndef KIO_SLAVE_H
  23 #define KIO_SLAVE_H
  24
  25 #define KIO_SLAVE_EXPORT KIO_EXPORT
  26
  27 #include <time.h>
  28 #include <unistd.h>
  29
  30 #include <QtCore/QObject>
  31
  32 #include <kurl.h>
  33
  34 #include "kio/slaveinterface.h"
  35
  36 namespace KIO {
  37
  38     class SlavePrivate;
  39     // Attention developers: If you change the implementation of KIO::Slave,
  40     // do *not* use connection() or slaveconn but the respective KIO::Slave
  41     // accessor methods. Otherwise classes derived from Slave might break. (LS)
  42     //
  43     // Do not use this class directly, outside of KIO. Only use the Slave pointer
  44     // that is returned by the scheduler for passing it around.
  45     //
  46     // TODO: KDE5: Separate public API and private stuff for this better
  47     class KIO_SLAVE_EXPORT Slave : public KIO::SlaveInterface
  48     {
  49         Q_OBJECT
  50     public:
  51         explicit Slave(const QString &protocol, QObject *parent = 0);
  52
  53         virtual ~Slave();
  54
  55         void setPID(pid_t);
  56
  57         int slave_pid();
  58
  59         /**
  60          * Force termination
  61          */
  62         void kill();
  63
  64         /**
  65          * @return true if the slave survived the last mission.
  66          */
  67         bool isAlive();
  68
  69         /**
  70          * Set host for url
  71          * @param host to connect to.
  72          * @param port to connect to.
  73          * @param user to login as
  74          * @param passwd to login with
  75          */
  76         virtual void setHost( const QString &host, quint16 port,
  77                       const QString &user, const QString &passwd);
  78
  79         /**
  80          * Clear host info.
  81          */
  82         void resetHost();
  83
  84         /**
  85          * Configure slave
  86          */
  87         virtual void setConfig(const MetaData &config);
  88
  89         /**
  90          * The protocol this slave handles.
  91          *
  92          * @return name of protocol handled by this slave, as seen by the user
  93          */
  94         QString protocol();
  95
  96         void setProtocol(const QString & protocol);
  97         /**
  98          * The actual protocol used to handle the request.
  99          *
 100          * This method will return a different protocol than
 101          * the one obtained by using protocol() if a
 102          * proxy-server is used for the given protocol.  This
 103          * usually means that this method will return "http"
 104          * when the actuall request was to retrieve a resource
 105          * from an "ftp" server by going through a proxy server.
 106          *
 107          * @return the actual protocol (io-slave) that handled the request
 108          */
 109         QString slaveProtocol();
 110
 111         /**
 112          * @return Host this slave is (was?) connected to
 113          */
 114         QString host();
 115
 116         /**
 117          * @return port this slave is (was?) connected to
 118          */
 119         quint16 port();
 120
 121         /**
 122          * @return User this slave is (was?) logged in as
 123          */
 124         QString user();
 125
 126         /**
 127          * @return Passwd used to log in
 128          */
 129         QString passwd();
 130
 131         /**
 132          * Creates a new slave.
 133          *
 134          * @param protocol the protocol
 135          * @param url is the url
 136          * @param error is the error code on failure and undefined else.
 137          * @param error_text is the error text on failure and undefined else.
 138          *
 139          * @return 0 on failure, or a pointer to a slave otherwise.
 140          */
 141         static Slave* createSlave( const QString &protocol, const KUrl& url, int& error, QString& error_text );
 142
 143         /**
 144          * Requests a slave on hold for ths url, from klauncher, if there is such a job.
 145          * See hold()
 146          */
 147         static Slave* holdSlave( const QString &protocol, const KUrl& url );
 148
 149         // == communication with connected kioslave ==
 150         // whenever possible prefer these methods over the respective
 151         // methods in connection()
 152         /**
 153          * Suspends the operation of the attached kioslave.
 154          */
 155         virtual void suspend();
 156         /**
 157          * Resumes the operation of the attached kioslave.
 158          */
 159         virtual void resume();
 160         /**
 161          * Tells whether the kioslave is suspended.
 162          * @return true if the kioslave is suspended.
 163          */
 164         virtual bool suspended();
 165         /**
 166          * Sends the given command to the kioslave.
 167          * @param cmd command id
 168          * @param arr byte array containing data
 169          */
 170         virtual void send(int cmd, const QByteArray &arr = QByteArray());
 171
 172         // == end communication with connected kioslave ==
 173         /**
 174          * Puts the kioslave associated with @p url at halt, and return it to klauncher, in order
 175          * to let another application connect to it and finish the job.
 176          * This is for the krunner case: type a URL in krunner, it will start downloading
 177          * to find the mimetype (KRun), and then hold the slave, publish the held slave using,
 178          * this method, and the final application can continue the same download by requesting
 179          * the same URL.
 180          */
 181         virtual void hold(const KUrl &url); // TODO KDE5: no reason to be virtual
 182
 183         /**
 184          * @return The time this slave has been idle.
 185          */
 186         time_t idleTime();
 187
 188         /**
 189          * Marks this slave as idle.
 190          */
 191         void setIdle();
 192
 193         /*
 194          * @returns Whether the slave is connected
 195          * (Connection oriented slaves only)
 196          */
 197         bool isConnected();
 198         void setConnected(bool c);
 199
 200         void ref();
 201         void deref();
 202
 203     public Q_SLOTS:
 204         void accept();
 205         void gotInput();
 206         void timeout();
 207     Q_SIGNALS:
 208         void slaveDied(KIO::Slave *slave);
 209
 210     private:
 211         Q_DECLARE_PRIVATE(Slave)
 212     };
 213 }
 214
 215 #undef KIO_SLAVE_EXPORT
 216
 217 #endif