#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 }

Public Slots
virtual void	configure (WId windowId)

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 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)

	QObject (QObject parent, const char name)

bool	blockSignals (bool block)

QObject *	child (const char objName, const char inheritsClass, bool recursiveSearch) const

const QObjectList &	children () const

const char *	className () const

bool	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const

void	deleteLater ()

void	destroyed (QObject *obj)

bool	disconnect (const QObject receiver, const char method)

bool	disconnect (const char signal, const QObject receiver, const char *method)

void	dumpObjectInfo ()

void	dumpObjectTree ()

QList< QByteArray >	dynamicPropertyNames () const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	findChild (const QString &name) const

QList< T >	findChildren (const QRegExp &regExp) const

QList< T >	findChildren (const QString &name) const

bool	inherits (const char *className) const

void	insertChild (QObject *object)

void	installEventFilter (QObject *filterObj)

bool	isA (const char *className) const

bool	isWidgetType () const

void	killTimer (int id)

virtual const QMetaObject *	metaObject () const

void	moveToThread (QThread *targetThread)

const char *	name () const

const char *	name (const char *defaultName) const

QString	objectName () const

QObject *	parent () const

QVariant	property (const char *name) const

void	removeChild (QObject *object)

void	removeEventFilter (QObject *obj)

void	setName (const char *name)

void	setObjectName (const QString &name)

void	setParent (QObject *parent)

bool	setProperty (const char *name, const QVariant &value)

bool	signalsBlocked () const

int	startTimer (int interval)

QThread *	thread () const

Static Public Member Functions
static KComponentData	componentData ()

template<typename T >
static int	init (int argc, char **argv)

Static Public Member Functions inherited from QObject
bool	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

bool	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

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)

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 void	aboutToQuit ()

void	changeProcessed ()

ChangeRecorder *	changeRecorder () 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
bool	checkConnectArgs (const char signal, const QObject object, const char *method)

virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const char *signal)

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const char *signal)

int	receivers (const char *signal) const

QObject *	sender () const

int	senderSignalIndex () const

virtual void	timerEvent (QTimerEvent *event)

Protected Member Functions inherited from QDBusContext
bool	calledFromDBus () const

QDBusConnection	connection () const

bool	isDelayedReply () const

const QDBusMessage &	message () const

void	sendErrorReply (QDBusError::ErrorType type, const QString &msg) const

void	sendErrorReply (const QString &name, const QString &msg) const

void	setDelayedReply (bool enable) const

Additional Inherited Members
Static Protected Member Functions inherited from QObject
QByteArray	normalizeSignalSlot (const char *signalSlot)

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() and AgentBase::componentData(). Additionally, one cannot use QDBusConnection::sessionBus() with dbus < 1.4, because of a multithreading bug in libdbus. Instead one should use DBusConnectionPool::threadConnection() 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 80 of file agentbase.h.

Member Enumeration Documentation

enum Akonadi::AgentBase::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 411 of file agentbase.h.

Constructor & Destructor Documentation

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

protected

Creates an agent base.

Parameters

id	The 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

status The 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 1159 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

name	The 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 1169 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 1175 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.

KComponentData AgentBase::componentData ( )

static

Returns the component data object for this agent instance.

In case of stand-alone agents this is identical to KGlobal::mainComponent(). In case of in-process agents there is one component data object per agent instance thread. This method provides valid results even when called in the agent ctor.

Since: 4.6

Definition at line 1201 of file agentbase.cpp.

KSharedConfigPtr AgentBase::config ( )

protected

Returns the config object for this Agent.

Definition at line 1180 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

windowId The 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

online online status

Reimplemented in Akonadi::ResourceBase.

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

signal

This signal shall be used to report errors.

Parameters

message The i18n'ed error message.

QString AgentBase::identifier ( ) const

Returns the instance identifier of this agent.

Definition at line 1131 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

argc	number of arguments
argv	arguments for the function

Definition at line 443 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

online The 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

progress The 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

observer The 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 1061 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

name	name of the agent

Definition at line 1136 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 Solid::Networking::Notifier to change the onLine status of the agent.

Parameters

needsNetwork true 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()) {
        emit status(Broken, job->errorString());
        deferTask();
        setTemporaryOffline(300);
        return;
    }
    ...
}

Since: 4.13

Parameters

makeOnlineInSeconds timeout 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

status	The new Status code.
message	A 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

message The 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:

akonadi

Classes

Public Types

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

akonadi

kdepimlibs API Reference

Search