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 | |
34 | class OrgKdeKLauncherInterface; |
35 | class KUrl; |
36 | class 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 | */ |
71 | class KDECORE_EXPORT KToolInvocation : public QObject |
72 | { |
73 | |
74 | Q_OBJECT |
75 | private: |
76 | KToolInvocation(); |
77 | public: |
78 | // @internal |
79 | ~KToolInvocation(); |
80 | static KToolInvocation *self(); |
81 | |
82 | public 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 | |
175 | public: |
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 | |
374 | Q_SIGNALS: |
375 | /** |
376 | * Hook for KApplication in kdeui |
377 | * @internal |
378 | */ |
379 | void kapplication_hook(QStringList& env , QByteArray& startup_id); |
380 | |
381 | private: |
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 | |