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

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