collection.h

/*
    Copyright (c) 2006 - 2007 Volker Krause <vkrause@kde.org>

    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_COLLECTION_H
#define AKONADI_COLLECTION_H

#include "akonadicore_export.h"
#include "attribute.h"

#include <QMetaType>
#include <QSharedDataPointer>
#include <QDebug>

class QUrl;

namespace Akonadi
{

class CachePolicy;
class CollectionPrivate;
class CollectionStatistics;

class AKONADICORE_EXPORT Collection
{
public:
    typedef qint64 Id;

    typedef QVector<Collection> List;

    enum Right {
        ReadOnly = 0x0,                   
        CanChangeItem = 0x1,              
        CanCreateItem = 0x2,              
        CanDeleteItem = 0x4,              
        CanChangeCollection = 0x8,        
        CanCreateCollection = 0x10,       
        CanDeleteCollection = 0x20,       
        CanLinkItem = 0x40,               
        CanUnlinkItem = 0x80,             
        AllRights = (CanChangeItem | CanCreateItem | CanDeleteItem |
                     CanChangeCollection | CanCreateCollection | CanDeleteCollection)  
    };
    Q_DECLARE_FLAGS(Rights, Right)

    
    Collection();

    explicit Collection(Id id);

    ~Collection();

    Collection(const Collection &other);

    static Collection fromUrl(const QUrl &url);

    void setId(Id identifier);

    Q_REQUIRED_RESULT Id id() const;

    void setRemoteId(const QString &id);

    Q_REQUIRED_RESULT QString remoteId() const;

    void setRemoteRevision(const QString &revision);

    Q_REQUIRED_RESULT QString remoteRevision() const;

    Q_REQUIRED_RESULT bool isValid() const;

    Q_REQUIRED_RESULT bool operator==(const Collection &other) const;

    Q_REQUIRED_RESULT bool operator!=(const Collection &other) const;

    Collection &operator=(const Collection &other);

    Q_REQUIRED_RESULT bool operator<(const Collection &other) const;

    Q_REQUIRED_RESULT Collection parentCollection() const;

    Q_REQUIRED_RESULT Collection &parentCollection();

    void setParentCollection(const Collection &parent);

    void addAttribute(Attribute *attribute);

    void removeAttribute(const QByteArray &name);

    bool hasAttribute(const QByteArray &name) const;

    Q_REQUIRED_RESULT Attribute::List attributes() const;

    void clearAttributes();

    Attribute *attribute(const QByteArray &name);
    const Attribute *attribute(const QByteArray &name) const;

    enum CreateOption {
        AddIfMissing,    
        DontCreate       
    };

    template <typename T>
    inline T *attribute(CreateOption option = DontCreate);

    template <typename T>
    inline const T *attribute() const;

    template <typename T>
    inline void removeAttribute();

    template <typename T>
    inline bool hasAttribute() const;

    Q_REQUIRED_RESULT QString name() const;

    Q_REQUIRED_RESULT QString displayName() const;

    void setName(const QString &name);

    Q_REQUIRED_RESULT Rights rights() const;

    void setRights(Rights rights);

    Q_REQUIRED_RESULT QStringList contentMimeTypes() const;

    void setContentMimeTypes(const QStringList &types);

    Q_REQUIRED_RESULT static Collection root();

    Q_REQUIRED_RESULT static QString mimeType();

    Q_REQUIRED_RESULT static QString virtualMimeType();

    Q_REQUIRED_RESULT QString resource() const;

    void setResource(const QString &identifier);

    Q_REQUIRED_RESULT CachePolicy cachePolicy() const;

    void setCachePolicy(const CachePolicy &policy);

    Q_REQUIRED_RESULT CollectionStatistics statistics() const;

    void setStatistics(const CollectionStatistics &statistics);

    enum UrlType {
        UrlShort = 0,     
        UrlWithName = 1   
    };

    Q_REQUIRED_RESULT QUrl url(UrlType type = UrlShort) const;

    Q_REQUIRED_RESULT bool isVirtual() const;

    void setVirtual(bool isVirtual);

    void setEnabled(bool enabled);

    Q_REQUIRED_RESULT bool enabled() const;

    enum ListPreference {
        ListEnabled,  
        ListDisabled, 
        ListDefault   
    };

    enum ListPurpose {
        ListSync,     
        ListDisplay,  
        ListIndex     
    };

    void setLocalListPreference(ListPurpose purpose, ListPreference preference);

    Q_REQUIRED_RESULT ListPreference localListPreference(ListPurpose purpose) const;

    Q_REQUIRED_RESULT bool shouldList(ListPurpose purpose) const;

    void setShouldList(ListPurpose purpose, bool shouldList);

    void setKeepLocalChanges(const QSet<QByteArray> &parts);

    QSet<QByteArray> keepLocalChanges() const;

private:
    friend class CollectionCreateJob;
    friend class CollectionFetchJob;
    friend class CollectionModifyJob;
    friend class ProtocolHelper;

    void markAttributeModified(const QByteArray &type);

    //@cond PRIVATE
    QSharedDataPointer<CollectionPrivate> d_ptr;
    friend class CollectionPrivate;
    //@endcond
};

AKONADICORE_EXPORT uint qHash(const Akonadi::Collection &collection);

template <typename T>
inline T *Akonadi::Collection::attribute(Collection::CreateOption option)
{
    const QByteArray type = T().type();
    markAttributeModified(type); // do this first in case it detaches
    if (hasAttribute(type)) {
        if (T *attr = dynamic_cast<T *>(attribute(type))) {
            return attr;
        }
        qWarning() << "Found attribute of unknown type" << type
                   << ". Did you forget to call AttributeFactory::registerAttribute()?";
    } else if (option == AddIfMissing) {
        T *attr = new T();
        addAttribute(attr);
        return attr;
    }

    return nullptr;
}

template <typename T>
inline const T *Akonadi::Collection::attribute() const
{
    const QByteArray type = T().type();
    if (hasAttribute(type)) {
        if (const T *attr = dynamic_cast<const T *>(attribute(type))) {
            return attr;
        }
        qWarning() << "Found attribute of unknown type" << type
                   << ". Did you forget to call AttributeFactory::registerAttribute()?";
    }

    return nullptr;
}

template <typename T>
inline void Akonadi::Collection::removeAttribute()
{
    removeAttribute(T().type());
}

template <typename T>
inline bool Akonadi::Collection::hasAttribute() const
{
    return hasAttribute(T().type());
}

} // namespace Akonadi

AKONADICORE_EXPORT QDebug operator<<(QDebug d, const Akonadi::Collection &collection);

Q_DECLARE_METATYPE(Akonadi::Collection)
Q_DECLARE_METATYPE(Akonadi::Collection::List)
Q_DECLARE_OPERATORS_FOR_FLAGS(Akonadi::Collection::Rights)
Q_DECLARE_TYPEINFO(Akonadi::Collection, Q_MOVABLE_TYPE);

#endif