KIO

openurljob.h
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{
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 * Returns the URL the OpenUrlJob was created with.
67 *
68 * @since 6.15
69 */
70 QUrl url() const;
71
72 /**
73 * Specifies that the URL passed to the application will be deleted when it exits (if the URL is a local file)
74 */
75 void setDeleteTemporaryFile(bool b);
76
77 /**
78 * Sets the file name to use in the case of downloading the file to a tempfile,
79 * in order to give it to a non-URL-aware application.
80 * Some apps rely on the extension to determine the MIME type of the file.
81 * Usually the file name comes from the URL, but in the case of the
82 * HTTP Content-Disposition header, we need to override the file name.
83 * @param suggestedFileName the file name
84 */
85 void setSuggestedFileName(const QString &suggestedFileName);
86
87 /**
88 * Sets the platform-specific startup id of the application launch.
89 * @param startupId startup id, if any (otherwise "").
90 * For X11, this would be the id for the Startup Notification protocol.
91 * For Wayland, this would be the token for the XDG Activation protocol.
92 */
93 void setStartupId(const QByteArray &startupId);
94
95 /**
96 * Set this to true if this class should allow the user to run executables.
97 * Unlike KF5's KRun, this setting is OFF by default here for security reasons.
98 * File managers can enable this, but e.g. web browsers, mail clients etc. shouldn't.
99 */
100 void setRunExecutables(bool allow);
101
102 /**
103 * Set this to @c true if this class should show a dialog to ask the user about how
104 * to handle various types of executable files; note that executing/running remote
105 * files is disallowed as that is not secure (in the case of remote shell scripts
106 * and .desktop files, they are always opened as text in the default application):
107 * - For native binaries: whether to execute or cancel
108 * - For .exe files: whether to execute or cancel, ("execute" on Linux in this
109 * context means running the file with the default application (e.g. WINE))
110 * - For executable shell scripts: whether to execute the file or open it as
111 * text in the default application; note that if the file doesn't have the
112 * execute bit, it'll always be opened as text
113 * - For .desktop files: whether to run the file or open it as text in the default
114 * application; note that if the .desktop file is located in a non-standard
115 * location (on Linux standard locations are /usr/share/applications or
116 * ~/.local/share/applications) and does not have the execute bit, another dialog
117 * (see UntrustedProgramHandlerInterface) will be launched to ask the user whether
118 * they trust running the application (the one the .desktop file launches based on
119 * the Exec line)
120 *
121 * Note that the dialog, ExecutableFileOpenDialog (from KIOWidgets), provides an option
122 * to remember the last value used and not ask again, if that is set, then the dialog will
123 * not be shown.
124 *
125 * When set to @c true this will take precedence over setRunExecutables (the latter can be
126 * used to allow running executables without first asking the user for confirmation).
127 *
128 * @since 5.73
129 */
130 void setShowOpenOrExecuteDialog(bool b);
131
132 /**
133 * Sets whether the external webbrowser setting should be honoured.
134 * This is enabled by default.
135 * This should only be disabled in webbrowser applications.
136 * @param b whether to let the external browser handle the URL or not
137 */
138 void setEnableExternalBrowser(bool b);
139
140 /**
141 * Sets whether the job should follow URL redirections.
142 * This is enabled by default.
143 * @param b whether to follow redirections or not.
144 */
145 void setFollowRedirections(bool b);
146
147 /**
148 * Starts the job.
149 * You must call this, after having called all the needed setters.
150 * This is a GUI job, never use exec(), it would block user interaction.
151 */
152 void start() override;
153
154 /**
155 * Returns whether the @p url of @p mimetype is executable.
156 * To be executable the file must pass the following rules:
157 * -# Must reside on the local filesystem.
158 * -# Must be marked as executable for the user by the filesystem.
159 * -# The MIME type must inherit application/x-executable, application/x-executable-script
160 */
161 static bool isExecutableFile(const QUrl &url, const QString &mimetypeName);
162
164 /**
165 * Emitted when the MIME type is determined.
166 * This can be used for special cases like webbrowsers
167 * who want to embed the URL in some cases, rather than starting a different
168 * application. In that case they can kill the job.
169 */
170 void mimeTypeFound(const QString &mimeType);
171
172protected:
173 bool doKill() override;
174
175private:
176 void slotResult(KJob *job) override;
177
178 friend class OpenUrlJobPrivate;
180};
181
182} // namespace KIO
183
184#endif // OPENURLJOB_H
KCompositeJob(QObject *parent=nullptr)
void setSuggestedFileName(const QString &suggestedFileName)
Sets the file name to use in the case of downloading the file to a tempfile, in order to give it to a...
void setDeleteTemporaryFile(bool b)
Specifies that the URL passed to the application will be deleted when it exits (if the URL is a local...
void setEnableExternalBrowser(bool b)
Sets whether the external webbrowser setting should be honoured.
void setFollowRedirections(bool b)
Sets whether the job should follow URL redirections.
void setRunExecutables(bool allow)
Set this to true if this class should allow the user to run executables.
void mimeTypeFound(const QString &mimeType)
Emitted when the MIME type is determined.
OpenUrlJob(const QUrl &url, QObject *parent=nullptr)
Creates an OpenUrlJob in order to open a URL.
static bool isExecutableFile(const QUrl &url, const QString &mimetypeName)
Returns whether the url of mimetype is executable.
QUrl url() const
Returns the URL the OpenUrlJob was created with.
void setShowOpenOrExecuteDialog(bool b)
Set this to true if this class should show a dialog to ask the user about how to handle various types...
void setStartupId(const QByteArray &startupId)
Sets the platform-specific startup id of the application launch.
KJob(QObject *parent=nullptr)
Q_SCRIPTABLE Q_NOREPLY void start()
A namespace for KIO globals.
QObject(QObject *parent)
Q_OBJECTQ_OBJECT
Q_SIGNALSQ_SIGNALS
QObject * parent() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2025 The KDE developers.
Generated on Fri May 2 2025 12:02:24 by doxygen 1.13.2 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.