• Skip to content
  • Skip to link menu
  • KDE API Reference
  • kdepimlibs-4.11.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 "itempayloadinternals_p.h"
29 
30 #include <QtCore/QByteArray>
31 #include <QtCore/QMetaType>
32 #include <QtCore/QSet>
33 
34 #include <boost/static_assert.hpp>
35 #include <boost/type_traits/is_pointer.hpp>
36 #include <boost/utility/enable_if.hpp>
37 
38 #include <typeinfo>
39 #include <memory>
40 
41 class KUrl;
42 
43 template <typename T>
44 class QVector;
45 
46 namespace Akonadi {
47 
48 class ItemPrivate;
49 
115 class AKONADI_EXPORT Item : public Entity
116 {
117  public:
121  typedef QList<Item> List;
122 
126  typedef QByteArray Flag;
127 
131  typedef QSet<QByteArray> Flags;
132 
137  static const char* FullPayload;
138 
142  Item();
143 
147  explicit Item( Id id );
148 
154  explicit Item( const QString &mimeType );
155 
159  Item( const Item &other );
160 
164  ~Item();
165 
169  static Item fromUrl( const KUrl &url );
170 
174  Flags flags() const;
175 
180  QDateTime modificationTime() const;
181 
189  void setModificationTime( const QDateTime &datetime );
190 
195  bool hasFlag( const QByteArray &name ) const;
196 
200  void setFlag( const QByteArray &name );
201 
205  void clearFlag( const QByteArray &name );
206 
210  void setFlags( const Flags &flags );
211 
215  void clearFlags();
216 
224  void setPayloadFromData( const QByteArray &data );
225 
232  QByteArray payloadData() const;
233 
238  QSet<QByteArray> loadedPayloadParts() const;
239 
249  void clearPayload();
250 
257  void setRevision( int revision );
258 
262  int revision() const;
263 
272  Entity::Id storageCollectionId() const;
273 
279  void setSize( qint64 size );
280 
286  qint64 size() const;
287 
291  void setMimeType( const QString &mimeType );
292 
296  QString mimeType() const;
297 
304  QVector<int> availablePayloadMetaTypeIds() const;
305 
317  template <typename T> void setPayload( const T &p );
318  //@cond PRIVATE
319  template <typename T> void setPayload( T* p );
320  template <typename T> void setPayload( std::auto_ptr<T> p );
321  //@endcond
322 
336  template <typename T> T payload() const;
337 
341  bool hasPayload() const;
342 
352  template <typename T> bool hasPayload() const;
353 
357  enum UrlType
358  {
359  UrlShort = 0,
360  UrlWithMimeType = 1
361  };
362 
366  KUrl url( UrlType type = UrlShort ) const;
367 
376  QSet<QByteArray> availablePayloadParts() const;
377 
387  QSet<QByteArray> cachedPayloadParts() const;
388 
402  void apply( const Item &other );
403 
413  template <typename T> static void addToLegacyMapping( const QString & mimeType );
414  void setCachedPayloadParts(const QSet<QByteArray> &cachedParts);
415 
416  private:
417  //@cond PRIVATE
418  friend class ItemCreateJob;
419  friend class ItemModifyJob;
420  friend class ItemModifyJobPrivate;
421  friend class ItemSync;
422  friend class ProtocolHelper;
423  PayloadBase* payloadBase() const;
424  void setPayloadBase( PayloadBase* );
425  PayloadBase* payloadBaseV2( int sharedPointerId, int metaTypeId ) const;
426  //std::auto_ptr<PayloadBase> takePayloadBase( int sharedPointerId, int metaTypeId );
427  void setPayloadBaseV2( int sharedPointerId, int metaTypeId, std::auto_ptr<PayloadBase> p );
428  void addPayloadBaseVariant( int sharedPointerId, int metaTypeId, std::auto_ptr<PayloadBase> p ) const;
429  static void addToLegacyMappingImpl( const QString & mimeType, int sharedPointerId, int metaTypeId, std::auto_ptr<PayloadBase> p );
430 
435  bool ensureMetaTypeId( int mtid ) const;
436 
437  template <typename T>
438  typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,void>::type
439  setPayloadImpl( const T &, const int * /*disambiguate*/ = 0 );
440  template <typename T>
441  typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,void>::type
442  setPayloadImpl( const T & );
443 
444  template <typename T>
445  typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,T>::type
446  payloadImpl( const int * /*disambiguate*/ = 0 ) const;
447  template <typename T>
448  typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,T>::type
449  payloadImpl() const;
450 
451  template <typename T>
452  typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,bool>::type
453  hasPayloadImpl( const int * /*disambiguate*/ = 0 ) const;
454  template <typename T>
455  typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,bool>::type
456  hasPayloadImpl() const;
457 
458  template <typename T>
459  typename boost::enable_if<Internal::is_shared_pointer<T>,bool>::type
460  tryToClone( T *, const int * /*disambiguate*/ = 0 ) const;
461  template <typename T>
462  typename boost::disable_if<Internal::is_shared_pointer<T>,bool>::type
463  tryToClone( T * ) const;
464 
470  void setStorageCollectionId( Entity::Id collectionId);
471 
472 #if 0
473 
476  QString payloadExceptionText( int spid, int mtid ) const;
477 
483  inline void throwPayloadException( int spid, int mtid ) const {
484  throw PayloadException( payloadExceptionText( spid, mtid ) );
485  }
486 #else
487  void throwPayloadException( int spid, int mtid ) const;
488 #endif
489  //@endcond
490 
491  AKONADI_DECLARE_PRIVATE( Item )
492 };
493 
494 
495 template <typename T>
496 T Item::payload() const
497 {
498  BOOST_STATIC_ASSERT( !boost::is_pointer<T>::value );
499 
500  if ( !hasPayload() )
501  throwPayloadException( -1, -1 );
502 
503  return payloadImpl<T>();
504 }
505 
506 template <typename T>
507 typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,T>::type
508 Item::payloadImpl( const int * ) const
509 {
510  typedef Internal::PayloadTrait<T> PayloadType;
511  BOOST_STATIC_ASSERT(( PayloadType::isPolymorphic ));
512 
513  typedef typename Internal::get_hierarchy_root<T>::type Root_T;
514  typedef Internal::PayloadTrait<Root_T> RootType;
515  BOOST_STATIC_ASSERT(( !RootType::isPolymorphic )); // prevent endless recursion
516 
517  return PayloadType::castFrom( payloadImpl<Root_T>() );
518 }
519 
520 template <typename T>
521 typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,T>::type
522 Item::payloadImpl() const
523 {
524  typedef Internal::PayloadTrait<T> PayloadType;
525  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));
526 
527  const int metaTypeId = PayloadType::elementMetaTypeId();
528 
529  // make sure that we have a payload format represented by 'metaTypeId':
530  if ( !ensureMetaTypeId( metaTypeId ) )
531  throwPayloadException( PayloadType::sharedPointerId, metaTypeId );
532 
533  // Check whether we have the exact payload
534  // (metatype id and shared pointer type match)
535  if ( const Payload<T> * const p = Internal::payload_cast<T>( payloadBaseV2( PayloadType::sharedPointerId, metaTypeId ) ) )
536  return p->payload;
537 
538  T ret;
539  if ( !tryToClone<T>( &ret ) )
540  throwPayloadException( PayloadType::sharedPointerId, metaTypeId );
541  return ret;
542 }
543 
544 template <typename T>
545 typename boost::enable_if<Internal::is_shared_pointer<T>,bool>::type
546 Item::tryToClone( T * ret, const int * ) const
547 {
548  typedef Internal::PayloadTrait<T> PayloadType;
549  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));
550 
551  const int metaTypeId = PayloadType::elementMetaTypeId();
552 
553  // Check whether we have the same payload in 'the other
554  // shared pointer' (### make it recurse, trying to find one, but
555  // don't introduce infinite recursion):
556  typedef typename Internal::shared_pointer_traits<T>::next_shared_ptr NewT;
557  typedef Internal::PayloadTrait<NewT> NewPayloadType;
558 
559  if ( const Payload<NewT> * const p = Internal::payload_cast<NewT>( payloadBaseV2( NewPayloadType::sharedPointerId, metaTypeId ) ) ) {
560  // If found, attempt to make a clone (required the payload to provide virtual T * T::clone() const)
561  const T nt = PayloadType::clone( p->payload );
562  if ( !PayloadType::isNull( nt ) ) {
563  // if clone succeeded, add the clone to the Item:
564  std::auto_ptr<PayloadBase> npb( new Payload<T>( nt ) );
565  addPayloadBaseVariant( PayloadType::sharedPointerId, metaTypeId, npb );
566  // and return it
567  if ( ret ) *ret = nt;
568  return true;
569  }
570  }
571 
572  return false;
573 }
574 
575 template <typename T>
576 typename boost::disable_if<Internal::is_shared_pointer<T>, bool>::type
577 Item::tryToClone( T * ) const
578 {
579  typedef Internal::PayloadTrait<T> PayloadType;
580  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));
581 
582  return false;
583 }
584 
585 template <typename T>
586 bool Item::hasPayload() const
587 {
588  BOOST_STATIC_ASSERT( !boost::is_pointer<T>::value );
589  return hasPayload() && hasPayloadImpl<T>();
590 }
591 
592 template <typename T>
593 typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,bool>::type
594 Item::hasPayloadImpl( const int * ) const
595 {
596  typedef Internal::PayloadTrait<T> PayloadType;
597  BOOST_STATIC_ASSERT(( PayloadType::isPolymorphic ));
598 
599  typedef typename Internal::get_hierarchy_root<T>::type Root_T;
600  typedef Internal::PayloadTrait<Root_T> RootType;
601  BOOST_STATIC_ASSERT(( !RootType::isPolymorphic )); // prevent endless recursion
602 
603  try {
604  return hasPayloadImpl<Root_T>()
605  && PayloadType::canCastFrom( payload<Root_T>() );
606  } catch ( const Akonadi::PayloadException & ) {
607  return false;
608  }
609 }
610 
611 template <typename T>
612 typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,bool>::type
613 Item::hasPayloadImpl() const
614 {
615  typedef Internal::PayloadTrait<T> PayloadType;
616  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));
617 
618  const int metaTypeId = PayloadType::elementMetaTypeId();
619 
620  // make sure that we have a payload format represented by 'metaTypeId':
621  if ( !ensureMetaTypeId( metaTypeId ) )
622  return false;
623 
624  // Check whether we have the exact payload
625  // (metatype id and shared pointer type match)
626  if ( const Payload<T> * const p = Internal::payload_cast<T>( payloadBaseV2( PayloadType::sharedPointerId, metaTypeId ) ) )
627  return true;
628 
629  return tryToClone<T>( 0 );
630 }
631 
632 template <typename T>
633 void Item::setPayload( const T &p )
634 {
635  BOOST_STATIC_ASSERT(( !boost::is_pointer<T>::value ));
636  setPayloadImpl( p );
637 }
638 
639 template <typename T>
640 typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic>::type
641 Item::setPayloadImpl( const T & p, const int * )
642 {
643  typedef Internal::PayloadTrait<T> PayloadType;
644  BOOST_STATIC_ASSERT(( PayloadType::isPolymorphic ));
645 
646  typedef typename Internal::get_hierarchy_root<T>::type Root_T;
647  typedef Internal::PayloadTrait<Root_T> RootType;
648  BOOST_STATIC_ASSERT(( !RootType::isPolymorphic )); // prevent endless recursion
649 
650  setPayloadImpl<Root_T>( p );
651 }
652 
653 template <typename T>
654 typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic>::type
655 Item::setPayloadImpl( const T & p )
656 {
657  typedef Internal::PayloadTrait<T> PayloadType;
658  std::auto_ptr<PayloadBase> pb( new Payload<T>( p ) );
659  setPayloadBaseV2( PayloadType::sharedPointerId,
660  PayloadType::elementMetaTypeId(),
661  pb );
662 }
663 
664 template <typename T>
665 void Item::setPayload( T* p )
666 {
667  p->You_MUST_NOT_use_a_pointer_as_payload;
668 }
669 
670 template <typename T>
671 void Item::setPayload( std::auto_ptr<T> p )
672 {
673  p.Nice_try_but_a_std_auto_ptr_is_not_allowed_as_payload_either;
674 }
675 
676 template <typename T>
677 void Item::addToLegacyMapping( const QString & mimeType ) {
678  typedef Internal::PayloadTrait<T> PayloadType;
679  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));
680  std::auto_ptr<PayloadBase> p( new Payload<T> );
681  addToLegacyMappingImpl( mimeType, PayloadType::sharedPointerId, PayloadType::elementMetaTypeId(), p );
682 }
683 
684 }
685 
686 Q_DECLARE_METATYPE(Akonadi::Item)
687 Q_DECLARE_METATYPE(Akonadi::Item::List)
688 
689 #endif
Akonadi::Entity::Id
qint64 Id
Describes the unique id type.
Definition: entity.h:64
This file is part of the KDE documentation.
Documentation copyright © 1996-2013 The KDE developers.
Generated on Tue Nov 26 2013 09:03:17 by doxygen 1.8.5 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.11.3 API Reference

Skip menu "kdepimlibs-4.11.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