item.h

/*
    Copyright (c) 2006 Volker Krause <vkrause@kde.org>
                  2007 Till Adam <adam@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_ITEM_H
#define AKONADI_ITEM_H

#include "akonadi_export.h"

#include <akonadi/entity.h>
#include <akonadi/exception.h>
#include "itempayloadinternals_p.h"

#include <QtCore/QByteArray>
#include <QtCore/QMetaType>
#include <QtCore/QSet>

#include <boost/static_assert.hpp>
#include <boost/type_traits/is_pointer.hpp>
#include <boost/utility/enable_if.hpp>

#include <typeinfo>
#include <memory>

class KUrl;

template <typename T>
class QVector;

namespace Akonadi {

class ItemPrivate;

class AKONADI_EXPORT Item : public Entity
{
  public:
    typedef QList<Item> List;

    typedef QByteArray Flag;

    typedef QSet<QByteArray> Flags;

    static const char* FullPayload;

    Item();

    explicit Item( Id id );

    explicit Item( const QString &mimeType );

    Item( const Item &other );

    ~Item();

    static Item fromUrl( const KUrl &url );

    Flags flags() const;

    QDateTime modificationTime() const;

    void setModificationTime( const QDateTime &datetime );

    bool hasFlag( const QByteArray &name ) const;

    void setFlag( const QByteArray &name );

    void clearFlag( const QByteArray &name );

    void setFlags( const Flags &flags );

    void clearFlags();

    void setPayloadFromData( const QByteArray &data );

    QByteArray payloadData() const;

    QSet<QByteArray> loadedPayloadParts() const;

    void clearPayload();

    void setRevision( int revision );

    int revision() const;

    Entity::Id storageCollectionId() const;

    void setSize( qint64 size );

    qint64 size() const;

    void setMimeType( const QString &mimeType );

    QString mimeType() const;

    void setGid( const QString &gid );

    QString gid() const;

    QVector<int> availablePayloadMetaTypeIds() const;

    template <typename T> void setPayload( const T &p );
    //@cond PRIVATE
    template <typename T> void setPayload( T* p );
    template <typename T> void setPayload( std::auto_ptr<T> p );
    //@endcond

    template <typename T> T payload() const;

    bool hasPayload() const;

    template <typename T> bool hasPayload() const;

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

    KUrl url( UrlType type = UrlShort ) const;

    QSet<QByteArray> availablePayloadParts() const;

    QSet<QByteArray> cachedPayloadParts() const;

    void apply( const Item &other );

    template <typename T> static void addToLegacyMapping( const QString & mimeType );
    void setCachedPayloadParts(const QSet<QByteArray> &cachedParts);

  private:
    //@cond PRIVATE
    friend class ItemCreateJob;
    friend class ItemModifyJob;
    friend class ItemModifyJobPrivate;
    friend class ItemSync;
    friend class ProtocolHelper;
    PayloadBase* payloadBase() const;
    void setPayloadBase( PayloadBase* );
    PayloadBase* payloadBaseV2( int sharedPointerId, int metaTypeId ) const;
    //std::auto_ptr<PayloadBase> takePayloadBase( int sharedPointerId, int metaTypeId );
    void setPayloadBaseV2( int sharedPointerId, int metaTypeId, std::auto_ptr<PayloadBase> p );
    void addPayloadBaseVariant( int sharedPointerId, int metaTypeId, std::auto_ptr<PayloadBase> p ) const;
    static void addToLegacyMappingImpl( const QString & mimeType, int sharedPointerId, int metaTypeId, std::auto_ptr<PayloadBase> p );

    bool ensureMetaTypeId( int mtid ) const;

    template <typename T>
    typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,void>::type
    setPayloadImpl( const T &, const int * /*disambiguate*/ = 0 );
    template <typename T>
    typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,void>::type
    setPayloadImpl( const T & );

    template <typename T>
    typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,T>::type
    payloadImpl( const int * /*disambiguate*/ = 0 ) const;
    template <typename T>
    typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,T>::type
    payloadImpl() const;

    template <typename T>
    typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,bool>::type
    hasPayloadImpl( const int * /*disambiguate*/ = 0 ) const;
    template <typename T>
    typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,bool>::type
    hasPayloadImpl() const;

    template <typename T>
    typename boost::enable_if<Internal::is_shared_pointer<T>,bool>::type
    tryToClone( T *, const int * /*disambiguate*/ = 0 ) const;
    template <typename T>
    typename boost::disable_if<Internal::is_shared_pointer<T>,bool>::type
    tryToClone( T * ) const;

    void setStorageCollectionId( Entity::Id collectionId);

