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_OPENURLJOB_H
9#define KIO_OPENURLJOB_H
10
11#include "applicationlauncherjob.h"
12#include "kiogui_export.h"
13#include <KCompositeJob>
14#include <QScopedPointer>
15
16class QUrl;
17
18namespace KIO
19{
20class OpenUrlJobPrivate;
21
22/*!
23 * \class KIO::OpenUrlJob
24 * \inmodule KIOGui
25 * \inheaderfile KIO/OpenUrlJob
26 *
27 * \brief OpenUrlJob finds out the right way to "open" a URL.
28 *
29 * This includes finding out its MIME type, and then the associated application,
30 * or running desktop files, executables, etc.
31 * It also honours the "use this webbrowser for all http(s) URLs" setting.
32 *
33 * For the "Open With" dialog functionality to work, make sure to set
34 * KIO::JobUiDelegate as the delegate for this job (in widgets applications).
35 * \code
36 * // Since 5.98 use:
37 * job->setUiDelegate(KIO::createDefaultJobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, window));
38 * // For older releases use:
39 * job->setUiDelegate(new KIO::JobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, window));
40 * \endcode
41 *
42 * \since 5.71
43 */
44class KIOGUI_EXPORT OpenUrlJob : public KCompositeJob
45{
46 Q_OBJECT
47public:
48 /*!
49 * Creates an OpenUrlJob in order to open a URL.
50 *
51 * \a url the URL of the file/directory to open
52 */
53 explicit OpenUrlJob(const QUrl &url, QObject *parent = nullptr);
54
55 /*!
56 * Creates an OpenUrlJob for the case where the MIME type is already known.
57 *
58 * \a url the URL of the file/directory to open
59 *
60 * \a mimeType the type of file/directory. See QMimeType.
61 */
62 explicit OpenUrlJob(const QUrl &url, const QString &mimeType, QObject *parent = nullptr);
63
64 /*!
65 * Destructor
66 *
67 * Note that by default jobs auto-delete themselves after emitting result.
68 */
69 ~OpenUrlJob() override;
70
71 /*!
72 * Returns the URL the OpenUrlJob was created with.
73 *
74 * \since 6.14
75 */
76 QUrl url() const;
77
78 /*!
79 * Specifies that the URL passed to the application will be deleted when it exits (if the URL is a local file)
80 */
81 void setDeleteTemporaryFile(bool b);
82
83 /*!
84 * Sets the file name to use in the case of downloading the file to a tempfile,
85 * in order to give it to a non-URL-aware application.
86 * Some apps rely on the extension to determine the MIME type of the file.
87 * Usually the file name comes from the URL, but in the case of the
88 * HTTP Content-Disposition header, we need to override the file name.
89 *
90 * \a suggestedFileName the file name
91 */
92 void setSuggestedFileName(const QString &suggestedFileName);
93
94 /*!
95 * Sets the platform-specific startup id of the application launch.
96 *
97 * \a startupId startup id, if any (otherwise "").
98 *
99 * For X11, this would be the id for the Startup Notification protocol.
100 *
101 * For Wayland, this would be the token for the XDG Activation protocol.
102 */
103 void setStartupId(const QByteArray &startupId);
104
105 /*!
106 * Set this to true if this class should allow the user to run executables.
107 * Unlike KF5's KRun, this setting is OFF by default here for security reasons.
108 * File managers can enable this, but e.g. web browsers, mail clients etc. shouldn't.
109 */
110 void setRunExecutables(bool allow);
111
112 /*!
113 * Set this to \c true if this class should show a dialog to ask the user about how
114 * to handle various types of executable files; note that executing/running remote
115 * files is disallowed as that is not secure (in the case of remote shell scripts
116 * and .desktop files, they are always opened as text in the default application):
117 * \list
118 * \li For native binaries: whether to execute or cancel
119 * \li For .exe files: whether to execute or cancel, ("execute" on Linux in this
120 * context means running the file with the default application (e.g. WINE))
121 * \li For executable shell scripts: whether to execute the file or open it as
122 * text in the default application; note that if the file doesn't have the
123 * execute bit, it'll always be opened as text
124 * \li For .desktop files: whether to run the file or open it as text in the default
125 * application; note that if the .desktop file is located in a non-standard
126 * location (on Linux standard locations are /usr/share/applications or
127 * ~/.local/share/applications) and does not have the execute bit, another dialog
128 * (see UntrustedProgramHandlerInterface) will be launched to ask the user whether
129 * they trust running the application (the one the .desktop file launches based on
130 * the Exec line)
131 * \endlist
132 *
133 * Note that the dialog, ExecutableFileOpenDialog (from KIOWidgets), provides an option
134 * to remember the last value used and not ask again, if that is set, then the dialog will
135 * not be shown.
136 *
137 * When set to \c true this will take precedence over setRunExecutables (the latter can be
138 * used to allow running executables without first asking the user for confirmation).
139 *
140 * \since 5.73
141 */
142 void setShowOpenOrExecuteDialog(bool b);
143
144 /*!
145 * Sets whether the external webbrowser setting should be honoured.
146 *
147 * This is enabled by default.
148 *
149 * This should only be disabled in webbrowser applications.
150 *
151 * \a b whether to let the external browser handle the URL or not
152 */
153 void setEnableExternalBrowser(bool b);
154
155 /*!
156 * Sets whether the job should follow URL redirections.
157 *
158 * This is enabled by default.
159 *
160 * \a b whether to follow redirections or not.
161 */
162 void setFollowRedirections(bool b);
163
164 /*!
165 * Starts the job.
166 * You must call this, after having called all the needed setters.
167 * This is a GUI job, never use exec(), it would block user interaction.
168 */
169 void start() override;
170
171 /*!
172 * Returns whether the \a url of type \a mimetypeName is executable.
173 * To be executable the file must pass the following rules:
174 * -# Must reside on the local filesystem.
175 * -# Must be marked as executable for the user by the filesystem.
176 * -# The MIME type must inherit application/x-executable, application/x-executable-script
177 */
178 static bool isExecutableFile(const QUrl &url, const QString &mimetypeName);
179
180Q_SIGNALS:
181 /*!
182 * Emitted when the MIME type is determined.
183 * This can be used for special cases like webbrowsers
184 * who want to embed the URL in some cases, rather than starting a different
185 * application. In that case they can kill the job.
186 */
187 void mimeTypeFound(const QString &mimeType);
188
189protected:
190 bool doKill() override;
191
192private:
193 void slotResult(KJob *job) override;
194
195 friend class OpenUrlJobPrivate;
196 QScopedPointer<OpenUrlJobPrivate> d;
197};
198
199} // namespace KIO
200
201#endif // OPENURLJOB_H
202

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