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 * 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
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;
173};
174
175} // namespace KIO
176
177#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.
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 Jan 24 2025 11:49:37 by doxygen 1.13.2 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.