This file is indexed.

/usr/include/KF5/KService/ktoolinvocation.h is in libkf5service-dev 5.28.0-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
/* This file is part of the KDE libraries
    Copyright (c) 1997-1999 Matthias Kalle Dalheimer <kalle@kde.org>
    Copyright (c) 1997-2000 Matthias Ettrich <ettrich@troll.no>
    Copyright (c) 1998-2005 Stephan Kulow <coolo@kde.org>
    Copyright (c) 1999-2004 Waldo Bastian <bastian@kde.org>
    Copyright (c) 2001-2005 Lubos Lunak <l.lunak@kde.org>
    Copyright (C) 2008 Aaron Seigo <aseigo@kde.org>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to
    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    Boston, MA 02110-1301, USA.
*/

#ifndef _KTOOLINVOCATION_H
#define _KTOOLINVOCATION_H

#include <kservice_export.h>

#include <QtCore/QObject>
#include <QtCore/QByteArray>
#include <QtCore/QStringList>

class QUrl;
class KToolInvocationPrivate;

/**
 * KToolInvocation: for starting other programs
 *
 * @section desktopfiles Desktop files for startServiceBy
 *
 * The way a service gets started depends on the 'X-DBUS-StartupType'
 * entry in the desktop file of the service:
 *
 * There are three possibilities:
 * @li X-DBUS-StartupType=None (default)
 *    Always start a new service,
 *    don't wait till the service registers with D-Bus.
 * @li X-DBUS-StartupType=Multi
 *    Always start a new service,
 *    wait until the service has registered with D-Bus.
 * @li X-DBUS-StartupType=Unique
 *    Only start the service if it isn't already running,
 *    wait until the service has registered with D-Bus.
 * The .desktop file can specify the name that the application will use when registering
 * using X-DBUS-ServiceName=org.domain.mykapp. Otherwise org.kde.binaryname is assumed.
 *
 * @section thread Multi-threading
 *
 * The static members (apart from self()), have to be called from the QApplication main thread.
 * Calls to members are only allowed if there is a Q(Core)Application object created
 * If you call the members with signal/slot connections across threads, you can't use the return values
 * If a function is called from the wrong thread and it has a return value -1 is returned
 * Investigate if this is really needed or if D-Bus is threadsafe anyway
 *
 * For more details see <a
 * href="http://techbase.kde.org/Development/Architecture/KDE4/Starting_Other_Programs#KToolInvocation::startServiceByDesktopPath">techbase</a>.
 *
 */
class KSERVICE_EXPORT KToolInvocation : public QObject
{

    Q_OBJECT
private:
    KToolInvocation();
public:
    // @internal
    ~KToolInvocation();
    static KToolInvocation *self();

public Q_SLOTS:

    /**
     * Convenience method; invokes the standard email application.
     *
     * @param address The destination address
     * @param subject Subject string. Can be QString().
     * @param startup_id for app startup notification, "0" for none,
     *           "" ( empty string ) is the default
     *
     * @deprecated since 5.0, use QDesktopServices::openUrl(mailtoURL),
     * using QUrl::setPath(address) and a query item of "subject" for the subject.
     */
    KSERVICE_DEPRECATED static void invokeMailer(const QString &address, const QString &subject,
                             const QByteArray &startup_id = QByteArray());

    /**
     * Invokes the standard email application.
     *
     * @param mailtoURL A mailto URL.
     * @param startup_id for app startup notification, "0" for none,
     *           "" ( empty string ) is the default
     * @param allowAttachments whether attachments specified in mailtoURL should be honoured.
     *           The default is false; do not honor requests for attachments.
     * @deprecated since 5.0, use QDesktopServices::openUrl(mailtoURL)
     */
    KSERVICE_DEPRECATED static void invokeMailer(const QUrl &mailtoURL, const QByteArray &startup_id = QByteArray(),
                             bool allowAttachments = false);