#if 0

    QString payloadExceptionText( int spid, int mtid ) const;

    inline void throwPayloadException( int spid, int mtid ) const {
        throw PayloadException( payloadExceptionText( spid, mtid ) );
    }
#else
    void throwPayloadException( int spid, int mtid ) const;
#endif
    //@endcond

    AKONADI_DECLARE_PRIVATE( Item )
};

template <typename T>
T Item::payload() const
{
  BOOST_STATIC_ASSERT( !boost::is_pointer<T>::value );

  if ( !hasPayload() )
    throwPayloadException( -1, -1 );

  return payloadImpl<T>();
}

template <typename T>
typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,T>::type
Item::payloadImpl( const int * ) const
{
  typedef Internal::PayloadTrait<T> PayloadType;
  BOOST_STATIC_ASSERT(( PayloadType::isPolymorphic ));

  typedef typename Internal::get_hierarchy_root<T>::type Root_T;
  typedef Internal::PayloadTrait<Root_T> RootType;
  BOOST_STATIC_ASSERT(( !RootType::isPolymorphic )); // prevent endless recursion

  return PayloadType::castFrom( payloadImpl<Root_T>() );
}

template <typename T>
typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,T>::type
Item::payloadImpl() const
{
  typedef Internal::PayloadTrait<T> PayloadType;
  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));

  const int metaTypeId = PayloadType::elementMetaTypeId();

  // make sure that we have a payload format represented by 'metaTypeId':
  if ( !ensureMetaTypeId( metaTypeId ) )
      throwPayloadException( PayloadType::sharedPointerId, metaTypeId );

  // Check whether we have the exact payload
  // (metatype id and shared pointer type match)
  if ( const Payload<T> * const p = Internal::payload_cast<T>( payloadBaseV2( PayloadType::sharedPointerId, metaTypeId ) ) )
      return p->payload;

  T ret;
  if ( !tryToClone<T>( &ret ) )
      throwPayloadException( PayloadType::sharedPointerId, metaTypeId );
  return ret;
}

template <typename T>
typename boost::enable_if<Internal::is_shared_pointer<T>,bool>::type
Item::tryToClone( T * ret, const int * ) const
{
  typedef Internal::PayloadTrait<T> PayloadType;
  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));

  const int metaTypeId = PayloadType::elementMetaTypeId();

  // Check whether we have the same payload in 'the other
  // shared pointer' (### make it recurse, trying to find one, but
  // don't introduce infinite recursion):
  typedef typename Internal::shared_pointer_traits<T>::next_shared_ptr NewT;
  typedef Internal::PayloadTrait<NewT> NewPayloadType;

  if ( const Payload<NewT> * const p = Internal::payload_cast<NewT>( payloadBaseV2( NewPayloadType::sharedPointerId, metaTypeId ) ) ) {
      // If found, attempt to make a clone (required the payload to provide virtual T * T::clone() const)
      const T nt = PayloadType::clone( p->payload );
      if ( !PayloadType::isNull( nt ) ) {
          // if clone succeeded, add the clone to the Item:
          std::auto_ptr<PayloadBase> npb( new Payload<T>( nt ) );
          addPayloadBaseVariant( PayloadType::sharedPointerId, metaTypeId, npb  );
          // and return it
          if ( ret ) {
            *ret = nt;
          }
          return true;
      }
  }

  return false;
}

