File indexing completed on 2023-11-26 07:34:14

0001 /*
0002     This file is part of the KDE project
0003     SPDX-FileCopyrightText: 1998, 1999 Torben Weis <weis@kde.org>
0004     SPDX-FileCopyrightText: 2006 David Faure <faure@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-or-later
0007 */
0008 
0009 #ifndef KRUN_H
0010 #define KRUN_H
0011 
0012 #include "kiowidgets_export.h"
0013 
0014 #include <QObject>
0015 #include <QString>
0016 #include <QUrl>
0017 
0018 #include <memory>
0019 
0020 class KService;
0021 class KJob;
0022 class QTimer;
0023 class KRunPrivate;
0024 
0025 namespace KIO
0026 {
0027 class Job;
0028 }
0029 
0030 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 71)
0031 /**
0032  * @class KRun krun.h <KRun>
0033  *
0034  * To open files with their associated applications in KDE, use KRun.
0035  *
0036  * It can execute any desktop entry, as well as any file, using
0037  * the default application or another application "bound" to the file type
0038  * (or URL protocol).
0039  *
0040  * In that example, the MIME type of the file is not known by the application,
0041  * so a KRun instance must be created. It will determine the MIME type by itself.
0042  * If the MIME type is known, or if you even know the service (application) to
0043  * use for this file, use one of the static methods.
0044  *
0045  * By default KRun uses auto deletion. It causes the KRun instance to delete
0046  * itself when the it finished its task. If you allocate the KRun
0047  * object on the stack you must disable auto deletion, otherwise it will crash.
0048  *
0049  * This respects the "shell_access", "openwith" and "run_desktop_files" Kiosk
0050  * action restrictions (see KAuthorized::authorize()).
0051  *
0052  * @short Opens files with their associated applications in KDE
0053  */
0054 class KIOWIDGETS_EXPORT KRun : public QObject
0055 {
0056     Q_OBJECT
0057 public:
0058     /**
0059      * @param url the URL of the file or directory to 'run'
0060      *
0061      * @param window
0062      *        The top-level widget of the app that invoked this object.
0063      *        It is used to make sure private information like passwords
0064      *        are properly handled per application.
0065      *
0066      * @param showProgressInfo
0067      *        Whether to show progress information when determining the
0068      *        type of the file (i.e. when using KIO::stat and KIO::mimetype)
0069      *        Before you set this to false to avoid a dialog box, think about
0070      *        a very slow FTP server...
0071      *        It is always better to provide progress info in such cases.
0072      *
0073      * @param asn
0074      *        Application startup notification id, if available (otherwise "").
0075      *
0076      * @deprecated since 5.71, use KIO::OpenUrlJob(url) (except for KRun subclasses, for now)
0077      * @code
0078      *    auto *job = new KIO::OpenUrlJob(url);
0079      *    job->setUiDelegate(new KIO::JobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, window));
0080      *    job->setStartupId(asn);
0081      *    // methods like setRunExecutables, setSuggestedFilename, setEnableExternalBrowser, setFollowRedirections
0082      *    // exist in both classes
0083      *    job->start();
0084      * @endcode
0085      */
0086     KRun(const QUrl &url, QWidget *window, bool showProgressInfo = true, const QByteArray &asn = QByteArray());
0087 
0088     /**
0089      * Destructor. Don't call it yourself, since a KRun object auto-deletes
0090      * itself.
0091      */
0092     ~KRun() override;
0093 
0094     /**
0095      * Abort this KRun. This kills any jobs launched by it,
0096      * and leads to deletion if auto-deletion is on.
0097      * This is much safer than deleting the KRun (in case it's
0098      * currently showing an error dialog box, for instance)
0099      */
0100     void abort();
0101 
0102     /**
0103      * Returns true if the KRun instance has an error.
0104      * @return true when an error occurred
0105      * @see error()
0106      */
0107     bool hasError() const;
0108 
0109     /**
0110      * Returns true if the KRun instance has finished.
0111      * @return true if the KRun instance has finished
0112      * @see finished()
0113      */
0114     bool hasFinished() const;
0115 
0116     /**
0117      * Checks whether auto delete is activated.
0118      * Auto-deletion causes the KRun instance to delete itself
0119      * when it finished its task.
0120      * By default auto deletion is on.
0121      * @return true if auto deletion is on, false otherwise
0122      */
0123     bool autoDelete() const;
0124 
0125     /**
0126      * Enables or disabled auto deletion.
0127      * Auto deletion causes the KRun instance to delete itself
0128      * when it finished its task. If you allocate the KRun
0129      * object on the stack you must disable auto deletion.
0130      * By default auto deletion is on.
0131      * @param b true to enable auto deletion, false to disable
0132      */
0133     void setAutoDelete(bool b);
0134 
0135     /**
0136      * Set the preferred service for opening this URL, after
0137      * its MIME type will have been found by KRun. IMPORTANT: the service is
0138      * only used if its configuration says it can handle this MIME type.
0139      * This is used for instance for the X-KDE-LastOpenedWith key in
0140      * the recent documents list, or for the app selection in
0141      * KParts::BrowserOpenOrSaveQuestion.
0142      * @param desktopEntryName the desktopEntryName of the service, e.g. "kate".
0143      */
0144     void setPreferredService(const QString &desktopEntryName);
0145 
0146     /**
0147      * Sets whether executables, .desktop files or shell scripts should
0148      * be run by KRun. This is enabled by default.
0149      * @param b whether to run executable files or not.
0150      * @see isExecutable()
0151      */
0152     void setRunExecutables(bool b);
0153 
0154     /**
0155      * Sets whether KRun should follow URLs redirections.
0156      * This is enabled by default
0157      * @param b whether to follow redirections or not.
0158      * @since 5.55
0159      */
0160     void setFollowRedirections(bool b);
0161 
0162     /**
0163      * Sets whether the external webbrowser setting should be honoured.
0164      * This is enabled by default.
0165      * This should only be disabled in webbrowser applications.
0166      * @param b whether to enable the external browser or not.
0167      */
0168     void setEnableExternalBrowser(bool b);
0169 
0170     /**
0171      * Sets the file name to use in the case of downloading the file to a tempfile
0172      * in order to give to a non-url-aware application. Some apps rely on the extension
0173      * to determine the MIME type of the file. Usually the file name comes from the URL,
0174      * but in the case of the HTTP Content-Disposition header, we need to override the
0175      * file name.
0176      */
0177     void setSuggestedFileName(const QString &fileName);
0178 
0179     /**
0180      * Sets whether a prompt should be shown before executing scripts or desktop files.
0181      * If enabled, KRun uses the "kiorc" configuration file to decide whether to open the
0182      * file, execute it or show a prompt.
0183      * @since 5.4
0184      */
0185     void setShowScriptExecutionPrompt(bool showPrompt);
0186 
0187     /**
0188      * Suggested file name given by the server (e.g.\ HTTP content-disposition)
0189      */
0190     QString suggestedFileName() const;
0191 
0192     /**
0193      * Associated window, as passed to the constructor
0194      * @since 4.9.3
0195      */
0196     QWidget *window() const;
0197 
0198 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 6)
0199     /**
0200      * Open a list of URLs with a certain service (application).
0201      *
0202      * @param service the service to run
0203      * @param urls the list of URLs, can be empty (app launched
0204      *        without argument)
0205      * @param window The top-level widget of the app that invoked this object.
0206      * @param tempFiles if true and urls are local files, they will be deleted
0207      *        when the application exits.
0208      * @param suggestedFileName see setSuggestedFileName
0209      * @param asn Application startup notification id, if any (otherwise "").
0210      * @return @c true on success, @c false on error
0211      *
0212      * @deprecated since 5.6. Since 5.71 use ApplicationLauncherJob, otherwise runApplication instead.
0213      * @code
0214      *    auto *job = new KIO::ApplicationLauncherJob(service);
0215      *    job->setUrls(urls);
0216      *    job->setUiDelegate(new KIO::JobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, window));
0217      *    if (tempFiles) {
0218      *        job->setRunFlags(KIO::ApplicationLauncherJob::DeleteTemporaryFiles);
0219      *    }
0220      *    job->setSuggestedFileName(suggestedFileName);
0221      *    job->setStartupId(asn);
0222      *    job->start();
0223      * @endcode
0224      */
0225     KIOWIDGETS_DEPRECATED_VERSION(5, 6, "Use KIO::ApplicationLauncherJob, see API docs for a code sample")
0226     static bool run(const KService &service,
0227                     const QList<QUrl> &urls,
0228                     QWidget *window,
0229                     bool tempFiles = false,
0230                     const QString &suggestedFileName = QString(),
0231                     const QByteArray &asn = QByteArray());
0232 #endif
0233 
0234 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 71)
0235     /**
0236      * Open a list of URLs with a certain service (application).
0237      *
0238      * Prefer runApplication(), unless you need to wait for the application
0239      * to register to D-Bus before this method returns (but that should rather
0240      * be done with D-Bus activation).
0241      *
0242      * @param service the service to run
0243      * @param urls the list of URLs, can be empty (app launched
0244      *        without argument)
0245      * @param window The top-level widget of the app that invoked this object.
0246      * @param tempFiles if true and urls are local files, they will be deleted
0247      *        when the application exits.
0248      * @param suggestedFileName see setSuggestedFileName
0249      * @param asn Application startup notification id, if any (otherwise "").
0250      * @return 0 on error, the process ID on success
0251      * @since 5.6
0252      * @deprecated since 5.71, use ApplicationLauncherJob instead.
0253      * @code
0254      *    auto *job = new KIO::ApplicationLauncherJob(service);
0255      *    job->setUrls(urls);
0256      *    job->setUiDelegate(new KIO::JobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, window));
0257      *    if (tempFiles) {
0258      *        job->setRunFlags(KIO::ApplicationLauncherJob::DeleteTemporaryFiles);
0259      *    }
0260      *    job->setSuggestedFileName(suggestedFileName);
0261      *    job->setStartupId(asn);
0262      *    job->start();
0263      * @endcode
0264      */
0265     KIOWIDGETS_DEPRECATED_VERSION(5, 71, "Use KIO::ApplicationLauncherJob, see API docs for a code sample")
0266     static qint64 runService(const KService &service,
0267                              const QList<QUrl> &urls,
0268                              QWidget *window,
0269                              bool tempFiles = false,
0270                              const QString &suggestedFileName = QString(),
0271                              const QByteArray &asn = QByteArray());
0272 #endif
0273 
0274 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 71)
0275     /**
0276      * @see RunFlags
0277      */
0278     enum RunFlag {
0279         DeleteTemporaryFiles = 0x1, ///< the URLs passed to the service will be deleted when it exits (if the URLs are local files)
0280         RunExecutables = 0x2, ///< Whether to run URLs that are executable scripts or binaries @see isExecutableFile() @since 5.31
0281     };
0282     /**
0283      * Stores a combination of #RunFlag values.
0284      * @deprecated since 5.71, see porting instructions in the respective methods
0285      */
0286     Q_DECLARE_FLAGS(RunFlags, RunFlag)
0287 #endif
0288 
0289 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 71)
0290     /**
0291      * Run an application (known from its .desktop file, i.e.\ as a KService).
0292      *
0293      * If you need to wait for the application to register to D-Bus, use D-Bus activation instead.
0294      *
0295      * If you don't need the prompt for asking the user whether to add the executable bit for
0296      * desktop files or binaries that don't have it, you can use KIO::ApplicationLauncherJob from KIOGui directly.
0297      *
0298      * @param service the service to run
0299      * @param urls the list of URLs, can be empty (app launched
0300      *        without argument)
0301      * @param window The top-level widget of the app that invoked this object.
0302      * @param flags various flags
0303      * @param suggestedFileName see setSuggestedFileName
0304      * @param asn Application startup notification id, if any (otherwise "").
0305      * @return 0 on error, the process ID on success
0306      * @since 5.24
0307      *
0308      * @deprecated since 5.71, use ApplicationLauncherJob instead.
0309      * @code
0310      *    auto *job = new KIO::ApplicationLauncherJob(service);
0311      *    job->setUrls(urls);
0312      *    job->setUiDelegate(new KIO::JobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, window));
0313      *    job->setSuggestedFileName(suggestedFileName);
0314      *    job->setRunFlags(flags);
0315      *    job->setStartupId(asn);
0316      *    job->start();
0317      * @endcode
0318      */
0319     KIOWIDGETS_DEPRECATED_VERSION(5, 71, "Use KIO::ApplicationLauncherJob, see API docs for a code sample")
0320     static qint64 runApplication(const KService &service,
0321                                  const QList<QUrl> &urls,
0322                                  QWidget *window,
0323                                  RunFlags flags = RunFlags(),
0324                                  const QString &suggestedFileName = QString(),
0325                                  const QByteArray &asn = QByteArray());
0326 #endif
0327 
0328 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 71)
0329     /**
0330      * Open a list of URLs with an executable.
0331      *
0332      * @param exec the name of the executable, for example
0333      *        "/usr/bin/netscape %u".
0334      *        Don't forget to include the %u if you know that the applications
0335      *        supports URLs. Otherwise, non-local urls will first be downloaded
0336      *        to a temp file (using kioexec).
0337      * @param urls  the list of URLs to open, can be empty (app launched without argument)
0338      * @param window The top-level widget of the app that invoked this object.
0339      * @param name the logical name of the application, for example
0340      *        "Netscape 4.06".
0341      * @param icon the icon which should be used by the application.
0342      * @param asn Application startup notification id, if any (otherwise "").
0343      * @return @c true on success, @c false on error
0344      *
0345      * @deprecated since 5.71, use KIO::ApplicationLauncherJob with a temporary KService
0346      * @code
0347      *    KService::Ptr service(new KService(name, exec, icon));
0348      *    auto *job = new KIO::ApplicationLauncherJob(service);
0349      *    job->setUrls(urls);
0350      *    job->setUiDelegate(new KDialogJobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, window));
0351      *    job->setStartupId(asn);
0352      *    job->start();
0353      * @endcode
0354      */
0355     KIOWIDGETS_DEPRECATED_VERSION(5, 71, "Use KIO::ApplicationLauncherJob with a temporary KService, see API docs for a code sample")
0356     static bool run(const QString &exec,
0357                     const QList<QUrl> &urls,
0358                     QWidget *window,
0359                     const QString &name = QString(),
0360                     const QString &icon = QString(),
0361                     const QByteArray &asn = QByteArray());
0362 #endif
0363 
0364 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 31)
0365     /**
0366      * Open the given URL.
0367      *
0368      * This function is used after the MIME type
0369      * is found out. It will search for all services which can handle
0370      * the MIME type and call run() afterwards.
0371      * @param url the URL to open
0372      * @param mimetype the MIME type of the resource
0373      * @param window The top-level widget of the app that invoked this object.
0374      * @param tempFile if true and url is a local file, it will be deleted
0375      *        when the launched application exits.
0376      * @param runExecutables if false then local .desktop files,
0377      *        executables and shell scripts will not be run.
0378      *        See also isExecutable().
0379      * @param suggestedFileName see setSuggestedFileName
0380      * @param asn Application startup notification id, if any (otherwise "").
0381      * @return @c true on success, @c false on error
0382      * @deprecated since 5.31. Since 5.71 use OpenUrlJob, otherwise runUrl() with RunFlags.
0383      * @code
0384      *    auto *job = new KIO::OpenUrlJob(url, mimetype);
0385      *    job->setSuggestedFileName(suggestedFileName);
0386      *    job->setUiDelegate(new KIO::JobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, window));
0387      *    job->setRunExecutables(runExecutables);
0388      *    job->setDeleteTemporaryFile(...); // depending on the old RunFlags
0389      *    job->setStartupId(asn);
0390      *    job->start();
0391      * @endcode
0392      */
0393     KIOWIDGETS_DEPRECATED_VERSION(5, 31, "Use KIO::OpenUrlJob, see API docs for a code sample")
0394     static bool runUrl(const QUrl &url,
0395                        const QString &mimetype,
0396                        QWidget *window,
0397                        bool tempFile = false,
0398                        bool runExecutables = true,
0399                        const QString &suggestedFileName = QString(),
0400                        const QByteArray &asn = QByteArray());
0401 #endif
0402 
0403 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 71)
0404     /**
0405      * Open the given URL.
0406      *
0407      * This function can be used after the MIME type has been found out.
0408      * It will search for all services which can handle the MIME type and call run() afterwards.
0409      *
0410      * @param url The URL to open.
0411      * @param mimetype the MIME type of the resource
0412      * @param window The top-level widget of the app that invoked this object.
0413      * @param flags Various run flags.
0414      * @param suggestedFileName See setSuggestedFileName()
0415      * @param asn Application startup notification id, if any (otherwise "").
0416      * @return @c true on success, @c false on error
0417      * @since 5.31
0418      * @deprecated since 5.71, use KIO::OpenUrlJob:
0419      * @code
0420      *    auto *job = new KIO::OpenUrlJob(url, mimetype);
0421      *    job->setUiDelegate(new KIO::JobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, window));
0422      *    job->setRunExecutables(runExecutables);
0423      *    job->setDeleteTemporaryFile(...); // depending on the old RunFlags
0424      *    job->setSuggestedFileName(suggestedFileName);
0425      *    job->setStartupId(asn);
0426      *    job->start();
0427      * @endcode
0428      */
0429     KIOWIDGETS_DEPRECATED_VERSION(5, 71, "Use KIO::OpenUrlJob, see API docs for a code sample")
0430     static bool runUrl(const QUrl &url,
0431                        const QString &mimetype,
0432                        QWidget *window,
0433                        RunFlags flags,
0434                        const QString &suggestedFileName = QString(),
0435                        const QByteArray &asn = QByteArray());
0436 #endif
0437 
0438 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 71)
0439     /**
0440      * Run the given shell command and notifies KDE of the starting
0441      * of the application. If the program to be called doesn't exist,
0442      * an error box will be displayed.
0443      *
0444      * Use only when you know the full command line. Otherwise use the other
0445      * static methods, or KRun's constructor.
0446      *
0447      * @param cmd must be a shell command. You must not append "&"
0448      * to it, since the function will do that for you.
0449      * @param window The top-level widget of the app that invoked this object.
0450      * @param workingDirectory directory to use for relative paths, so that
0451      * a command like "kwrite file.txt" finds file.txt from the right place
0452      *
0453      * @return @c true on success, @c false on error
0454      * @deprecated since 5.71, use KIO::CommandLauncherJob
0455      * @code
0456      *    auto *job = new KIO::CommandLauncherJob(cmd);
0457      *    job->setUiDelegate(new KDialogJobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, window));
0458      *    job->setWorkingDirectory(workingDirectory);
0459      *    job->start();
0460      * @endcode
0461      */
0462     KIOWIDGETS_DEPRECATED_VERSION(5, 71, "Use KIO::CommandLauncherJob, see API docs for a code sample")
0463     static bool runCommand(const QString &cmd, QWidget *window, const QString &workingDirectory = QString());
0464 #endif
0465 
0466 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 71)
0467     /**
0468      * Same as the other runCommand(), but it also takes the name of the
0469      * binary, to display an error message in case it couldn't find it.
0470      *
0471      * @param cmd must be a shell command. You must not append "&"
0472      * to it, since the function will do that for you.
0473      * @param execName the name of the executable
0474      * @param icon icon for app starting notification
0475      * @param window The top-level widget of the app that invoked this object.
0476      * @param asn Application startup notification id, if any (otherwise "").
0477      * @return @c true on success, @c false on error
0478      * @deprecated since 5.71, use KIO::CommandLauncherJob
0479      * @code
0480      *    auto *job = new KIO::CommandLauncherJob(cmd);
0481      *    job->setUiDelegate(new KDialogJobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, window));
0482      *    job->setWorkingDirectory(workingDirectory);
0483      *    job->setExecutable(execName);
0484      *    job->setIcon(icon);
0485      *    job->setStartupId(asn);
0486      *    job->start();
0487      * @endcode
0488      */
0489     KIOWIDGETS_DEPRECATED_VERSION(5, 71, "Use KIO::CommandLauncherJob, see API docs for a code sample")
0490     static bool runCommand(const QString &cmd, const QString &execName, const QString &icon, QWidget *window, const QByteArray &asn = QByteArray());
0491 #endif
0492 
0493 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 71)
0494     /**
0495      * Overload that also takes a working directory, so that a command like
0496      * "kwrite file.txt" finds file.txt from the right place.
0497      * @param workingDirectory the working directory for the started process. The default
0498      *                         (if passing an empty string) is the user's document path.
0499      * @since 4.4
0500      * @deprecated since 5.71, use KIO::CommandLauncherJob instead
0501      * @code
0502      *    auto *job = new KIO::CommandLauncherJob(cmd);
0503      *    job->setUiDelegate(new KDialogJobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, window));
0504      *    job->setWorkingDirectory(workingDirectory);
0505      *    job->setExecutable(execName);
0506      *    job->setIcon(icon);
0507      *    job->setStartupId(asn);
0508      *    job->start();
0509      * @endcode
0510      */
0511     KIOWIDGETS_DEPRECATED_VERSION(5, 71, "Use KIO::CommandLauncherJob, see API docs for a code sample")
0512     static bool
0513     runCommand(const QString &cmd, const QString &execName, const QString &icon, QWidget *window, const QByteArray &asn, const QString &workingDirectory);
0514 #endif
0515 
0516 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 71)
0517     /**
0518      * Display the Open-With dialog for those URLs, and run the chosen application.
0519      * @param lst the list of URLs to open
0520      * @param window The top-level widget of the app that invoked this object.
0521      * @param tempFiles if true and lst are local files, they will be deleted
0522      *        when the application exits.
0523      * @param suggestedFileName see setSuggestedFileName
0524      * @param asn Application startup notification id, if any (otherwise "").
0525      * @return false if the dialog was canceled
0526      * @deprecated since 5.71, use KIO::ApplicationLauncherJob with no service argument (or a null service)
0527      * @code
0528      *    auto *job = new KIO::ApplicationLauncherJob();
0529      *    job->setUrls(urls);
0530      *    job->setUiDelegate(new KIO::JobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, window));
0531      *    if (tempFiles) {
0532      *        job->setRunFlags(KIO::ApplicationLauncherJob::DeleteTemporaryFiles);
0533      *    }
0534      *    job->setSuggestedFileName(suggestedFileName);
0535      *    job->setStartupId(asn);
0536      *    job->start();
0537      * @endcode
0538      */
0539     KIOWIDGETS_DEPRECATED_VERSION(5, 71, "Use KIO::ApplicationLauncherJob, see API docs for a code sample")
0540     static bool displayOpenWithDialog(const QList<QUrl> &lst,
0541                                       QWidget *window,
0542                                       bool tempFiles = false,
0543                                       const QString &suggestedFileName = QString(),
0544                                       const QByteArray &asn = QByteArray());
0545 #endif
0546 
0547 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 0)
0548     /**
0549      * Quotes a string for the shell.
0550      * An empty string will @em not be quoted.
0551      *
0552      * @param str the string to quote. The quoted string will be written here
0553      *
0554      * @deprecated Since 4.0, use KShell::quoteArg() instead. @em Note that this function
0555      *  behaves differently for empty arguments and returns the result
0556      *  differently.
0557      */
0558     KIOWIDGETS_DEPRECATED_VERSION(4, 0, "Use KShell::quoteArg(...)")
0559     static void shellQuote(QString &str);
0560 #endif
0561 
0562 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 0)
0563     /**
0564      * Processes a Exec= line as found in .desktop files.
0565      * @param _service the service to extract information from.
0566      * @param _urls The urls the service should open.
0567      * @param tempFiles if true and urls are local files, they will be deleted
0568      *        when the application exits.
0569      * @param suggestedFileName see setSuggestedFileName
0570      *
0571      * @return a list of arguments suitable for QProcess.
0572      * @deprecated since 5.0, use KIO::DesktopExecParser
0573      */
0574     KIOWIDGETS_DEPRECATED_VERSION(5, 0, "Use KIO::DesktopExecParser")
0575     static QStringList
0576     processDesktopExec(const KService &_service, const QList<QUrl> &_urls, bool tempFiles = false, const QString &suggestedFileName = QString());
0577 #endif
0578 
0579 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 0)
0580     /**
0581      * Given a full command line (e.g.\ the Exec= line from a .desktop file),
0582      * extract the name of the binary being run.
0583      * @param execLine the full command line
0584      * @param removePath if true, remove a (relative or absolute) path. E.g. /usr/bin/ls becomes ls.
0585      * @return the name of the executable to run
0586      * @deprecated since 5.0, use KIO::DesktopExecParser::executableName if removePath was true,
0587      * or KIO::DesktopExecParser::executablePath if removePath was false.
0588      */
0589     KIOWIDGETS_DEPRECATED_VERSION(5, 0, "See API docs")
0590     static QString binaryName(const QString &execLine, bool removePath);
0591 #endif
0592 
0593     /**
0594      * Returns whether @p mimeType refers to an executable program instead
0595      * of a data file.
0596      */
0597     static bool isExecutable(const QString &mimeType);
0598 
0599     /**
0600      * Returns whether the @p url of @p mimetype is executable.
0601      * To be executable the file must pass the following rules:
0602      * -# Must reside on the local filesystem.
0603      * -# Must be marked as executable for the user by the filesystem.
0604      * -# The MIME type must inherit application/x-executable, application/x-executable-script or application/x-sharedlib.
0605      * To allow a script to run when the above rules are satisfied add the entry
0606      * @code
0607      * X-KDE-IsAlso=application/x-executable-script
0608      * @endcode
0609      * to the MIME type's desktop file.
0610      */
0611     static bool isExecutableFile(const QUrl &url, const QString &mimetype);
0612 
0613     /**
0614      * @internal
0615      */
0616     static bool checkStartupNotify(const QString &binName, const KService *service, bool *silent_arg, QByteArray *wmclass_arg);
0617 
0618 Q_SIGNALS:
0619     /**
0620      * Emitted when the operation finished.
0621      * This signal is emitted in all cases of completion, whether successful or with error.
0622      * @see hasFinished()
0623      */
0624     void finished();
0625     /**
0626      * Emitted when the operation had an error.
0627      * @see hasError()
0628      */
0629     void error();
0630 
0631 protected Q_SLOTS:
0632     /**
0633      * All following protected slots are used by subclasses of KRun!
0634      */
0635 
0636     /**
0637      * This slot is called whenever the internal timer fired,
0638      * in order to move on to the next step.
0639      */
0640     void slotTimeout();
0641 
0642     /**
0643      * This slot is called when the scan job is finished.
0644      */
0645     void slotScanFinished(KJob *);
0646 
0647     /**
0648      * This slot is called when the scan job has found out
0649      * the MIME type.
0650      */
0651     void slotScanMimeType(KIO::Job *, const QString &type);
0652 
0653     /**
0654      * Call this from subclasses when you have determined the MIME type.
0655      * It will call foundMimeType, but also sets up protection against deletion during message boxes.
0656      * @since 4.0.2
0657      */
0658     void mimeTypeDetermined(const QString &mimeType);
0659 
0660     /**
0661      * This slot is called when the 'stat' job has finished.
0662      */
0663     virtual void slotStatResult(KJob *);
0664 
0665 protected:
0666     /**
0667      * All following protected methods are used by subclasses of KRun!
0668      */
0669 
0670     /**
0671      * Initializes the krun object.
0672      */
0673     virtual void init();
0674 
0675     /**
0676      * Start scanning a file.
0677      */
0678     virtual void scanFile();
0679 
0680     /**
0681      * Called if the MIME type has been detected. The function runs
0682      * the application associated with this MIME type.
0683      * Reimplement this method to implement a different behavior,
0684      * like opening the component for displaying the URL embedded.
0685      *
0686      * Important: call setFinished(true) once you are done!
0687      * Usually at the end of the foundMimeType reimplementation, but if the
0688      * reimplementation is asynchronous (e.g. uses KIO jobs) then
0689      * it can be called later instead.
0690      */
0691     virtual void foundMimeType(const QString &type);
0692 
0693     /**
0694      * Kills the file scanning job.
0695      */
0696     virtual void killJob();
0697 
0698     /**
0699      * Called when KRun detects an error during the init phase.
0700      *
0701      * The default implementation shows a message box.
0702      * @since 5.0
0703      */
0704     virtual void handleInitError(int kioErrorCode, const QString &errorMsg);
0705 
0706     /**
0707      * Called when a KIO job started by KRun gives an error.
0708      *
0709      * The default implementation shows a message box.
0710      */
0711     virtual void handleError(KJob *job);
0712 
0713     /**
0714      * Sets the url.
0715      */
0716     void setUrl(const QUrl &url);
0717 
0718     /**
0719      * Returns the url.
0720      */
0721     QUrl url() const;
0722 
0723     /**
0724      * Sets whether an error has occurred.
0725      */
0726     void setError(bool error);
0727 
0728     /**
0729      * Sets whether progress information shall be shown.
0730      */
0731     void setProgressInfo(bool progressInfo);
0732 
0733     /**
0734      * Returns whether progress information are shown.
0735      */
0736     bool progressInfo() const;
0737 
0738     /**
0739      * Marks this 'KRun' instance as finished.
0740      */
0741     void setFinished(bool finished);
0742 
0743     /**
0744      * Sets the job.
0745      */
0746     void setJob(KIO::Job *job);
0747 
0748     /**
0749      * Returns the job.
0750      */
0751     KIO::Job *job();
0752 
0753 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 4)
0754     /**
0755      * Returns the timer object.
0756      * @deprecated Since 4.4. setFinished(true) now takes care of the timer().start(0),
0757      * so this can be removed.
0758      */
0759     KIOWIDGETS_DEPRECATED_VERSION(4, 4, "See API docs")
0760     QTimer &timer();
0761 #endif
0762 
0763 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 1)
0764     /**
0765      * Indicate that the next action is to scan the file.
0766      * @deprecated Since 4.1. Not useful in public API
0767      */
0768     KIOWIDGETS_DEPRECATED_VERSION(4, 1, "Do not use")
0769     void setDoScanFile(bool scanFile);
0770 #endif
0771 
0772 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 1)
0773     /**
0774      * Returns whether the file shall be scanned.
0775      * @deprecated Since 4.1. Not useful in public API
0776      */
0777     KIOWIDGETS_DEPRECATED_VERSION(4, 1, "Do not use")
0778     bool doScanFile() const;
0779 #endif
0780 
0781 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 1)
0782     /**
0783      * Sets whether it is a directory.
0784      * @deprecated Since 4.1. Typo in the name, and not useful as a public method
0785      */
0786     KIOWIDGETS_DEPRECATED_VERSION(4, 1, "Do not use")
0787     void setIsDirecory(bool isDirectory);
0788 #endif
0789 
0790     /**
0791      * Returns whether it is a directory.
0792      */
0793     bool isDirectory() const;
0794 
0795 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 1)
0796     /**
0797      * @deprecated Since 4.1. Not useful in public API
0798      */
0799     KIOWIDGETS_DEPRECATED_VERSION(4, 1, "Do not use")
0800     void setInitializeNextAction(bool initialize);
0801 #endif
0802 
0803 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 1)
0804     /**
0805      * @deprecated Since 4.1. Not useful in public API
0806      */
0807     KIOWIDGETS_DEPRECATED_VERSION(4, 1, "Do not use")
0808     bool initializeNextAction() const;
0809 #endif
0810 
0811     /**
0812      * Returns whether it is a local file.
0813      */
0814     bool isLocalFile() const;
0815 
0816 private:
0817     friend class KRunPrivate;
0818     std::unique_ptr<KRunPrivate> const d;
0819 };
0820 #endif
0821 
0822 #endif