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 | |
14 | class KRunPrivate; // KF6 REMOVE |
15 | class CommandLauncherJobTest; // KF6 REMOVE |
16 | |
17 | class QProcessEnvironment; |
18 | namespace KIO |
19 | { |
20 | class 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 | */ |
46 | class KIOGUI_EXPORT CommandLauncherJob : public KJob |
47 | { |
48 | public: |
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 | |
158 | private: |
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 | |