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 * Triggers a synchronization of relations by the given agent instance.
161 */
162 void synchronizeRelations();
163
164 /**
165 * @internal
166 * @param other other agent instance
167 */
168 AgentInstance &operator=(const AgentInstance &other);
169
170 /**
171 * @internal
172 * @param other other agent instance
173 */
174 [[nodiscard]] bool operator==(const AgentInstance &other) const;
175
176 /**
177 * Tell the agent to abort its current operation.
178 * @since 4.4
179 */
180 void abortCurrentTask() const;
181
182 /**
183 * Tell the agent that its configuration has been changed remotely via D-Bus
184 */
185 void reconfigure() const;
186
187 /**
188 * Restart the agent process.
189 */
190 void restart() const;
191
192private:
193 /// @cond PRIVATE
195 /// @endcond
196};
197
198}
199
200Q_DECLARE_TYPEINFO(Akonadi::AgentInstance, Q_RELOCATABLE_TYPE);
201
202Q_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 Sun Feb 25 2024 18:38:51 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.