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 | |
28 | namespace Akonadi { |
29 | |
30 | class 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 | */ |
42 | class AKONADI_EXPORT ServerManager : public QObject |
43 | { |
44 | Q_OBJECT |
45 | public: |
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 | |
164 | Q_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 | |
182 | private: |
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 | |
195 | Q_DECLARE_METATYPE(Akonadi::ServerManager::State) |
196 | |
197 | #endif |
198 | |