agentbase.h

/*
    This file is part of akonadiresources.

    Copyright (c) 2006 Till Adam <adam@kde.org>
    Copyright (c) 2007 Volker Krause <vkrause@kde.org>
    Copyright (c) 2008 Kevin Krammer <kevin.krammer@gmx.at>

    This library is free software; you can redistribute it and/or modify it
    under the terms of the GNU Library General Public License as published by
    the Free Software Foundation; either version 2 of the License, or (at your
    option) any later version.

    This library is distributed in the hope that it will be useful, but WITHOUT
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
    License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to the
    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
    02110-1301, USA.
*/

#ifndef AKONADI_AGENTBASE_H
#define AKONADI_AGENTBASE_H

#include "akonadi_export.h"
#include <akonadi/item.h>

#include <KDE/KApplication>

#include <QtDBus/QDBusConnection>
#include <QtDBus/QDBusContext>

class Akonadi__ControlAdaptor;
class Akonadi__StatusAdaptor;

namespace Akonadi {

class AgentBasePrivate;
class ChangeRecorder;
class Collection;
class Item;
class Session;

class AKONADI_EXPORT AgentBase : public QObject, protected QDBusContext
{
    Q_OBJECT

public:
    class AKONADI_EXPORT Observer  // krazy:exclude=dpointer
    {
    public:
        Observer();

        virtual ~Observer();

        virtual void itemAdded(const Akonadi::Item &item, const Akonadi::Collection &collection);

        virtual void itemChanged(const Akonadi::Item &item, const QSet<QByteArray> &partIdentifiers);

        virtual void itemRemoved(const Akonadi::Item &item);

        virtual void collectionAdded(const Akonadi::Collection &collection, const Akonadi::Collection &parent);

        virtual void collectionChanged(const Akonadi::Collection &collection);

        virtual void collectionRemoved(const Akonadi::Collection &collection);
    };

    class AKONADI_EXPORT ObserverV2 : public Observer  // krazy:exclude=dpointer
    {
    public:
        using Observer::collectionChanged;

        virtual void itemMoved(const Akonadi::Item &item, const Akonadi::Collection &collectionSource,
                               const Akonadi::Collection &collectionDestination);

        virtual void itemLinked(const Akonadi::Item &item, const Akonadi::Collection &collection);

        virtual void itemUnlinked(const Akonadi::Item &item, const Akonadi::Collection &collection);

        virtual void collectionMoved(const Akonadi::Collection &collection, const Akonadi::Collection &collectionSource,
                                     const Akonadi::Collection &collectionDestination);

        virtual void collectionChanged(const Akonadi::Collection &collection, const QSet<QByteArray> &changedAttributes);
    };

    class AKONADI_EXPORT ObserverV3 : public ObserverV2 // krazy:exclude=dpointer
    {
    public:
        virtual void itemsFlagsChanged(const Akonadi::Item::List &items, const QSet<QByteArray> &addedFlags, const QSet<QByteArray> &removedFlags);

        virtual void itemsRemoved(const Akonadi::Item::List &items);

        virtual void itemsMoved(const Akonadi::Item::List &items, const Akonadi::Collection &sourceCollection,
                                const Akonadi::Collection &destinationCollection);

        virtual void itemsLinked(const Akonadi::Item::List &items, const Akonadi::Collection &collection);

        virtual void itemsUnlinked(const Akonadi::Item::List &items, const Akonadi::Collection &collection);
    };

    class AKONADI_EXPORT ObserverV4 : public ObserverV3 // krazy:exclude=dpointer
    {
    public:
        virtual void tagAdded(const Akonadi::Tag &tag);

        virtual void tagChanged(const Akonadi::Tag &tag);

        virtual void tagRemoved(const Akonadi::Tag &tag);

        virtual void itemsTagsChanged(const Akonadi::Item::List &items, const QSet<Akonadi::Tag> &addedTags, const QSet<Akonadi::Tag> &removedTags);
    };

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

    template <typename T>
    static int init(int argc, char **argv)
    {
        const QString id = parseArguments(argc, argv);
        KApplication app;
        T *r = new T(id);

        // check if T also inherits AgentBase::Observer and
        // if it does, automatically register it on itself
        Observer *observer = dynamic_cast<Observer *>(r);
        if (observer != 0) {
            r->registerObserver(observer);
        }
        return init(r);
    }

    virtual int status() const;

    virtual QString statusMessage() const;

    virtual int progress() const;

    virtual QString progressMessage() const;

public Q_SLOTS:
    virtual void configure(WId windowId);

public:
    WId winIdForDialogs() const;

#ifdef Q_OS_WIN

    void configure(qlonglong windowId);
#endif

    QString identifier() const;

    virtual void cleanup();

    void registerObserver(Observer *observer);

    //FIXME_API: make sure location is renamed to this by agentbase
    void setAgentName(const QString &name);

    QString agentName() const;

    static KComponentData componentData();

Q_SIGNALS:
    void agentNameChanged(const QString &name);

    void status(int status, const QString &message = QString());

    void percent(int progress);

    void warning(const QString &message);

    void error(const QString &message);

    void advancedStatus(const QVariantMap &status);

    void abortRequested();

    void reloadConfiguration();

    void onlineChanged(bool online);

    void configurationDialogAccepted();

    void configurationDialogRejected();

protected:
    AgentBase(const QString &id);

    ~AgentBase();

    virtual void aboutToQuit();

    ChangeRecorder *changeRecorder() const;

    KSharedConfigPtr config();

    void changeProcessed();

    bool isOnline() const;

    void setNeedsNetwork(bool needsNetwork);

    void setOnline(bool state);

protected:
    void setTemporaryOffline(int makeOnlineInSeconds = 300);

    //@cond PRIVATE
    AgentBasePrivate *d_ptr;
    explicit AgentBase(AgentBasePrivate *d, const QString &id);
    friend class ObserverV2;
    //@endcond

    virtual void doSetOnline(bool online);

private:
    //@cond PRIVATE
    static QString parseArguments(int, char **);
    static int init(AgentBase *r);
    void setOnlineInternal(bool state);

    // D-Bus interface stuff
    void abort();
    void reconfigure();
    void quit();

    // dbus agent interface
    friend class ::Akonadi__StatusAdaptor;
    friend class ::Akonadi__ControlAdaptor;

    Q_DECLARE_PRIVATE(AgentBase)
    Q_PRIVATE_SLOT(d_func(), void delayedInit())
    Q_PRIVATE_SLOT(d_func(), void slotStatus(int, const QString &))
    Q_PRIVATE_SLOT(d_func(), void slotPercent(int))
    Q_PRIVATE_SLOT(d_func(), void slotWarning(const QString &))
    Q_PRIVATE_SLOT(d_func(), void slotError(const QString &))
    Q_PRIVATE_SLOT(d_func(), void slotNetworkStatusChange(Solid::Networking::Status))
    Q_PRIVATE_SLOT(d_func(), void slotResumedFromSuspend())
    Q_PRIVATE_SLOT(d_func(), void slotTemporaryOfflineTimeout())

    //@endcond
};

}

#ifndef AKONADI_AGENT_MAIN

#define AKONADI_AGENT_MAIN( agentClass )                       \
  int main( int argc, char **argv )                            \
  {                                                            \
    return Akonadi::AgentBase::init<agentClass>( argc, argv ); \
  }
#endif

#endif