File indexing completed on 2023-09-24 04:08:43

0001 /*
0002     SPDX-FileCopyrightText: 2000 David Faure <faure@kde.org>
0003 
0004     SPDX-License-Identifier: LGPL-2.0-or-later
0005 */
0006 
0007 #ifndef SLAVEBASE_H
0008 #define SLAVEBASE_H
0009 
0010 #include "job_base.h" // for KIO::JobFlags
0011 #include <kio/authinfo.h>
0012 #include <kio/global.h>
0013 #include <kio/udsentry.h>
0014 
0015 #include <QByteArray>
0016 #include <QHostInfo>
0017 
0018 #include <memory>
0019 
0020 class KConfigGroup;
0021 class KRemoteEncoding;
0022 class QUrl;
0023 
0024 namespace KIO
0025 {
0026 class Connection;
0027 class SlaveBasePrivate;
0028 
0029 // TODO: Enable once file KIO worker is ported away and add endif, similar in the cpp file
0030 // #if KIOCORE_ENABLE_DEPRECATED_SINCE(version where file:/ KIO worker was ported)
0031 
0032 /**
0033  * @class KIO::SlaveBase slavebase.h <KIO/SlaveBase>
0034  *
0035  * There are two classes that specifies the protocol between application (job)
0036  * and kioslave. SlaveInterface is the class to use on the application end,
0037  * SlaveBase is the one to use on the slave end.
0038  *
0039  * Slave implementations should simply inherit SlaveBase
0040  *
0041  * A call to foo() results in a call to slotFoo() on the other end.
0042  *
0043  * Note that a kioslave doesn't have a Qt event loop. When idle, it's waiting for a command
0044  * on the socket that connects it to the application. So don't expect a kioslave to react
0045  * to D-Bus signals for instance. KIOSlaves are short-lived anyway, so any kind of watching
0046  * or listening for notifications should be done elsewhere, for instance in a kded module
0047  * (see kio_desktop's desktopnotifier.cpp for an example).
0048  *
0049  * If a kioslave needs a Qt event loop within the implementation of one method, e.g. to
0050  * wait for an asynchronous operation to finish, that is possible, using QEventLoop.
0051  *
0052  * @deprecated Since 5.96, use WorkerBase.
0053  */
0054 class KIOCORE_EXPORT SlaveBase
0055 {
0056 public:
0057     KIOCORE_DEPRECATED_VERSION_BELATED(5, 101, 5, 96, "Use WorkerBase")
0058     SlaveBase(const QByteArray &protocol, const QByteArray &pool_socket, const QByteArray &app_socket);
0059     virtual ~SlaveBase();
0060 
0061     /**
0062      * @internal
0063      * Terminate the slave by calling the destructor and then ::exit()
0064      */
0065     void exit();
0066 
0067     /**
0068      * @internal
0069      */
0070     void dispatchLoop();
0071 
0072     ///////////
0073     // Message Signals to send to the job
0074     ///////////
0075 
0076     /**
0077      * Sends data in the slave to the job (i.e.\ in get).
0078      *
0079      * To signal end of data, simply send an empty
0080      * QByteArray().
0081      *
0082      * @param data the data read by the slave
0083      */
0084     void data(const QByteArray &data);
0085 
0086     /**
0087      * Asks for data from the job.
0088      * @see readData
0089      */
0090     void dataReq();
0091 
0092     /**
0093      * open succeeds
0094      * @see open()
0095      */
0096     void opened();
0097 
0098     /**
0099      * Call to signal an error.
0100      * This also finishes the job, so you must not call
0101      * finished() after calling this.
0102      *
0103      * If the error code is KIO::ERR_SLAVE_DEFINED then the
0104      * _text should contain the complete translated text of
0105      * of the error message.
0106      *
0107      * For all other error codes, _text should match the corresponding
0108      * error code. Usually, _text is a file or host name, or the error which
0109      * was passed from the server.<br>
0110      * For example, for KIO::ERR_DOES_NOT_EXIST, _text may only
0111      * be the file or folder which does not exist, nothing else. Otherwise,
0112      * this would break error strings generated by KIO::buildErrorString().<br>
0113      * If you have to add more details than what the standard error codes
0114      * provide, you'll need to use KIO::ERR_SLAVE_DEFINED.
0115      * For a complete list of what _text should contain for each error code,
0116      * look at the source of KIO::buildErrorString().
0117      *
0118      * You can add rich text markup to the message, the places where the
0119      * error message will be displayed are rich text aware.
0120      *
0121      * @see KIO::Error
0122      * @see KIO::buildErrorString
0123      * @param _errid the error code from KIO::Error
0124      * @param _text the rich text error message
0125      */
0126     void error(int _errid, const QString &_text);
0127 
0128     /**
0129      * Call in openConnection, if you reimplement it, when you're done.
0130      */
0131     void connected();
0132 
0133     /**
0134      * Call to signal successful completion of any command
0135      * besides openConnection and closeConnection. Do not
0136      * call this after calling error().
0137      */
0138     void finished();
0139 
0140     /**
0141      * Call to signal that data from the sub-URL is needed
0142      */
0143     void needSubUrlData();
0144 
0145     /**
0146      * Used to report the status of the slave.
0147      * @param host the slave is currently connected to. (Should be
0148      *        empty if not connected)
0149      * @param connected Whether an actual network connection exists.
0150      **/
0151     void slaveStatus(const QString &host, bool connected);
0152 
0153     /**
0154      * Call this from stat() to express details about an object, the
0155      * UDSEntry customarily contains the atoms describing file name, size,
0156      * MIME type, etc.
0157      * @param _entry The UDSEntry containing all of the object attributes.
0158      */
0159     void statEntry(const UDSEntry &_entry);
0160 
0161     /**
0162      * Call this in listDir, each time you have a bunch of entries
0163      * to report.
0164      * @param _entry The UDSEntry containing all of the object attributes.
0165      */
0166     void listEntries(const UDSEntryList &_entry);
0167 
0168     /**
0169      * Call this at the beginning of put(), to give the size of the existing
0170      * partial file, if there is one. The @p offset argument notifies the
0171      * other job (the one that gets the data) about the offset to use.
0172      * In this case, the boolean returns whether we can indeed resume or not
0173      * (we can't if the protocol doing the get() doesn't support setting an offset)
0174      */
0175     bool canResume(KIO::filesize_t offset);
0176 
0177     /**
0178      * Call this at the beginning of get(), if the "range-start" metadata was set
0179      * and returning byte ranges is implemented by this protocol.
0180      */
0181     void canResume();
0182 
0183     ///////////
0184     // Info Signals to send to the job
0185     ///////////
0186 
0187     /**
0188      * Call this in get and copy, to give the total size
0189      * of the file.
0190      */
0191     void totalSize(KIO::filesize_t _bytes);
0192     /**
0193      * Call this during get and copy, once in a while,
0194      * to give some info about the current state.
0195      * Don't emit it in listDir, listEntries speaks for itself.
0196      */
0197     void processedSize(KIO::filesize_t _bytes);
0198 
0199     void position(KIO::filesize_t _pos);
0200 
0201     void written(KIO::filesize_t _bytes);
0202 
0203     /**
0204      * @since 5.66
0205      */
0206     void truncated(KIO::filesize_t _length);
0207 
0208     /**
0209      * Only use this if you can't know in advance the size of the
0210      * copied data. For example, if you're doing variable bitrate
0211      * compression of the source.
0212      *
0213      * STUB ! Currently unimplemented. Here now for binary compatibility.
0214      *
0215      * Call this during get and copy, once in a while,
0216      * to give some info about the current state.
0217      * Don't emit it in listDir, listEntries speaks for itself.
0218      */
0219     void processedPercent(float percent); // KF6 TODO REMOVE
0220 
0221     /**
0222      * Call this in get and copy, to give the current transfer
0223      * speed, but only if it can't be calculated out of the size you
0224      * passed to processedSize (in most cases you don't want to call it)
0225      */
0226     void speed(unsigned long _bytes_per_second);
0227 
0228     /**
0229      * Call this to signal a redirection.
0230      * The job will take care of going to that url.
0231      */
0232     void redirection(const QUrl &_url);
0233 
0234     /**
0235      * Tell that we will only get an error page here.
0236      * This means: the data you'll get isn't the data you requested,
0237      * but an error page (usually HTML) that describes an error.
0238      */
0239     void errorPage();
0240 
0241     /**
0242      * Call this in mimetype() and in get(), when you know the MIME type.
0243      * See mimetype() about other ways to implement it.
0244      */
0245     void mimeType(const QString &_type);
0246 
0247     /**
0248      * Call to signal a warning, to be displayed in a dialog box.
0249      */
0250     void warning(const QString &msg);
0251 
0252     /**
0253      * Call to signal a message, to be displayed if the application wants to,
0254      * for instance in a status bar. Usual examples are "connecting to host xyz", etc.
0255      */
0256     void infoMessage(const QString &msg);
0257 
0258     /**
0259      * Type of message box. Should be kept in sync with KMessageBox::DialogType.
0260      */
0261     enum MessageBoxType {
0262         QuestionTwoActions = 1, ///< @since 5.100
0263         WarningTwoActions = 2, ///< @since 5.100
0264         WarningContinueCancel = 3,
0265         WarningTwoActionsCancel = 4, ///< @since 5.100
0266         Information = 5,
0267         SSLMessageBox = 6,
0268         // In KMessageBox::DialogType; Sorry = 7, Error = 8, QuestionTwoActionsCancel = 9
0269         WarningContinueCancelDetailed = 10,
0270 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 100)
0271         QuestionYesNo ///< @deprecated Since 5.100, use QuestionTwoActions.
0272             KIOCORE_ENUMERATOR_DEPRECATED_VERSION(5, 100, "Use QuestionTwoActions.") = QuestionTwoActions,
0273         WarningYesNo ///< @deprecated Since 5.100, use WarningTwoActions.
0274             KIOCORE_ENUMERATOR_DEPRECATED_VERSION(5, 100, "Use WarningTwoActions.") = WarningTwoActions,
0275         WarningYesNoCancel ///< @deprecated Since 5.100, use WarningTwoActionsCancel.
0276             KIOCORE_ENUMERATOR_DEPRECATED_VERSION(5, 100, "Use WarningTwoActionsCancel.") = WarningTwoActionsCancel,
0277 #endif
0278     };
0279 
0280     /**
0281      * Button codes. Should be kept in sync with KMessageBox::ButtonCode
0282      */
0283     enum ButtonCode {
0284         Ok = 1,
0285         Cancel = 2,
0286         PrimaryAction = 3, ///< @since 5.100
0287         SecondaryAction = 4, ///< @since 5.100
0288         Continue = 5,
0289 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 100)
0290         Yes ///< @deprecated Since 5.100, use PrimaryAction.
0291             KIOCORE_ENUMERATOR_DEPRECATED_VERSION(5, 100, "Use PrimaryAction.") = PrimaryAction,
0292         No ///< @deprecated Since 5.100, use SecondaryAction.
0293             KIOCORE_ENUMERATOR_DEPRECATED_VERSION(5, 100, "Use SecondaryAction.") = SecondaryAction,
0294 #endif
0295     };
0296 
0297     /**
0298      * Call this to show a message box from the slave
0299      * @param type type of message box: QuestionTwoActions, WarningTwoActions, WarningContinueCancel...
0300      * @param text Message string. May contain newlines.
0301      * @param title Message box title.
0302      * @param primaryActionText the text for the first button.
0303      *                          Ignored for @p type Information & SSLMessageBox.
0304      *                          The (deprecated since 5.100) default is i18n("&Yes").
0305      * @param secondaryActionText the text for the second button.
0306      *                            Ignored for @p type WarningContinueCancel, WarningContinueCancelDetailed,
0307      *                            Information & SSLMessageBox.
0308      *                            The (deprecated since 5.100) default is i18n("&No").
0309      * @return a button code, as defined in ButtonCode, or 0 on communication error.
0310      */
0311     int messageBox(MessageBoxType type,
0312                    const QString &text,
0313                    const QString &title = QString(),
0314                    const QString &primaryActionText = QString(),
0315                    const QString &secondaryActionText = QString());
0316 
0317     /**
0318      * Call this to show a message box from the slave
0319      * @param text Message string. May contain newlines.
0320      * @param type type of message box: QuestionTwoActions, WarningTwoActions, WarningContinueCancel...
0321      * @param title Message box title.
0322      * @param primaryActionText the text for the first button.
0323      *                          Ignored for @p type Information & SSLMessageBox.
0324      *                          The (deprecated since 5.100) default is i18n("&Yes").
0325      * @param secondaryActionText the text for the second button.
0326      *                            Ignored for @p type WarningContinueCancel, WarningContinueCancelDetailed,
0327      *                            Information & SSLMessageBox.
0328      *                            The (deprecated since 5.100) default is i18n("&No").
0329      * @param dontAskAgainName the name used to store result from 'Do not ask again' checkbox.
0330      * @return a button code, as defined in ButtonCode, or 0 on communication error.
0331      */
0332     int messageBox(const QString &text,
0333                    MessageBoxType type,
0334                    const QString &title = QString(),
0335                    const QString &primaryActionText = QString(),
0336                    const QString &secondaryActionText = QString(),
0337                    const QString &dontAskAgainName = QString());
0338 
0339     /**
0340      * Sets meta-data to be send to the application before the first
0341      * data() or finished() signal.
0342      */
0343     void setMetaData(const QString &key, const QString &value);
0344 
0345     /**
0346      * Queries for the existence of a certain config/meta-data entry
0347      * send by the application to the slave.
0348      */
0349     bool hasMetaData(const QString &key) const;
0350 
0351     /**
0352      * Queries for config/meta-data send by the application to the slave.
0353      */
0354     QString metaData(const QString &key) const;
0355 
0356     /**
0357      * @internal for ForwardingSlaveBase
0358      * Contains all metadata (but no config) sent by the application to the slave.
0359      */
0360     MetaData allMetaData() const;
0361 
0362     /**
0363      * Returns a map to query config/meta-data information from.
0364      *
0365      * The application provides the slave with all configuration information
0366      * relevant for the current protocol and host.
0367      *
0368      * Use configValue() as shortcut.
0369      * @since 5.64
0370      */
0371     QMap<QString, QVariant> mapConfig() const;
0372 
0373     /**
0374      * Returns a bool from the config/meta-data information.
0375      * @since 5.64
0376      */
0377     bool configValue(const QString &key, bool defaultValue) const;
0378 
0379     /**
0380      * Returns an int from the config/meta-data information.
0381      * @since 5.64
0382      */
0383     int configValue(const QString &key, int defaultValue) const;
0384 
0385     /**
0386      * Returns a QString from the config/meta-data information.
0387      * @since 5.64
0388      */
0389     QString configValue(const QString &key, const QString &defaultValue = QString()) const;
0390 
0391     /**
0392      * Returns a configuration object to query config/meta-data information
0393      * from.
0394      *
0395      * The application provides the slave with all configuration information
0396      * relevant for the current protocol and host.
0397      *
0398      * @note Since 5.64 prefer to use mapConfig() or one of the configValue(...) overloads.
0399      * @todo Find replacements for the other current usages of this method.
0400      */
0401     KConfigGroup *config();
0402     // KF6: perhaps rename mapConfig() to config() when removing this
0403 
0404     /**
0405      * Returns an object that can translate remote filenames into proper
0406      * Unicode forms. This encoding can be set by the user.
0407      */
0408     KRemoteEncoding *remoteEncoding();
0409 
0410     ///////////
0411     // Commands sent by the job, the slave has to
0412     // override what it wants to implement
0413     ///////////
0414 
0415     /**
0416      * Set the host
0417      *
0418      * Called directly by createSlave, this is why there is no equivalent in
0419      * SlaveInterface, unlike the other methods.
0420      *
0421      * This method is called whenever a change in host, port or user occurs.
0422      */
0423     virtual void setHost(const QString &host, quint16 port, const QString &user, const QString &pass);
0424 
0425     /**
0426      * Prepare slave for streaming operation
0427      */
0428     virtual void setSubUrl(const QUrl &url); // TODO KF6 remove
0429 
0430     /**
0431      * Opens the connection (forced).
0432      *
0433      * When this function gets called the slave is operating in
0434      * connection-oriented mode.
0435      * When a connection gets lost while the slave operates in
0436      * connection oriented mode, the slave should report
0437      * ERR_CONNECTION_BROKEN instead of reconnecting. The user is
0438      * expected to disconnect the slave in the error handler.
0439      */
0440     virtual void openConnection();
0441 
0442     /**
0443      * Closes the connection (forced).
0444      *
0445      * Called when the application disconnects the slave to close
0446      * any open network connections.
0447      *
0448      * When the slave was operating in connection-oriented mode,
0449      * it should reset itself to connectionless (default) mode.
0450      */
0451     virtual void closeConnection();
0452 
0453     /**
0454      * get, aka read.
0455      * @param url the full url for this request. Host, port and user of the URL
0456      *        can be assumed to be the same as in the last setHost() call.
0457      *
0458      * The slave should first "emit" the MIME type by calling mimeType(),
0459      * and then "emit" the data using the data() method.
0460      *
0461      * The reason why we need get() to emit the MIME type is:
0462      * when pasting a URL in krunner, or konqueror's location bar,
0463      * we have to find out what is the MIME type of that URL.
0464      * Rather than doing it with a call to mimetype(), then the app or part
0465      * would have to do a second request to the same server, this is done
0466      * like this: get() is called, and when it emits the MIME type, the job
0467      * is put on hold and the right app or part is launched. When that app
0468      * or part calls get(), the slave is magically reused, and the download
0469      * can now happen. All with a single call to get() in the slave.
0470      * This mechanism is also described in KIO::get().
0471      */
0472     virtual void get(const QUrl &url);
0473 
0474     /**
0475      * open.
0476      * @param url the full url for this request. Host, port and user of the URL
0477      *        can be assumed to be the same as in the last setHost() call.
0478      * @param mode see \ref QIODevice::OpenMode
0479      */
0480     virtual void open(const QUrl &url, QIODevice::OpenMode mode);
0481 
0482     /**
0483      * read.
0484      * @param size the requested amount of data to read
0485      * @see KIO::FileJob::read()
0486      */
0487     virtual void read(KIO::filesize_t size);
0488     /**
0489      * write.
0490      * @param data the data to write
0491      * @see KIO::FileJob::write()
0492      */
0493     virtual void write(const QByteArray &data);
0494     /**
0495      * seek.
0496      * @param offset the requested amount of data to read
0497      * @see KIO::FileJob::read()
0498      */
0499     virtual void seek(KIO::filesize_t offset);
0500     /**
0501      * close.
0502      * @see KIO::FileJob::close()
0503      */
0504     virtual void close();
0505 
0506     /**
0507      * put, i.e.\ write data into a file.
0508      *
0509      * @param url where to write the file
0510      * @param permissions may be -1. In this case no special permission mode is set.
0511      * @param flags We support Overwrite here. Hopefully, we're going to
0512      * support Resume in the future, too.
0513      * If the file indeed already exists, the slave should NOT apply the
0514      * permissions change to it.
0515      * The support for resuming using .part files is done by calling canResume().
0516      *
0517      * IMPORTANT: Use the "modified" metadata in order to set the modification time of the file.
0518      *
0519      * @see canResume()
0520      */
0521     virtual void put(const QUrl &url, int permissions, JobFlags flags);
0522 
0523     /**
0524      * Finds all details for one file or directory.
0525      * The information returned is the same as what listDir returns,
0526      * but only for one file or directory.
0527      * Call statEntry() after creating the appropriate UDSEntry for this
0528      * url.
0529      *
0530      * You can use the "details" metadata to optimize this method to only
0531      * do as much work as needed by the application.
0532      * By default details is 2 (all details wanted, including modification time, size, etc.),
0533      * details==1 is used when deleting: we don't need all the information if it takes
0534      * too much time, no need to follow symlinks etc.
0535      * details==0 is used for very simple probing: we'll only get the answer
0536      * "it's a file or a directory (or a symlink), or it doesn't exist".
0537      */
0538     virtual void stat(const QUrl &url);
0539 
0540     /**
0541      * Finds MIME type for one file or directory.
0542      *
0543      * This method should either emit 'mimeType' or it
0544      * should send a block of data big enough to be able
0545      * to determine the MIME type.
0546      *
0547      * If the slave doesn't reimplement it, a get will
0548      * be issued, i.e. the whole file will be downloaded before
0549      * determining the MIME type on it - this is obviously not a
0550      * good thing in most cases.
0551      */
0552     virtual void mimetype(const QUrl &url);
0553 
0554     /**
0555      * Lists the contents of @p url.
0556      * The slave should emit ERR_CANNOT_ENTER_DIRECTORY if it doesn't exist,
0557      * if we don't have enough permissions.
0558      * You should not list files if the path in @p url is empty, but redirect
0559      * to a non-empty path instead.
0560      */
0561     virtual void listDir(const QUrl &url);
0562 
0563     /**
0564      * Create a directory
0565      * @param url path to the directory to create
0566      * @param permissions the permissions to set after creating the directory
0567      * (-1 if no permissions to be set)
0568      * The slave emits ERR_CANNOT_MKDIR if failure.
0569      */
0570     virtual void mkdir(const QUrl &url, int permissions);
0571 
0572     /**
0573      * Rename @p oldname into @p newname.
0574      * If the slave returns an error ERR_UNSUPPORTED_ACTION, the job will
0575      * ask for copy + del instead.
0576      *
0577      * Important: the slave must implement the logic "if the destination already
0578      * exists, error ERR_DIR_ALREADY_EXIST or ERR_FILE_ALREADY_EXIST".
0579      * For performance reasons no stat is done in the destination before hand,
0580      * the slave must do it.
0581      *
0582      * By default, rename() is only called when renaming (moving) from
0583      * yourproto://host/path to yourproto://host/otherpath.
0584      *
0585      * If you set renameFromFile=true then rename() will also be called when
0586      * moving a file from file:///path to yourproto://host/otherpath.
0587      * Otherwise such a move would have to be done the slow way (copy+delete).
0588      * See KProtocolManager::canRenameFromFile() for more details.
0589      *
0590      * If you set renameToFile=true then rename() will also be called when
0591      * moving a file from yourproto: to file:.
0592      * See KProtocolManager::canRenameToFile() for more details.
0593      *
0594      * @param src where to move the file from
0595      * @param dest where to move the file to
0596      * @param flags We support Overwrite here
0597      */
0598     virtual void rename(const QUrl &src, const QUrl &dest, JobFlags flags);
0599 
0600     /**
0601      * Creates a symbolic link named @p dest, pointing to @p target, which
0602      * may be a relative or an absolute path.
0603      * @param target The string that will become the "target" of the link (can be relative)
0604      * @param dest The symlink to create.
0605      * @param flags We support Overwrite here
0606      */
0607     virtual void symlink(const QString &target, const QUrl &dest, JobFlags flags);
0608 
0609     /**
0610      * Change permissions on @p url.
0611      *
0612      * The slave emits ERR_DOES_NOT_EXIST or ERR_CANNOT_CHMOD
0613      */
0614     virtual void chmod(const QUrl &url, int permissions);
0615 
0616     /**
0617      * Change ownership of @p url.
0618      *
0619      * The slave emits ERR_DOES_NOT_EXIST or ERR_CANNOT_CHOWN
0620      */
0621     virtual void chown(const QUrl &url, const QString &owner, const QString &group);
0622 
0623     /**
0624      * Sets the modification time for @p url.
0625      *
0626      * For instance this is what CopyJob uses to set mtime on dirs at the end of a copy.
0627      * It could also be used to set the mtime on any file, in theory.
0628      * The usual implementation on unix is to call utime(path, &myutimbuf).
0629      * The slave emits ERR_DOES_NOT_EXIST or ERR_CANNOT_SETTIME
0630      */
0631     virtual void setModificationTime(const QUrl &url, const QDateTime &mtime);
0632 
0633     /**
0634      * Copy @p src into @p dest.
0635      *
0636      * By default, copy() is only called when copying a file from
0637      * yourproto://host/path to yourproto://host/otherpath.
0638      *
0639      * If you set copyFromFile=true then copy() will also be called when
0640      * moving a file from file:///path to yourproto://host/otherpath.
0641      * Otherwise such a copy would have to be done the slow way (get+put).
0642      * See also KProtocolManager::canCopyFromFile().
0643      *
0644      * If you set copyToFile=true then copy() will also be called when
0645      * moving a file from yourproto: to file:.
0646      * See also KProtocolManager::canCopyToFile().
0647      *
0648      * If the slave returns an error ERR_UNSUPPORTED_ACTION, the job will
0649      * ask for get + put instead.
0650      *
0651      * If the slave returns an error ERR_FILE_ALREADY_EXIST, the job will
0652      * ask for a different destination filename.
0653      *
0654      * @param src where to copy the file from (decoded)
0655      * @param dest where to copy the file to (decoded)
0656      * @param permissions may be -1. In this case no special permission mode is set,
0657      *        and the owner and group permissions are not preserved.
0658      * @param flags We support Overwrite here
0659      *
0660      * Don't forget to set the modification time of @p dest to be the modification time of @p src.
0661      */
0662     virtual void copy(const QUrl &src, const QUrl &dest, int permissions, JobFlags flags);
0663 
0664     /**
0665      * Delete a file or directory.
0666      * @param url file/directory to delete
0667      * @param isfile if true, a file should be deleted.
0668      *               if false, a directory should be deleted.
0669      *
0670      * By default, del() on a directory should FAIL if the directory is not empty.
0671      * However, if metadata("recurse") == "true", then the slave can do a recursive deletion.
0672      * This behavior is only invoked if the slave specifies deleteRecursive=true in its protocol file.
0673      */
0674     virtual void del(const QUrl &url, bool isfile);
0675 
0676     /**
0677      * Change the destination of a symlink
0678      * @param url the url of the symlink to modify
0679      * @param target the new destination (target) of the symlink
0680      */
0681     virtual void setLinkDest(const QUrl &url, const QString &target);
0682 
0683     /**
0684      * Used for any command that is specific to this slave (protocol).
0685      *
0686      * Examples are : HTTP POST, mount and unmount (kio_file)
0687      *
0688      * @param data packed data; the meaning is completely dependent on the
0689      *        slave, but usually starts with an int for the command number.
0690      * Document your slave's commands, at least in its header file.
0691      */
0692     virtual void special(const QByteArray &data);
0693 
0694     /**
0695      * Used for multiple get. Currently only used for HTTP pipelining
0696      * support.
0697      *
0698      * @param data packed data; Contains number of URLs to fetch, and for
0699      * each URL the URL itself and its associated MetaData.
0700      */
0701     virtual void multiGet(const QByteArray &data);
0702 
0703     /**
0704      * Called to get the status of the slave. Slave should respond
0705      * by calling slaveStatus(...)
0706      */
0707     virtual void slave_status();
0708 
0709     /**
0710      * Called by the scheduler to tell the slave that the configuration
0711      * changed (i.e.\ proxy settings).
0712      */
0713     virtual void reparseConfiguration();
0714 
0715     /**
0716      * @return timeout value for connecting to remote host.
0717      */
0718     int connectTimeout();
0719 
0720     /**
0721      * @return timeout value for connecting to proxy in secs.
0722      */
0723     int proxyConnectTimeout();
0724 
0725     /**
0726      * @return timeout value for read from first data from
0727      * remote host in seconds.
0728      */
0729     int responseTimeout();
0730 
0731     /**
0732      * @return timeout value for read from subsequent data from
0733      * remote host in secs.
0734      */
0735     int readTimeout();
0736 
0737     /**
0738      * This function sets a timeout of @p timeout seconds and calls
0739      * special(data) when the timeout occurs as if it was called by the
0740      * application.
0741      *
0742      * A timeout can only occur when the slave is waiting for a command
0743      * from the application.
0744      *
0745      * Specifying a negative timeout cancels a pending timeout.
0746      *
0747      * Only one timeout at a time is supported, setting a timeout
0748      * cancels any pending timeout.
0749      */
0750     void setTimeoutSpecialCommand(int timeout, const QByteArray &data = QByteArray());
0751 
0752     /////////////////
0753     // Dispatching (internal)
0754     ////////////////
0755 
0756     /**
0757      * @internal
0758      */
0759     virtual void dispatch(int command, const QByteArray &data);
0760 
0761     /**
0762      * @internal
0763      */
0764     virtual void dispatchOpenCommand(int command, const QByteArray &data);
0765 
0766     /**
0767      * Read data sent by the job, after a dataReq
0768      *
0769      * @param buffer buffer where data is stored
0770      * @return 0 on end of data,
0771      *         > 0 bytes read
0772      *         < 0 error
0773      **/
0774     int readData(QByteArray &buffer);
0775 
0776 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0)
0777     /**
0778      * It collects entries and emits them via listEntries
0779      * when enough of them are there or a certain time
0780      * frame exceeded (to make sure the app gets some
0781      * items in time but not too many items one by one
0782      * as this will cause a drastic performance penalty).
0783      * @param _entry The UDSEntry containing all of the object attributes.
0784      * @param ready set to true after emitting all items. @p _entry is not
0785      *        used in this case
0786      * @deprecated since 5.0. the listEntry(entry, true) indicated
0787      * that the entry listing was completed. However, each slave should
0788      * already call finished() to also tell us that we're done listing.
0789      * You should make sure that finished() is called when the entry
0790      * listing is completed and simply remove the call to listEntry(entry, true).
0791      */
0792     KIOCORE_DEPRECATED_VERSION(5, 0, "See API docs")
0793     void listEntry(const UDSEntry &_entry, bool ready);
0794 #endif
0795 
0796     /**
0797      * It collects entries and emits them via listEntries
0798      * when enough of them are there or a certain time
0799      * frame exceeded (to make sure the app gets some
0800      * items in time but not too many items one by one
0801      * as this will cause a drastic performance penalty).
0802      * @param entry The UDSEntry containing all of the object attributes.
0803      * @since 5.0
0804      */
0805     void listEntry(const UDSEntry &entry);
0806 
0807     /**
0808      * internal function to connect a slave to/ disconnect from
0809      * either the slave pool or the application
0810      */
0811     void connectSlave(const QString &path);
0812     void disconnectSlave();
0813 
0814     /**
0815      * Prompt the user for Authorization info (login & password).
0816      *
0817      * Use this function to request authorization information from
0818      * the end user. You can also pass an error message which explains
0819      * why a previous authorization attempt failed. Here is a very
0820      * simple example:
0821      *
0822      * \code
0823      * KIO::AuthInfo authInfo;
0824      * int errorCode = openPasswordDialogV2(authInfo);
0825      * if (!errorCode) {
0826      *    qDebug() << QLatin1String("User: ") << authInfo.username;
0827      *    qDebug() << QLatin1String("Password: not displayed here!");
0828      * } else {
0829      *    error(errorCode, QString());
0830      * }
0831      * \endcode
0832      *
0833      * You can also preset some values like the username, caption or
0834      * comment as follows:
0835      *
0836      * \code
0837      * KIO::AuthInfo authInfo;
0838      * authInfo.caption = i18n("Acme Password Dialog");
0839      * authInfo.username = "Wile E. Coyote";
0840      * QString errorMsg = i18n("You entered an incorrect password.");
0841      * int errorCode = openPasswordDialogV2(authInfo, errorMsg);
0842      * [...]
0843      * \endcode
0844      *
0845      * \note You should consider using checkCachedAuthentication() to
0846      * see if the password is available in kpasswdserver before calling
0847      * this function.
0848      *
0849      * \note A call to this function can fail and return @p false,
0850      * if the password server could not be started for whatever reason.
0851      *
0852      * \note This function does not store the password information
0853      * automatically (and has not since kdelibs 4.7). If you want to
0854      * store the password information in a persistent storage like
0855      * KWallet, then you MUST call @ref cacheAuthentication.
0856      *
0857      * @see checkCachedAuthentication
0858      * @param info  See AuthInfo.
0859      * @param errorMsg Error message to show
0860      * @return a KIO error code: NoError (0), KIO::USER_CANCELED, or other error codes.
0861      */
0862     int openPasswordDialogV2(KIO::AuthInfo &info, const QString &errorMsg = QString());
0863 
0864 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 24)
0865     /**
0866      * @deprecated since KF 5.24, use openPasswordDialogV2.
0867      * The return value works differently:
0868      *  instead of
0869      *        if (!openPasswordDialog()) { error(USER_CANCELED); }
0870      *  store and pass the return value to error(), when NOT zero,
0871      *  as shown documentation for openPasswordDialogV2().
0872      */
0873     KIOCORE_DEPRECATED_VERSION(5, 24, "Use SlaveBase::openPasswordDialogV2(...)")
0874     bool openPasswordDialog(KIO::AuthInfo &info, const QString &errorMsg = QString());
0875 #endif
0876 
0877     /**
0878      * Checks for cached authentication based on parameters
0879      * given by @p info.
0880      *
0881      * Use this function to check if any cached password exists
0882      * for the URL given by @p info.  If @p AuthInfo::realmValue
0883      * and/or @p AuthInfo::verifyPath flag is specified, then
0884      * they will also be factored in determining the presence
0885      * of a cached password.  Note that @p Auth::url is a required
0886      * parameter when attempting to check for cached authorization
0887      * info. Here is a simple example:
0888      *
0889      * \code
0890      * AuthInfo info;
0891      * info.url = QUrl("https://www.foobar.org/foo/bar");
0892      * info.username = "somename";
0893      * info.verifyPath = true;
0894      * if ( !checkCachedAuthentication( info ) )
0895      * {
0896      *    int errorCode = openPasswordDialogV2(info);
0897      *     ....
0898      * }
0899      * \endcode
0900      *
0901      * @param       info See AuthInfo.
0902      * @return      @p true if cached Authorization is found, false otherwise.
0903      */
0904     bool checkCachedAuthentication(AuthInfo &info);
0905 
0906     /**
0907      * Caches @p info in a persistent storage like KWallet.
0908      *
0909      * Note that calling openPasswordDialogV2 does not store passwords
0910      * automatically for you (and has not since kdelibs 4.7).
0911      *
0912      * Here is a simple example of how to use cacheAuthentication:
0913      *
0914      * \code
0915      * AuthInfo info;
0916      * info.url = QUrl("https://www.foobar.org/foo/bar");
0917      * info.username = "somename";
0918      * info.verifyPath = true;
0919      * if ( !checkCachedAuthentication( info ) ) {
0920      *    int errorCode = openPasswordDialogV2(info);
0921      *    if (!errorCode) {
0922      *        if (info.keepPassword)  {  // user asked password be save/remembered
0923      *             cacheAuthentication(info);
0924      *        }
0925      *    }
0926      * }
0927      * \endcode
0928      *
0929      * @param info See AuthInfo.
0930      * @return @p true if @p info was successfully cached.
0931      */
0932     bool cacheAuthentication(const AuthInfo &info);
0933 
0934 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0)
0935     /**
0936      * Used by the slave to check if it can connect
0937      * to a given host. This should be called where the slave is ready
0938      * to do a ::connect() on a socket. For each call to
0939      * requestNetwork must exist a matching call to
0940      * dropNetwork, or the system will stay online until
0941      * KNetMgr gets closed (or the SlaveBase gets destructed)!
0942      *
0943      * If KNetMgr is not running, then this is a no-op and returns true
0944      *
0945      * @param host tells the netmgr the host the slave wants to connect
0946      *             to. As this could also be a proxy, we can't just take
0947      *             the host currently connected to (but that's the default
0948      *             value)
0949      *
0950      * @return true in theory, the host is reachable
0951      *         false the system is offline and the host is in a remote network.
0952      *
0953      * @deprecated Since 5.0, for a very very long time, not implemented anymore
0954      * Probably dates back to model dialup times.
0955      */
0956     KIOCORE_DEPRECATED_VERSION(5, 0, "Not implemented & used")
0957     bool requestNetwork(const QString &host = QString());
0958 #endif
0959 
0960 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 0)
0961     /**
0962      *
0963      * Used by the slave to withdraw a connection requested by
0964      * requestNetwork. This function cancels the last call to
0965      * requestNetwork. If a client uses more than one internet
0966      * connection, it must use dropNetwork(host) to
0967      * stop each request.
0968      *
0969      * If KNetMgr is not running, then this is a no-op.
0970      *
0971      * @param host the host passed to requestNetwork
0972      *
0973      * A slave should call this function every time it disconnect from a host.
0974      *
0975      * @deprecated Since 5.0, for a very very long time, not implemented anymore
0976      * Probably dates back to model dialup times.
0977      */
0978     KIOCORE_DEPRECATED_VERSION(5, 0, "Not implemented & used")
0979     void dropNetwork(const QString &host = QString());
0980 #endif
0981 
0982     /**
0983      * Wait for an answer to our request, until we get @p expected1 or @p expected2
0984      * @return the result from readData, as well as the cmd in *pCmd if set, and the data in @p data
0985      */
0986     int waitForAnswer(int expected1, int expected2, QByteArray &data, int *pCmd = nullptr);
0987 
0988     /**
0989      * Internal function to transmit meta data to the application.
0990      * m_outgoingMetaData will be cleared; this means that if the slave is for
0991      * example put on hold and picked up by a different KIO::Job later the new
0992      * job will not see the metadata sent before.
0993      * See kio/DESIGN.krun for an overview of the state
0994      * progression of a job/slave.
0995      * @warning calling this method may seriously interfere with the operation
0996      * of KIO which relies on the presence of some metadata at some points in time.
0997      * You should not use it if you are not familiar with KIO and not before
0998      * the slave is connected to the last job before returning to idle state.
0999      */
1000     void sendMetaData();
1001 
1002     /**
1003      * Internal function to transmit meta data to the application.
1004      * Like sendMetaData() but m_outgoingMetaData will not be cleared.
1005      * This method is mainly useful in code that runs before the slave is connected
1006      * to its final job.
1007      */
1008     void sendAndKeepMetaData();
1009 
1010     /** If your ioslave was killed by a signal, wasKilled() returns true.
1011      Check it regularly in lengthy functions (e.g. in get();) and return
1012      as fast as possible from this function if wasKilled() returns true.
1013      This will ensure that your slave destructor will be called correctly.
1014      */
1015     bool wasKilled() const;
1016 
1017     /** Internally used.
1018      * @internal
1019      */
1020     void setKillFlag();
1021 
1022     /** Internally used
1023      * @internal
1024      */
1025     void lookupHost(const QString &host);
1026 
1027     /** Internally used
1028      * @internal
1029      */
1030     int waitForHostInfo(QHostInfo &info);
1031 
1032     /**
1033      * Checks with job if privilege operation is allowed.
1034      * @return privilege operation status.
1035      * @see PrivilegeOperationStatus
1036      * @since 5.66
1037      */
1038     PrivilegeOperationStatus requestPrivilegeOperation(const QString &operationDetails);
1039 
1040     /**
1041      * Adds @p action to the list of PolicyKit actions which the
1042      * slave is authorized to perform.
1043      *
1044      * @param action the PolicyKit action
1045      * @since 5.45
1046      */
1047     void addTemporaryAuthorization(const QString &action);
1048 
1049 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 66)
1050     /**
1051      * @deprecated since 5.66, use requestPrivilegeOperation(QString)
1052      */
1053     KIOCORE_DEPRECATED_VERSION(5, 66, "Pass QString action to requestPrivilegeOperation")
1054     PrivilegeOperationStatus requestPrivilegeOperation();
1055 #endif
1056 
1057 protected:
1058     /**
1059      * Name of the protocol supported by this slave
1060      */
1061     QByteArray mProtocol;
1062     // Often used by TcpSlaveBase and unlikely to change
1063     MetaData mOutgoingMetaData;
1064     MetaData mIncomingMetaData;
1065 
1066     enum VirtualFunctionId {
1067         AppConnectionMade = 0,
1068         GetFileSystemFreeSpace = 1, // KF6 TODO: Turn into a virtual method
1069         Truncate = 2, // KF6 TODO: Turn into a virtual method
1070     };
1071     virtual void virtual_hook(int id, void *data);
1072 
1073 private:
1074     // Convenience function converting mProtocol to QString as unsupportedActionErrorString(), which
1075     // is used in many places in the code, takes a QString parameter
1076     inline const QString protocolName() const
1077     {
1078         return QString::fromLatin1(mProtocol);
1079     }
1080 
1081     void setRunInThread(bool b);
1082 
1083     // This helps catching missing tr()/i18n() calls in error().
1084     void error(int _errid, const QByteArray &_text);
1085     void send(int cmd, const QByteArray &arr = QByteArray());
1086 
1087     std::unique_ptr<SlaveBasePrivate> const d;
1088     friend class SlaveBasePrivate;
1089     friend class WorkerThread;
1090     friend class WorkerBasePrivate;
1091     friend class WorkerSlaveBaseBridge;
1092 };
1093 
1094 /**
1095  * Returns an appropriate error message if the given command @p cmd
1096  * is an unsupported action (ERR_UNSUPPORTED_ACTION).
1097  * @param protocol name of the protocol
1098  * @param cmd given command
1099  * @see enum Command
1100  */
1101 KIOCORE_EXPORT QString unsupportedActionErrorString(const QString &protocol, int cmd);
1102 }
1103 
1104 #endif