Akonadi::AgentBase Class

Member Function Documentation

[explicit protected] AgentBase::AgentBase(const QString &id)

Creates an agent base.

id The instance id of the agent.

[override virtual noexcept protected] AgentBase::~AgentBase()

Destroys the agent base.

[signal] void AgentBase::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.

[virtual protected] void AgentBase::aboutToQuit()

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

Returns the accountId for the associated online account, if any

See also setAccountId().

[since 6.3] QStringList AgentBase::activities() const

Returns the activities of the agent.

This function was introduced in 6.3.

See also setActivities().

[since 6.3] bool AgentBase::activitiesEnabled() const

Returns the activities status of the agent.

This function was introduced in 6.3.

See also setActivitiesEnabled().

[signal] void AgentBase::advancedStatus(const QVariantMap &status)

This signal should be emitted whenever the status of the agent has been changed. status The object that describes the status change.

[signal, since 6.3] void AgentBase::agentActivitiesChanged(const QStringList &activities)

This signal is emitted whenever the user has changed activities.

This function was introduced in 6.3.

[signal, since 6.3] void AgentBase::agentActivitiesEnabledChanged(bool enabled)

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

This function was introduced in 6.3.

QString AgentBase::agentName() const

Returns the name of the agent.

[signal] void AgentBase::agentNameChanged(const QString &name)

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

name The new name of the agent.

[protected] void AgentBase::changeProcessed()

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.

[protected] Akonadi::ChangeRecorder *AgentBase::changeRecorder() const

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

[virtual] void AgentBase::cleanup()

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

[protected] KSharedConfigPtr AgentBase::config()

Returns the config object for this Agent.

[signal] void AgentBase::configurationDialogAccepted()

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

[signal] void AgentBase::configurationDialogRejected()

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

[virtual slot] void AgentBase::configure(WId 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.

windowId The parent window id.

[virtual protected] void AgentBase::doSetOnline(bool online)

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

[signal] void AgentBase::error(const QString &message)

This signal shall be used to report errors.

message The i18n'ed error message.

QString AgentBase::identifier() const

Returns the instance identifier of this agent.

[static] template <typename T> int AgentBase::initCore(int argc, char **argv)

Use this method in the main function of your agent application to initialize your agent subclass. This method also takes care of creating a QCoreApplication object and parsing command line arguments.

 class MyAgent : public AgentBase
 {
   ...
 };

 AKONADI_AGENT_CORE_MAIN( MyAgent )

argc number of arguments argv arguments for the function

[protected] bool AgentBase::isOnline() const

Returns whether the agent is currently online.

[signal] void AgentBase::onlineChanged(bool online)

Emitted when the online state changed. online The online state.

[signal] void AgentBase::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.

progress The progress of the action in percent.

[protected] QString AgentBase::programName() const

Get the application display name

[virtual] int AgentBase::progress() const

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

[virtual] QString AgentBase::progressMessage() const

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

void AgentBase::registerObserver(Akonadi::AgentBase::Observer *observer)

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

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

[signal] void AgentBase::reloadConfiguration()

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

void AgentBase::setAccountId(const QString &accountId)

Set the accountId for the associated online account

See also accountId().

[since 6.3] void AgentBase::setActivities(const QStringList &activities)

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

This function was introduced in 6.3.

See also activities().

[since 6.3] void AgentBase::setActivitiesEnabled(bool enabled)

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

This function was introduced in 6.3.

See also activitiesEnabled().

[protected] void AgentBase::setNeedsNetwork(bool needsNetwork)

Sets whether the agent needs network or not.

\todouse this in combination with QNetworkConfiguration to change the onLine status of the agent. needsNetwork true if the agents needs network. Defaults to false

[protected] void AgentBase::setOnline(bool state)

Sets whether the agent shall be online or not.

See also isOnline().

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

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

makeOnlineInSeconds timeout in seconds after which the agent changes to online

[virtual] int AgentBase::status() const

This method returns the current status code of the agent.

The following return values are possible:

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

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

This signal should be emitted whenever the status of the agent has been changed. status The new Status code. message A i18n'ed description of the new status.

 // Connect using qOverload:
 connect(agentBase, qOverload(&AgentBase::status),
         receiver, &ReceiverClass::slot);

 // Or using a lambda:
 connect(agentBase, qOverload(&AgentBase::status),
         this, [](int status, const QString &message) { /* handle status */ });

[virtual] QString AgentBase::statusMessage() const

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

[signal] void AgentBase::warning(const QString &message)

This signal shall be used to report warnings.

message The i18n'ed warning message.

WId AgentBase::winIdForDialogs() const

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