Akonadi

akonadicontrol/agentmanager.h
1 /***************************************************************************
2  * SPDX-FileCopyrightText: 2006 Tobias Koenig <[email protected]> *
3  * SPDX-FileCopyrightText: 2007 Volker Krause <[email protected]> *
4  * *
5  * SPDX-License-Identifier: LGPL-2.0-or-later *
6  ***************************************************************************/
7 
8 #pragma once
9 
10 #include <QHash>
11 #include <QStringList>
12 
13 #include "agentinstance.h"
14 #include "agenttype.h"
15 
16 class QDir;
17 
18 namespace Akonadi
19 {
20 class ProcessControl;
21 }
22 
23 /**
24  * The agent manager has knowledge about all available agents (it scans
25  * for .desktop files in the agent directory) and the available configured
26  * instances.
27  */
28 class AgentManager : public QObject, protected QDBusContext
29 {
30  Q_OBJECT
31  Q_CLASSINFO("D-Bus Interface", "org.freedesktop.Akonadi.AgentManager")
32 
33 public:
34  /**
35  * Creates a new agent manager.
36  *
37  * @param parent The parent object.
38  */
39  explicit AgentManager(bool verbose, QObject *parent = nullptr);
40 
41  /**
42  * Destroys the agent manager.
43  */
44  ~AgentManager() override;
45 
46  /**
47  * Called by the crash handler and dtor to terminate
48  * the child processes.
49  */
50  void cleanup();
51 
52  /**
53  * Returns the list of identifiers of all available
54  * agent types.
55  */
56  Q_REQUIRED_RESULT QStringList agentTypes() const;
57 
58  /**
59  * Returns the i18n'ed name of the agent type for
60  * the given @p identifier.
61  */
62  Q_REQUIRED_RESULT QString agentName(const QString &identifier) const;
63 
64  /**
65  * Returns the i18n'ed comment of the agent type for
66  * the given @p identifier..
67  */
68  Q_REQUIRED_RESULT QString agentComment(const QString &identifier) const;
69 
70  /**
71  * Returns the icon name of the agent type for the
72  * given @p identifier.
73  */
74  Q_REQUIRED_RESULT QString agentIcon(const QString &identifier) const;
75 
76  /**
77  * Returns a list of supported mimetypes of the agent type
78  * for the given @p identifier.
79  */
80  Q_REQUIRED_RESULT QStringList agentMimeTypes(const QString &identifier) const;
81 
82  /**
83  * Returns a list of supported capabilities of the agent type
84  * for the given @p identifier.
85  */
86  Q_REQUIRED_RESULT QStringList agentCapabilities(const QString &identifier) const;
87 
88  /**
89  * Returns a list of Custom added properties of the agent type
90  * for the given @p identifier
91  * @since 1.11
92  */
93  Q_REQUIRED_RESULT QVariantMap agentCustomProperties(const QString &identifier) const;
94 
95  /**
96  * Creates a new agent of the given agent type @p identifier.
97  *
98  * @return The identifier of the new agent if created successfully,
99  * an empty string otherwise.
100  * The identifier consists of two parts, the type of the
101  * agent and an unique instance number, and looks like
102  * the following: 'file_1' or 'imap_267'.
103  */
104  Q_REQUIRED_RESULT QString createAgentInstance(const QString &identifier);
105 
106  /**
107  * Removes the agent with the given @p identifier.
108  */
109  void removeAgentInstance(const QString &identifier);
110 
111  /**
112  * Returns the type of the agent instance with the given @p identifier.
113  */
114  Q_REQUIRED_RESULT QString agentInstanceType(const QString &identifier);
115 
116  /**
117  * Returns the list of identifiers of configured instances.
118  */
119  Q_REQUIRED_RESULT QStringList agentInstances() const;
120 
121  /**
122  * Returns the current status code of the agent with the given @p identifier.
123  */
124  int agentInstanceStatus(const QString &identifier) const;
125 
126  /**
127  * Returns the i18n'ed description of the current status of the agent with
128  * the given @p identifier.
129  */
130  Q_REQUIRED_RESULT QString agentInstanceStatusMessage(const QString &identifier) const;
131 
132  /**
133  * Returns the current progress of the agent with the given @p identifier
134  * in percentage.
135  */
136  Q_REQUIRED_RESULT uint agentInstanceProgress(const QString &identifier) const;
137 
138  /**
139  * Returns the i18n'ed description of the current progress of the agent with
140  * the given @p identifier.
141  */
142  QString agentInstanceProgressMessage(const QString &identifier) const;
143 
144  /**
145  * Sets the @p name of the agent instance with the given @p identifier.
146  */
147  void setAgentInstanceName(const QString &identifier, const QString &name);
148 
149  /**
150  * Returns the name of the agent instance with the given @p identifier.
151  */
152  Q_REQUIRED_RESULT QString agentInstanceName(const QString &identifier) const;
153 
154  /**
155  * Triggers the agent instance with the given @p identifier to show
156  * its configuration dialog.
157  * @param windowId Parent window id for the configuration dialog.
158  */
159  void agentInstanceConfigure(const QString &identifier, qlonglong windowId);
160 
161  /**
162  * Triggers the agent instance with the given @p identifier to start
163  * synchronization.
164  */
165  void agentInstanceSynchronize(const QString &identifier);
166 
167  /**
168  Trigger a synchronization of the collection tree by the given resource agent.
169  @param identifier The resource agent identifier.
170  */
171  void agentInstanceSynchronizeCollectionTree(const QString &identifier);
172 
173  /**
174  Trigger a synchronization of the given collection by its owning resource agent.
175  */
176  void agentInstanceSynchronizeCollection(const QString &identifier, qint64 collection);
177 
178  /**
179  Trigger a synchronization of the given collection by its owning resource agent.
180  @param recursive set it true to have sub-collection synchronized as well
181  */
182  void agentInstanceSynchronizeCollection(const QString &identifier, qint64 collection, bool recursive);
183 
184  /**
185  * Trigger a synchronization of tags by the given resource agent.
186  * @param identifier The resource agent identifier.
187  */
188  void agentInstanceSynchronizeTags(const QString &identifier);
189 
190  /**
191  * Trigger a synchronization of relations by the given resource agent.
192  * @param identifier The resource agent identifier.
193  */
194  void agentInstanceSynchronizeRelations(const QString &identifier);
195 
196  /**
197  Returns if the agent instance @p identifier is in online mode.
198  */
199  bool agentInstanceOnline(const QString &identifier);
200 
201  /**
202  Sets agent instance @p identifier to online or offline mode.
203  */
204  void setAgentInstanceOnline(const QString &identifier, bool state);
205 
206  /**
207  Restarts the agent instance @p identifier. This is supposed to be used as a
208  development aid and not something to use during normal operations.
209  */
210  void restartAgentInstance(const QString &identifier);
211 
212  /**
213  * Add a persistent search to remote search agents.
214  */
215  void addSearch(const QString &query, const QString &queryLanguage, qint64 resultCollectionId);
216 
217  /**
218  * Removes a persistent search for the given result collection.
219  */
220  void removeSearch(quint64 resultCollectionId);
221 
222 Q_SIGNALS:
223  /**
224  * This signal is emitted whenever a new agent type was installed on the system.
225  *
226  * @param agentType The identifier of the new agent type.
227  */
228  void agentTypeAdded(const QString &agentType);
229 
230  /**
231  * This signal is emitted whenever an agent type was removed from the system.
232  *
233  * @param agentType The identifier of the removed agent type.
234  */
235  void agentTypeRemoved(const QString &agentType);
236 
237  /**
238  * This signal is emitted whenever a new agent instance was created.
239  *
240  * @param agentIdentifier The identifier of the new agent instance.
241  */
242  void agentInstanceAdded(const QString &agentIdentifier);
243 
244  /**
245  * This signal is emitted whenever an agent instance was removed.
246  *
247  * @param agentIdentifier The identifier of the removed agent instance.
248  */
249  void agentInstanceRemoved(const QString &agentIdentifier);
250 
251  /**
252  * This signal is emitted whenever the status of an agent instance has
253  * changed.
254  *
255  * @param agentIdentifier The identifier of the agent that has changed.
256  * @param status The new status code.
257  * @param message The i18n'ed description of the new status.
258  */
259  void agentInstanceStatusChanged(const QString &agentIdentifier, int status, const QString &message);
260 
261  /**
262  * This signal is emitted whenever the status of an agent instance has
263  * changed.
264  *
265  * @param agentIdentifier The identifier of the agent that has changed.
266  * @param status The object that describes the status change.
267  */
268  void agentInstanceAdvancedStatusChanged(const QString &agentIdentifier, const QVariantMap &status);
269 
270  /**
271  * This signal is emitted whenever the progress of an agent instance has
272  * changed.
273  *
274  * @param agentIdentifier The identifier of the agent that has changed.
275  * @param progress The new progress in percentage.
276  * @param message The i18n'ed description of the new progress.
277  */
278  void agentInstanceProgressChanged(const QString &agentIdentifier, uint progress, const QString &message);
279 
280  /**
281  * This signal is emitted whenever an agent instance raised a warning.
282  *
283  * @param agentIdentifier The identifier of the agent instance.
284  * @param message The i18n'ed warning message.
285  */
286  void agentInstanceWarning(const QString &agentIdentifier, const QString &message);
287 
288  /**
289  * This signal is emitted whenever an agent instance raised an error.
290  *
291  * @param agentIdentifier The identifier of the agent instance.
292  * @param message The i18n'ed error message.
293  */
294  void agentInstanceError(const QString &agentIdentifier, const QString &message);
295 
296  /**
297  * This signal is emitted whenever the name of the agent instance has changed.
298  *
299  * @param agentIdentifier The identifier of the agent that has changed.
300  * @param name The new name of the agent instance.
301  */
302  void agentInstanceNameChanged(const QString &agentIdentifier, const QString &name);
303 
304  /**
305  * Emitted when the online state of an agent changed.
306  */
307  void agentInstanceOnlineChanged(const QString &agentIdentifier, bool state);
308 
309 private Q_SLOTS:
310  void updatePluginInfos();
311  void serviceOwnerChanged(const QString &name, const QString &oldOwner, const QString &newOwner);
312  void agentExeChanged(const QString &fileName);
313 
314 private:
315  /**
316  * Returns the list of directory paths where the .desktop files
317  * for the plugins are located.
318  */
319  static QStringList pluginInfoPathList();
320 
321  /**
322  * Loads the internal state from config file.
323  */
324  void load();
325 
326  /**
327  * Saves internal state to the config file.
328  */
329  void save();
330 
331  /**
332  * Reads the plugin information from directory.
333  */
334  void readPluginInfos();
335 
336  /**
337  * Reads the plugin information from directory.
338  *
339  * @param directory the directory to get plugin information from
340  */
341  void readPluginInfos(const QDir &directory);
342 
343  AgentInstance::Ptr createAgentInstance(const AgentType &type);
344  bool checkAgentInterfaces(const QString &identifier, const QString &method) const;
345  bool checkInstance(const QString &identifier) const;
346  bool checkResourceInterface(const QString &identifier, const QString &method) const;
347  bool checkAgentExists(const QString &identifier) const;
348  void ensureAutoStart(const AgentType &info);
349  void continueStartup();
350  void registerAgentAtServer(const QString &agentIdentifier, const AgentType &type);
351 
352 private:
353  /**
354  * The map which stores the .desktop file
355  * entries for every agent type.
356  *
357  * Key is the agent type (e.g. 'file' or 'imap').
358  */
360 
361  /**
362  * The map which stores the active instances.
363  *
364  * Key is the instance identifier.
365  */
366  QHash<QString, AgentInstance::Ptr> mAgentInstances;
367 
368  std::unique_ptr<Akonadi::ProcessControl> mAgentServer;
369  std::unique_ptr<Akonadi::ProcessControl> mStorageController;
370  bool mAgentServerEnabled = false;
371  bool mVerbose = false;
372 
373  friend class AgentInstance;
374 };
375 
Q_OBJECTQ_OBJECT
void agentInstanceRemoved(const QString &agentIdentifier)
This signal is emitted whenever an agent instance was removed.
QStringList agentMimeTypes(const QString &identifier) const
Returns a list of supported mimetypes of the agent type for the given identifier.
void agentInstanceStatusChanged(const QString &agentIdentifier, int status, const QString &message)
This signal is emitted whenever the status of an agent instance has changed.
void agentInstanceSynchronizeRelations(const QString &identifier)
Trigger a synchronization of relations by the given resource agent.
QStringList agentInstances() const
Returns the list of identifiers of configured instances.
QString agentIcon(const QString &identifier) const
Returns the icon name of the agent type for the given identifier.
Q_SLOTSQ_SLOTS
void cleanup()
Called by the crash handler and dtor to terminate the child processes.
~AgentManager() override
Destroys the agent manager.
void setAgentInstanceName(const QString &identifier, const QString &name)
Sets the name of the agent instance with the given identifier.
QString agentInstanceName(const QString &identifier) const
Returns the name of the agent instance with the given identifier.
Q_CLASSINFO(Name, Value)
void removeSearch(quint64 resultCollectionId)
Removes a persistent search for the given result collection.
QString agentInstanceProgressMessage(const QString &identifier) const
Returns the i18n'ed description of the current progress of the agent with the given identifier.
QString agentInstanceStatusMessage(const QString &identifier) const
Returns the i18n'ed description of the current status of the agent with the given identifier.
QVariantMap agentCustomProperties(const QString &identifier) const
Returns a list of Custom added properties of the agent type for the given identifier.
The agent manager has knowledge about all available agents (it scans for .desktop files in the agent ...
AgentManager(bool verbose, QObject *parent=nullptr)
Creates a new agent manager.
uint agentInstanceProgress(const QString &identifier) const
Returns the current progress of the agent with the given identifier in percentage.
void agentTypeRemoved(const QString &agentType)
This signal is emitted whenever an agent type was removed from the system.
void agentInstanceSynchronizeCollection(const QString &identifier, qint64 collection)
Trigger a synchronization of the given collection by its owning resource agent.
void agentInstanceAdded(const QString &agentIdentifier)
This signal is emitted whenever a new agent instance was created.
void addSearch(const QString &query, const QString &queryLanguage, qint64 resultCollectionId)
Add a persistent search to remote search agents.
void removeAgentInstance(const QString &identifier)
Removes the agent with the given identifier.
void agentInstanceProgressChanged(const QString &agentIdentifier, uint progress, const QString &message)
This signal is emitted whenever the progress of an agent instance has changed.
Represents one agent instance and takes care of communication with it.
QString agentName(const QString &identifier) const
Returns the i18n'ed name of the agent type for the given identifier.
void agentInstanceOnlineChanged(const QString &agentIdentifier, bool state)
Emitted when the online state of an agent changed.
QString agentComment(const QString &identifier) const
Returns the i18n'ed comment of the agent type for the given identifier.
QString agentInstanceType(const QString &identifier)
Returns the type of the agent instance with the given identifier.
void agentInstanceSynchronizeTags(const QString &identifier)
Trigger a synchronization of tags by the given resource agent.
void agentInstanceSynchronizeCollectionTree(const QString &identifier)
Trigger a synchronization of the collection tree by the given resource agent.
void restartAgentInstance(const QString &identifier)
Restarts the agent instance identifier.
int agentInstanceStatus(const QString &identifier) const
Returns the current status code of the agent with the given identifier.
const QDBusMessage & message() const const
void setAgentInstanceOnline(const QString &identifier, bool state)
Sets agent instance identifier to online or offline mode.
QStringList agentCapabilities(const QString &identifier) const
Returns a list of supported capabilities of the agent type for the given identifier.
Q_SIGNALSQ_SIGNALS
bool agentInstanceOnline(const QString &identifier)
Returns if the agent instance identifier is in online mode.
QString createAgentInstance(const QString &identifier)
Creates a new agent of the given agent type identifier.
void agentInstanceConfigure(const QString &identifier, qlonglong windowId)
Triggers the agent instance with the given identifier to show its configuration dialog.
void agentInstanceSynchronize(const QString &identifier)
Triggers the agent instance with the given identifier to start synchronization.
void agentInstanceAdvancedStatusChanged(const QString &agentIdentifier, const QVariantMap &status)
This signal is emitted whenever the status of an agent instance has changed.
void agentInstanceWarning(const QString &agentIdentifier, const QString &message)
This signal is emitted whenever an agent instance raised a warning.
void agentInstanceError(const QString &agentIdentifier, const QString &message)
This signal is emitted whenever an agent instance raised an error.
void agentTypeAdded(const QString &agentType)
This signal is emitted whenever a new agent type was installed on the system.
QStringList agentTypes() const
Returns the list of identifiers of all available agent types.
QObject * parent() const const
void agentInstanceNameChanged(const QString &agentIdentifier, const QString &name)
This signal is emitted whenever the name of the agent instance has changed.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jul 2 2022 06:41:46 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.