template <typename T>
typename boost::disable_if<Internal::is_shared_pointer<T>, bool>::type
Item::tryToClone( T * ) const
{
  typedef Internal::PayloadTrait<T> PayloadType;
  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));

  return false;
}

template <typename T>
bool Item::hasPayload() const
{
  BOOST_STATIC_ASSERT( !boost::is_pointer<T>::value );
  return hasPayload() && hasPayloadImpl<T>();
}

template <typename T>
typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,bool>::type
Item::hasPayloadImpl( const int * ) const
{
  typedef Internal::PayloadTrait<T> PayloadType;
  BOOST_STATIC_ASSERT(( PayloadType::isPolymorphic ));

  typedef typename Internal::get_hierarchy_root<T>::type Root_T;
  typedef Internal::PayloadTrait<Root_T> RootType;
  BOOST_STATIC_ASSERT(( !RootType::isPolymorphic )); // prevent endless recursion

  try {
      return hasPayloadImpl<Root_T>()
          && PayloadType::canCastFrom( payload<Root_T>() );
  } catch ( const Akonadi::PayloadException & ) {
      return false;
  }
}

template <typename T>
typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,bool>::type
Item::hasPayloadImpl() const
{
  typedef Internal::PayloadTrait<T> PayloadType;
  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));

  const int metaTypeId = PayloadType::elementMetaTypeId();

  // make sure that we have a payload format represented by 'metaTypeId':
  if ( !ensureMetaTypeId( metaTypeId ) )
      return false;

  // Check whether we have the exact payload
  // (metatype id and shared pointer type match)
  if ( const Payload<T> * const p = Internal::payload_cast<T>( payloadBaseV2( PayloadType::sharedPointerId, metaTypeId ) ) )
      return true;

  return tryToClone<T>( 0 );
}

template <typename T>
void Item::setPayload( const T &p )
{
  BOOST_STATIC_ASSERT(( !boost::is_pointer<T>::value ));
  setPayloadImpl( p );
}

template <typename T>
typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic>::type
Item::setPayloadImpl( const T & p, const int * )
{
  typedef Internal::PayloadTrait<T> PayloadType;
  BOOST_STATIC_ASSERT(( PayloadType::isPolymorphic ));

  typedef typename Internal::get_hierarchy_root<T>::type Root_T;
  typedef Internal::PayloadTrait<Root_T> RootType;
  BOOST_STATIC_ASSERT(( !RootType::isPolymorphic )); // prevent endless recursion

  setPayloadImpl<Root_T>( p );
}

template <typename T>
typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic>::type
Item::setPayloadImpl( const T & p )
{
  typedef Internal::PayloadTrait<T> PayloadType;
  std::auto_ptr<PayloadBase> pb( new Payload<T>( p ) );
  setPayloadBaseV2( PayloadType::sharedPointerId,
                    PayloadType::elementMetaTypeId(),
                    pb );
}

template <typename T>
void Item::setPayload( T* p )
{
  p->You_MUST_NOT_use_a_pointer_as_payload;
}

template <typename T>
void Item::setPayload( std::auto_ptr<T> p )
{
  p.Nice_try_but_a_std_auto_ptr_is_not_allowed_as_payload_either;
}

template <typename T>
void Item::addToLegacyMapping( const QString & mimeType ) {
  typedef Internal::PayloadTrait<T> PayloadType;
  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));
  std::auto_ptr<PayloadBase> p( new Payload<T> );
  addToLegacyMappingImpl( mimeType, PayloadType::sharedPointerId, PayloadType::elementMetaTypeId(), p );
}

}

Q_DECLARE_METATYPE(Akonadi::Item)
Q_DECLARE_METATYPE(Akonadi::Item::List)

#endif