Warning, file /office/calligra/libs/store/KoNetAccess.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).
0001 /* 0002 This file is part of the KDE libraries 0003 Copyright (C) 1997 Torben Weis (weis@kde.org) 0004 Copyright (C) 1998 Matthias Ettrich (ettrich@kde.org) 0005 Copyright (C) 1999-2004 David Faure (faure@kde.org) 0006 0007 This library is free software; you can redistribute it and/or 0008 modify it under the terms of the GNU Library General Public 0009 License as published by the Free Software Foundation; either 0010 version 2 of the License, or (at your option) any later version. 0011 0012 This library is distributed in the hope that it will be useful, 0013 but WITHOUT ANY WARRANTY; without even the implied warranty of 0014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0015 Library General Public License for more details. 0016 0017 You should have received a copy of the GNU Library General Public License 0018 along with this library; see the file COPYING.LIB. If not, write to 0019 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 0020 Boston, MA 02110-1301, USA. 0021 */ 0022 0023 #ifndef KO_NETACCESS_h 0024 #define KO_NETACCESS_h 0025 0026 #include <QtCore/QObject> 0027 #include <QtCore/QString> 0028 #include <kio/global.h> 0029 #include <kio/udsentry.h> 0030 #include <kio/jobclasses.h> // for KIO::JobFlags 0031 0032 class QStringList; 0033 class QWidget; 0034 0035 #include <kostore_export.h> 0036 0037 0038 template<typename T, typename K> class QMap; 0039 0040 class KJob; 0041 namespace KIO 0042 { 0043 0044 class Job; 0045 0046 class NetAccessPrivate; 0047 /** 0048 * Net Transparency. 0049 * 0050 * NetAccess allows you to do simple file operation (load, save, 0051 * copy, delete...) without working with KIO::Job directly. 0052 * Whereas a KIO::Job is asynchronous, meaning that the 0053 * developer has to connect slots for it, KIO::NetAccess provides 0054 * synchronous downloads and uploads, as well as temporary file 0055 * creation and removal. The functions appear to be blocking, 0056 * but the Qt event loop continues running while the operations 0057 * are handled. More precisely, the GUI will still repaint, but no user 0058 * interaction will be possible. If you can, please use async KIO jobs instead! 0059 * See the documentation of KJob::exec() for more about the dangers of NetAccess. 0060 * 0061 * This class isn't meant to be used as a class but only as a simple 0062 * namespace for static functions, though an instance of the class 0063 * is built for internal purposes. TODO KDE5: turn into namespace, 0064 * and make the qobject class private. 0065 * 0066 * Port to kio done by David Faure, faure@kde.org 0067 * 0068 * @short Provides a blocking interface to KIO file operations. 0069 */ 0070 class KOSTORE_EXPORT NetAccess : public QObject 0071 { 0072 Q_OBJECT 0073 0074 public: 0075 enum StatSide { 0076 SourceSide, 0077 DestinationSide 0078 }; 0079 0080 /** 0081 * Downloads a file from an arbitrary URL (@p src) to a 0082 * temporary file on the local filesystem (@p target). 0083 * 0084 * If the argument 0085 * for @p target is an empty string, download will generate a 0086 * unique temporary filename in /tmp. Since @p target is a reference 0087 * to QString you can access this filename easily. Download will 0088 * return true if the download was successful, otherwise false. 0089 * 0090 * Special case: 0091 * If the URL is of kind file:, then no downloading is 0092 * processed but the full filename is returned in @p target. 0093 * That means you @em have to take care about the @p target argument. 0094 * (This is very easy to do, please see the example below.) 0095 * 0096 * Download is synchronous. That means you can use it like this: 0097 * (assuming your application has a loadFile() function) 0098 * 0099 * \code 0100 * QString tmpFile; 0101 * if( KIO::NetAccess::download(url, tmpFile, window)) { 0102 * loadFile(tmpFile); 0103 * KIO::NetAccess::removeTempFile(tmpFile); 0104 * } else { 0105 * KMessageBox::error(this, KIO::NetAccess::lastErrorString()); 0106 * } 0107 * \endcode 0108 * 0109 * Of course, your user interface will still process exposure/repaint 0110 * events during the download. 0111 * 0112 * If the download fails, lastError() and lastErrorString() will be set. 0113 * 0114 * If the url is always remote, then you could also just write the more usual way: 0115 * \code 0116 * QTemporaryFile tmpFile; 0117 * if (tmpFile.open()) { 0118 * KIO::Job* getJob = KIO::file_copy(url, QUrl::fromLocalFile(tmpFile.fileName()), -1, KIO::Overwrite | KIO::HideProgressInfo); 0119 * getJob->ui()->setWindow(window); 0120 * if (KIO::NetAccess::synchronousRun(getJob, 0)) { 0121 * loadFile(tmpFile.fileName()); 0122 * } else { 0123 * getJob->ui()->showErrorMessage(); 0124 * } 0125 * } 0126 * \endcode 0127 * 0128 * @param src URL Reference to the file to download. 0129 * @param target String containing the final local location of the 0130 * file. If you insert an empty string, it will 0131 * return a location in a temporary spot. <B>Note:</B> 0132 * you are responsible for the removal of this file when 0133 * you are finished reading it using removeTempFile. 0134 * @param window main window associated with this job. This is used to 0135 * automatically cache and discard authentication information 0136 * as needed. If NULL, authentication information will be 0137 * cached only for a short duration after which the user will 0138 * again be prompted for passwords as needed. 0139 * @return true if successful, false for failure. Use lastErrorString() to 0140 * get the reason it failed. 0141 * 0142 * @see lastErrorString() 0143 * @deprecated since 5.0, use KIO::storedGet + KJobWidgets::setWindow + job->exec() instead 0144 */ 0145 static bool download(const QUrl &src, QString &target, QWidget *window); 0146 0147 /** 0148 * Removes the specified file if and only if it was created 0149 * by KIO::NetAccess as a temporary file for a former download. 0150 * 0151 * Note: This means that if you created your temporary with KTempFile, 0152 * use KTempFile::unlink() or KTempFile::setAutoDelete() to have 0153 * it removed. 0154 * 0155 * @param name Path to temporary file to remove. May not be 0156 * empty. 0157 */ 0158 static void removeTempFile(const QString &name); 0159 0160 /** 0161 * Uploads file @p src to URL @p target. 0162 * 0163 * Both must be specified, unlike download. 0164 * Note that this is assumed to be used for saving a file over 0165 * the network, so overwriting is set to true. This is not the 0166 * case with copy. 0167 * 0168 * @param src URL Referencing the file to upload. 0169 * @param target URL containing the final location of the file. 0170 * @param window main window associated with this job. This is used to 0171 * automatically cache and discard authentication information 0172 * as needed. If NULL, authentication information will be cached 0173 * only for a short duration after which the user will again be 0174 * prompted for passwords as needed. 0175 * 0176 * @return true if successful, false for failure 0177 * @deprecated since 5.0, use KIO::storedPut + KJobWidgets::setWindow + job->exec() instead 0178 */ 0179 static bool upload(const QString &src, const QUrl &target, QWidget *window); 0180 0181 /** 0182 * Alternative to upload for copying over the network. 0183 * Overwrite is false, so this will fail if @p target exists. 0184 * 0185 * This one takes two URLs and is a direct equivalent of KIO::file_copy. 0186 * 0187 * @param src URL Referencing the file to upload. 0188 * @param target URL containing the final location of the file. 0189 * @param window main window associated with this job. This is used to 0190 * automatically cache and discard authentication information 0191 * as needed. If NULL, authentication information will be cached 0192 * only for a short duration after which the user will again be 0193 * prompted for passwords as needed. 0194 * 0195 * @return true if successful, false for failure 0196 * @deprecated since 5.0, use KIO::file_copy + job->ui()->setWindow() + job->exec() instead 0197 */ 0198 static bool file_copy(const QUrl &src, const QUrl &target, QWidget *window = 0); 0199 static bool copy(const QUrl &src, const QUrl &target, 0200 QWidget *window = 0); 0201 0202 /** 0203 * Alternative method for copying over the network. 0204 * 0205 * This one takes two URLs and is a direct equivalent 0206 * of KIO::copy!. 0207 * This means that it can copy files and directories alike 0208 * (it should have been named copy()). 0209 * 0210 * This method will bring up a dialog if the destination already exists. 0211 * 0212 * @param src URL Referencing the file to upload. 0213 * @param target URL containing the final location of the 0214 * file. 0215 * @param window main window associated with this job. This is used to 0216 * automatically cache and discard authentication information 0217 * as needed. If NULL, authentication information will be cached 0218 * only for a short duration after which the user will again be 0219 * prompted for passwords as needed. 0220 * @return true if successful, false for failure 0221 * @deprecated since 5.0, use KIO::copy + job->ui()->setWindow() + job->exec() instead 0222 */ 0223 static bool dircopy(const QUrl &src, const QUrl &target, QWidget *window); 0224 0225 /** 0226 * Overloaded method, which takes a list of source URLs 0227 * @deprecated since 5.0, use KIO::copy + job->ui()->setWindow() + job->exec() instead 0228 */ 0229 static bool dircopy(const QList<QUrl> &src, const QUrl &target, QWidget *window = 0L); 0230 0231 /** 0232 * Full-fledged equivalent of KIO::move. 0233 * Moves or renames one file or directory. 0234 * @deprecated since 5.0, use KIO::move + job->ui()->setWindow() + job->exec() instead 0235 */ 0236 static bool move(const QUrl &src, const QUrl &target, QWidget *window = 0L); 0237 0238 /** 0239 * Full-fledged equivalent of KIO::move. 0240 * Moves or renames a list of files or directories. 0241 * @deprecated since 5.0, use KIO::move + job->ui()->setWindow() + job->exec() instead 0242 */ 0243 static bool move(const QList<QUrl> &src, const QUrl &target, QWidget *window = 0L); 0244 0245 /** 0246 * Tests whether a URL exists. 0247 * 0248 * @param url the URL we are testing 0249 * @param source if true, we want to read from that URL. 0250 * If false, we want to write to it. 0251 * IMPORTANT: see documentation for KIO::stat for more details about this. 0252 * @param window main window associated with this job. This is used to 0253 * automatically cache and discard authentication information 0254 * as needed. If NULL, authentication information will be 0255 * cached only for a short duration after which the user will 0256 * again be prompted for passwords as needed. 0257 * @return true if the URL exists and we can do the operation specified by 0258 * @p source, false otherwise 0259 * 0260 * @deprecated use the StatSide enum instead of the bool source 0261 */ 0262 static bool exists(const QUrl &url, bool source, QWidget *window); 0263 0264 /** 0265 * Tests whether a URL exists. 0266 * 0267 * @param url the URL we are testing 0268 * @param statSide determines if we want to read or write. 0269 * IMPORTANT: see documentation for KIO::stat for more details about this. 0270 * @param window main window associated with this job. This is used to 0271 * automatically cache and discard authentication information 0272 * as needed. If NULL, authentication information will be 0273 * cached only for a short duration after which the user will 0274 * again be prompted for passwords as needed. 0275 * @return true if the URL exists and we can do the operation specified by 0276 * @p source, false otherwise 0277 * @deprecated since 5.0, use QFile::exists for local files and KIO::stat for transparency 0278 */ 0279 static bool exists(const QUrl &url, StatSide statSide, QWidget *window); 0280 0281 /** 0282 * Tests whether a URL exists and return information on it. 0283 * 0284 * This is a convenience function for KIO::stat 0285 * (it saves creating a slot and testing for the job result). 0286 * 0287 * @param url The URL we are testing. 0288 * @param entry The result of the stat. Iterate over the list 0289 * of atoms to get hold of name, type, size, etc., or use KFileItem. 0290 * @param window main window associated with this job. This is used to 0291 * automatically cache and discard authentication information 0292 * as needed. If NULL, authentication information will be 0293 * cached only for a short duration after which the user will 0294 * again be prompted for passwords as needed. 0295 * @return true if successful, false for failure 0296 * @deprecated since 5.0, use KIO::stat + KJobWidgets::setWindow + job->exec() instead 0297 */ 0298 static bool stat(const QUrl &url, KIO::UDSEntry &entry, QWidget *window); 0299 0300 /** 0301 * Tries to map a local URL for the given URL. 0302 * 0303 * This is a convenience function for KIO::stat + parsing the 0304 * resulting UDSEntry. 0305 * 0306 * @param url The URL we are testing. 0307 * @param window main window associated with this job. This is used to 0308 * automatically cache and discard authentication information 0309 * as needed. If NULL, authentication information will be 0310 * cached only for a short duration after which the user will 0311 * again be prompted for passwords as needed. 0312 * @return a local URL corresponding to the same resource than the 0313 * original URL, or the original URL if no local URL can be mapped 0314 * @deprecated since 5.0, use KIO::mostLocalUrl + KJobWidgets::setWindow + job->exec() instead 0315 */ 0316 static QUrl mostLocalUrl(const QUrl &url, QWidget *window); 0317 0318 /** 0319 * Deletes a file or a directory in a synchronous way. 0320 * 0321 * This is a convenience function for KIO::del 0322 * (it saves creating a slot and testing for the job result). 0323 * 0324 * @param url The file or directory to delete. 0325 * @param window main window associated with this job. This is used to 0326 * automatically cache and discard authentication information 0327 * as needed. If NULL, authentication information will be 0328 * cached only for a short duration after which the user will 0329 * again be prompted for passwords as needed. 0330 * @return true on success, false on failure. 0331 * @deprecated since 5.0, use KIO::del + job->ui()->setWindow() + job->exec() instead 0332 */ 0333 static bool del(const QUrl &url, QWidget *window); 0334 0335 /** 0336 * Creates a directory in a synchronous way. 0337 * 0338 * This is a convenience function for @p KIO::mkdir 0339 * (it saves creating a slot and testing for the job result). 0340 * 0341 * @param url The directory to create. 0342 * @param window main window associated with this job. This is used to 0343 * automatically cache and discard authentication information 0344 * as needed. If NULL, authentication information will be 0345 * cached only for a short duration after which the user will 0346 * again be prompted for passwords as needed. 0347 * @param permissions directory permissions. 0348 * @return true on success, false on failure. 0349 * @deprecated since 5.0, use KIO::mkdir + job->ui()->setWindow() + job->exec() instead 0350 */ 0351 static bool mkdir(const QUrl &url, QWidget *window, int permissions = -1); 0352 0353 /** 0354 * Executes a remote process via the fish ioslave in a synchronous way. 0355 * 0356 * @param url The remote machine where the command should be executed. 0357 * e.g. fish://someuser\@somehost:sshport/ 0358 * some special cases exist. 0359 * fish://someuser\@localhost/ 0360 * will use su instead of ssh to connect and execute the command. 0361 * fish://someuser\@localhost:port/ 0362 * will use ssh to connect and execute the command. 0363 * @param command The command to be executed. 0364 * @param window main window associated with this job. This is used to 0365 * automatically cache and discard authentication information 0366 * as needed. If NULL, authentication information will be 0367 * cached only for a short duration after which the user will 0368 * again be prompted for passwords as needed. 0369 * @return The resulting output of the @p command that is executed. 0370 */ 0371 static QString fish_execute(const QUrl &url, const QString &command, QWidget *window); 0372 0373 /** 0374 * This function executes a job in a synchronous way. 0375 * If a job fetches some data, pass a QByteArray pointer as data parameter to this function 0376 * and after the function returns it will contain all the data fetched by this job. 0377 * 0378 * @code 0379 * KIO::Job *job = KIO::get( url ); 0380 * QMap<QString, QString> metaData; 0381 * metaData.insert( "PropagateHttpHeader", "true" ); 0382 * if ( NetAccess::synchronousRun( job, 0, &data, &url, &metaData ) ) { 0383 * QString responseHeaders = metaData[ "HTTP-Headers" ]; 0384 * qDebug()<<"Response header = "<< responseHeaders; 0385 * } 0386 * @endcode 0387 * 0388 * @param job job which the function will run. Note that after this function 0389 * finishes running, job is deleted and you can't access it anymore! 0390 * @param window main window associated with this job. This is used to 0391 * automatically cache and discard authentication information 0392 * as needed. If NULL, authentication information will be 0393 * cached only for a short duration after which the user will 0394 * again be prompted for passwords as needed. 0395 * @param data if passed and relevant to this job then it will contain the data 0396 * that was fetched by the job 0397 * @param finalURL if passed will contain the final url of this job (it might differ 0398 * from the one it was created with if there was a redirection) 0399 * @param metaData you can pass a pointer to the map with meta data you wish to 0400 * set on the job. After the job finishes this map will hold all the 0401 * meta data from the job. 0402 * 0403 * @return true on success, false on failure. 0404 * @deprecated since 5.0, KJobWidgets::setWindow + job->exec() instead 0405 */ 0406 static bool synchronousRun(Job *job, QWidget *window, QByteArray *data = 0, 0407 QUrl *finalURL = 0, QMap<QString, QString> *metaData = 0); 0408 0409 /** 0410 * Determines the mimetype of a given URL. 0411 * 0412 * This is a convenience function for KIO::mimetype. You 0413 * should call this only when really necessary. 0414 * QMimeDatabase::mimeTypeForUrl can determine the mimetype a lot faster, but 0415 * less reliably for remote files. When mimeTypeForUrl() returns 0416 * unknown (application/octet-stream) for a remote file, then this one 0417 * should be used. 0418 * 0419 * @param url The URL whose mimetype we are interested in. 0420 * @param window main window associated with this job. This is used to 0421 * automatically cache and discard authentication information 0422 * as needed. If NULL, authentication information will be 0423 * cached only for a short duration after which the user will 0424 * again be prompted for passwords as needed. 0425 * @return The mimetype name. 0426 * @deprecated since 5.0, use KIO::mimetype + KJobWidgets::setWindow + job->exec() instead 0427 */ 0428 static QString mimetype(const QUrl &url, QWidget *window); 0429 0430 /** 0431 * Returns the error string for the last job, in case it failed. 0432 * Note that this is already translated. 0433 * @return the last error string, or QString() 0434 */ 0435 static QString lastErrorString(); 0436 0437 /** 0438 * Returns the error code for the last job, in case it failed. 0439 * @return the last error code 0440 */ 0441 static int lastError(); 0442 0443 Q_SIGNALS: 0444 void leaveModality(); 0445 private: 0446 /** 0447 * Private constructor 0448 */ 0449 NetAccess(); 0450 0451 /** 0452 * Private destructor 0453 */ 0454 ~NetAccess() override; 0455 0456 /** 0457 * Internal methods 0458 */ 0459 bool filecopyInternal(const QUrl &src, const QUrl &target, int permissions, 0460 KIO::JobFlags flags, QWidget *window, bool move); 0461 bool dircopyInternal(const QList<QUrl> &src, const QUrl &target, 0462 QWidget *window, bool move); 0463 bool statInternal(const QUrl &url, int details, StatSide side, QWidget *window = 0); 0464 0465 bool delInternal(const QUrl &url, QWidget *window = 0); 0466 bool mkdirInternal(const QUrl &url, int permissions, QWidget *window = 0); 0467 QString fish_executeInternal(const QUrl &url, const QString &command, QWidget *window = 0); 0468 bool synchronousRunInternal(Job *job, QWidget *window, QByteArray *data, 0469 QUrl *finalURL, QMap<QString, QString> *metaData); 0470 0471 QString mimetypeInternal(const QUrl &url, QWidget *window = 0); 0472 void enter_loop(); 0473 0474 friend class I_like_this_class; 0475 0476 private Q_SLOTS: 0477 void slotResult(KJob *job); 0478 void slotMimetype(KIO::Job *job, const QString &type); 0479 void slotData(KIO::Job *, const QByteArray &); 0480 void slotRedirection(KIO::Job *, const QUrl &); 0481 0482 private: 0483 NetAccessPrivate *const d; 0484 }; 0485 0486 } 0487 0488 #endif