    /**
     * Convenience method; invokes the standard email application.
     *
     * All parameters are optional.
     *
     * @param to          The destination address.
     * @param cc          The Cc field
     * @param bcc         The Bcc field
     * @param subject     Subject string
     * @param body        A string containing the body of the mail (exclusive with messageFile)
     * @param messageFile A file (URL) containing the body of the mail (exclusive with body) - currently unsupported
     * @param attachURLs  List of URLs to be attached to the mail.
     * @param startup_id for app startup notification, "0" for none,
     *           "" ( empty string ) is the default
     */
    static void invokeMailer(const QString &to, const QString &cc, const QString &bcc,
                             const QString &subject, const QString &body,
                             const QString &messageFile = QString(),
                             const QStringList &attachURLs = QStringList(),
                             const QByteArray &startup_id = QByteArray());

    /**
     * Invokes the user's preferred browser.
     * Note that you should only do this when you know for sure that the browser can
     * handle the URL (i.e. its mimetype). In doubt, if the URL can point to an image
     * or anything else than HTML, prefer to use new KRun( url ).
     *
     * See also <a
     * href="http://techbase.kde.org/Development/Architecture/KDE4/Starting_Other_Programs#KToolInvocation::invokeBrowser>techbase</a>
     * for a discussion of invokeBrowser vs KRun.
     *
     * @param url The destination address
     * @param startup_id for app startup notification, "0" for none,
     *           "" ( empty string ) is the default
     * @deprecated since 5.0, use QDesktopServices::openUrl(url)
     */
    KSERVICE_DEPRECATED static void invokeBrowser(const QString &url,
                                                  const QByteArray &startup_id = QByteArray());

    /**
     * Invokes the standard terminal application.
     *
     * @param command the command to execute, can be empty.
     * @param workdir the initial working directory, can be empty.
     * @param startup_id for app startup notification, "0" for none,
     *           "" ( empty string ) is the default
     *
     * @since 4.1
     */
    static void invokeTerminal(const QString &command,
                               const QString &workdir = QString(),
                               const QByteArray &startup_id = "");

public:

    /**
     * Starts a service based on the (translated) name of the service.
     * E.g. "Web Browser"
     *
     * @param _name the name of the service
     * @param URL if not empty this URL is passed to the service
     * @param error On failure, error contains a description of the error
     *         that occurred. If the pointer is 0, the argument will be
     *         ignored
     * @param serviceName On success, serviceName contains the DCOP name
     *         under which this service is available. If empty, the service does
     *         not provide DCOP services. If the pointer is 0 the argument
     *         will be ignored
     * @param pid On success, the process id of the new service will be written
     *        here. If the pointer is 0, the argument will be ignored.
     * @param startup_id for app startup notification, "0" for none,
     *           "" ( empty string ) is the default
     * @param noWait if set, the function does not wait till the service is running.
     * @return an error code indicating success (== 0) or failure (> 0).
     * @deprecated Use startServiceByDesktopName or startServiceByDesktopPath
     */
#ifndef KSERVICE_NO_DEPRECATED
    KSERVICE_DEPRECATED static int startServiceByName(const QString &_name, const QString &URL,
            QString *error = 0, QString *serviceName = 0, int *pid = 0,
            const QByteArray &startup_id = QByteArray(), bool noWait = false);
#endif

    /**
     * Starts a service based on the (translated) name of the service.
     * E.g. "Web Browser"
     *
     * @param _name the name of the service
     * @param URLs if not empty these URLs will be passed to the service
     * @param error On failure, @p error contains a description of the error
     *         that occurred. If the pointer is 0, the argument will be
     *         ignored
     * @param serviceName On success, @p serviceName contains the DCOP name
     *         under which this service is available. If empty, the service does
     *         not provide DCOP services. If the pointer is 0 the argument
     *         will be ignored
     * @param pid On success, the process id of the new service will be written
     *        here. If the pointer is 0, the argument will be ignored.
     * @param startup_id for app startup notification, "0" for none,
     *           "" ( empty string ) is the default
     * @param noWait if set, the function does not wait till the service is running.
     * @return an error code indicating success (== 0) or failure (> 0).
     * @deprecated Use startServiceByDesktopName or startServiceByDesktopPath
     */
#ifndef KSERVICE_NO_DEPRECATED
    KSERVICE_DEPRECATED static int startServiceByName(const QString &_name, const QStringList &URLs = QStringList(),
            QString *error = 0, QString *serviceName = 0, int *pid = 0,
            const QByteArray &startup_id = QByteArray(), bool noWait = false);
#endif

