KDE 4.6 PyKDE API Reference

- KDE's Python API

# AgentBase Class Reference

`from PyKDE4.akonadi import *`

Inherits: QObject
Subclasses: Akonadi.PreprocessorBase, Akonadi.ResourceBase
Namespace: Akonadi

## 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 serveral ways to launch agents and resources: - As a seperate application (@see AKONADI_AGENT_MAIN) - As a thread in the AgentServer - As a seperate process, using the akonadi_agent_launcher

The idea is this, the agent or resource is written as a plugin instead of an executable (@see AgentFactory). In the AgentServer case, the AgentServer looks up the plugin and launches the agent in a seperate 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@kde.org>, Volker Krause <vkrause@kde.org>

## Enumerations

Status | { Idle, Running, Broken }

## Signals

| abortRequested ()
| advancedStatus ({QString:QVariant} status)
| agentNameChanged (QString name)
| configurationDialogAccepted ()
| configurationDialogRejected ()
| error (QString message)
| onlineChanged (bool online)
| percent (int progress)
| reloadConfiguration ()
| status (int status, QString message=QString())
| warning (QString message)

## Methods

| __init__ (self, QString id)
| aboutToQuit (self)
QString | agentName (self)
| changeProcessed (self)
Akonadi.ChangeRecorder | changeRecorder (self)
| cleanup (self)
KSharedPtr<KSharedConfig> | config (self)
| configure (self, int windowId)
| doSetOnline (self, bool online)
QString | identifier (self)
bool | isOnline (self)
int | progress (self)
QString | progressMessage (self)
| registerObserver (self, Akonadi.AgentBase.Observer observer)
| setAgentName (self, QString name)
| setNeedsNetwork (self, bool needsNetwork)
| setOnline (self, bool state)
int | status (self)
QString | statusMessage (self)
int | winIdForDialogs (self)

## Static Methods

KComponentData | componentData ()

## Signal Documentation

abortRequested | ( |  | ) |

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

Signal syntax:
  `QObject.connect(source, SIGNAL("abortRequested()"), target_slot)`

advancedStatus | ( | {QString:QVariant} | status
| ) |  |  |

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

Signal syntax:
  `QObject.connect(source, SIGNAL("advancedStatus(const QVariantMap&)"), target_slot)`

agentNameChanged | ( | QString | name
| ) |  |  |

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

Parameters:

  | name | The new name of the agent.

Since:
  4.3

Signal syntax:
  `QObject.connect(source, SIGNAL("agentNameChanged(const QString&)"), target_slot)`

configurationDialogAccepted | ( |  | ) |

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

Signal syntax:
  `QObject.connect(source, SIGNAL("configurationDialogAccepted()"), target_slot)`

configurationDialogRejected | ( |  | ) |

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

Signal syntax:
  `QObject.connect(source, SIGNAL("configurationDialogRejected()"), target_slot)`

error | ( | QString | message
| ) |  |  |

This signal shall be used to report errors.

Parameters:

  | message | The i18n'ed error message.

Signal syntax:
  `QObject.connect(source, SIGNAL("error(const QString&)"), target_slot)`

onlineChanged | ( | bool | online
| ) |  |  |

Emitted when the online state changed.

Parameters:

  | online | The online state.

Since:
  4.2

Signal syntax:
  `QObject.connect(source, SIGNAL("onlineChanged(bool)"), target_slot)`

percent | ( | int | progress
| ) |  |  |

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.

Signal syntax:
  `QObject.connect(source, SIGNAL("percent(int)"), target_slot)`

reloadConfiguration | ( |  | ) |

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

Since:
  4.2

Signal syntax:
  `QObject.connect(source, SIGNAL("reloadConfiguration()"), target_slot)`

status | ( | int | status,
|  | QString | message=QString()
| ) |  |  |

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.

Signal syntax:
  `QObject.connect(source, SIGNAL("status(int, const QString&)"), target_slot)`

warning | ( | QString | message
| ) |  |  |

This signal shall be used to report warnings.

Parameters:

  | message | The i18n'ed warning message.

Signal syntax:
  `QObject.connect(source, SIGNAL("warning(const QString&)"), target_slot)`

## Method Documentation

__init__ | ( | self, |
|  | QString | id
| ) |  |  |

Creates an agent base.

Parameters:

  | id | The instance id of the agent.

aboutToQuit | ( |  | self ) |

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

QString agentName | ( |  | self ) |

Returns the name of the agent.

Since:
  4.3

changeProcessed | ( |  | self ) |

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.

Akonadi.ChangeRecorder changeRecorder | ( |  | self ) |

Returns the Akonadi.ChangeRecorder object used for monitoring. Use this to configure which parts you want to monitor.

cleanup | ( |  | self ) |

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.

KSharedPtr<KSharedConfig> config | ( |  | self ) |

Returns the config object for this Agent.

configure | ( | self, |
|  | int | windowId
| ) |  |  |

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.

doSetOnline | ( | self, |
|  | bool | online
| ) |  |  |

This method is called whenever the online status has changed. Reimplement this method to react on online status changes.

QString identifier | ( |  | self ) |

Returns the instance identifier of this agent.

bool isOnline | ( |  | self ) |

Returns whether the agent is currently online.

int progress | ( |  | self ) |

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

QString progressMessage | ( |  | self ) |

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

registerObserver | ( | self, |
|  | Akonadi.AgentBase.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

setAgentName | ( | self, |
|  | QString | name
| ) |  |  |

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

Since:
  4.3

setNeedsNetwork | ( | self, |
|  | bool | needsNetwork
| ) |  |  |

Sets whether the agent needs network or not.

Since:
  4.2

To do: use this in combination with Solid.Networking.Notifier to change the onLine status of the agent.

setOnline | ( | self, |
|  | bool | state
| ) |  |  |

Sets whether the agent shall be online or not.

int status | ( |  | self ) |

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.

QString statusMessage | ( |  | self ) |

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

int winIdForDialogs | ( |  | self ) |

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

## Static Method Documentation

KComponentData componentData | ( |  | ) |

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

## Enumeration Documentation

Status

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

Enumerator:

  Idle = 0 |
  Running |
  Broken |