Akonadi

core/agentinstance.h
1 /*
2  SPDX-FileCopyrightText: 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 <QMetaType>
12 #include <QSharedDataPointer>
13 
14 class QString;
15 class QWidget;
16 
17 namespace Akonadi
18 {
19 class AgentType;
20 class 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 <[email protected]>
45  */
46 class AKONADICORE_EXPORT AgentInstance
47 {
48  friend class AgentManager;
49  friend class AgentManagerPrivate;
50 
51 public:
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  */
70  AgentInstance();
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  */
80  ~AgentInstance();
81 
82  /**
83  * Returns whether the agent instance object is valid.
84  */
85  Q_REQUIRED_RESULT bool isValid() const;
86 
87  /**
88  * Returns the agent type of this instance.
89  */
90  Q_REQUIRED_RESULT AgentType type() const;
91 
92  /**
93  * Returns the unique identifier of the agent instance.
94  */
95  Q_REQUIRED_RESULT QString identifier() const;
96 
97  /**
98  * Returns the user visible name of the agent instance.
99  */
100  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT Status status() const;
111 
112  /**
113  * Returns a textual presentation of the status of the agent instance.
114  */
115  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT int progress() const;
122 
123  /**
124  * Returns whether the agent instance is online currently.
125  */
126  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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 
192 private:
193  /// @cond PRIVATE
195  /// @endcond
196 };
197 
198 }
199 
200 Q_DECLARE_TYPEINFO(Akonadi::AgentInstance, Q_RELOCATABLE_TYPE);
201 
202 Q_DECLARE_METATYPE(Akonadi::AgentInstance)
@ Running
The agent instance is working on something.
@ Broken
The agent instance encountered an error state.
A representation of an agent type.
Status
Describes the status of the agent instance.
Provides an interface to retrieve agent types and manage agent instances.
Q_SCRIPTABLE CaptureState status()
A representation of an agent instance.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Sep 22 2023 03:51:42 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.