1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2020 David Faure <faure@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
6*/
7
8#ifndef KIO_APPLICATIONLAUNCHERJOB_H
9#define KIO_APPLICATIONLAUNCHERJOB_H
10
11#include "kiogui_export.h"
12#include <KJob>
13#include <KService>
14#include <QUrl>
15
16class ApplicationLauncherJobTest;
17class KDesktopFileAction;
18
19namespace KIO
20{
21class ApplicationLauncherJobPrivate;
22
23/**
24 * @class ApplicationLauncherJob applicationlauncherjob.h <KIO/ApplicationLauncherJob>
25 *
26 * @brief ApplicationLauncherJob runs an application and watches it while running.
27 *
28 * It creates a startup notification and finishes it on success or on error (for the taskbar).
29 * It also emits an error message if necessary (e.g. "program not found").
30 *
31 * When passing multiple URLs to an application that doesn't support opening
32 * multiple files, the application will be launched once for each URL.
33 *
34 * The job finishes when the application is successfully started. At that point you can
35 * query the PID(s).
36 *
37 * For error handling, either connect to the result() signal, or for a simple messagebox on error,
38 * you can use:
39 * @code
40 * // Since 5.98 use:
41 * job->setUiDelegate(KIO::createDefaultJobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, this));
42 * // For older releases use:
43 * job->setUiDelegate(new KIO::JobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, this));
44 * @endcode
45 * Using JobUiDelegate (which is widgets based) also enables the feature of asking the user
46 * in case the executable or desktop file isn't marked as executable. Otherwise the job will
47 * just refuse executing such files.
48 *
49 * To invoke the open-with dialog (from KIOWidgets), construct an ApplicationLauncherJob without
50 * any arguments or with a null KService.
51 *
52 * @since 5.69
53 */
54class KIOGUI_EXPORT ApplicationLauncherJob : public KJob
55{
56public:
57 /**
58 * Creates an ApplicationLauncherJob.
59 * @param service the service (application desktop file) to run
60 * @param parent the parent QObject
61 */
62 explicit ApplicationLauncherJob(const KService::Ptr &service, QObject *parent = nullptr);
63
64 /**
65 * Creates an ApplicationLauncherJob.
66 * @param serviceAction the service action to run
67 * @param parent the parent QObject
68 */
69 explicit ApplicationLauncherJob(const KServiceAction &serviceAction, QObject *parent = nullptr);
70
71 /**
72 * @overload
73 * @since 6.0
74 */
75 explicit ApplicationLauncherJob(const KDesktopFileAction &desktopFileAction, QObject *parent = nullptr);
76
77 /**
78 * Creates an ApplicationLauncherJob which will prompt the user for which application to use
79 * (via the open-with dialog from KIOWidgets).
80 * @param parent the parent QObject
81 * @since 5.71
82 */
83 explicit ApplicationLauncherJob(QObject *parent = nullptr);
84
85 /**
86 * Destructor
87 *
88 * Note that jobs auto-delete themselves after emitting result.
89 * Deleting/killing the job will not stop the started application.
90 */
91 ~ApplicationLauncherJob() override;
92
93 /**
94 * Specifies the URLs to be passed to the application.
95 * @param urls list of files (local or remote) to open
96 *
97 * Note that when passing multiple URLs to an application that doesn't support opening
98 * multiple files, the application will be launched once for each URL.
99 */
100 void setUrls(const QList<QUrl> &urls);
101
102 /**
103 * @see RunFlag
104 */
105 enum RunFlag {
106 DeleteTemporaryFiles = 0x1, ///< the URLs passed to the service will be deleted when it exits (if the URLs are local files)
107 };
108 /**
109 * Stores a combination of #RunFlag values.
110 */
111 Q_DECLARE_FLAGS(RunFlags, RunFlag)
112
113 /**
114 * Specifies various flags.
115 * @param runFlags the flags to be set. For instance, whether the URLs are temporary files that should be deleted after execution.
116 */
117 void setRunFlags(RunFlags runFlags);
118
119 /**
120 * Sets the file name to use in the case of downloading the file to a tempfile
121 * in order to give to a non-URL-aware application.
122 * Some apps rely on the extension to determine the MIME type of the file.
123 * Usually the file name comes from the URL, but in the case of the
124 * HTTP Content-Disposition header, we need to override the file name.
125 * @param suggestedFileName the file name
126 */
127 void setSuggestedFileName(const QString &suggestedFileName);
128
129 /**
130 * Sets the platform-specific startup id of the application launch.
131 * @param startupId startup id, if any (otherwise "").
132 * For X11, this would be the id for the Startup Notification protocol.
133 * For Wayland, this would be the token for the XDG Activation protocol.
134 */
135 void setStartupId(const QByteArray &startupId);
136
137 /**
138 * Starts the job.
139 * You must call this, after having done all the setters.
140 * This is (potentially) a GUI job, never use exec(), it would block user interaction.
141 */
142 void start() override;
143
144 /**
145 * @return the PID of the application that was started
146 *
147 * Convenience method for pids().at(0). You should only use this when specifying zero or one URL,
148 * or when you are sure that the application supports opening multiple files. Otherwise use pids().
149 * Available after the job emits result().
150 */
151 qint64 pid() const;
152
153 /**
154 * @return the PIDs of the applications that were started
155 *
156 * Available after the job emits result().
157 */
158 QList<qint64> pids() const;
159
160private:
161 friend class ::ApplicationLauncherJobTest;
162 /**
163 * Blocks until the process has started.
164 */
165 bool waitForStarted();
166 KIOGUI_NO_EXPORT void emitUnauthorizedError();
167 KIOGUI_NO_EXPORT void proceedAfterSecurityChecks();
168
169 friend class ApplicationLauncherJobPrivate;
170 QScopedPointer<ApplicationLauncherJobPrivate> d;
171};
172
173} // namespace KIO
174
175#endif
176

source code of kio/src/gui/applicationlauncherjob.h