• Skip to content
  • Skip to link menu
  • KDE API Reference
  • kdepimlibs-4.10.5 API Reference
  • KDE Home
  • Contact Us
 

akonadi

  • Akonadi
  • AgentBase
Classes | Public Types | Public Slots | Signals | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
Akonadi::AgentBase Class Reference

#include <agentbase.h>

Inheritance diagram for Akonadi::AgentBase:
Akonadi::PreprocessorBase Akonadi::ResourceBase

Classes

class  Observer
 
class  ObserverV2
 

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
 

Static Public Member Functions

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

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)
 

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 79 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 302 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
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 714 of file agentbase.cpp.

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 789 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 799 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 805 of file agentbase.cpp.

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

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

KSharedConfigPtr AgentBase::config ( )
protected

Returns the config object for this Agent.

Definition at line 810 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
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 668 of file agentbase.cpp.

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.

Reimplemented in Akonadi::ResourceBase.

Definition at line 663 of file agentbase.cpp.

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

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 )

Definition at line 331 of file agentbase.h.

bool AgentBase::isOnline ( ) const
protected

Returns whether the agent is currently online.

Definition at line 617 of file agentbase.cpp.

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.
int AgentBase::progress ( ) const
virtual

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

Definition at line 603 of file agentbase.cpp.

QString AgentBase::progressMessage ( ) const
virtual

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

Definition at line 610 of file agentbase.cpp.

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

Definition at line 766 of file agentbase.cpp.

void 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.

Definition at line 624 of file agentbase.cpp.

void AgentBase::setOnline ( bool  state)
protected

Sets whether the agent shall be online or not.

Definition at line 641 of file agentbase.cpp.

int 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

Definition at line 589 of file agentbase.cpp.

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.
QString AgentBase::statusMessage ( ) const
virtual

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

Definition at line 596 of file agentbase.cpp.

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

This signal shall be used to report warnings.

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

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

Definition at line 681 of file agentbase.cpp.


The documentation for this class was generated from the following files:
  • agentbase.h
  • agentbase.cpp
This file is part of the KDE documentation.
Documentation copyright © 1996-2013 The KDE developers.
Generated on Sat Jul 13 2013 01:27:45 by doxygen 1.8.3.1 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.

akonadi

Skip menu "akonadi"
  • Main Page
  • Namespace List
  • Namespace Members
  • Alphabetical List
  • Class List
  • Class Hierarchy
  • Class Members
  • File List
  • Modules
  • Related Pages

kdepimlibs-4.10.5 API Reference

Skip menu "kdepimlibs-4.10.5 API Reference"
  • akonadi
  •   contact
  •   kmime
  •   socialutils
  • kabc
  • kalarmcal
  • kblog
  • kcal
  • kcalcore
  • kcalutils
  • kholidays
  • kimap
  • kioslave
  •   imap4
  •   mbox
  •   nntp
  • kldap
  • kmbox
  • kmime
  • kontactinterface
  • kpimidentities
  • kpimtextedit
  • kpimutils
  • kresources
  • ktnef
  • kxmlrpcclient
  • mailtransport
  • microblog
  • qgpgme
  • syndication
  •   atom
  •   rdf
  •   rss2
Report problems with this website to our bug tracking system.
Contact the specific authors with questions and comments about the page contents.

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal