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 | |
26 | namespace 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 | */ |
62 | class AKONADI_EXPORT Control : public QObject |
63 | { |
64 | Q_OBJECT |
65 | |
66 | public: |
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 | |
125 | protected: |
126 | /** |
127 | * Creates the control object. |
128 | */ |
129 | Control(); |
130 | |
131 | private: |
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 | |