Akonadi::AgentBase

#include <agentbase.h>

Inheritance diagram for Akonadi::AgentBase:

Classes

class  Observer
 
class  ObserverV2
 
class  ObserverV3
 
class  ObserverV4
 

Public Types

enum  Status { Idle = 0, Running, Broken, NotConfigured }
 

Signals

void abortRequested ()
 
void advancedStatus (const QVariantMap &status)
 
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

QString agentName () const
 
virtual void cleanup ()
 
QString identifier () const
 
virtual int progress () const
 
virtual QString progressMessage () const
 
void registerObserver (Observer *observer)
 
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)
 
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 ()
 
void dumpObjectInfo () const const
 
void dumpObjectTree ()
 
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 QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
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_DISABLE_COPY (Class)
 
 Q_DISABLE_COPY_MOVE (Class)
 
 Q_DISABLE_MOVE (Class)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 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
 
qFindChild (const QObject *obj, const QString &name)
 
QList< T > qFindChildren (const QObject *obj, const QRegExp &regExp)
 
QList< T > qFindChildren (const QObject *obj, const QString &name)
 
qobject_cast (QObject *object)
 
qobject_cast (const QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds time, 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 *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
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, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 

Protected Member Functions

 AgentBase (const QString &id)
 
 ~AgentBase ()
 
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 (QDBusError::ErrorType type, const QString &msg) const const
 
void sendErrorReply (const QString &name, const QString &msg) const const
 
void setDelayedReply (bool enable) const const
 

Additional Inherited Members

- Properties inherited from QObject
 objectName
 
- Public Attributes inherited from QObject
typedef QObjectList
 

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 [email protected][email protected]kde.[email protected]org, Volker Krause vkrau[email protected][email protected][email protected]de.or[email protected]g

Definition at line 71 of file agentbase.h.

Member Enumeration Documentation

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 422 of file agentbase.h.

Constructor & Destructor Documentation

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

Creates an agent base.

Parameters
idThe instance id of the agent.
Akonadi::AgentBase::~AgentBase ( )
protected

Destroys the agent base.

Member Function Documentation

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
virtual void Akonadi::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).

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
QString AgentBase::agentName ( ) const

Returns the name of the agent.

Since
4.3

Definition at line 1249 of file agentbase.cpp.

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
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 1259 of file agentbase.cpp.

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 1265 of file agentbase.cpp.

virtual void Akonadi::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.
KSharedConfigPtr AgentBase::config ( )
protected

Returns the config object for this Agent.

Definition at line 1270 of file agentbase.cpp.

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
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
virtual void Akonadi::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.
virtual void Akonadi::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.

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

This signal shall be used to report errors.

Parameters
messageThe i18n'ed error message.
QString AgentBase::identifier ( ) const

Returns the instance identifier of this agent.

Definition at line 1220 of file agentbase.cpp.

template<typename T >
static int Akonadi::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 )
Parameters
argcnumber of arguments
argvarguments for the function

Definition at line 454 of file agentbase.h.

bool Akonadi::AgentBase::isOnline ( ) const
protected

Returns whether the agent is currently online.

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

Emitted when the online state changed.

Parameters
onlineThe online state.
Since
4.2
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.
virtual int Akonadi::AgentBase::progress ( ) const
virtual

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

virtual QString Akonadi::AgentBase::progressMessage ( ) const
virtual

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

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 1176 of file agentbase.cpp.

void Akonadi::AgentBase::reloadConfiguration ( )
signal

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

Since
4.2
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 1225 of file agentbase.cpp.

void Akonadi::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
void Akonadi::AgentBase::setOnline ( bool  state)
protected

Sets whether the agent shall be online or not.

void Akonadi::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;
}
...
}
Since
4.13
Parameters
makeOnlineInSecondstimeout in seconds after which the agent changes to online
virtual int Akonadi::AgentBase::status ( ) const
virtual

This method returns the current status code of the agent.

The following return values are possible:

  • 0 - Idle
  • 1 - Running
  • 2 - Broken
  • 3 - NotConfigured
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.
virtual QString Akonadi::AgentBase::statusMessage ( ) const
virtual

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

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

This signal shall be used to report warnings.

Parameters
messageThe i18n'ed warning message.
WId Akonadi::AgentBase::winIdForDialogs ( ) const

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


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Thu Aug 13 2020 23:16:24 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.