Akonadi

core/agentinstance.h
1/*
2 SPDX-FileCopyrightText: 2008 Tobias Koenig <tokoe@kde.org>
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 <QSharedDataPointer>
13
14class QString;
15class QWidget;
16
17namespace Akonadi
18{
19class AgentType;
20class AgentInstancePrivate;
21
22/**
23 * @short A representation of an agent instance.
24 *
25 * The agent instance is a representation of a running agent process.
26 * It provides information about the instance and a reference to the
27 * AgentType of that instance.
28 *
29 * All available agent instances can be retrieved from the AgentManager.
30 *
31 * @code
32 *
33 * Akonadi::AgentInstance::List instances = Akonadi::AgentManager::self()->instances();
34 * for( const Akonadi::AgentInstance &instance : instances ) {
35 * qDebug() << "Name:" << instance.name() << "(" << instance.identifier() << ")";
36 * }
37 *
38 * @endcode
39 *
40 * @note To find the collections belonging to an AgentInstance, use
41 * CollectionFetchJob and supply AgentInstance::identifier() as the parameter
42 * to CollectionFetchScope::setResource().
43 *
44 * @author Tobias Koenig <tokoe@kde.org>
45 */
46class AKONADICORE_EXPORT AgentInstance
47{
48 friend class AgentManager;
49 friend class AgentManagerPrivate;
50
51public:
52 /**
53 * Describes a list of agent instances.
54 */
56
57 /**
58 * Describes the status of the agent instance.
59 */
60 enum Status {
61 Idle = 0, ///< The agent instance does currently nothing.
62 Running, ///< The agent instance is working on something.
63 Broken, ///< The agent instance encountered an error state.
64 NotConfigured ///< The agent is lacking required configuration
65 };
66
67 /**
68 * Creates a new agent instance object.
69 */
71
72 /**
73 * Creates an agent instance from an @p other agent instance.
74 */
75 AgentInstance(const AgentInstance &other);
76
77 /**
78 * Destroys the agent instance object.
79 */
81
82 /**
83 * Returns whether the agent instance object is valid.
84 */
85 [[nodiscard]] bool isValid() const;
86
87 /**
88 * Returns the agent type of this instance.
89 */
90 [[nodiscard]] AgentType type() const;
91
92 /**
93 * Returns the unique identifier of the agent instance.
94 */
95 [[nodiscard]] QString identifier() const;
96
97 /**
98 * Returns the user visible name of the agent instance.
99 */
100 [[nodiscard]] QString name() const;
101
102 /**
103 * Sets the user visible @p name of the agent instance.
104 */
105 void setName(const QString &name);
106
107 /**
108 * Returns the status of the agent instance.
109 */
110 [[nodiscard]] Status status() const;
111
112 /**
113 * Returns a textual presentation of the status of the agent instance.
114 */
115 [[nodiscard]] QString statusMessage() const;
116
117 /**
118 * Returns the progress of the agent instance in percent, or -1 if no
119 * progress information are available.
120 */
121 [[nodiscard]] int progress() const;
122
123 /**
124 * Returns whether the agent instance is online currently.
125 */
126 [[nodiscard]] bool isOnline() const;
127
128 /**
129 * Sets @p online status of the agent instance.
130 */
131 void setIsOnline(bool online);
132
133 /**
134 * Triggers the agent instance to show its configuration dialog.
135 *
136 * @deprecated Use the new Akonadi::AgentConfigurationWidget and
137 * Akonadi::AgentConfigurationDialog to display configuration dialogs
138 * in-process
139 *
140 * @param parent Parent window for the configuration dialog.
141 */
142 AKONADICORE_DEPRECATED void configure(QWidget *parent = nullptr);
143
144 /**
145 * Triggers the agent instance to start synchronization.
146 */
147 void synchronize();
148
149 /**
150 * Triggers a synchronization of the collection tree by the given agent instance.
151 */
152 void synchronizeCollectionTree();
153
154 /**
155 * Triggers a synchronization of tags by the given agent instance.
156 */
157 void synchronizeTags();
158
159 /**
160 * @internal
161 * @param other other agent instance
162 */
163 AgentInstance &operator=(const AgentInstance &other);
164
165 /**
166 * @internal
167 * @param other other agent instance
168 */
169 [[nodiscard]] bool operator==(const AgentInstance &other) const;
170
171 /**
172 * Tell the agent to abort its current operation.
173 * @since 4.4
174 */
175 void abortCurrentTask() const;
176
177 /**
178 * Tell the agent that its configuration has been changed remotely via D-Bus
179 */
180 void reconfigure() const;
181
182 /**
183 * Restart the agent process.
184 */
185 void restart() const;
186
187 /**
188 * Returns a list of activities of the agent instance.
189 */
190 [[nodiscard]] QStringList activities() const;
191
192 /**
193 * Sets list of activities of the agent instance
194 */
195 void setActivities(const QStringList &online);
196
197 /**
198 * Returns true if agent instance has activities support enabled.
199 */
200 [[nodiscard]] bool activitiesEnabled() const;
201
202 /**
203 * Sets activities support enabled
204 */
205 void setActivitiesEnabled(bool enabled);
206
207private:
208 /// @cond PRIVATE
210 /// @endcond
211};
212
213}
214
215Q_DECLARE_TYPEINFO(Akonadi::AgentInstance, Q_RELOCATABLE_TYPE);
216
217Q_DECLARE_METATYPE(Akonadi::AgentInstance)
A representation of an agent instance.
Status status() const
Returns the status of the agent instance.
QString identifier() const
Returns the unique identifier of the agent instance.
~AgentInstance()
Destroys the agent instance object.
Status
Describes the status of the agent instance.
@ Running
The agent instance is working on something.
@ Broken
The agent instance encountered an error state.
QString statusMessage() const
Returns a textual presentation of the status of the agent instance.
bool isOnline() const
Returns whether the agent instance is online currently.
int progress() const
Returns the progress of the agent instance in percent, or -1 if no progress information are available...
Provides an interface to retrieve agent types and manage agent instances.
A representation of an agent type.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Mon Nov 4 2024 16:31:58 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.