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 | |
16 | class QUrl; |
17 | |
18 | namespace KIO |
19 | { |
20 | class 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 | */ |
44 | class KIOGUI_EXPORT OpenUrlJob : public KCompositeJob |
45 | { |
46 | Q_OBJECT |
47 | public: |
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 | |
180 | Q_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 | |
189 | protected: |
190 | bool doKill() override; |
191 | |
192 | private: |
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 | |