1/* This file is part of the KDE libraries
2 Copyright (c) 1997-1999 Matthias Kalle Dalheimer <kalle@kde.org>
3 Copyright (c) 1997-2000 Matthias Ettrich <ettrich@troll.no>
4 Copyright (c) 1998-2005 Stephan Kulow <coolo@kde.org>
5 Copyright (c) 1999-2004 Waldo Bastian <bastian@kde.org>
6 Copyright (c) 2001-2005 Lubos Lunak <l.lunak@kde.org>
7 Copyright (C) 2008 Aaron Seigo <aseigo@kde.org>
8
9 This library is free software; you can redistribute it and/or
10 modify it under the terms of the GNU Library General Public
11 License as published by the Free Software Foundation; either
12 version 2 of the License, or (at your option) any later version.
13
14 This library is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 Library General Public License for more details.
18
19 You should have received a copy of the GNU Library General Public License
20 along with this library; see the file COPYING.LIB. If not, write to
21 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
22 Boston, MA 02110-1301, USA.
23*/
24
25#ifndef _KTOOLINVOCATION_H
26#define _KTOOLINVOCATION_H
27
28#include <kdecore_export.h>
29
30#include <QtCore/QObject>
31#include <QtCore/QByteArray>
32#include <QtCore/QStringList>
33
34class OrgKdeKLauncherInterface;
35class KUrl;
36class KToolInvocationPrivate;
37
38/**
39 * KToolInvocation: for starting other programs
40 *
41 * @section desktopfiles Desktop files for startServiceBy
42 *
43 * The way a service gets started depends on the 'X-DBUS-StartupType'
44 * entry in the desktop file of the service:
45 *
46 * There are three possibilities:
47 * @li X-DBUS-StartupType=None (default)
48 * Always start a new service,
49 * don't wait till the service registers with D-Bus.
50 * @li X-DBUS-StartupType=Multi
51 * Always start a new service,
52 * wait until the service has registered with D-Bus.
53 * @li X-DBUS-StartupType=Unique
54 * Only start the service if it isn't already running,
55 * wait until the service has registered with D-Bus.
56 * The .desktop file can specify the name that the application will use when registering
57 * using X-DBUS-ServiceName=org.domain.mykapp. Otherwise org.kde.binaryname is assumed.
58 *
59 * @section thread Multi-threading
60 *
61 * The static members (apart from self()), have to be called from the QApplication main thread.
62 * Calls to members are only allowed if there is a Q(Core)Application object created
63 * If you call the members with signal/slot connections across threads, you can't use the return values
64 * If a function is called from the wrong thread and it has a return value -1 is returned
65 * Investigate if this is really needed or if D-Bus is threadsafe anyway
66 *
67 * For more details see <a
68 * href="http://techbase.kde.org/Development/Architecture/KDE4/Starting_Other_Programs#KToolInvocation::startServiceByDesktopPath">techbase</a>.
69 *
70 */
71class KDECORE_EXPORT KToolInvocation : public QObject
72{
73
74 Q_OBJECT
75private:
76 KToolInvocation();
77public:
78 // @internal
79 ~KToolInvocation();
80 static KToolInvocation *self();
81
82public Q_SLOTS:
83 /**
84 * Invokes the KHelpCenter HTML help viewer from docbook sources.
85 *
86 * @param anchor This has to be a defined anchor in your
87 * docbook sources. If empty the main index
88 * is loaded
89 * @param appname This allows you to show the help of another
90 * application. If empty the current name() is
91 * used
92 * @param startup_id for app startup notification, "0" for none,
93 * "" ( empty string ) is the default
94 */
95
96 static void invokeHelp( const QString& anchor = QString(),
97 const QString& appname = QString(),
98 const QByteArray& startup_id = QByteArray());
99
100 /**
101 * Convenience method; invokes the standard email application.
102 *
103 * @param address The destination address
104 * @param subject Subject string. Can be QString().
105 * @param startup_id for app startup notification, "0" for none,
106 * "" ( empty string ) is the default
107 */
108 static void invokeMailer( const QString &address, const QString &subject,
109 const QByteArray& startup_id = QByteArray() );
110
111 /**
112 * Invokes the standard email application.
113 *
114 * @param mailtoURL A mailto URL.
115 * @param startup_id for app startup notification, "0" for none,
116 * "" ( empty string ) is the default
117 * @param allowAttachments whether attachments specified in mailtoURL should be honoured.
118 The default is false; do not honor requests for attachments.
119 */
120 static void invokeMailer( const KUrl &mailtoURL, const QByteArray& startup_id = QByteArray(),
121 bool allowAttachments = false );
122
123 /**
124 * Convenience method; invokes the standard email application.
125 *
126 * All parameters are optional.
127 *
128 * @param to The destination address.
129 * @param cc The Cc field
130 * @param bcc The Bcc field
131 * @param subject Subject string
132 * @param body A string containing the body of the mail (exclusive with messageFile)
133 * @param messageFile A file (URL) containing the body of the mail (exclusive with body) - currently unsupported
134 * @param attachURLs List of URLs to be attached to the mail.
135 * @param startup_id for app startup notification, "0" for none,
136 * "" ( empty string ) is the default
137 */
138 static void invokeMailer(const QString &to, const QString &cc, const QString &bcc,
139 const QString &subject, const QString &body,
140 const QString &messageFile = QString(),
141 const QStringList &attachURLs = QStringList(),
142 const QByteArray& startup_id = QByteArray() );
143
144 /**
145 * Invokes the user's preferred browser.
146 * Note that you should only do this when you know for sure that the browser can
147 * handle the URL (i.e. its mimetype). In doubt, if the URL can point to an image
148 * or anything else than HTML, prefer to use new KRun( url ).
149 *
150 * See also <a
151 * href="http://techbase.kde.org/Development/Architecture/KDE4/Starting_Other_Programs#KToolInvocation::invokeBrowser>techbase</a>
152 * for a discussion of invokeBrowser vs KRun.
153 *
154 * @param url The destination address
155 * @param startup_id for app startup notification, "0" for none,
156 * "" ( empty string ) is the default
157 */
158 static void invokeBrowser( const QString &url,
159 const QByteArray& startup_id = QByteArray() );
160
161 /**
162 * Invokes the standard terminal application.
163 *
164 * @param command the command to execute, can be empty.
165 * @param workdir the initial working directory, can be empty.
166 * @param startup_id for app startup notification, "0" for none,
167 * "" ( empty string ) is the default
168 *
169 * @since 4.1
170 */
171 static void invokeTerminal(const QString &command,
172 const QString& workdir = QString(),
173 const QByteArray &startup_id = "");
174
175public:
176 /**
177 * Returns the D-Bus interface of the service launcher.
178 * The returned object is owned by KApplication, do not delete it!
179 */
180 static OrgKdeKLauncherInterface *klauncher();
181 // KDE5: remove this from the public API. Make it kdelibs-private, and provide
182 // replacements for setLaunchEnv and for "making sure kdeinit/klauncher is running".
183 // (We could do the last two without waiting, of course).
184
185 /**
186 * Starts a service based on the (translated) name of the service.
187 * E.g. "Web Browser"
188 *
189 * @param _name the name of the service
190 * @param URL if not empty this URL is passed to the service
191 * @param error On failure, error contains a description of the error
192 * that occurred. If the pointer is 0, the argument will be
193 * ignored
194 * @param serviceName On success, serviceName contains the DCOP name
195 * under which this service is available. If empty, the service does
196 * not provide DCOP services. If the pointer is 0 the argument
197 * will be ignored
198 * @param pid On success, the process id of the new service will be written
199 * here. If the pointer is 0, the argument will be ignored.
200 * @param startup_id for app startup notification, "0" for none,
201 * "" ( empty string ) is the default
202 * @param noWait if set, the function does not wait till the service is running.
203 * @return an error code indicating success (== 0) or failure (> 0).
204 * @deprecated Use startServiceByDesktopName or startServiceByDesktopPath
205 */
206#ifndef KDE_NO_DEPRECATED
207 KDE_DEPRECATED static int startServiceByName( const QString& _name, const QString &URL,
208 QString *error=0, QString *serviceName=0, int *pid=0,
209 const QByteArray &startup_id = QByteArray(), bool noWait = false );
210#endif
211
212 /**
213 * Starts a service based on the (translated) name of the service.
214 * E.g. "Web Browser"
215 *
216 * @param _name the name of the service
217 * @param URLs if not empty these URLs will be passed to the service
218 * @param error On failure, @p error contains a description of the error
219 * that occurred. If the pointer is 0, the argument will be
220 * ignored
221 * @param serviceName On success, @p serviceName contains the DCOP name
222 * under which this service is available. If empty, the service does
223 * not provide DCOP services. If the pointer is 0 the argument
224 * will be ignored
225 * @param pid On success, the process id of the new service will be written
226 * here. If the pointer is 0, the argument will be ignored.
227 * @param startup_id for app startup notification, "0" for none,
228 * "" ( empty string ) is the default
229 * @param noWait if set, the function does not wait till the service is running.
230 * @return an error code indicating success (== 0) or failure (> 0).
231 * @deprecated Use startServiceByDesktopName or startServiceByDesktopPath
232 */
233#ifndef KDE_NO_DEPRECATED
234 KDE_DEPRECATED static int startServiceByName( const QString& _name, const QStringList &URLs=QStringList(),
235 QString *error=0, QString *serviceName=0, int *pid=0,
236 const QByteArray &startup_id = QByteArray(), bool noWait = false );
237#endif
238
239 /**
240 * Starts a service based on the desktop path of the service.
241 * E.g. "Applications/konqueror.desktop" or "/home/user/bla/myfile.desktop"
242 *
243 * @param _name the path of the desktop file
244 * @param URL if not empty this URL is passed to the service
245 * @param error On failure, @p error contains a description of the error
246 * that occurred. If the pointer is 0, the argument will be
247 * ignored
248 * @param serviceName On success, @p serviceName contains the DCOP name
249 * under which this service is available. If empty, the service does
250 * not provide DCOP services. If the pointer is 0 the argument
251 * will be ignored
252 * @param pid On success, the process id of the new service will be written
253 * here. If the pointer is 0, the argument will be ignored.
254 * @param startup_id for app startup notification, "0" for none,
255 * "" ( empty string ) is the default
256 * @param noWait if set, the function does not wait till the service is running.
257 * @return an error code indicating success (== 0) or failure (> 0).
258 */
259 static int startServiceByDesktopPath( const QString& _name, const QString &URL,
260 QString *error=0, QString *serviceName=0, int *pid = 0,
261 const QByteArray &startup_id = QByteArray(), bool noWait = false );
262
263 /**
264 * Starts a service based on the desktop path of the service.
265 * E.g. "Applications/konqueror.desktop" or "/home/user/bla/myfile.desktop"
266 *
267 * @param _name the path of the desktop file
268 * @param URLs if not empty these URLs will be passed to the service
269 * @param error On failure, @p error contains a description of the error
270 * that occurred. If the pointer is 0, the argument will be
271 * ignored * @param serviceName On success, @p serviceName contains the DCOP name
272 * under which this service is available. If empty, the service does
273 * not provide DCOP services. If the pointer is 0 the argument
274 * will be ignored
275 * @param pid On success, the process id of the new service will be written
276 * here. If the pointer is 0, the argument will be ignored.
277 * @param startup_id for app startup notification, "0" for none,
278 * "" ( empty string ) is the default
279 * @param noWait if set, the function does not wait till the service is running.
280 * @return an error code indicating success (== 0) or failure (> 0).
281 */
282 static int startServiceByDesktopPath( const QString& _name, const QStringList &URLs=QStringList(),
283 QString *error=0, QString *serviceName=0, int *pid = 0,
284 const QByteArray &startup_id = QByteArray(), bool noWait = false );
285
286 /**
287 * Starts a service based on the desktop name of the service.
288 * E.g. "konqueror"
289 *
290 * @param _name the desktop name of the service
291 * @param URL if not empty this URL is passed to the service
292 * @param error On failure, @p error contains a description of the error
293 * that occurred. If the pointer is 0, the argument will be
294 * ignored
295 * @param serviceName On success, @p serviceName contains the D-Bus service name
296 * under which this service is available. If empty, the service does
297 * not provide D-Bus services. If the pointer is 0 the argument
298 * will be ignored
299 * @param pid On success, the process id of the new service will be written
300 * here. If the pointer is 0, the argument will be ignored.
301 * @param startup_id for app startup notification, "0" for none,
302 * "" ( empty string ) is the default
303 * @param noWait if set, the function does not wait till the service is running.
304 * @return an error code indicating success (== 0) or failure (> 0).
305 */
306 static int startServiceByDesktopName( const QString& _name, const QString &URL,
307 QString *error=0, QString *serviceName=0, int *pid = 0,
308 const QByteArray &startup_id = QByteArray(), bool noWait = false );
309
310 /**
311 * Starts a service based on the desktop name of the service.
312 * E.g. "konqueror"
313 *
314 * @param _name the desktop name of the service
315 * @param URLs if not empty these URLs will be passed to the service
316 * @param error On failure, @p error contains a description of the error
317 * that occurred. If the pointer is 0, the argument will be
318 * ignored
319 * @param serviceName On success, @p serviceName contains the D-Bus service name
320 * under which this service is available. If empty, the service does
321 * not provide D-Bus services. If the pointer is 0 the argument
322 * will be ignored
323 * @param pid On success, the process id of the new service will be written
324 * here. If the pointer is 0, the argument will be ignored.
325 * @param startup_id for app startup notification, "0" for none,
326 * "" ( empty string ) is the default
327 * @param noWait if set, the function does not wait till the service is running.
328 * @return an error code indicating success (== 0) or failure (> 0).
329 */
330 static int startServiceByDesktopName( const QString& _name, const QStringList &URLs=QStringList(),
331 QString *error=0, QString *serviceName=0, int *pid = 0,
332 const QByteArray &startup_id = QByteArray(), bool noWait = false );
333
334 /**
335 * Starts a program via kdeinit.
336 *
337 * program name and arguments are converted to according to the
338 * local encoding and passed as is to kdeinit.
339 *
340 * @param name Name of the program to start
341 * @param args Arguments to pass to the program
342 * @param error On failure, @p error contains a description of the error
343 * that occurred. If the pointer is 0, the argument will be
344 * ignored
345 * @param pid On success, the process id of the new service will be written
346 * here. If the pointer is 0, the argument will be ignored.
347 * @param startup_id for app startup notification, "0" for none,
348 * "" ( empty string ) is the default
349 * @return an error code indicating success (== 0) or failure (> 0).
350 */
351 static int kdeinitExec( const QString& name, const QStringList &args=QStringList(),
352 QString *error=0, int *pid = 0, const QByteArray& startup_id = QByteArray() );
353
354 /**
355 * Starts a program via kdeinit and wait for it to finish.
356 *
357 * Like kdeinitExec(), but it waits till the program is finished.
358 * As such it behaves similar to the system(...) function.
359 *
360 * @param name Name of the program to start
361 * @param args Arguments to pass to the program
362 * @param error On failure, @p error contains a description of the error
363 * that occurred. If the pointer is 0, the argument will be
364 * ignored
365 * @param pid On success, the process id of the new service will be written
366 * here. If the pointer is 0, the argument will be ignored.
367 * @param startup_id for app startup notification, "0" for none,
368 * "" ( empty string ) is the default
369 * @return an error code indicating success (== 0) or failure (> 0).
370 */
371 static int kdeinitExecWait( const QString& name, const QStringList &args=QStringList(),
372 QString *error=0, int *pid = 0, const QByteArray& startup_id = QByteArray() );
373
374Q_SIGNALS:
375 /**
376 * Hook for KApplication in kdeui
377 * @internal
378 */
379 void kapplication_hook(QStringList& env , QByteArray& startup_id);
380
381private:
382 /**
383 * @internal
384 */
385 static void startKdeinit();
386
387 int startServiceInternal(const char *_function,
388 const QString& _name, const QStringList &URLs,
389 QString *error, QString *serviceName, int *pid,
390 const QByteArray& startup_id, bool noWait,
391 const QString& workdir = QString());
392 static bool isMainThreadActive(QString* error = 0);
393
394 KToolInvocationPrivate * const d;
395};
396
397#endif
398
399