• Skip to content
  • Skip to link menu
  • KDE API Reference
  • kdepimlibs-4.13.3 API Reference
  • KDE Home
  • Contact Us
 

akonadi

  • akonadi
item.h
1 /*
2  Copyright (c) 2006 Volker Krause <vkrause@kde.org>
3  2007 Till Adam <adam@kde.org>
4 
5  This library is free software; you can redistribute it and/or modify it
6  under the terms of the GNU Library General Public License as published by
7  the Free Software Foundation; either version 2 of the License, or (at your
8  option) any later version.
9 
10  This library is distributed in the hope that it will be useful, but WITHOUT
11  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12  FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13  License for more details.
14 
15  You should have received a copy of the GNU Library General Public License
16  along with this library; see the file COPYING.LIB. If not, write to the
17  Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18  02110-1301, USA.
19 */
20 
21 #ifndef AKONADI_ITEM_H
22 #define AKONADI_ITEM_H
23 
24 #include "akonadi_export.h"
25 
26 #include <akonadi/entity.h>
27 #include <akonadi/exception.h>
28 #include <akonadi/tag.h>
29 #include "itempayloadinternals_p.h"
30 
31 #include <QtCore/QByteArray>
32 #include <QtCore/QMetaType>
33 #include <QtCore/QSet>
34 
35 #include <boost/static_assert.hpp>
36 #include <boost/type_traits/is_pointer.hpp>
37 #include <boost/utility/enable_if.hpp>
38 
39 #include <typeinfo>
40 #include <memory>
41 
42 class KUrl;
43 
44 template <typename T>
45 class QVector;
46 
47 namespace Akonadi {
48 
49 class ItemPrivate;
50 
116 class AKONADI_EXPORT Item : public Entity
117 {
118  public:
122  typedef QList<Item> List;
123 
127  typedef QByteArray Flag;
128 
132  typedef QSet<QByteArray> Flags;
133 
138  static const char* FullPayload;
139 
143  Item();
144 
148  explicit Item( Id id );
149 
155  explicit Item( const QString &mimeType );
156 
160  Item( const Item &other );
161 
165  ~Item();
166 
170  static Item fromUrl( const KUrl &url );
171 
175  Flags flags() const;
176 
181  QDateTime modificationTime() const;
182 
190  void setModificationTime( const QDateTime &datetime );
191 
196  bool hasFlag( const QByteArray &name ) const;
197 
201  void setFlag( const QByteArray &name );
202 
206  void clearFlag( const QByteArray &name );
207 
211  void setFlags( const Flags &flags );
212 
216  void clearFlags();
217 
218  void setTags( const Tag::List &list );
219 
220  void setTag( const Tag & );
221 
222  Tag::List tags() const;
223 
224  bool hasTag( const Tag & ) const;
225 
226  void clearTag( const Tag & );
227 
228  void clearTags();
229 
237  void setPayloadFromData( const QByteArray &data );
238 
245  QByteArray payloadData() const;
246 
251  QSet<QByteArray> loadedPayloadParts() const;
252 
262  void clearPayload();
263 
270  void setRevision( int revision );
271 
275  int revision() const;
276 
285  Entity::Id storageCollectionId() const;
286 
292  void setSize( qint64 size );
293 
299  qint64 size() const;
300 
304  void setMimeType( const QString &mimeType );
305 
309  QString mimeType() const;
310 
316  void setGid( const QString &gid );
317 
323  QString gid() const;
324 
331  QVector<int> availablePayloadMetaTypeIds() const;
332 
344  template <typename T> void setPayload( const T &p );
345  //@cond PRIVATE
346  template <typename T> void setPayload( T* p );
347  template <typename T> void setPayload( std::auto_ptr<T> p );
348  //@endcond
349 
363  template <typename T> T payload() const;
364 
368  bool hasPayload() const;
369 
379  template <typename T> bool hasPayload() const;
380 
384  enum UrlType
385  {
386  UrlShort = 0,
387  UrlWithMimeType = 1
388  };
389 
393  KUrl url( UrlType type = UrlShort ) const;
394 
403  QSet<QByteArray> availablePayloadParts() const;
404 
414  QSet<QByteArray> cachedPayloadParts() const;
415 
429  void apply( const Item &other );
430 
440  template <typename T> static void addToLegacyMapping( const QString & mimeType );
441  void setCachedPayloadParts(const QSet<QByteArray> &cachedParts);
442 
443  private:
444  //@cond PRIVATE
445  friend class ItemCreateJob;
446  friend class ItemModifyJob;
447  friend class ItemModifyJobPrivate;
448  friend class ItemSync;
449  friend class ProtocolHelper;
450  PayloadBase* payloadBase() const;
451  void setPayloadBase( PayloadBase* );
452  PayloadBase* payloadBaseV2( int sharedPointerId, int metaTypeId ) const;
453  //std::auto_ptr<PayloadBase> takePayloadBase( int sharedPointerId, int metaTypeId );
454  void setPayloadBaseV2( int sharedPointerId, int metaTypeId, std::auto_ptr<PayloadBase> p );
455  void addPayloadBaseVariant( int sharedPointerId, int metaTypeId, std::auto_ptr<PayloadBase> p ) const;
456  static void addToLegacyMappingImpl( const QString & mimeType, int sharedPointerId, int metaTypeId, std::auto_ptr<PayloadBase> p );
457 
462  bool ensureMetaTypeId( int mtid ) const;
463 
464  template <typename T>
465  typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,void>::type
466  setPayloadImpl( const T &, const int * /*disambiguate*/ = 0 );
467  template <typename T>
468  typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,void>::type
469  setPayloadImpl( const T & );
470 
471  template <typename T>
472  typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,T>::type
473  payloadImpl( const int * /*disambiguate*/ = 0 ) const;
474  template <typename T>
475  typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,T>::type
476  payloadImpl() const;
477 
478  template <typename T>
479  typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,bool>::type
480  hasPayloadImpl( const int * /*disambiguate*/ = 0 ) const;
481  template <typename T>
482  typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,bool>::type
483  hasPayloadImpl() const;
484 
485  template <typename T>
486  typename boost::enable_if<Internal::is_shared_pointer<T>,bool>::type
487  tryToClone( T *, const int * /*disambiguate*/ = 0 ) const;
488  template <typename T>
489  typename boost::disable_if<Internal::is_shared_pointer<T>,bool>::type
490  tryToClone( T * ) const;
491 
497  void setStorageCollectionId( Entity::Id collectionId);
498 
499 #if 0
500 
503  QString payloadExceptionText( int spid, int mtid ) const;
504 
510  inline void throwPayloadException( int spid, int mtid ) const {
511  throw PayloadException( payloadExceptionText( spid, mtid ) );
512  }
513 #else
514  void throwPayloadException( int spid, int mtid ) const;
515 #endif
516  //@endcond
517 
518  AKONADI_DECLARE_PRIVATE( Item )
519 };
520 
521 template <typename T>
522 T Item::payload() const
523 {
524  BOOST_STATIC_ASSERT( !boost::is_pointer<T>::value );
525 
526  if ( !hasPayload() )
527  throwPayloadException( -1, -1 );
528 
529  return payloadImpl<T>();
530 }
531 
532 template <typename T>
533 typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,T>::type
534 Item::payloadImpl( const int * ) const
535 {
536  typedef Internal::PayloadTrait<T> PayloadType;
537  BOOST_STATIC_ASSERT(( PayloadType::isPolymorphic ));
538 
539  typedef typename Internal::get_hierarchy_root<T>::type Root_T;
540  typedef Internal::PayloadTrait<Root_T> RootType;
541  BOOST_STATIC_ASSERT(( !RootType::isPolymorphic )); // prevent endless recursion
542 
543  return PayloadType::castFrom( payloadImpl<Root_T>() );
544 }
545 
546 template <typename T>
547 typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,T>::type
548 Item::payloadImpl() const
549 {
550  typedef Internal::PayloadTrait<T> PayloadType;
551  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));
552 
553  const int metaTypeId = PayloadType::elementMetaTypeId();
554 
555  // make sure that we have a payload format represented by 'metaTypeId':
556  if ( !ensureMetaTypeId( metaTypeId ) )
557  throwPayloadException( PayloadType::sharedPointerId, metaTypeId );
558 
559  // Check whether we have the exact payload
560  // (metatype id and shared pointer type match)
561  if ( const Payload<T> * const p = Internal::payload_cast<T>( payloadBaseV2( PayloadType::sharedPointerId, metaTypeId ) ) )
562  return p->payload;
563 
564  T ret;
565  if ( !tryToClone<T>( &ret ) )
566  throwPayloadException( PayloadType::sharedPointerId, metaTypeId );
567  return ret;
568 }
569 
570 template <typename T>
571 typename boost::enable_if<Internal::is_shared_pointer<T>,bool>::type
572 Item::tryToClone( T * ret, const int * ) const
573 {
574  typedef Internal::PayloadTrait<T> PayloadType;
575  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));
576 
577  const int metaTypeId = PayloadType::elementMetaTypeId();
578 
579  // Check whether we have the same payload in 'the other
580  // shared pointer' (### make it recurse, trying to find one, but
581  // don't introduce infinite recursion):
582  typedef typename Internal::shared_pointer_traits<T>::next_shared_ptr NewT;
583  typedef Internal::PayloadTrait<NewT> NewPayloadType;
584 
585  if ( const Payload<NewT> * const p = Internal::payload_cast<NewT>( payloadBaseV2( NewPayloadType::sharedPointerId, metaTypeId ) ) ) {
586  // If found, attempt to make a clone (required the payload to provide virtual T * T::clone() const)
587  const T nt = PayloadType::clone( p->payload );
588  if ( !PayloadType::isNull( nt ) ) {
589  // if clone succeeded, add the clone to the Item:
590  std::auto_ptr<PayloadBase> npb( new Payload<T>( nt ) );
591  addPayloadBaseVariant( PayloadType::sharedPointerId, metaTypeId, npb );
592  // and return it
593  if ( ret ) {
594  *ret = nt;
595  }
596  return true;
597  }
598  }
599 
600  return false;
601 }
602 
603 template <typename T>
604 typename boost::disable_if<Internal::is_shared_pointer<T>, bool>::type
605 Item::tryToClone( T * ) const
606 {
607  typedef Internal::PayloadTrait<T> PayloadType;
608  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));
609 
610  return false;
611 }
612 
613 template <typename T>
614 bool Item::hasPayload() const
615 {
616  BOOST_STATIC_ASSERT( !boost::is_pointer<T>::value );
617  return hasPayload() && hasPayloadImpl<T>();
618 }
619 
620 template <typename T>
621 typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,bool>::type
622 Item::hasPayloadImpl( const int * ) const
623 {
624  typedef Internal::PayloadTrait<T> PayloadType;
625  BOOST_STATIC_ASSERT(( PayloadType::isPolymorphic ));
626 
627  typedef typename Internal::get_hierarchy_root<T>::type Root_T;
628  typedef Internal::PayloadTrait<Root_T> RootType;
629  BOOST_STATIC_ASSERT(( !RootType::isPolymorphic )); // prevent endless recursion
630 
631  try {
632  return hasPayloadImpl<Root_T>()
633  && PayloadType::canCastFrom( payload<Root_T>() );
634  } catch ( const Akonadi::PayloadException & ) {
635  return false;
636  }
637 }
638 
639 template <typename T>
640 typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,bool>::type
641 Item::hasPayloadImpl() const
642 {
643  typedef Internal::PayloadTrait<T> PayloadType;
644  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));
645 
646  const int metaTypeId = PayloadType::elementMetaTypeId();
647 
648  // make sure that we have a payload format represented by 'metaTypeId':
649  if ( !ensureMetaTypeId( metaTypeId ) )
650  return false;
651 
652  // Check whether we have the exact payload
653  // (metatype id and shared pointer type match)
654  if ( const Payload<T> * const p = Internal::payload_cast<T>( payloadBaseV2( PayloadType::sharedPointerId, metaTypeId ) ) )
655  return true;
656 
657  return tryToClone<T>( 0 );
658 }
659 
660 template <typename T>
661 void Item::setPayload( const T &p )
662 {
663  BOOST_STATIC_ASSERT(( !boost::is_pointer<T>::value ));
664  setPayloadImpl( p );
665 }
666 
667 template <typename T>
668 typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic>::type
669 Item::setPayloadImpl( const T & p, const int * )
670 {
671  typedef Internal::PayloadTrait<T> PayloadType;
672  BOOST_STATIC_ASSERT(( PayloadType::isPolymorphic ));
673 
674  typedef typename Internal::get_hierarchy_root<T>::type Root_T;
675  typedef Internal::PayloadTrait<Root_T> RootType;
676  BOOST_STATIC_ASSERT(( !RootType::isPolymorphic )); // prevent endless recursion
677 
678  setPayloadImpl<Root_T>( p );
679 }
680 
681 template <typename T>
682 typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic>::type
683 Item::setPayloadImpl( const T & p )
684 {
685  typedef Internal::PayloadTrait<T> PayloadType;
686  std::auto_ptr<PayloadBase> pb( new Payload<T>( p ) );
687  setPayloadBaseV2( PayloadType::sharedPointerId,
688  PayloadType::elementMetaTypeId(),
689  pb );
690 }
691 
692 template <typename T>
693 void Item::setPayload( T* p )
694 {
695  p->You_MUST_NOT_use_a_pointer_as_payload;
696 }
697 
698 template <typename T>
699 void Item::setPayload( std::auto_ptr<T> p )
700 {
701  p.Nice_try_but_a_std_auto_ptr_is_not_allowed_as_payload_either;
702 }
703 
704 template <typename T>
705 void Item::addToLegacyMapping( const QString & mimeType ) {
706  typedef Internal::PayloadTrait<T> PayloadType;
707  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));
708  std::auto_ptr<PayloadBase> p( new Payload<T> );
709  addToLegacyMappingImpl( mimeType, PayloadType::sharedPointerId, PayloadType::elementMetaTypeId(), p );
710 }
711 
712 }
713 
714 Q_DECLARE_METATYPE(Akonadi::Item)
715 Q_DECLARE_METATYPE(Akonadi::Item::List)
716 
717 #endif
Akonadi::Entity::Id
qint64 Id
Describes the unique id type.
Definition: entity.h:65
This file is part of the KDE documentation.
Documentation copyright © 1996-2014 The KDE developers.
Generated on Mon Jul 21 2014 08:03:53 by doxygen 1.8.6 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.

akonadi

Skip menu "akonadi"
  • Main Page
  • Namespace List
  • Namespace Members
  • Alphabetical List
  • Class List
  • Class Hierarchy
  • Class Members
  • File List
  • Modules
  • Related Pages

kdepimlibs-4.13.3 API Reference

Skip menu "kdepimlibs-4.13.3 API Reference"
  • akonadi
  •   contact
  •   kmime
  •   socialutils
  • kabc
  • kalarmcal
  • kblog
  • kcal
  • kcalcore
  • kcalutils
  • kholidays
  • kimap
  • kioslave
  •   imap4
  •   mbox
  •   nntp
  • kldap
  • kmbox
  • kmime
  • kontactinterface
  • kpimidentities
  • kpimtextedit
  • kpimutils
  • kresources
  • ktnef
  • kxmlrpcclient
  • mailtransport
  • microblog
  • qgpgme
  • syndication
  •   atom
  •   rdf
  •   rss2
Report problems with this website to our bug tracking system.
Contact the specific authors with questions and comments about the page contents.

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal