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_COMMANDLAUNCHERJOB_H
9#define KIO_COMMANDLAUNCHERJOB_H
10
11#include "kiogui_export.h"
12#include <KJob>
13
14class KRunPrivate; // KF6 REMOVE
15class CommandLauncherJobTest; // KF6 REMOVE
16
17class QProcessEnvironment;
18namespace KIO
19{
20class CommandLauncherJobPrivate;
21
22/*!
23 * \class KIO::CommandLauncherJob
24 * \inmodule KIOGui
25 * \inheaderfile KIO/CommandLauncherJob
26 *
27 * \brief CommandLauncherJob runs a command and watches it while running.
28 *
29 * It creates a startup notification and finishes it on success or on error (for the taskbar).
30 * It also emits a "program not found" error message if the requested command did not exist.
31 *
32 * The job finishes when the command is successfully started; at that point you can
33 * query the PID with pid(). Note that no other errors are handled automatically after the
34 * command starts running. As far as CommandLauncherJob is concerned, if the command was
35 * launched, the result is a success. If you need to query the command for its exit status
36 * or error text later, it is recommended to use QProcess instead.
37 *
38 * For error handling, either connect to the result() signal, or for a simple messagebox on error,
39 * you can do
40 * \code
41 * job->setUiDelegate(new KDialogJobUiDelegate(KJobUiDelegate::AutoHandlingEnabled, this));
42 * \endcode
43 *
44 * \since 5.69
45 */
46class KIOGUI_EXPORT CommandLauncherJob : public KJob
47{
48public:
49 /*!
50 * Creates a CommandLauncherJob.
51 *
52 * \a command the shell command to run
53 *
54 * The command is given "as is" to the shell, it must already be quoted if necessary.
55 * If \a command is instead a filename, consider using the other constructor, even if no args are present.
56 *
57 * \a parent the parent QObject
58 *
59 * Please consider also calling setDesktopName() for better startup notification.
60 */
61 explicit CommandLauncherJob(const QString &command, QObject *parent = nullptr);
62
63 /*!
64 * Creates a CommandLauncherJob.
65 *
66 * \a executable the name of the executable
67 *
68 * \a args the commandline arguments to pass to the executable
69 *
70 * \a parent the parent QObject
71 *
72 * Please consider also calling setDesktopName() for better startup notification.
73 */
74 explicit CommandLauncherJob(const QString &executable, const QStringList &args, QObject *parent = nullptr);
75
76 /*!
77 * Destructor
78 *
79 * Note that jobs auto-delete themselves after emitting result
80 */
81 ~CommandLauncherJob() override;
82
83 /*!
84 * Sets the command to execute, this will change the command that was set by any of the constructors.
85 * \since 5.83
86 */
87 void setCommand(const QString &command);
88
89 /*!
90 * Returns the command executed by this job.
91 * \since 5.83
92 */
93 QString command() const;
94
95 /*!
96 * Sets the name of the executable, used in the startup notification
97 * (see KStartupInfoData::setBin()).
98 *
99 * \a executable executable name, with or without a path
100 *
101 * Alternatively, use setDesktopName().
102 */
103 void setExecutable(const QString &executable);
104
105 /*!
106 * Set the name of the desktop file (e.g.\ "org.kde.dolphin", without the ".desktop" filename extension).
107 *
108 * This is necessary for startup notification to work.
109 */
110 void setDesktopName(const QString &desktopName);
111
112 /*!
113 * Sets the platform-specific startup id of the command launch.
114 *
115 * \a startupId startup id, if any (otherwise "").
116 *
117 * For X11, this would be the id for the Startup Notification protocol.
118 * For Wayland, this would be the token for the XDG Activation protocol.
119 */
120 void setStartupId(const QByteArray &startupId);
121
122 /*!
123 * Sets the working directory from which to run the command.
124 *
125 * \a workingDirectory path of a local directory
126 */
127 void setWorkingDirectory(const QString &workingDirectory);
128
129 /*!
130 * Returns the working directory, which was previously set with @c setWorkingDirectory().
131 * \since 5.83
132 */
133 QString workingDirectory() const;
134
135 /*!
136 * Can be used to pass environment variables to the child process.
137 *
138 * \a environment set of environment variables to pass to the child process
139 *
140 * \sa QProcessEnvironment
141 * \since 5.82
142 */
143 void setProcessEnvironment(const QProcessEnvironment &environment);
144
145 /*!
146 * Starts the job.
147 * You must call this, after having called all the necessary setters.
148 */
149 void start() override;
150
151 /*!
152 * Returns the PID of the command that was started
153 *
154 * Available after the job emits result().
155 */
156 qint64 pid() const;
157
158private:
159 friend class ::KRunPrivate; // KF6 REMOVE
160 friend class ::CommandLauncherJobTest; // KF6 REMOVE
161 /*!
162 * Blocks until the process has started. Only exists for KRun, will disappear in KF6.
163 */
164 bool waitForStarted();
165
166 friend class CommandLauncherJobPrivate;
167 QScopedPointer<CommandLauncherJobPrivate> d;
168};
169
170} // namespace KIO
171
172#endif
173

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