1/* This file is part of the KDE libraries
2 Copyright (C) 2003 David Faure <faure@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License version 2 as published by the Free Software Foundation.
7
8 This library is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 Library General Public License for more details.
12
13 You should have received a copy of the GNU Library General Public License
14 along with this library; see the file COPYING.LIB. If not, write to
15 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16 Boston, MA 02110-1301, USA.
17*/
18
19#ifndef KDBUSSERVICESTARTER_H
20#define KDBUSSERVICESTARTER_H
21
22#include <kio/kio_export.h>
23
24#include <QtCore/QString>
25
26class KDBusServiceStarterPrivate;
27
28/**
29 * A generic DBUS service starter, using KServiceTypeTrader.
30 * The default implementation starts new processes, but this interface can
31 * also be reimplemented by specific applications to provide dlopened in-process DBus objects.
32 * This interface is similar to the startServiceByName() function found in QDBusBusService, but
33 * with the added benefit of using KTrader (and, therefore, additional constraints and the
34 * ability to search the standard KDE dirs).
35 * @author David Faure <faure@kde.org>
36 */
37class KIO_EXPORT KDBusServiceStarter { //krazy:exclude=dpointer (uses K_GLOBAL_STATIC)
38public:
39
40 static KDBusServiceStarter* self();
41
42 /**
43 * Check if a given DBus service is available - from the serviceType it's supposed to implement.
44 *
45 * The trader is queried to find the preferred application for this serviceType,
46 * with the constraint that its X-DBus-ServiceName property must be defined.
47 * Then the DBus server is checked. If the service is not available,
48 * this method will call startServiceFor to start it.
49 *
50 * @param serviceType the type of service we're looking for
51 * @param constraint see KServiceTypeTrader
52 * @param error On failure, @p error contains a description of the error
53 * that occurred. If the pointer is 0, the argument will be
54 * ignored
55 * @param dbusService On success, @p dbusService contains the DBus service name
56 * under which this service is available. If the pointer is 0 the argument
57 * will be ignored
58 * @param flags for future extensions (currently unused)
59 *
60 * @return an error code indicating success (== 0) or failure (< 0).
61 */
62 int findServiceFor( const QString& serviceType,
63 const QString& constraint = QString(),
64 QString *error=0, QString* dbusService=0,
65 int flags=0 );
66
67 /**
68 * Find an implementation of the given @p serviceType,
69 * and start it, to use its DBus interface.
70 * The default implementation uses KServiceTypeTrader to find the preferred Application,
71 * and then starts it using KToolInvocation::startService...
72 *
73 * However applications (like kontact) can reimplement this method, to provide
74 * an in-process way of loading the implementation for this service type.
75 *
76 * @param serviceType the type of service we're looking for
77 * @param constraint see KServiceTypeTrader
78 * @param error On failure, @p error contains a description of the error
79 * that occurred. If the pointer is 0, the argument will be
80 * ignored
81 * @param dbusService On success, @p dbusService contains the DBus service name
82 * under which this service is available. If the pointer is 0 the argument
83 * will be ignored
84 * @param flags for future extensions (currently unused)
85 *
86 * @return an error code indicating success (== 0) or failure (> 0).
87 */
88 virtual int startServiceFor( const QString& serviceType,
89 const QString& constraint = QString(),
90 QString *error=0, QString* dbusService=0,
91 int flags=0 );
92protected:
93 friend class KDBusServiceStarterPrivate;
94 KDBusServiceStarter();
95 virtual ~KDBusServiceStarter();
96};
97
98#endif
99
100