Akonadi::AgentBase

Search for usage in LXR

#include <agentbase.h>

Inheritance diagram for Akonadi::AgentBase:

Classes

class  Observer
 
class  ObserverV2
 
class  ObserverV3
 

Public Types

enum  Status { Idle = 0 , Running , Broken , NotConfigured }
 
- Public Types inherited from QObject
typedef  QObjectList
 

Signals

void abortRequested ()
 
void advancedStatus (const QVariantMap &status)
 
void agentActivitiesChanged (const QStringList &activities)
 
void agentActivitiesEnabledChanged (bool enabled)
 
void agentNameChanged (const QString &name)
 
void configurationDialogAccepted ()
 
void configurationDialogRejected ()
 
void error (const QString &message)
 
void onlineChanged (bool online)
 
void percent (int progress)
 
void reloadConfiguration ()
 
void status (int status, const QString &message=QString())
 
void warning (const QString &message)
 

Public Slots

virtual void configure (WId windowId)
 

Public Member Functions

QStringList activities () const
 
bool activitiesEnabled () const
 
QString agentName () const
 
virtual void cleanup ()
 
QString identifier () const
 
virtual int progress () const
 
virtual QString progressMessage () const
 
void registerObserver (Observer *observer)
 
void setActivities (const QStringList &activities)
 
void setActivitiesEnabled (bool enabled)
 
void setAgentName (const QString &name)
 
virtual int status () const
 
virtual QString statusMessage () const
 
WId winIdForDialogs () const
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
QBindable< QStringbindableObjectName ()
 
bool blockSignals (bool block)
 
const QObjectListchildren () const const
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method) const const
 
bool disconnect (const QObject *receiver, const char *method) const const
 
void dumpObjectInfo () const const
 
void dumpObjectTree () const const
 
QList< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isQuickItemType () const const
 
bool isWidgetType () const const
 
bool isWindowType () const const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () const const
 
QVariant property (const char *name) const const
 
 Q_CLASSINFO (Name, Value)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_GADGET_EXPORT (EXPORT_MACRO)
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 Q_MOC_INCLUDE Q_MOC_INCLUDE
 
 Q_NAMESPACE Q_NAMESPACE
 
 Q_NAMESPACE_EXPORT (EXPORT_MACRO)
 
 Q_OBJECT Q_OBJECT
 
 Q_PROPERTY (...)
 
 Q_REVISION Q_REVISION
 
 Q_SET_OBJECT_NAME (Object)
 
 Q_SIGNAL Q_SIGNAL
 
 Q_SIGNALS Q_SIGNALS
 
 Q_SLOT Q_SLOT
 
 Q_SLOTS Q_SLOTS
 
qobject_cast (const QObject *object)
 
