1/*
2 Copyright (c) 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_AGENTINSTANCE_H
21#define AKONADI_AGENTINSTANCE_H
22
23#include "akonadi_export.h"
24
25#include <QtCore/QList>
26#include <QtCore/QMetaType>
27#include <QtCore/QSharedDataPointer>
28
29class QString;
30class QStringList;
31class QWidget;
32
33namespace Akonadi
34{
35
36class AgentType;
37
38/**
39 * @short A representation of an agent instance.
40 *
41 * The agent instance is a representation of a running agent process.
42 * It provides information about the instance and a reference to the
43 * AgentType of that instance.
44 *
45 * All available agent instances can be retrieved from the AgentManager.
46 *
47 * @code
48 *
49 * Akonadi::AgentInstance::List instances = Akonadi::AgentManager::self()->instances();
50 * foreach ( const Akonadi::AgentInstance &instance, instances ) {
51 * qDebug() << "Name:" << instance.name() << "(" << instance.identifier() << ")";
52 * }
53 *
54 * @endcode
55 *
56 * @note To find the collections belonging to an AgentInstance, use
57 * CollectionFetchJob and supply AgentInstance::identifier() as the parameter
58 * to CollectionFetchScope::setResource().
59 *
60 * @author Tobias Koenig <tokoe@kde.org>
61 */
62class AKONADI_EXPORT AgentInstance
63{
64 friend class AgentManager;
65 friend class AgentManagerPrivate;
66
67public:
68 /**
69 * Describes a list of agent instances.
70 */
71 typedef QList<AgentInstance> List;
72
73 /**
74 * Describes the status of the agent instance.
75 */
76 enum Status {
77 Idle = 0, ///< The agent instance does currently nothing.
78 Running, ///< The agent instance is working on something.
79 Broken, ///< The agent instance encountered an error state.
80 NotConfigured ///< The agent is lacking required configuration
81 };
82
83 /**
84 * Creates a new agent instance object.
85 */
86 AgentInstance();
87
88 /**
89 * Creates an agent instance from an @p other agent instance.
90 */
91 AgentInstance(const AgentInstance &other);
92
93 /**
94 * Destroys the agent instance object.
95 */
96 ~AgentInstance();
97
98 /**
99 * Returns whether the agent instance object is valid.
100 */
101 bool isValid() const;
102
103 /**
104 * Returns the agent type of this instance.
105 */
106 AgentType type() const;
107
108 /**
109 * Returns the unique identifier of the agent instance.
110 */
111 QString identifier() const;
112
113 /**
114 * Returns the user visible name of the agent instance.
115 */
116 QString name() const;
117
118 /**
119 * Sets the user visible @p name of the agent instance.
120 */
121 void setName(const QString &name);
122
123 /**
124 * Returns the status of the agent instance.
125 */
126 Status status() const;
127
128 /**
129 * Returns a textual presentation of the status of the agent instance.
130 */
131 QString statusMessage() const;
132
133 /**
134 * Returns the progress of the agent instance in percent, or -1 if no
135 * progress information are available.
136 */
137 int progress() const;
138
139 /**
140 * Returns whether the agent instance is online currently.
141 */
142 bool isOnline() const;
143
144 /**
145 * Sets @p online status of the agent instance.
146 */
147 void setIsOnline(bool online);
148
149 /**
150 * Triggers the agent instance to show its configuration dialog.
151 *
152 * @param parent Parent window for the configuration dialog.
153 */
154 void configure(QWidget *parent = 0);
155
156 /**
157 * Triggers the agent instance to start synchronization.
158 */
159 void synchronize();
160
161 /**
162 * Triggers a synchronization of the collection tree by the given agent instance.
163 */
164 void synchronizeCollectionTree();
165
166 /**
167 * @internal
168 * @param other other agent instance
169 */
170 AgentInstance &operator=(const AgentInstance &other);
171
172 /**
173 * @internal
174 * @param other other agent instance
175 */
176 bool operator==(const AgentInstance &other) const;
177
178 /**
179 * Tell the agent to abort its current operation.
180 * @since 4.4
181 */
182 void abortCurrentTask() const;
183
184 /**
185 * Tell the agent that its configuration has been changed remotely via D-Bus
186 */
187 void reconfigure() const;
188
189 /**
190 * Restart the agent process.
191 */
192 void restart() const;
193
194private:
195 //@cond PRIVATE
196 class Private;
197 QSharedDataPointer<Private> d;
198 //@endcond
199};
200
201}
202
203Q_DECLARE_TYPEINFO(Akonadi::AgentInstance, Q_MOVABLE_TYPE);
204
205Q_DECLARE_METATYPE(Akonadi::AgentInstance)
206
207#endif
208