    /**
     * Starts a service based on the desktop path of the service.
     * E.g. "Applications/konqueror.desktop" or "/home/user/bla/myfile.desktop"
     *
     * @param _name the path of the desktop file
     * @param URL if not empty this URL is passed to the service
     * @param error On failure, @p error contains a description of the error
     *         that occurred. If the pointer is 0, the argument will be
     *         ignored
     * @param serviceName On success, @p serviceName contains the DCOP name
     *         under which this service is available. If empty, the service does
     *         not provide DCOP services. If the pointer is 0 the argument
     *         will be ignored
     * @param pid On success, the process id of the new service will be written
     *        here. If the pointer is 0, the argument will be ignored.
     * @param startup_id for app startup notification, "0" for none,
     *           "" ( empty string ) is the default
     * @param noWait if set, the function does not wait till the service is running.
     * @return an error code indicating success (== 0) or failure (> 0).
     *
     * @deprecated since 5.0 use QDBusConnectionInterface::startService("org.kde.serviceName"),
     *   to start a unique application in order to make dbus calls to it (after ensuring that
     *   it installs a dbus org.kde.serviceName.service file). Otherwise just use QProcess or KRun.
     */
    static int startServiceByDesktopPath(const QString &_name, const QString &URL,
                                         QString *error = 0, QString *serviceName = 0, int *pid = 0,
                                         const QByteArray &startup_id = QByteArray(), bool noWait = false);

    /**
     * Starts a service based on the desktop path of the service.
     * E.g. "Applications/konqueror.desktop" or "/home/user/bla/myfile.desktop"
     *
     * @param _name the path of the desktop file
     * @param URLs if not empty these URLs will be passed to the service
     * @param error On failure, @p error contains a description of the error
     *         that occurred. If the pointer is 0, the argument will be
     *         ignored   * @param serviceName On success, @p serviceName contains the DCOP name
     *         under which this service is available. If empty, the service does
     *         not provide DCOP services. If the pointer is 0 the argument
     *         will be ignored
     * @param pid On success, the process id of the new service will be written
     *        here. If the pointer is 0, the argument will be ignored.
     * @param startup_id for app startup notification, "0" for none,
     *           "" ( empty string ) is the default
     * @param noWait if set, the function does not wait till the service is running.
     * @return an error code indicating success (== 0) or failure (> 0).
     * @deprecated since 5.0 use QDBusConnectionInterface::startService("org.kde.serviceName"),
     *   to start a unique application in order to make dbus calls to it (after ensuring that
     *   it installs a dbus org.kde.serviceName.service file). Otherwise just use QProcess or KRun.
     */
    static int startServiceByDesktopPath(const QString &_name, const QStringList &URLs = QStringList(),
                                         QString *error = 0, QString *serviceName = 0, int *pid = 0,
                                         const QByteArray &startup_id = QByteArray(), bool noWait = false);

    /**
     * Starts a service based on the desktop name of the service.
     * E.g. "konqueror"
     *
     * @param _name the desktop name of the service
     * @param URL if not empty this URL is passed to the service
     * @param error On failure, @p error contains a description of the error
     *         that occurred. If the pointer is 0, the argument will be
     *         ignored
     * @param serviceName On success, @p serviceName contains the D-Bus service name
     *         under which this service is available. If empty, the service does
     *         not provide D-Bus services. If the pointer is 0 the argument
     *         will be ignored
     * @param pid On success, the process id of the new service will be written
     *        here. If the pointer is 0, the argument will be ignored.
     * @param startup_id for app startup notification, "0" for none,
     *           "" ( empty string ) is the default
     * @param noWait if set, the function does not wait till the service is running.
     * @return an error code indicating success (== 0) or failure (> 0).
     * @deprecated since 5.0 use QDBusConnectionInterface::startService("org.kde.serviceName"),
     *   to start a unique application in order to make dbus calls to it (after ensuring that
     *   it installs a dbus org.kde.serviceName.service file). Otherwise just use QProcess or KRun.
     */
    static int startServiceByDesktopName(const QString &_name, const QString &URL,
                                         QString *error = 0, QString *serviceName = 0, int *pid = 0,
                                         const QByteArray &startup_id = QByteArray(), bool noWait = false);