qobject_cast (QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setObjectName (QAnyStringView name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool setProperty (const char *name, QVariant &&value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds interval, Qt::TimerType timerType)
 
QThreadthread () const const
 

Static Public Member Functions

template<typename T >
static int init (int argc, char **argv)
 
- Static Public Member Functions inherited from QObject
QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
bool disconnect (const QMetaObject::Connection &connection)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 

Protected Member Functions

 AgentBase (const QString &id)
 
 ~AgentBase () override
 
virtual KAboutData aboutData () const
 
virtual void aboutToQuit ()
 
void changeProcessed ()
 
ChangeRecorderchangeRecorder () const
 
KSharedConfigPtr config ()
 
virtual void doSetOnline (bool online)
 
bool isOnline () const
 
void setNeedsNetwork (bool needsNetwork)
 
void setOnline (bool state)
 
void setTemporaryOffline (int makeOnlineInSeconds=300)
 
- Protected Member Functions inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
bool isSignalConnected (const QMetaMethod &signal) const const
 
int receivers (const char *signal) const const
 
QObjectsender () const const
 
int senderSignalIndex () const const
 
virtual void timerEvent (QTimerEvent *event)
 
- Protected Member Functions inherited from QDBusContext
bool calledFromDBus () const const
 
QDBusConnection connection () const const
 
bool isDelayedReply () const const
 
const QDBusMessagemessage () const const
 
void sendErrorReply (const QString &name, const QString &msg) const const
 
void sendErrorReply (QDBusError::ErrorType type, const QString &msg) const const
 
void setDelayedReply (bool enable) const const
 

Additional Inherited Members

- Properties inherited from QObject
 objectName
 

Detailed Description

The base class for all Akonadi agents and resources.

This class is a base class for all Akonadi agents, which covers the real agent processes and all resources.

It provides:

  • lifetime management
  • change monitoring and recording
  • configuration interface
  • problem reporting

Akonadi Server supports several ways to launch agents and resources:

  • As a separate application (
    See also
    AKONADI_AGENT_MAIN)
  • As a thread in the AgentServer
  • As a separate process, using the akonadi_agent_launcher

The idea is this, the agent or resource is written as a plugin instead of an executable (

See also
AgentFactory). In the AgentServer case, the AgentServer looks up the plugin and launches the agent in a separate thread. In the launcher case, a new akonadi_agent_launcher process is started for each agent or resource instance.

When making an Agent or Resource suitable for running in the AgentServer some extra caution is needed. Because multiple instances of several kinds of agents run in the same process, one cannot blindly use global objects like KGlobal. For this reasons several methods where added to avoid problems in this context, most notably AgentBase::config(). Additionally, one cannot use QDBusConnection::sessionBus() with dbus < 1.4, because of a multithreading bug in libdbus. Instead one should use QDBusConnection::sessionBus() which works around this problem.

Author
Till Adam adam@.nosp@m.kde..nosp@m.org, Volker Krause vkrau.nosp@m.se@k.nosp@m.de.or.nosp@m.g

Definition at line 72 of file agentbase.h.

Member Enumeration Documentation

◆ Status

This enum describes the different states the agent can be in.

Enumerator
Idle 

The agent does currently nothing.

Running 

The agent is working on something.

Broken 

The agent encountered an error state.

NotConfigured 

The agent is lacking required configuration.

Definition at line 396 of file agentbase.h.

Constructor & Destructor Documentation

◆ AgentBase()

Akonadi::AgentBase::AgentBase ( const QString & id)
protected

Creates an agent base.

Parameters
idThe instance id of the agent.

◆ ~AgentBase()

Akonadi::AgentBase::~AgentBase ( )
overrideprotected

Destroys the agent base.

Member Function Documentation

◆ abortRequested

void Akonadi::AgentBase::abortRequested ( )
signal

Emitted when another application has remotely asked the agent to abort its current operation.

Connect to this signal if your agent supports abortion. After aborting and cleaning up, agents should return to Idle status.

Since
4.4

◆ aboutData()

KAboutData AgentBase::aboutData ( ) const
protectedvirtual

Definition at line 966 of file agentbase.cpp.

◆ aboutToQuit()

void AgentBase::aboutToQuit ( )
protectedvirtual

This method is called whenever the agent application is about to quit.

Reimplement this method to do session cleanup (e.g. disconnecting from groupware server).

Definition at line 1034 of file agentbase.cpp.

◆ activities()

QStringList AgentBase::activities ( ) const
nodiscard

Returns the activities of the agent.

Since
6.3

Definition at line 1191 of file agentbase.cpp.

◆ activitiesEnabled()

bool AgentBase::activitiesEnabled ( ) const
nodiscard

Returns the activities status of the agent.

Since
6.3

Definition at line 1197 of file agentbase.cpp.

◆ advancedStatus

void Akonadi::AgentBase::advancedStatus ( const QVariantMap & status)
signal

This signal should be emitted whenever the status of the agent has been changed.

Parameters
statusThe object that describes the status change.
Since
4.6

◆ agentActivitiesChanged

void Akonadi::AgentBase::agentActivitiesChanged ( const QStringList & activities)
signal

This signal is emitted whenever the user has changed activities.

Since
6.3

◆ agentActivitiesEnabledChanged

void Akonadi::AgentBase::agentActivitiesEnabledChanged ( bool enabled)
signal

This signal is emitted whenever the user has changed enabled activities.

Since
6.3

◆ agentName()

QString AgentBase::agentName ( ) const
nodiscard

Returns the name of the agent.

Since
4.3

Definition at line 1165 of file agentbase.cpp.

◆ agentNameChanged

void Akonadi::AgentBase::agentNameChanged ( const QString & name)
signal

This signal is emitted whenever the name of the agent has changed.

Parameters
nameThe new name of the agent.
Since
4.3

◆ changeProcessed()

void AgentBase::changeProcessed ( )
protected

Marks the current change as processes and replays the next change if change recording is enabled (noop otherwise).

This method is called from the default implementation of the change notification slots. While not required when not using change recording, it is nevertheless recommended to call this method when done with processing a change notification.

Definition at line 1215 of file agentbase.cpp.

◆ changeRecorder()

ChangeRecorder * AgentBase::changeRecorder ( ) const
protected

Returns the Akonadi::ChangeRecorder object used for monitoring.

Use this to configure which parts you want to monitor.

Definition at line 1221 of file agentbase.cpp.

◆ cleanup()

void AgentBase::cleanup ( )
virtual

This method is called when the agent is removed from the system, so it can do some cleanup stuff.

Note
If you reimplement this in a subclass make sure to call this base implementation at the end.

Definition at line 1040 of file agentbase.cpp.

◆ config()

KSharedConfigPtr AgentBase::config ( )
protected

Returns the config object for this Agent.

Definition at line 1226 of file agentbase.cpp.

◆ configurationDialogAccepted

void Akonadi::AgentBase::configurationDialogAccepted ( )
signal

This signal is emitted whenever the user has accepted the configuration dialog.

Note
Implementors of agents/resources are responsible to emit this signal if the agent/resource reimplements configure().
Since
4.4

◆ configurationDialogRejected

void Akonadi::AgentBase::configurationDialogRejected ( )
signal

This signal is emitted whenever the user has rejected the configuration dialog.

Note
Implementors of agents/resources are responsible to emit this signal if the agent/resource reimplements configure().
Since
4.4

◆ configure

void AgentBase::configure ( WId windowId)
virtualslot

This method is called whenever the agent shall show its configuration dialog to the user.

It will be automatically called when the agent is started for the first time.

Parameters
windowIdThe parent window id.
Note
If the method is reimplemented it has to emit the configurationDialogAccepted() or configurationDialogRejected() signals depending on the users choice.

Definition at line 976 of file agentbase.cpp.

◆ doSetOnline()

void AgentBase::doSetOnline ( bool online)
protectedvirtual

This method is called whenever the online status has changed.

Reimplement this method to react on online status changes.

Parameters
onlineonline status

Reimplemented in Akonadi::ResourceBase.

Definition at line 961 of file agentbase.cpp.

◆ error

void Akonadi::AgentBase::error ( const QString & message)
signal

This signal shall be used to report errors.

Parameters
messageThe i18n'ed error message.

◆ identifier()

QString AgentBase::identifier ( ) const
nodiscard

Returns the instance identifier of this agent.

Definition at line 1136 of file agentbase.cpp.

◆ init()

template<typename T >
int AgentBase::init ( int argc,
char ** argv )
inlinestatic

Use this method in the main function of your agent application to initialize your agent subclass.

This method also takes care of creating a KApplication object and parsing command line arguments.

Note
In case the given class is also derived from AgentBase::Observer it gets registered as its own observer (see AgentBase::Observer), e.g. agentInstance->registerObserver( agentInstance );
class MyAgent : public AgentBase
{
...
};
AKONADI_AGENT_MAIN( MyAgent )
The base class for all Akonadi agents and resources.
Definition agentbase.h:73
Parameters
argcnumber of arguments
argvarguments for the function

Definition at line 428 of file agentbase.h.

◆ isOnline()

bool AgentBase::isOnline ( ) const
protected

Returns whether the agent is currently online.

Definition at line 879 of file agentbase.cpp.

◆ onlineChanged

void Akonadi::AgentBase::onlineChanged ( bool online)
signal

Emitted when the online state changed.

Parameters
onlineThe online state.
Since
4.2

◆ percent

void Akonadi::AgentBase::percent ( int progress)
signal

This signal should be emitted whenever the progress of an action in the agent (e.g.

data transfer, connection establishment to remote server etc.) has changed.

Parameters
progressThe progress of the action in percent.

◆ progress()

int AgentBase::progress ( ) const
nodiscardvirtual

This method returns the current progress of the agent in percentage.

Definition at line 865 of file agentbase.cpp.

◆ progressMessage()

QString AgentBase::progressMessage ( ) const
nodiscardvirtual

This method returns an i18n'ed description of the current progress.

Definition at line 872 of file agentbase.cpp.

◆ registerObserver()

void AgentBase::registerObserver ( Observer * observer)

Registers the given observer for reacting on monitored or recorded changes.

Parameters
observerThe change handler to register. No ownership transfer, i.e. the caller stays owner of the pointer and can reset the registration by calling this method with 0

Definition at line 1085 of file agentbase.cpp.

◆ reloadConfiguration

void Akonadi::AgentBase::reloadConfiguration ( )
signal

Emitted if another application has changed the agent's configuration remotely and called AgentInstance::reconfigure().

Since
4.2

◆ setActivities()

void AgentBase::setActivities ( const QStringList & activities)

This method is used to set the activities of the agent.

Since
6.3

Definition at line 1175 of file agentbase.cpp.

◆ setActivitiesEnabled()

void AgentBase::setActivitiesEnabled ( bool enabled)

This method is used to enabled the activities of the agent.

Since
6.3

Definition at line 1203 of file agentbase.cpp.

◆ setAgentName()

void AgentBase::setAgentName ( const QString & name)

This method is used to set the name of the agent.

Since
4.3
Parameters
namename of the agent

Definition at line 1141 of file agentbase.cpp.

◆ setNeedsNetwork()

void AgentBase::setNeedsNetwork ( bool needsNetwork)
protected

Sets whether the agent needs network or not.

Since
4.2
Todo
use this in combination with QNetworkConfiguration to change the onLine status of the agent.
Parameters
needsNetworktrue if the agents needs network. Defaults to false

Definition at line 886 of file agentbase.cpp.

◆ setOnline()

void AgentBase::setOnline ( bool state)
protected

Sets whether the agent shall be online or not.

Definition at line 900 of file agentbase.cpp.

◆ setTemporaryOffline()

void AgentBase::setTemporaryOffline ( int makeOnlineInSeconds = 300)
protected

Sets the agent offline but will make it online again after a given time.

Use this method when the agent detects some problem with its backend but it wants to retry all pending operations after some time - e.g. a server can not be reached currently

Example usage:

void ExampleResource::onItemRemovedFinished(KJob *job)
{
if (job->error()) {
deferTask();
return;
}
...
}
void setTemporaryOffline(int makeOnlineInSeconds=300)
Sets the agent offline but will make it online again after a given time.
virtual int status() const
This method returns the current status code of the agent.
@ Broken
The agent encountered an error state.
Definition agentbase.h:399
virtual QString errorString() const
int error() const
Q_EMITQ_EMIT
Since
4.13
Parameters
makeOnlineInSecondstimeout in seconds after which the agent changes to online

Definition at line 917 of file agentbase.cpp.

◆ status() [1/2]

int AgentBase::status ( ) const
nodiscardvirtual

This method returns the current status code of the agent.

The following return values are possible:

  • 0 - Idle
  • 1 - Running
  • 2 - Broken
  • 3 - NotConfigured

Definition at line 851 of file agentbase.cpp.

◆ status [2/2]

void Akonadi::AgentBase::status ( int status,
const QString & message = QString() )
signal

This signal should be emitted whenever the status of the agent has been changed.

Parameters
statusThe new Status code.
messageA i18n'ed description of the new status.

◆ statusMessage()

QString AgentBase::statusMessage ( ) const
nodiscardvirtual

This method returns an i18n'ed description of the current status code.

Definition at line 858 of file agentbase.cpp.

◆ warning

void Akonadi::AgentBase::warning ( const QString & message)
signal

This signal shall be used to report warnings.

Parameters
messageThe i18n'ed warning message.

◆ winIdForDialogs()

WId AgentBase::winIdForDialogs ( ) const
nodiscard

This method returns the windows id, which should be used for dialogs.

Definition at line 999 of file agentbase.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Mon Nov 4 2024 16:31:59 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.