1/*
2 Copyright (c) 2008 Volker Krause <vkrause@kde.org>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef AKONADI_SERVERMANAGER_H
21#define AKONADI_SERVERMANAGER_H
22
23#include "akonadi_export.h"
24
25#include <QtCore/QObject>
26#include <QtCore/QMetaType>
27
28namespace Akonadi {
29
30class ServerManagerPrivate;
31
32/**
33 * @short Provides methods to control the Akonadi server process.
34 *
35 * Asynchronous, low-level control of the Akonadi server.
36 * Akonadi::Control provides a synchronous interface to some of the methods in here.
37 *
38 * @author Volker Krause <vkrause@kde.org>
39 * @see Akonadi::Control
40 * @since 4.2
41 */
42class AKONADI_EXPORT ServerManager : public QObject
43{
44 Q_OBJECT
45public:
46 /**
47 * Enum for the various states the server can be in.
48 * @since 4.5
49 */
50 enum State {
51 NotRunning, ///< Server is not running, could be no one started it yet or it failed to start.
52 Starting, ///< Server was started but is not yet running.
53 Running, ///< Server is running and operational.
54 Stopping, ///< Server is shutting down.
55 Broken, ///< Server is not operational and an error has been detected.
56 Upgrading ///< Server is performing a database upgrade as part of a new startup.
57 };
58
59 /**
60 * Starts the server. This method returns imediately and does not wait
61 * until the server is actually up and running.
62 * @return @c true if the start was possible (which not necessarily means
63 * the server is really running though) and @c false if an immediate error occurred.
64 * @see Akonadi::Control::start()
65 */
66 static bool start();
67
68 /**
69 * Stops the server. This methods returns immediately after the shutdown
70 * command has been send and does not wait until the server is actually
71 * shut down.
72 * @return @c true if the shutdown command was sent successfully, @c false
73 * otherwise
74 */
75 static bool stop();
76
77 /**
78 * Shows the Akonadi self test dialog, which tests Akonadi for various problems
79 * and reports these to the user if.
80 * @param parent the parent widget for the dialog
81 */
82 static void showSelfTestDialog(QWidget *parent);
83
84 /**
85 * Checks if the server is available currently. For more detailed status information
86 * see state().
87 * @see state()
88 */
89 static bool isRunning();
90
91 /**
92 * Returns the state of the server.
93 * @since 4.5
94 */
95 static State state();
96
97 /**
98 * Returns the identifier of the Akonadi instance we are connected to. This is usually
99 * an empty string (representing the default instance), unless you have explicitly set
100 * the AKONADI_INSTANCE environment variable to connect to a different one.
101 * @since 4.10
102 */
103 static QString instanceIdentifier();
104
105 /**
106 * Returns @c true if we are connected to a non-default Akonadi server instance.
107 * @since 4.10
108 */
109 static bool hasInstanceIdentifier();
110
111 /**
112 * Types of known D-Bus services.
113 * @since 4.10
114 */
115 enum ServiceType {
116 Server,
117 Control,
118 ControlLock,
119 UpgradeIndicator
120 };
121
122 /**
123 * Returns the namespaced D-Bus service name for @p serviceType.
124 * Use this rather the raw service name strings in order to support usage of a non-default
125 * instance of the Akonadi server.
126 * @param serviceType the service type for which to return the D-Bus name
127 * @since 4.10
128 */
129 static QString serviceName(ServiceType serviceType);
130
131 /**
132 * Known agent types.
133 * @since 4.10
134 */
135 enum ServiceAgentType {
136 Agent,
137 Resource,
138 Preprocessor
139 };
140
141 /**
142 * Returns the namespaced D-Bus service name for an agent of type @p agentType with agent
143 * identifier @p identifier.
144 * @param agentType the agent type to use for D-Bus base name
145 * @param identifier the agent identifier to include in the D-Bus name
146 * @since 4.10
147 */
148 static QString agentServiceName(ServiceAgentType agentType, const QString &identifier);
149
150 /**
151 * Adds the multi-instance namespace to @p string if required (with '_' as separator).
152 * Use whenever a multi-instance safe name is required (configfiles, identifiers, ...).
153 * @param string the string to adapt
154 * @since 4.10
155 */
156 static QString addNamespace(const QString &string);
157
158 /**
159 * Returns the singleton instance of this class, for connecting to its
160 * signals
161 */
162 static ServerManager *self();
163
164Q_SIGNALS:
165 /**
166 * Emitted whenever the server becomes fully operational.
167 */
168 void started();
169
170 /**
171 * Emitted whenever the server becomes unavailable.
172 */
173 void stopped();
174
175 /**
176 * Emitted whenever the server state changes.
177 * @param state the new server state
178 * @since 4.5
179 */
180 void stateChanged(Akonadi::ServerManager::State state);
181
182private:
183 //@cond PRIVATE
184 friend class ServerManagerPrivate;
185 ServerManager(ServerManagerPrivate *dd);
186 ServerManagerPrivate *const d;
187 Q_PRIVATE_SLOT(d, void serviceOwnerChanged(const QString &, const QString &, const QString &))
188 Q_PRIVATE_SLOT(d, void checkStatusChanged())
189 Q_PRIVATE_SLOT(d, void timeout())
190 //@endcond
191};
192
193}
194
195Q_DECLARE_METATYPE(Akonadi::ServerManager::State)
196
197#endif
198