Akonadi

core/agentmanager.h
1/*
2 SPDX-FileCopyrightText: 2006-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 "agentinstance.h"
12#include "agenttype.h"
13
14#include <QObject>
15
16#include <memory>
17
18namespace Akonadi
19{
20class AgentManagerPrivate;
21class Collection;
22
23/**
24 * @short Provides an interface to retrieve agent types and manage agent instances.
25 *
26 * This singleton class can be used to create or remove agent instances or trigger
27 * synchronization of collections. Furthermore it provides information about status
28 * changes of the agents.
29 *
30 * @code
31 *
32 * Akonadi::AgentManager *manager = Akonadi::AgentManager::self();
33 *
34 * Akonadi::AgentType::List types = manager->types();
35 * for ( const Akonadi::AgentType& type : types ) {
36 * qDebug() << "Type:" << type.name() << type.description();
37 * }
38 *
39 * @endcode
40 *
41 * @author Tobias Koenig <tokoe@kde.org>
42 */
43class AKONADICORE_EXPORT AgentManager : public QObject
44{
45 friend class AgentInstance;
46 friend class AgentInstanceCreateJobPrivate;
47 friend class AgentManagerPrivate;
48
49 Q_OBJECT
50
51public:
52 /**
53 * Returns the global instance of the agent manager.
54 */
55 static AgentManager *self();
56
57 /**
58 * Destroys the agent manager.
59 */
60 ~AgentManager() override;
61
62 /**
63 * Returns the list of all available agent types.
64 */
65 [[nodiscard]] AgentType::List types() const;
66
67 /**
68 * Returns the agent type with the given @p identifier or
69 * an invalid agent type if the identifier does not exist.
70 */
71 [[nodiscard]] AgentType type(const QString &identifier) const;
72
73 /**
74 * Returns the list of all available agent instances.
75 */
76 [[nodiscard]] AgentInstance::List instances() const;
77
78 /**
79 * Returns the agent instance with the given @p identifier or
80 * an invalid agent instance if the identifier does not exist.
81 *
82 * Note that because a resource is a special case of an agent, the
83 * identifier of a resource is the same as that of its agent instance.
84 * @param identifier identifier to choose the agent instance
85 */
86 [[nodiscard]] AgentInstance instance(const QString &identifier) const;
87
88 /**
89 * Removes the given agent @p instance.
90 */
91 void removeInstance(const AgentInstance &instance);
92
93 /**
94 * Trigger a synchronization of the given collection by its owning resource agent.
95 *
96 * @param collection The collection to synchronize.
97 */
98 void synchronizeCollection(const Collection &collection);
99
100 /**
101 * Trigger a synchronization of the given collection by its owning resource agent.
102 *
103 * @param collection The collection to synchronize.
104 * @param recursive If true, the sub-collections are also synchronized
105 *
106 * @since 4.6
107 */
108 void synchronizeCollection(const Collection &collection, bool recursive);
109
110Q_SIGNALS:
111 /**
112 * This signal is emitted whenever a new agent type was installed on the system.
113 *
114 * @param type The new agent type.
115 */
116 void typeAdded(const Akonadi::AgentType &type);
117
118 /**
119 * This signal is emitted whenever an agent type was removed from the system.
120 *
121 * @param type The removed agent type.
122 */
124
125 /**
126 * This signal is emitted whenever a new agent instance was created.
127 *
128 * @param instance The new agent instance.
129 */
131
132 /**
133 * This signal is emitted whenever an agent instance was removed.
134 *
135 * @param instance The removed agent instance.
136 */
138
139 /**
140 * This signal is emitted whenever the status of an agent instance has
141 * changed.
142 *
143 * @param instance The agent instance that status has changed.
144 */
146
147 /**
148 * This signal is emitted whenever the progress of an agent instance has
149 * changed.
150 *
151 * @param instance The agent instance that progress has changed.
152 */
154
155 /**
156 * This signal is emitted whenever the name of the agent instance has changed.
157 *
158 * @param instance The agent instance that name has changed.
159 */
161
162 /**
163 * This signal is emitted whenever the agent instance raised an error.
164 *
165 * @param instance The agent instance that raised the error.
166 * @param message The i18n'ed error message.
167 */
168 void instanceError(const Akonadi::AgentInstance &instance, const QString &message);
169
170 /**
171 * This signal is emitted whenever the agent instance raised a warning.
172 *
173 * @param instance The agent instance that raised the warning.
174 * @param message The i18n'ed warning message.
175 */
176 void instanceWarning(const Akonadi::AgentInstance &instance, const QString &message);
177
178 /**
179 * This signal is emitted whenever the online state of an agent changed.
180 *
181 * @param instance The agent instance that changed its online state.
182 * @param online The new online state.
183 * @since 4.2
184 */
185 void instanceOnline(const Akonadi::AgentInstance &instance, bool online);
186
187private:
188 /// @cond PRIVATE
189 explicit AgentManager();
190
191 std::unique_ptr<AgentManagerPrivate> const d;
192 /// @endcond
193};
194
195}
A representation of an agent instance.
Provides an interface to retrieve agent types and manage agent instances.
void instanceProgressChanged(const Akonadi::AgentInstance &instance)
This signal is emitted whenever the progress of an agent instance has changed.
void typeAdded(const Akonadi::AgentType &type)
This signal is emitted whenever a new agent type was installed on the system.
void instanceRemoved(const Akonadi::AgentInstance &instance)
This signal is emitted whenever an agent instance was removed.
void instanceNameChanged(const Akonadi::AgentInstance &instance)
This signal is emitted whenever the name of the agent instance has changed.
void typeRemoved(const Akonadi::AgentType &type)
This signal is emitted whenever an agent type was removed from the system.
void instanceAdded(const Akonadi::AgentInstance &instance)
This signal is emitted whenever a new agent instance was created.
void instanceOnline(const Akonadi::AgentInstance &instance, bool online)
This signal is emitted whenever the online state of an agent changed.
void instanceWarning(const Akonadi::AgentInstance &instance, const QString &message)
This signal is emitted whenever the agent instance raised a warning.
void instanceStatusChanged(const Akonadi::AgentInstance &instance)
This signal is emitted whenever the status of an agent instance has changed.
void instanceError(const Akonadi::AgentInstance &instance, const QString &message)
This signal is emitted whenever the agent instance raised an error.
~AgentManager() override
Destroys the agent manager.
A representation of an agent type.
Represents a collection of PIM items.
Definition collection.h:62
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:01:42 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.