    /**
     * Starts a service based on the desktop name of the service.
     * E.g. "konqueror"
     *
     * @param _name the desktop name of the service
     * @param URLs if not empty these URLs will be passed to the service
     * @param error On failure, @p error contains a description of the error
     *         that occurred. If the pointer is 0, the argument will be
     *         ignored
     * @param serviceName On success, @p serviceName contains the D-Bus service name
     *         under which this service is available. If empty, the service does
     *         not provide D-Bus services. If the pointer is 0 the argument
     *         will be ignored
     * @param pid On success, the process id of the new service will be written
     *        here. If the pointer is 0, the argument will be ignored.
     * @param startup_id for app startup notification, "0" for none,
     *           "" ( empty string ) is the default
     * @param noWait if set, the function does not wait till the service is running.
     * @return an error code indicating success (== 0) or failure (> 0).
     * @deprecated since 5.0 use QDBusConnectionInterface::startService("org.kde.serviceName"),
     *   to start a unique application in order to make dbus calls to it (after ensuring that
     *   it installs a dbus org.kde.serviceName.service file). Otherwise just use QProcess or KRun.
     */
    static int startServiceByDesktopName(const QString &_name, const QStringList &URLs = QStringList(),
                                         QString *error = 0, QString *serviceName = 0, int *pid = 0,
                                         const QByteArray &startup_id = QByteArray(), bool noWait = false);

    /**
     * Starts a program via kdeinit.
     *
     * program name and arguments are converted to according to the
     * local encoding and passed as is to kdeinit.
     *
     * @param name Name of the program to start
     * @param args Arguments to pass to the program
     * @param error On failure, @p error contains a description of the error
     *         that occurred. If the pointer is 0, the argument will be
     *         ignored
     * @param pid On success, the process id of the new service will be written
     *        here. If the pointer is 0, the argument will be ignored.
     * @param startup_id for app startup notification, "0" for none,
     *           "" ( empty string ) is the default
     * @return an error code indicating success (== 0) or failure (> 0).
     */
    static int kdeinitExec(const QString &name, const QStringList &args = QStringList(),
                           QString *error = 0, int *pid = 0, const QByteArray &startup_id = QByteArray());

    /**
     * Starts a program via kdeinit and wait for it to finish.
     *
     * Like kdeinitExec(), but it waits till the program is finished.
     * As such it behaves similar to the system(...) function.
     *
     * @param name Name of the program to start
     * @param args Arguments to pass to the program
     * @param error On failure, @p error contains a description of the error
     *         that occurred. If the pointer is 0, the argument will be
     *         ignored
     * @param pid On success, the process id of the new service will be written
     *        here. If the pointer is 0, the argument will be ignored.
     * @param startup_id for app startup notification, "0" for none,
     *           "" ( empty string ) is the default
     * @return an error code indicating success (== 0) or failure (> 0).
     */
    static int kdeinitExecWait(const QString &name, const QStringList &args = QStringList(),
                               QString *error = 0, int *pid = 0, const QByteArray &startup_id = QByteArray());

    /**
     * Ensures that kdeinit5 and klauncher are running.
     */
    static void ensureKdeinitRunning();

Q_SIGNALS:
    /**
     * Hook for KApplication in kdeui
     * @internal
     */
    void kapplication_hook(QStringList &env, QByteArray &startup_id);

private:
    int startServiceInternal(const char *_function,
                             const QString &_name, const QStringList &URLs,
                             QString *error, QString *serviceName, int *pid,
                             const QByteArray &startup_id, bool noWait,
                             const QString &workdir = QString());
    static bool isMainThreadActive(QString *error = 0);

    KToolInvocationPrivate *const d;
    friend class KToolInvocationSingleton;
};

#endif