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

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