1/*
2 Copyright (c) 2006-2008 Tobias Koenig <tokoe@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_AGENTMANAGER_H
21#define AKONADI_AGENTMANAGER_H
22
23#include "akonadi_export.h"
24
25#include <akonadi/agenttype.h>
26#include <akonadi/agentinstance.h>
27
28#include <QtCore/QObject>
29
30namespace Akonadi {
31
32class AgentManagerPrivate;
33class Collection;
34
35/**
36 * @short Provides an interface to retrieve agent types and manage agent instances.
37 *
38 * This singleton class can be used to create or remove agent instances or trigger
39 * synchronization of collections. Furthermore it provides information about status
40 * changes of the agents.
41 *
42 * @code
43 *
44 * Akonadi::AgentManager *manager = Akonadi::AgentManager::self();
45 *
46 * Akonadi::AgentType::List types = manager->types();
47 * foreach ( const Akonadi::AgentType& type, types ) {
48 * qDebug() << "Type:" << type.name() << type.description();
49 * }
50 *
51 * @endcode
52 *
53 * @author Tobias Koenig <tokoe@kde.org>
54 */
55class AKONADI_EXPORT AgentManager : public QObject
56{
57 friend class AgentInstance;
58 friend class AgentInstanceCreateJobPrivate;
59 friend class AgentManagerPrivate;
60
61 Q_OBJECT
62
63public:
64 /**
65 * Returns the global instance of the agent manager.
66 */
67 static AgentManager *self();
68
69 /**
70 * Destroys the agent manager.
71 */
72 ~AgentManager();
73
74 /**
75 * Returns the list of all available agent types.
76 */
77 AgentType::List types() const;
78
79 /**
80 * Returns the agent type with the given @p identifier or
81 * an invalid agent type if the identifier does not exist.
82 */
83 AgentType type(const QString &identifier) const;
84
85 /**
86 * Returns the list of all available agent instances.
87 */
88 AgentInstance::List instances() const;
89
90 /**
91 * Returns the agent instance with the given @p identifier or
92 * an invalid agent instance if the identifier does not exist.
93 *
94 * Note that because a resource is a special case of an agent, the
95 * identifier of a resource is the same as that of its agent instance.
96 * @param identifier identifier to choose the agent instance
97 */
98 AgentInstance instance(const QString &identifier) const;
99
100 /**
101 * Removes the given agent @p instance.
102 */
103 void removeInstance(const AgentInstance &instance);
104
105 /**
106 * Trigger a synchronization of the given collection by its owning resource agent.
107 *
108 * @param collection The collection to synchronize.
109 */
110 void synchronizeCollection(const Collection &collection);
111
112 /**
113 * Trigger a synchronization of the given collection by its owning resource agent.
114 *
115 * @param collection The collection to synchronize.
116 * @param recursive If true, the sub-collections are also synchronized
117 *
118 * @since 4.6
119 */
120 void synchronizeCollection(const Collection &collection, bool recursive);
121
122Q_SIGNALS:
123 /**
124 * This signal is emitted whenever a new agent type was installed on the system.
125 *
126 * @param type The new agent type.
127 */
128 void typeAdded(const Akonadi::AgentType &type);
129
130 /**
131 * This signal is emitted whenever an agent type was removed from the system.
132 *
133 * @param type The removed agent type.
134 */
135 void typeRemoved(const Akonadi::AgentType &type);
136
137 /**
138 * This signal is emitted whenever a new agent instance was created.
139 *
140 * @param instance The new agent instance.
141 */
142 void instanceAdded(const Akonadi::AgentInstance &instance);
143
144 /**
145 * This signal is emitted whenever an agent instance was removed.
146 *
147 * @param instance The removed agent instance.
148 */
149 void instanceRemoved(const Akonadi::AgentInstance &instance);
150
151 /**
152 * This signal is emitted whenever the status of an agent instance has
153 * changed.
154 *
155 * @param instance The agent instance that status has changed.
156 */
157 void instanceStatusChanged(const Akonadi::AgentInstance &instance);
158
159 /**
160 * This signal is emitted whenever the progress of an agent instance has
161 * changed.
162 *
163 * @param instance The agent instance that progress has changed.
164 */
165 void instanceProgressChanged(const Akonadi::AgentInstance &instance);
166
167 /**
168 * This signal is emitted whenever the name of the agent instance has changed.
169 *
170 * @param instance The agent instance that name has changed.
171 */
172 void instanceNameChanged(const Akonadi::AgentInstance &instance);
173
174 /**
175 * This signal is emitted whenever the agent instance raised an error.
176 *
177 * @param instance The agent instance that raised the error.
178 * @param message The i18n'ed error message.
179 */
180 void instanceError(const Akonadi::AgentInstance &instance, const QString &message);
181
182 /**
183 * This signal is emitted whenever the agent instance raised a warning.
184 *
185 * @param instance The agent instance that raised the warning.
186 * @param message The i18n'ed warning message.
187 */
188 void instanceWarning(const Akonadi::AgentInstance &instance, const QString &message);
189
190 /**
191 * This signal is emitted whenever the online state of an agent changed.
192 *
193 * @param instance The agent instance that changed its online state.
194 * @param online The new online state.
195 * @since 4.2
196 */
197 void instanceOnline(const Akonadi::AgentInstance &instance, bool online);
198
199private:
200 //@cond PRIVATE
201 AgentManager();
202
203 AgentManagerPrivate *const d;
204
205 Q_PRIVATE_SLOT(d, void agentTypeAdded(const QString &))
206 Q_PRIVATE_SLOT(d, void agentTypeRemoved(const QString &))
207 Q_PRIVATE_SLOT(d, void agentInstanceAdded(const QString &))
208 Q_PRIVATE_SLOT(d, void agentInstanceRemoved(const QString &))
209 Q_PRIVATE_SLOT(d, void agentInstanceStatusChanged(const QString &, int, const QString &))
210 Q_PRIVATE_SLOT(d, void agentInstanceProgressChanged(const QString &, uint, const QString &))
211 Q_PRIVATE_SLOT(d, void agentInstanceNameChanged(const QString &, const QString &))
212 Q_PRIVATE_SLOT(d, void agentInstanceWarning(const QString &, const QString &))
213 Q_PRIVATE_SLOT(d, void agentInstanceError(const QString &, const QString &))
214 Q_PRIVATE_SLOT(d, void agentInstanceOnlineChanged(const QString &, bool))
215 Q_PRIVATE_SLOT(d, void serviceOwnerChanged(const QString &, const QString &, const QString &))
216 //@endcond
217};
218
219}
220
221#endif
222