1/*
2 Copyright (c) 2007 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_CONTROL_H
21#define AKONADI_CONTROL_H
22
23#include "akonadi_export.h"
24#include <QtCore/QObject>
25
26namespace Akonadi {
27
28/**
29 * @short Provides methods to control the Akonadi server process.
30 *
31 * This class provides synchronous methods (ie. use a sub-eventloop)
32 * to control the Akonadi service. For asynchronous methods see
33 * Akonadi::ServerManager.
34 *
35 * The most important method in here is widgetNeedsAkonadi(). It is
36 * recommended to call it with every top-level widget of your application
37 * as argument, assuming your application relies on Akonadi being operational
38 * of course.
39 *
40 * While the Akonadi server automatically started by Akonadi::Session
41 * on first use, it might be necessary for some use-cases to guarantee
42 * a running Akonadi service at some point. This can be done using
43 * start().
44 *
45 * Example:
46 *
47 * @code
48 *
49 * if ( !Akonadi::Control::start() ) {
50 * qDebug() << "Unable to start Akonadi server, exit application";
51 * return 1;
52 * } else {
53 * ...
54 * }
55 *
56 * @endcode
57 *
58 * @author Volker Krause <vkrause@kde.org>
59 *
60 * @see Akonadi::ServerManager
61 */
62class AKONADI_EXPORT Control : public QObject
63{
64 Q_OBJECT
65
66public:
67 /**
68 * Destroys the control object.
69 */
70 ~Control();
71
72 /**
73 * Starts the Akonadi server synchronously if it is not already running.
74 * @return @c true if the server was started successfully or was already
75 * running, @c false otherwise
76 */
77 static bool start();
78
79 /**
80 * Same as start(), but with GUI feedback.
81 * @param parent The parent widget.
82 * @since 4.2
83 */
84 static bool start(QWidget *parent);
85
86 /**
87 * Stops the Akonadi server synchronously if it is currently running.
88 * @return @c true if the server was shutdown successfully or was
89 * not running at all, @c false otherwise.
90 * @since 4.2
91 */
92 static bool stop();
93
94 /**
95 * Same as stop(), but with GUI feedback.
96 * @param parent The parent widget.
97 * @since 4.2
98 */
99 static bool stop(QWidget *parent);
100
101 /**
102 * Restarts the Akonadi server synchronously.
103 * @return @c true if the restart was successful, @c false otherwise,
104 * the server state is undefined in this case.
105 * @since 4.2
106 */
107 static bool restart();
108
109 /**
110 * Same as restart(), but with GUI feedback.
111 * @param parent The parent widget.
112 * @since 4.2
113 */
114 static bool restart(QWidget *parent);
115
116 /**
117 * Disable the given widget when Akonadi is not operational and show
118 * an error overlay (given enough space). Cascading use is automatically
119 * detected and resolved.
120 * @param widget The widget depending on Akonadi being operational.
121 * @since 4.2
122 */
123 static void widgetNeedsAkonadi(QWidget *widget);
124
125protected:
126 /**
127 * Creates the control object.
128 */
129 Control();
130
131private:
132 //@cond PRIVATE
133 class Private;
134 Private *const d;
135
136 Q_PRIVATE_SLOT(d, void serverStateChanged(Akonadi::ServerManager::State))
137 Q_PRIVATE_SLOT(d, void createErrorOverlays())
138 Q_PRIVATE_SLOT(d, void cleanup())
139 //@endcond
140};
141
142}
143
144#endif
145