1 /* 2 This file is part of the KDE libraries 3 SPDX-FileCopyrightText: 2000 Stephan Kulow <coolo@kde.org> 4 SPDX-FileCopyrightText: 2000-2013 David Faure <faure@kde.org> 5 6 SPDX-License-Identifier: LGPL-2.0-or-later 7 */ 8 9 #ifndef KIO_SIMPLEJOB_H 10 #define KIO_SIMPLEJOB_H 11 12 #include "job_base.h" 13 #include <kio/global.h> // filesize_t 14 15 namespace KIO 16 { 17 class SimpleJobPrivate; 18 /** 19 * @class KIO::SimpleJob simplejob.h <KIO/SimpleJob> 20 * 21 * A simple job (one url and one command). 22 * This is the base class for all jobs that are scheduled. 23 * Other jobs are high-level jobs (CopyJob, DeleteJob, FileCopyJob...) 24 * that manage subjobs but aren't scheduled directly. 25 */ 26 class KIOCORE_EXPORT SimpleJob : public KIO::Job 27 { 28 Q_OBJECT 29 30 public: 31 ~SimpleJob() override; 32 33 protected: 34 /** 35 * Suspend this job 36 * @see resume 37 */ 38 bool doSuspend() override; 39 40 /** 41 * Resume this job 42 * @see suspend 43 */ 44 bool doResume() override; 45 46 /** 47 * Abort job. 48 * This kills all subjobs and deletes the job. 49 */ 50 bool doKill() override; 51 52 public: 53 /** 54 * Returns the SimpleJob's URL 55 * @return the url 56 */ 57 const QUrl &url() const; 58 59 /** 60 * Abort job. 61 * Suspends slave to be reused by another job for the same request. 62 */ 63 virtual void putOnHold(); 64 65 /** 66 * Discard suspended slave. 67 */ 68 static void removeOnHold(); 69 70 /** 71 * Returns true when redirections are handled internally, the default. 72 * 73 * @since 4.4 74 */ 75 bool isRedirectionHandlingEnabled() const; 76 77 /** 78 * Set @p handle to false to prevent the internal handling of redirections. 79 * 80 * When this flag is set, redirection requests are simply forwarded to the 81 * caller instead of being handled internally. 82 * 83 * @since 4.4 84 */ 85 void setRedirectionHandlingEnabled(bool handle); 86 87 public Q_SLOTS: 88 /** 89 * @internal 90 * Called on a slave's error. 91 * Made public for the scheduler. 92 */ 93 void slotError(int, const QString &); 94 95 protected Q_SLOTS: 96 /** 97 * Called when the slave marks the job 98 * as finished. 99 */ 100 virtual void slotFinished(); 101 102 /** 103 * @internal 104 * Called on a slave's warning. 105 */ 106 virtual void slotWarning(const QString &); 107 108 /** 109 * MetaData from the slave is received. 110 * @param _metaData the meta data 111 * @see metaData() 112 */ 113 virtual void slotMetaData(const KIO::MetaData &_metaData); 114 115 protected: 116 /** 117 * Allow jobs that inherit SimpleJob and are aware 118 * of redirections to store the SSL session used. 119 * Retrieval is handled by SimpleJob::start 120 * @param m_redirectionURL Reference to redirection URL, 121 * used instead of m_url if not empty 122 */ 123 void storeSSLSessionFromJob(const QUrl &m_redirectionURL); 124 125 /** 126 * Creates a new simple job. You don't need to use this constructor, 127 * unless you create a new job that inherits from SimpleJob. 128 */ 129 SimpleJob(SimpleJobPrivate &dd); 130 131 private: 132 Q_DECLARE_PRIVATE(SimpleJob) 133 }; 134 135 /** 136 * Removes a single directory. 137 * 138 * The directory is assumed to be empty. 139 * The job will fail if the directory is not empty. 140 * Use KIO::del() (DeleteJob) to delete non-empty directories. 141 * 142 * @param url The URL of the directory to remove. 143 * @return A pointer to the job handling the operation. 144 */ 145 KIOCORE_EXPORT SimpleJob *rmdir(const QUrl &url); 146 147 /** 148 * Changes permissions on a file or directory. 149 * See the other chmod in chmodjob.h for changing many files 150 * or directories. 151 * 152 * @param url The URL of file or directory. 153 * @param permissions The permissions to set. 154 * @return the job handling the operation. 155 */ 156 KIOCORE_EXPORT SimpleJob *chmod(const QUrl &url, int permissions); 157 158 /** 159 * Changes ownership and group of a file or directory. 160 * 161 * @param url The URL of file or directory. 162 * @param owner the new owner 163 * @param group the new group 164 * @return the job handling the operation. 165 */ 166 KIOCORE_EXPORT SimpleJob *chown(const QUrl &url, const QString &owner, const QString &group); 167 168 /** 169 * Changes the modification time on a file or directory. 170 * 171 * @param url The URL of file or directory. 172 * @param mtime The modification time to set. 173 * @return the job handling the operation. 174 */ 175 KIOCORE_EXPORT SimpleJob *setModificationTime(const QUrl &url, const QDateTime &mtime); 176 177 /** 178 * Rename a file or directory. 179 * Warning: this operation fails if a direct renaming is not 180 * possible (like with files or dirs on separate partitions) 181 * Use move or file_move in this case. 182 * 183 * @param src The original URL 184 * @param dest The final URL 185 * @param flags Can be Overwrite here 186 * @return the job handling the operation. 187 */ 188 KIOCORE_EXPORT SimpleJob *rename(const QUrl &src, const QUrl &dest, JobFlags flags = DefaultFlags); 189 190 /** 191 * Create or move a symlink. 192 * This is the lowlevel operation, similar to file_copy and file_move. 193 * It doesn't do any check (other than those the slave does) 194 * and it doesn't show rename and skip dialogs - use KIO::link for that. 195 * @param target The string that will become the "target" of the link (can be relative) 196 * @param dest The symlink to create. 197 * @param flags Can be Overwrite and HideProgressInfo 198 * @return the job handling the operation. 199 */ 200 KIOCORE_EXPORT SimpleJob *symlink(const QString &target, const QUrl &dest, JobFlags flags = DefaultFlags); 201 202 /** 203 * Execute any command that is specific to one slave (protocol). 204 * 205 * Examples are : HTTP POST, mount and unmount (kio_file) 206 * 207 * @param url The URL isn't passed to the slave, but is used to know 208 * which slave to send it to :-) 209 * @param data Packed data. The meaning is completely dependent on the 210 * slave, but usually starts with an int for the command number. 211 * @param flags Can be HideProgressInfo here 212 * @return the job handling the operation. 213 */ 214 KIOCORE_EXPORT SimpleJob *special(const QUrl &url, const QByteArray &data, JobFlags flags = DefaultFlags); 215 216 /** 217 * Mount filesystem. 218 * 219 * Special job for @p kio_file. 220 * 221 * @param ro Mount read-only if @p true. 222 * @param fstype File system type (e.g. "ext2", can be empty). 223 * @param dev Device (e.g. /dev/sda0). 224 * @param point Mount point, can be @p null. 225 * @param flags Can be HideProgressInfo here 226 * @return the job handling the operation. 227 */ 228 KIOCORE_EXPORT SimpleJob *mount(bool ro, const QByteArray &fstype, const QString &dev, const QString &point, JobFlags flags = DefaultFlags); 229 230 /** 231 * Unmount filesystem. 232 * 233 * Special job for @p kio_file. 234 * 235 * @param point Point to unmount. 236 * @param flags Can be HideProgressInfo here 237 * @return the job handling the operation. 238 */ 239 KIOCORE_EXPORT SimpleJob *unmount(const QString &point, JobFlags flags = DefaultFlags); 240 241 /** 242 * HTTP cache update 243 * 244 * @param url Url to update, protocol must be "http". 245 * @param no_cache If true, cache entry for @p url is deleted. 246 * @param expireDate Local machine time indicating when the entry is 247 * supposed to expire. 248 * @return the job handling the operation. 249 */ 250 KIOCORE_EXPORT SimpleJob *http_update_cache(const QUrl &url, bool no_cache, const QDateTime &expireDate); 251 252 /** 253 * Delete a single file. 254 * 255 * @param src File to delete. 256 * @param flags Can be HideProgressInfo here 257 * @return the job handling the operation. 258 */ 259 KIOCORE_EXPORT SimpleJob *file_delete(const QUrl &src, JobFlags flags = DefaultFlags); 260 261 } 262 263 #endif 264