Akonadi

core/agentmanager.h
1 /*
2  SPDX-FileCopyrightText: 2006-2008 Tobias Koenig <[email protected]>
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 
18 namespace Akonadi
19 {
20 class AgentManagerPrivate;
21 class 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 <[email protected]>
42  */
43 class AKONADICORE_EXPORT AgentManager : public QObject
44 {
45  friend class AgentInstance;
46  friend class AgentInstanceCreateJobPrivate;
47  friend class AgentManagerPrivate;
48 
49  Q_OBJECT
50 
51 public:
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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT AgentType type(const QString &identifier) const;
72 
73  /**
74  * Returns the list of all available agent instances.
75  */
76  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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 
110 Q_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  */
123  void typeRemoved(const Akonadi::AgentType &type);
124 
125  /**
126  * This signal is emitted whenever a new agent instance was created.
127  *
128  * @param instance The new agent instance.
129  */
130  void instanceAdded(const Akonadi::AgentInstance &instance);
131 
132  /**
133  * This signal is emitted whenever an agent instance was removed.
134  *
135  * @param instance The removed agent instance.
136  */
137  void instanceRemoved(const Akonadi::AgentInstance &instance);
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  */
145  void instanceStatusChanged(const Akonadi::AgentInstance &instance);
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  */
153  void instanceProgressChanged(const Akonadi::AgentInstance &instance);
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  */
160  void instanceNameChanged(const Akonadi::AgentInstance &instance);
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 
187 private:
188  /// @cond PRIVATE
189  explicit AgentManager();
190 
191  std::unique_ptr<AgentManagerPrivate> const d;
192  /// @endcond
193 };
194 
195 }
A representation of an agent type.
Represents a collection of PIM items.
Definition: collection.h:61
Provides an interface to retrieve agent types and manage agent instances.
A representation of an agent instance.
QString message
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Jun 7 2023 03:53:30 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.