Akonadi

servermanager.h
1 /*
2  SPDX-FileCopyrightText: 2008 Volker Krause <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #pragma once
8 
9 #include "akonadicore_export.h"
10 
11 #include <QMetaType>
12 #include <QObject>
13 
14 namespace Akonadi
15 {
16 class ServerManagerPrivate;
17 
18 /**
19  * @short Provides methods to control the Akonadi server process.
20  *
21  * Asynchronous, low-level control of the Akonadi server.
22  * Akonadi::Control provides a synchronous interface to some of the methods in here.
23  *
24  * @author Volker Krause <[email protected]>
25  * @see Akonadi::Control
26  * @since 4.2
27  */
28 class AKONADICORE_EXPORT ServerManager : public QObject
29 {
30  Q_OBJECT
31 public:
32  /**
33  * Enum for the various states the server can be in.
34  * @since 4.5
35  */
36  enum State {
37  NotRunning, ///< Server is not running, could be no one started it yet or it failed to start.
38  Starting, ///< Server was started but is not yet running.
39  Running, ///< Server is running and operational.
40  Stopping, ///< Server is shutting down.
41  Broken, ///< Server is not operational and an error has been detected.
42  Upgrading ///< Server is performing a database upgrade as part of a new startup.
43  };
44 
45  /**
46  * Starts the server. This method returns immediately and does not wait
47  * until the server is actually up and running.
48  * @return @c true if the start was possible (which not necessarily means
49  * the server is really running though) and @c false if an immediate error occurred.
50  * @see Akonadi::Control::start()
51  */
52  static bool start();
53 
54  /**
55  * Stops the server. This methods returns immediately after the shutdown
56  * command has been send and does not wait until the server is actually
57  * shut down.
58  * @return @c true if the shutdown command was sent successfully, @c false
59  * otherwise
60  */
61  static bool stop();
62 
63  /**
64  * Shows the Akonadi self test dialog, which tests Akonadi for various problems
65  * and reports these to the user if.
66  * @param parent the parent widget for the dialog
67  */
68  static void showSelfTestDialog(QWidget *parent);
69 
70  /**
71  * Checks if the server is available currently. For more detailed status information
72  * see state().
73  * @see state()
74  */
75  Q_REQUIRED_RESULT static bool isRunning();
76 
77  /**
78  * Returns the state of the server.
79  * @since 4.5
80  */
81  Q_REQUIRED_RESULT static State state();
82 
83  /**
84  * Returns the reason why the Server is broken, if known.
85  *
86  * If state() is @p Broken, then you can use this method to obtain a more
87  * detailed description of the problem and present it to users. Note that
88  * the message can be empty if the reason is not known.
89  *
90  * @since 5.6
91  */
92  Q_REQUIRED_RESULT static QString brokenReason();
93 
94  /**
95  * Returns the identifier of the Akonadi instance we are connected to. This is usually
96  * an empty string (representing the default instance), unless you have explicitly set
97  * the AKONADI_INSTANCE environment variable to connect to a different one.
98  * @since 4.10
99  */
100  Q_REQUIRED_RESULT static QString instanceIdentifier();
101 
102  /**
103  * Returns @c true if we are connected to a non-default Akonadi server instance.
104  * @since 4.10
105  */
106  Q_REQUIRED_RESULT static bool hasInstanceIdentifier();
107 
108  /**
109  * Types of known D-Bus services.
110  * @since 4.10
111  */
112  enum ServiceType {
113  Server,
114  Control,
115  ControlLock,
116  UpgradeIndicator,
117  };
118 
119  /**
120  * Returns the namespaced D-Bus service name for @p serviceType.
121  * Use this rather the raw service name strings in order to support usage of a non-default
122  * instance of the Akonadi server.
123  * @param serviceType the service type for which to return the D-Bus name
124  * @since 4.10
125  */
126  static QString serviceName(ServiceType serviceType);
127 
128  /**
129  * Known agent types.
130  * @since 4.10
131  */
133  Agent,
134  Resource,
135  Preprocessor,
136  };
137 
138  /**
139  * Returns the namespaced D-Bus service name for an agent of type @p agentType with agent
140  * identifier @p identifier.
141  * @param agentType the agent type to use for D-Bus base name
142  * @param identifier the agent identifier to include in the D-Bus name
143  * @since 4.10
144  */
145  Q_REQUIRED_RESULT static QString agentServiceName(ServiceAgentType agentType, const QString &identifier);
146 
147  /**
148  * Adds the multi-instance namespace to @p string if required (with '_' as separator).
149  * Use whenever a multi-instance safe name is required (configfiles, identifiers, ...).
150  * @param string the string to adapt
151  * @since 4.10
152  */
153  Q_REQUIRED_RESULT static QString addNamespace(const QString &string);
154 
155  /**
156  * Returns the singleton instance of this class, for connecting to its
157  * signals
158  */
159  static ServerManager *self();
160 
161  enum OpenMode {
162  ReadOnly,
163  ReadWrite,
164  };
165  /**
166  * Returns absolute path to akonadiserverrc file with Akonadi server
167  * configuration.
168  */
169  Q_REQUIRED_RESULT static QString serverConfigFilePath(OpenMode openMode);
170 
171  /**
172  * Returns absolute path to configuration file of an agent identified by
173  * given @p identifier.
174  */
175  Q_REQUIRED_RESULT static QString agentConfigFilePath(const QString &identifier);
176 
177  /**
178  * Returns current Akonadi database generation identifier
179  *
180  * Generation is guaranteed to never change unless as long as the database
181  * backend is not removed and re-created. In such case it is guaranteed that
182  * the new generation number will be higher than the previous one.
183  *
184  * Generation can be used by applications to detect when Akonadi database
185  * has been recreated and thus some of the configuration (for example
186  * collection IDs stored in a config file) must be invalidated.
187  *
188  * @note Note that the generation number is only available if the server
189  * is running. If this function is called before the server starts it will
190  * return 0.
191  *
192  * @since 5.4
193  */
194  Q_REQUIRED_RESULT static uint generation();
195 
196 Q_SIGNALS:
197  /**
198  * Emitted whenever the server becomes fully operational.
199  */
200  void started();
201 
202  /**
203  * Emitted whenever the server becomes unavailable.
204  */
205  void stopped();
206 
207  /**
208  * Emitted whenever the server state changes.
209  * @param state the new server state
210  * @since 4.5
211  */
212  void stateChanged(Akonadi::ServerManager::State state);
213 
214 private:
215  /// @cond PRIVATE
216  friend class ServerManagerPrivate;
217  ServerManager(ServerManagerPrivate *dd);
218  ServerManagerPrivate *const d;
219  /// @endcond
220 };
221 
222 }
223 
224 Q_DECLARE_METATYPE(Akonadi::ServerManager::State)
225 
@ Broken
Server is not operational and an error has been detected.
Definition: servermanager.h:41
void stop(Ekos::AlignState mode)
@ Starting
Server was started but is not yet running.
Definition: servermanager.h:38
Q_SCRIPTABLE Q_NOREPLY void start()
@ Running
Server is running and operational.
Definition: servermanager.h:39
ServiceType
Types of known D-Bus services.
@ NotRunning
Server is not running, could be no one started it yet or it failed to start.
Definition: servermanager.h:37
ServiceAgentType
Known agent types.
Provides methods to control the Akonadi server process.
Definition: control.h:53
State
Enum for the various states the server can be in.
Definition: servermanager.h:36
Provides methods to control the Akonadi server process.
Definition: servermanager.h:28
@ Stopping
Server is shutting down.
Definition: servermanager.h:40
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Mon Jun 27 2022 04:01:07 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.