Akonadi

agentbase.h
1/*
2 This file is part of akonadiresources.
3
4 SPDX-FileCopyrightText: 2006 Till Adam <adam@kde.org>
5 SPDX-FileCopyrightText: 2007 Volker Krause <vkrause@kde.org>
6 SPDX-FileCopyrightText: 2008 Kevin Krammer <kevin.krammer@gmx.at>
7
8 SPDX-License-Identifier: LGPL-2.0-or-later
9*/
10
11#pragma once
12
13#include "akonadiagentbase_export.h"
14
15// AkonadiCore
16#include "akonadi/item.h"
17
18#include <QCoreApplication>
19#include <QDBusConnection>
20#include <QDBusContext>
21#include <qwindowdefs.h>
22
23#include <KSharedConfig>
24
25#include <memory>
26
27class Akonadi__ControlAdaptor;
28class Akonadi__StatusAdaptor;
29
30class KAboutData;
31
32namespace Akonadi
33{
34class AgentBasePrivate;
35class ChangeRecorder;
36class Collection;
37class Item;
38
39/**
40 * @short The base class for all Akonadi agents and resources.
41 *
42 * This class is a base class for all Akonadi agents, which covers the real
43 * agent processes and all resources.
44 *
45 * It provides:
46 * - lifetime management
47 * - change monitoring and recording
48 * - configuration interface
49 * - problem reporting
50 *
51 * Akonadi Server supports several ways to launch agents and resources:
52 * - As a separate application (@see AKONADI_AGENT_MAIN)
53 * - As a thread in the AgentServer
54 * - As a separate process, using the akonadi_agent_launcher
55 *
56 * The idea is this, the agent or resource is written as a plugin instead of an
57 * executable (@see AgentFactory). In the AgentServer case, the AgentServer
58 * looks up the plugin and launches the agent in a separate thread. In the
59 * launcher case, a new akonadi_agent_launcher process is started for each
60 * agent or resource instance.
61 *
62 * When making an Agent or Resource suitable for running in the AgentServer some
63 * extra caution is needed. Because multiple instances of several kinds of agents
64 * run in the same process, one cannot blindly use global objects like KGlobal.
65 * For this reasons several methods where added to avoid problems in this context,
66 * most notably AgentBase::config(). Additionally,
67 * one cannot use QDBusConnection::sessionBus() with dbus < 1.4, because of a
68 * multithreading bug in libdbus. Instead one should use
69 * QDBusConnection::sessionBus() which works around this problem.
70 *
71 * @author Till Adam <adam@kde.org>, Volker Krause <vkrause@kde.org>
72 */
73class AKONADIAGENTBASE_EXPORT AgentBase : public QObject, protected QDBusContext
74{
76
77public:
78 /**
79 * @short The interface for reacting on monitored or replayed changes.
80 *
81 * The Observer provides an interface to react on monitored or replayed changes.
82 *
83 * Since the this base class does only tell the change recorder that the change
84 * has been processed, an AgentBase subclass which wants to actually process
85 * the change needs to subclass Observer and reimplement the methods it is
86 * interested in.
87 *
88 * Such an agent specific Observer implementation can either be done
89 * stand-alone, i.e. as a separate object, or by inheriting both AgentBase
90 * and AgentBase::Observer.
91 *
92 * The observer implementation then has registered with the agent, so it
93 * can forward the incoming changes to the observer.
94 *
95 * @note In the multiple inheritance approach the init() method automatically
96 * registers itself as the observer.
97 *
98 * @note Do not call the base implementation of reimplemented virtual methods!
99 * The default implementation disconnected themselves from the Akonadi::ChangeRecorder
100 * to enable internal optimizations for unused notifications.
101 *
102 * Example for stand-alone observer:
103 * @code
104 * class ExampleAgent : public AgentBase
105 * {
106 * public:
107 * ExampleAgent( const QString &id );
108 *
109 * ~ExampleAgent();
110 *
111 * private:
112 * AgentBase::Observer *mObserver;
113 * };
114 *
115 * class ExampleObserver : public AgentBase::Observer
116 * {
117 * protected:
118 * void itemChanged( const Item &item );
119 * };
120 *
121 * ExampleAgent::ExampleAgent( const QString &id )
122 : AgentBase( id )
123 , mObserver( 0 )
124 * {
125 * mObserver = new ExampleObserver();
126 * registerObserver( mObserver );
127 * }
128 *
129 * ExampleAgent::~ExampleAgent()
130 * {
131 * delete mObserver;
132 * }
133 *
134 * void ExampleObserver::itemChanged( const Item &item )
135 * {
136 * // do something with item
137 * qCDebug(AKONADIAGENTBASE_LOG) << "Item id=" << item.id();
138 *
139 * // let base implementation tell the change recorder that we
140 * // have processed the change
141 * AgentBase::Observer::itemChanged( item );
142 * }
143 * @endcode
144 *
145 * Example for observer through multiple inheritance:
146 * @code
147 * class ExampleAgent : public AgentBase, public AgentBase::Observer
148 * {
149 * public:
150 * ExampleAgent( const QString &id );
151 *
152 * protected:
153 * void itemChanged( const Item &item );
154 * };
155 *
156 * ExampleAgent::ExampleAgent( const QString &id )
157 : AgentBase( id )
158 * {
159 * // no need to create or register observer since
160 * // we are the observer and registration happens automatically
161 * // in init()
162 * }
163 *
164 * void ExampleAgent::itemChanged( const Item &item )
165 * {
166 * // do something with item
167 * qCDebug(AKONADIAGENTBASE_LOG) << "Item id=" << item.id();
168 *
169 * // let base implementation tell the change recorder that we
170 * // have processed the change
171 * AgentBase::Observer::itemChanged( item );
172 * }
173 * @endcode
174 *
175 * @author Kevin Krammer <kevin.krammer@gmx.at>
176 *
177 * @deprecated Use ObserverV2 instead
178 */
179 class AKONADIAGENTBASE_DEPRECATED AKONADIAGENTBASE_EXPORT Observer // krazy:exclude=dpointer
180 {
181 public:
182 /**
183 * Creates an observer instance.
184 */
185 Observer();
186
187 /**
188 * Destroys the observer instance.
189 */
190 virtual ~Observer();
191
192 /**
193 * Reimplement to handle adding of new items.
194 * @param item The newly added item.
195 * @param collection The collection @p item got added to.
196 */
197 virtual void itemAdded(const Akonadi::Item &item, const Akonadi::Collection &collection);
198
199 /**
200 * Reimplement to handle changes to existing items.
201 * @param item The changed item.
202 * @param partIdentifiers The identifiers of the item parts that has been changed.
203 */
204 virtual void itemChanged(const Akonadi::Item &item, const QSet<QByteArray> &partIdentifiers);
205
206 /**
207 * Reimplement to handle deletion of items.
208 * @param item The deleted item.
209 */
210 virtual void itemRemoved(const Akonadi::Item &item);
211
212 /**
213 * Reimplement to handle adding of new collections.
214 * @param collection The newly added collection.
215 * @param parent The parent collection.
216 */
217 virtual void collectionAdded(const Akonadi::Collection &collection, const Akonadi::Collection &parent);
218
219 /**
220 * Reimplement to handle changes to existing collections.
221 * @param collection The changed collection.
222 */
223 virtual void collectionChanged(const Akonadi::Collection &collection);
224
225 /**
226 * Reimplement to handle deletion of collections.
227 * @param collection The deleted collection.
228 */
229 virtual void collectionRemoved(const Akonadi::Collection &collection);
230 };
231
232 /**
233 * BC extension of Observer with support for monitoring item and collection moves.
234 * Use this one instead of Observer.
235 *
236 * @since 4.4
237 */
238 class AKONADIAGENTBASE_EXPORT ObserverV2 : public Observer // krazy:exclude=dpointer
239 {
240 public:
242
243 /**
244 * Reimplement to handle item moves.
245 * When using this class in combination with Akonadi::ResourceBase, inter-resource
246 * moves are handled internally already and the corresponding add or delete method
247 * is called instead.
248 *
249 * @param item The moved item.
250 * @param collectionSource The collection the item has been moved from.
251 * @param collectionDestination The collection the item has been moved to.
252 */
253 virtual void itemMoved(const Akonadi::Item &item, const Akonadi::Collection &collectionSource, const Akonadi::Collection &collectionDestination);
254
255 /**
256 * Reimplement to handle item linking.
257 * This is only relevant for virtual resources.
258 * @param item The linked item.
259 * @param collection The collection the item is linked to.
260 */
261 virtual void itemLinked(const Akonadi::Item &item, const Akonadi::Collection &collection);
262
263 /**
264 * Reimplement to handle item unlinking.
265 * This is only relevant for virtual resources.
266 * @param item The unlinked item.
267 * @param collection The collection the item is unlinked from.
268 */
269 virtual void itemUnlinked(const Akonadi::Item &item, const Akonadi::Collection &collection);
270
271 /**
272 * Reimplement to handle collection moves.
273 * When using this class in combination with Akonadi::ResourceBase, inter-resource
274 * moves are handled internally already and the corresponding add or delete method
275 * is called instead.
276 *
277 * @param collection The moved collection.
278 * @param collectionSource The previous parent collection.
279 * @param collectionDestination The new parent collection.
280 */
281 virtual void
282 collectionMoved(const Akonadi::Collection &collection, const Akonadi::Collection &collectionSource, const Akonadi::Collection &collectionDestination);
283
284 /**
285 * Reimplement to handle changes to existing collections.
286 * @param collection The changed collection.
287 * @param changedAttributes The identifiers of the collection parts/attributes that has been changed.
288 */
289 virtual void collectionChanged(const Akonadi::Collection &collection, const QSet<QByteArray> &changedAttributes);
290 };
291
292 /**
293 * BC extension of ObserverV2 with support for batch operations
294 *
295 * @warning When using ObserverV3, you will never get single-item notifications
296 * from AgentBase::Observer, even when you don't reimplement corresponding batch
297 * method from ObserverV3. For instance, when you don't reimplement itemsRemoved()
298 * here, you will not get any notifications about item removal whatsoever!
299 *
300 * @since 4.11
301 */
302 class AKONADIAGENTBASE_EXPORT ObserverV3 : public ObserverV2 // krazy:exclude=dpointer
303 {
304 public:
305 /**
306 * Reimplement to handle changes in flags of existing items
307 *
308 * @warning When using ObserverV3, you will never get notifications about
309 * flag changes via Observer::itemChanged(), even when you don't reimplement
310 * itemsFlagsChanged()!
311 *
312 * @param items The changed items
313 * @param addedFlags Flags that have been added to the item
314 * @param removedFlags Flags that have been removed from the item
315 */
316 virtual void itemsFlagsChanged(const Akonadi::Item::List &items, const QSet<QByteArray> &addedFlags, const QSet<QByteArray> &removedFlags);
317
318 /**
319 * Reimplement to handle batch notification about items deletion.
320 *
321 * @param items List of deleted items
322 */
323 virtual void itemsRemoved(const Akonadi::Item::List &items);
324
325 /**
326 * Reimplement to handle batch notification about items move
327 *
328 * @param items List of moved items
329 * @param sourceCollection Collection from where the items were moved
330 * @param destinationCollection Collection to which the items were moved
331 */
332 virtual void
333 itemsMoved(const Akonadi::Item::List &items, const Akonadi::Collection &sourceCollection, const Akonadi::Collection &destinationCollection);
334
335 /**
336 * Reimplement to handle batch notifications about items linking.
337 *
338 * @param items Linked items
339 * @param collection Collection to which the items have been linked
340 */
341 virtual void itemsLinked(const Akonadi::Item::List &items, const Akonadi::Collection &collection);
342
343 /**
344 * Reimplement to handle batch notifications about items unlinking.
345 *
346 * @param items Unlinked items
347 * @param collection Collection from which the items have been unlinked
348 */
349 virtual void itemsUnlinked(const Akonadi::Item::List &items, const Akonadi::Collection &collection);
350 };
351
352 class AKONADIAGENTBASE_EXPORT TagObserver
353 {
354 public:
355 TagObserver();
356 virtual ~TagObserver();
357
358 /**
359 * Reimplement to handle tags additions
360 *
361 * @param tag Newly added tag
362 */
363 virtual void tagAdded(const Akonadi::Tag &tag);
364
365 /**
366 * Reimplement to handle tags changes
367 *
368 * @param tag Tag that has been changed
369 */
370 virtual void tagChanged(const Akonadi::Tag &tag);
371
372 /**
373 * Reimplement to handle tags removal.
374 *
375 * @note All items that were tagged by @p tag will get a separate notification
376 * about untagging via itemsTagsChanged(). It is guaranteed that the itemsTagsChanged()
377 * notification will be delivered before this one.
378 *
379 * @param tag Tag that has been removed.
380 */
381 virtual void tagRemoved(const Akonadi::Tag &tag);
382
383 /**
384 * Reimplement to handle items tagging
385 *
386 * @param items Items that were tagged or untagged
387 * @param addedTags Set of tags that were added to all @p items
388 * @param removedTags Set of tags that were removed from all @p items
389 */
390 virtual void itemsTagsChanged(const Akonadi::Item::List &items, const QSet<Akonadi::Tag> &addedTags, const QSet<Akonadi::Tag> &removedTags);
391 };
392
393 /**
394 * This enum describes the different states the
395 * agent can be in.
396 */
397 enum Status {
398 Idle = 0, ///< The agent does currently nothing.
399 Running, ///< The agent is working on something.
400 Broken, ///< The agent encountered an error state.
401 NotConfigured ///< The agent is lacking required configuration
402 };
403
404 /**
405 * Use this method in the main function of your agent
406 * application to initialize your agent subclass.
407 * This method also takes care of creating a QCoreApplication
408 * object and parsing command line arguments.
409 *
410 * @note In case the given class is also derived from AgentBase::Observer
411 * it gets registered as its own observer (see AgentBase::Observer), e.g.
412 * <tt>agentInstance->registerObserver( agentInstance );</tt>
413 *
414 * @code
415 *
416 * class MyAgent : public AgentBase
417 * {
418 * ...
419 * };
420 *
421 * AKONADI_AGENT_CORE_MAIN( MyAgent )
422 *
423 * @endcode
424 *
425 * @param argc number of arguments
426 * @param argv arguments for the function
427 */
428 template<typename T>
429 static int initCore(int argc, char **argv)
430 {
431 // Disable session management
432 qunsetenv("SESSION_MANAGER");
433
434#if __has_include(<QApplication>)
435 static_assert(false, "This links to QWidgets");
436#endif
437
438 QCoreApplication app(argc, argv);
439 debugAgent(argc, argv);
440 const QString id = parseArguments(argc, argv);
441 T r(id);
442
443 // check if T also inherits AgentBase::Observer and
444 // if it does, automatically register it on itself
445 auto observer = dynamic_cast<Observer *>(&r);
446 if (observer != nullptr) {
447 r.registerObserver(observer);
448 }
449 return init(r);
450 }
451
452 /**
453 * This method returns the current status code of the agent.
454 *
455 * The following return values are possible:
456 *
457 * - 0 - Idle
458 * - 1 - Running
459 * - 2 - Broken
460 * - 3 - NotConfigured
461 */
462 [[nodiscard]] virtual int status() const;
463
464 /**
465 * This method returns an i18n'ed description of the current status code.
466 */
467 [[nodiscard]] virtual QString statusMessage() const;
468
469 /**
470 * This method returns the current progress of the agent in percentage.
471 */
472 [[nodiscard]] virtual int progress() const;
473
474 /**
475 * This method returns an i18n'ed description of the current progress.
476 */
477 [[nodiscard]] virtual QString progressMessage() const;
478
479public Q_SLOTS:
480 /**
481 * This method is called whenever the agent shall show its configuration dialog
482 * to the user. It will be automatically called when the agent is started for
483 * the first time.
484 *
485 * @param windowId The parent window id.
486 *
487 * @note If the method is reimplemented it has to emit the configurationDialogAccepted()
488 * or configurationDialogRejected() signals depending on the users choice.
489 */
490 virtual void configure(WId windowId);
491
492public:
493 /**
494 * This method returns the windows id, which should be used for dialogs.
495 */
496 [[nodiscard]] WId winIdForDialogs() const;
497
498#ifdef Q_OS_WIN
499 /**
500 * Overload of @ref configure needed because WId cannot be automatically casted
501 * to qlonglong on Windows.
502 */
503 void configure(qlonglong windowId);
504#endif
505
506 /**
507 * Returns the instance identifier of this agent.
508 */
509 [[nodiscard]] QString identifier() const;
510
511 /**
512 * This method is called when the agent is removed from
513 * the system, so it can do some cleanup stuff.
514 *
515 * @note If you reimplement this in a subclass make sure
516 * to call this base implementation at the end.
517 */
518 virtual void cleanup();
519
520 /**
521 * Registers the given observer for reacting on monitored or recorded changes.
522 *
523 * @param observer The change handler to register. No ownership transfer, i.e.
524 * the caller stays owner of the pointer and can reset
525 * the registration by calling this method with @c 0
526 */
527 void registerObserver(Observer *observer);
528
529 /**
530 * This method is used to set the name of the agent.
531 *
532 * @since 4.3
533 * @param name name of the agent
534 */
535 // FIXME_API: make sure location is renamed to this by agentbase
536 void setAgentName(const QString &name);
537
538 /**
539 * Returns the name of the agent.
540 *
541 * @since 4.3
542 */
543 [[nodiscard]] QString agentName() const;
544
545 /**
546 * This method is used to set the activities of the agent.
547 *
548 * @since 6.3
549 */
550 void setActivities(const QStringList &activities);
551
552 /**
553 * Returns the activities of the agent.
554 *
555 * @since 6.3
556 */
557 [[nodiscard]] QStringList activities() const;
558
559 /**
560 * This method is used to enabled the activities of the agent.
561 *
562 * @since 6.3
563 */
564 void setActivitiesEnabled(bool enabled);
565
566 /**
567 * Returns the activities status of the agent.
568 *
569 * @since 6.3
570 */
571 [[nodiscard]] bool activitiesEnabled() const;
572
573Q_SIGNALS:
574 /**
575 * This signal is emitted whenever the name of the agent has changed.
576 *
577 * @param name The new name of the agent.
578 *
579 * @since 4.3
580 */
581 void agentNameChanged(const QString &name);
582
583 /**
584 * This signal should be emitted whenever the status of the agent has been changed.
585 * @param status The new Status code.
586 * @param message A i18n'ed description of the new status.
587 */
588 void status(int status, const QString &message = QString());
589
590 /**
591 * This signal should be emitted whenever the progress of an action in the agent
592 * (e.g. data transfer, connection establishment to remote server etc.) has changed.
593 *
594 * @param progress The progress of the action in percent.
595 */
596 void percent(int progress);
597
598 /**
599 * This signal shall be used to report warnings.
600 *
601 * @param message The i18n'ed warning message.
602 */
603 void warning(const QString &message);
604
605 /**
606 * This signal shall be used to report errors.
607 *
608 * @param message The i18n'ed error message.
609 */
610 void error(const QString &message);
611
612 /**
613 * This signal should be emitted whenever the status of the agent has been changed.
614 * @param status The object that describes the status change.
615 *
616 * @since 4.6
617 */
618 void advancedStatus(const QVariantMap &status);
619
620 /**
621 * Emitted when another application has remotely asked the agent to abort
622 * its current operation.
623 * Connect to this signal if your agent supports abortion. After aborting
624 * and cleaning up, agents should return to Idle status.
625 *
626 * @since 4.4
627 */
629
630 /**
631 * Emitted if another application has changed the agent's configuration remotely
632 * and called AgentInstance::reconfigure().
633 *
634 * @since 4.2
635 */
637
638 /**
639 * Emitted when the online state changed.
640 * @param online The online state.
641 * @since 4.2
642 */
643 void onlineChanged(bool online);
644
645 /**
646 * This signal is emitted whenever the user has accepted the configuration dialog.
647 *
648 * @note Implementors of agents/resources are responsible to emit this signal if
649 * the agent/resource reimplements configure().
650 *
651 * @since 4.4
652 */
654
655 /**
656 * This signal is emitted whenever the user has rejected the configuration dialog.
657 *
658 * @note Implementors of agents/resources are responsible to emit this signal if
659 * the agent/resource reimplements configure().
660 *
661 * @since 4.4
662 */
664
665 /**
666 * This signal is emitted whenever the user has changed activities.
667 *
668 * @since 6.3
669 */
671
672 /**
673 * This signal is emitted whenever the user has changed enabled activities.
674 *
675 * @since 6.3
676 */
678
679protected:
680 /**
681 * Creates an agent base.
682 *
683 * @param id The instance id of the agent.
684 */
685 AgentBase(const QString &id);
686
687 /**
688 * Destroys the agent base.
689 */
690 ~AgentBase() override;
691
692 /**
693 * This method is called whenever the agent application is about to
694 * quit.
695 *
696 * Reimplement this method to do session cleanup (e.g. disconnecting
697 * from groupware server).
698 */
699 virtual void aboutToQuit();
700
701 /**
702 * Returns the Akonadi::ChangeRecorder object used for monitoring.
703 * Use this to configure which parts you want to monitor.
704 */
706
707 /**
708 * Returns the config object for this Agent.
709 */
710 KSharedConfigPtr config();
711
712 /**
713 * Marks the current change as processes and replays the next change if change
714 * recording is enabled (noop otherwise). This method is called
715 * from the default implementation of the change notification slots. While not
716 * required when not using change recording, it is nevertheless recommended
717 * to call this method when done with processing a change notification.
718 */
719 void changeProcessed();
720
721 /**
722 * Returns whether the agent is currently online.
723 */
724 bool isOnline() const;
725
726 /**
727 * Sets whether the agent needs network or not.
728 *
729 * @since 4.2
730 * @todo use this in combination with QNetworkConfiguration to change
731 * the onLine status of the agent.
732 * @param needsNetwork @c true if the agents needs network. Defaults to @c false
733 */
734 void setNeedsNetwork(bool needsNetwork);
735
736 /**
737 * Sets whether the agent shall be online or not.
738 */
739 void setOnline(bool state);
740
741 /**
742 * Get the application display name
743 */
744 [[nodiscard]] QString programName() const;
745
746 /**
747 * Sets the agent offline but will make it online again after a given time
748 *
749 * Use this method when the agent detects some problem with its backend but it wants
750 * to retry all pending operations after some time - e.g. a server can not be reached currently
751 *
752 * Example usage:
753 * @code
754 * void ExampleResource::onItemRemovedFinished(KJob *job)
755 * {
756 * if (job->error()) {
757 * Q_EMIT status(Broken, job->errorString());
758 * deferTask();
759 * setTemporaryOffline(300);
760 * return;
761 * }
762 * ...
763 * }
764 * @endcode
765 *
766 * @since 4.13
767 * @param makeOnlineInSeconds timeout in seconds after which the agent changes to online
768 */
769 void setTemporaryOffline(int makeOnlineInSeconds = 300);
770
771 /// @cond PRIVATE
772 static void debugAgent(int argc, char **argv);
773
774 std::unique_ptr<AgentBasePrivate> const d_ptr;
775 explicit AgentBase(AgentBasePrivate *d, const QString &id);
776 friend class ObserverV2;
777 /// @endcond
778
779 /**
780 * This method is called whenever the @p online status has changed.
781 * Reimplement this method to react on online status changes.
782 * @param online online status
783 */
784 virtual void doSetOnline(bool online);
785
786 virtual KAboutData aboutData() const;
787
788private:
789 /// @cond PRIVATE
790 static QString parseArguments(int argc, char **argv);
791 static int init(AgentBase &r);
792 void setOnlineInternal(bool state);
793
794 // D-Bus interface stuff
795 AKONADIAGENTBASE_NO_EXPORT void abort();
796 AKONADIAGENTBASE_NO_EXPORT void reconfigure();
797 AKONADIAGENTBASE_NO_EXPORT void quit();
798
799 // dbus agent interface
800 friend class ::Akonadi__StatusAdaptor;
801 friend class ::Akonadi__ControlAdaptor;
802
803 friend class AgentWidgetBase;
804 friend class ResourceWidgetBase;
805
806 Q_DECLARE_PRIVATE(AgentBase)
807 Q_PRIVATE_SLOT(d_func(), void delayedInit())
808 Q_PRIVATE_SLOT(d_func(), void slotStatus(int, const QString &))
809 Q_PRIVATE_SLOT(d_func(), void slotPercent(int))
810 Q_PRIVATE_SLOT(d_func(), void slotWarning(const QString &))
811 Q_PRIVATE_SLOT(d_func(), void slotError(const QString &))
812 Q_PRIVATE_SLOT(d_func(), void slotNetworkStatusChange(bool))
813 Q_PRIVATE_SLOT(d_func(), void slotResumedFromSuspend())
814 Q_PRIVATE_SLOT(d_func(), void slotTemporaryOfflineTimeout())
815
816 /// @endcond
817};
818
819}
820
821#ifndef AKONADI_AGENT_CORE_MAIN
822/**
823 * Convenience Macro for the most common main() function for Akonadi agents.
824 */
825#define AKONADI_AGENT_CORE_MAIN(agentClass) \
826 int main(int argc, char **argv) \
827 { \
828 return Akonadi::AgentBase::initCore<agentClass>(argc, argv); \
829 }
830#endif
BC extension of Observer with support for monitoring item and collection moves.
Definition agentbase.h:239
virtual void itemUnlinked(const Akonadi::Item &item, const Akonadi::Collection &collection)
Reimplement to handle item unlinking.
virtual void itemMoved(const Akonadi::Item &item, const Akonadi::Collection &collectionSource, const Akonadi::Collection &collectionDestination)
Reimplement to handle item moves.
virtual void collectionChanged(const Akonadi::Collection &collection, const QSet< QByteArray > &changedAttributes)
Reimplement to handle changes to existing collections.
virtual void collectionMoved(const Akonadi::Collection &collection, const Akonadi::Collection &collectionSource, const Akonadi::Collection &collectionDestination)
Reimplement to handle collection moves.
virtual void itemLinked(const Akonadi::Item &item, const Akonadi::Collection &collection)
Reimplement to handle item linking.
BC extension of ObserverV2 with support for batch operations.
Definition agentbase.h:303
virtual void itemsFlagsChanged(const Akonadi::Item::List &items, const QSet< QByteArray > &addedFlags, const QSet< QByteArray > &removedFlags)
Reimplement to handle changes in flags of existing items.
virtual void itemsLinked(const Akonadi::Item::List &items, const Akonadi::Collection &collection)
Reimplement to handle batch notifications about items linking.
virtual void itemsRemoved(const Akonadi::Item::List &items)
Reimplement to handle batch notification about items deletion.
virtual void itemsUnlinked(const Akonadi::Item::List &items, const Akonadi::Collection &collection)
Reimplement to handle batch notifications about items unlinking.
virtual void itemsMoved(const Akonadi::Item::List &items, const Akonadi::Collection &sourceCollection, const Akonadi::Collection &destinationCollection)
Reimplement to handle batch notification about items move.
The interface for reacting on monitored or replayed changes.
Definition agentbase.h:180
virtual void collectionAdded(const Akonadi::Collection &collection, const Akonadi::Collection &parent)
Reimplement to handle adding of new collections.
Definition agentbase.cpp:90
virtual void collectionChanged(const Akonadi::Collection &collection)
Reimplement to handle changes to existing collections.
Definition agentbase.cpp:99
virtual void collectionRemoved(const Akonadi::Collection &collection)
Reimplement to handle deletion of collections.
Observer()
Creates an observer instance.
Definition agentbase.cpp:56
virtual void itemAdded(const Akonadi::Item &item, const Akonadi::Collection &collection)
Reimplement to handle adding of new items.
Definition agentbase.cpp:64
virtual void itemChanged(const Akonadi::Item &item, const QSet< QByteArray > &partIdentifiers)
Reimplement to handle changes to existing items.
Definition agentbase.cpp:73
virtual void itemRemoved(const Akonadi::Item &item)
Reimplement to handle deletion of items.
Definition agentbase.cpp:82
void agentActivitiesEnabledChanged(bool enabled)
This signal is emitted whenever the user has changed enabled activities.
void warning(const QString &message)
This signal shall be used to report warnings.
void changeProcessed()
Marks the current change as processes and replays the next change if change recording is enabled (noo...
virtual void doSetOnline(bool online)
This method is called whenever the online status has changed.
QStringList activities() const
Returns the activities of the agent.
void configurationDialogAccepted()
This signal is emitted whenever the user has accepted the configuration dialog.
void setTemporaryOffline(int makeOnlineInSeconds=300)
Sets the agent offline but will make it online again after a given time.
void advancedStatus(const QVariantMap &status)
This signal should be emitted whenever the status of the agent has been changed.
void setNeedsNetwork(bool needsNetwork)
Sets whether the agent needs network or not.
virtual int status() const
This method returns the current status code of the agent.
void onlineChanged(bool online)
Emitted when the online state changed.
KSharedConfigPtr config()
Returns the config object for this Agent.
void reloadConfiguration()
Emitted if another application has changed the agent's configuration remotely and called AgentInstanc...
void agentActivitiesChanged(const QStringList &activities)
This signal is emitted whenever the user has changed activities.
QString programName() const
Get the application display name.
~AgentBase() override
Destroys the agent base.
ChangeRecorder * changeRecorder() const
Returns the Akonadi::ChangeRecorder object used for monitoring.
virtual void aboutToQuit()
This method is called whenever the agent application is about to quit.
void status(int status, const QString &message=QString())
This signal should be emitted whenever the status of the agent has been changed.
Status
This enum describes the different states the agent can be in.
Definition agentbase.h:397
@ Running
The agent is working on something.
Definition agentbase.h:399
@ NotConfigured
The agent is lacking required configuration.
Definition agentbase.h:401
@ Broken
The agent encountered an error state.
Definition agentbase.h:400
@ Idle
The agent does currently nothing.
Definition agentbase.h:398
void percent(int progress)
This signal should be emitted whenever the progress of an action in the agent (e.g.
void abortRequested()
Emitted when another application has remotely asked the agent to abort its current operation.
bool isOnline() const
Returns whether the agent is currently online.
virtual int progress() const
This method returns the current progress of the agent in percentage.
void agentNameChanged(const QString &name)
This signal is emitted whenever the name of the agent has changed.
void setOnline(bool state)
Sets whether the agent shall be online or not.
static int initCore(int argc, char **argv)
Use this method in the main function of your agent application to initialize your agent subclass.
Definition agentbase.h:429
void error(const QString &message)
This signal shall be used to report errors.
void configurationDialogRejected()
This signal is emitted whenever the user has rejected the configuration dialog.
AgentBase(const QString &id)
Creates an agent base.
Records and replays change notification.
Represents a collection of PIM items.
Definition collection.h:62
Represents a PIM item stored in Akonadi storage.
Definition item.h:100
QList< Item > List
Describes a list of items.
Definition item.h:110
An Akonadi Tag.
Definition tag.h:26
Q_SCRIPTABLE Q_NOREPLY void abort()
Q_SCRIPTABLE CaptureState status()
Helper integration between Akonadi and Qt.
const QDBusMessage & message() const const
QObject(QObject *parent)
Q_OBJECTQ_OBJECT
QObject * parent() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2025 The KDE developers.
Generated on Fri Mar 28 2025 11:53:20 by doxygen 1.13.2 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.