• Skip to content
  • Skip to link menu
  • KDE API Reference
  • kdepimlibs-4.10.5 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 
391  void apply( const Item &other );
392 
402  template <typename T> static void addToLegacyMapping( const QString & mimeType );
403 
404  private:
405  //@cond PRIVATE
406  friend class ItemCreateJob;
407  friend class ItemModifyJob;
408  friend class ItemSync;
409  friend class ProtocolHelper;
410  PayloadBase* payloadBase() const;
411  void setPayloadBase( PayloadBase* );
412  PayloadBase* payloadBaseV2( int sharedPointerId, int metaTypeId ) const;
413  //std::auto_ptr<PayloadBase> takePayloadBase( int sharedPointerId, int metaTypeId );
414  void setPayloadBaseV2( int sharedPointerId, int metaTypeId, std::auto_ptr<PayloadBase> p );
415  void addPayloadBaseVariant( int sharedPointerId, int metaTypeId, std::auto_ptr<PayloadBase> p ) const;
416  static void addToLegacyMappingImpl( const QString & mimeType, int sharedPointerId, int metaTypeId, std::auto_ptr<PayloadBase> p );
417 
422  bool ensureMetaTypeId( int mtid ) const;
423 
424  template <typename T>
425  typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,void>::type
426  setPayloadImpl( const T &, const int * /*disambiguate*/ = 0 );
427  template <typename T>
428  typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,void>::type
429  setPayloadImpl( const T & );
430 
431  template <typename T>
432  typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,T>::type
433  payloadImpl( const int * /*disambiguate*/ = 0 ) const;
434  template <typename T>
435  typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,T>::type
436  payloadImpl() const;
437 
438  template <typename T>
439  typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,bool>::type
440  hasPayloadImpl( const int * /*disambiguate*/ = 0 ) const;
441  template <typename T>
442  typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,bool>::type
443  hasPayloadImpl() const;
444 
445  template <typename T>
446  typename boost::enable_if<Internal::is_shared_pointer<T>,bool>::type
447  tryToClone( T *, const int * /*disambiguate*/ = 0 ) const;
448  template <typename T>
449  typename boost::disable_if<Internal::is_shared_pointer<T>,bool>::type
450  tryToClone( T * ) const;
451 
457  void setStorageCollectionId( Entity::Id collectionId);
458 
459 #if 0
460 
463  QString payloadExceptionText( int spid, int mtid ) const;
464 
470  inline void throwPayloadException( int spid, int mtid ) const {
471  throw PayloadException( payloadExceptionText( spid, mtid ) );
472  }
473 #else
474  void throwPayloadException( int spid, int mtid ) const;
475 #endif
476  //@endcond
477 
478  AKONADI_DECLARE_PRIVATE( Item )
479 };
480 
481 
482 template <typename T>
483 T Item::payload() const
484 {
485  BOOST_STATIC_ASSERT( !boost::is_pointer<T>::value );
486 
487  if ( !hasPayload() )
488  throwPayloadException( -1, -1 );
489 
490  return payloadImpl<T>();
491 }
492 
493 template <typename T>
494 typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,T>::type
495 Item::payloadImpl( const int * ) const
496 {
497  typedef Internal::PayloadTrait<T> PayloadType;
498  BOOST_STATIC_ASSERT(( PayloadType::isPolymorphic ));
499 
500  typedef typename Internal::get_hierarchy_root<T>::type Root_T;
501  typedef Internal::PayloadTrait<Root_T> RootType;
502  BOOST_STATIC_ASSERT(( !RootType::isPolymorphic )); // prevent endless recursion
503 
504  return PayloadType::castFrom( payloadImpl<Root_T>() );
505 }
506 
507 template <typename T>
508 typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,T>::type
509 Item::payloadImpl() const
510 {
511  typedef Internal::PayloadTrait<T> PayloadType;
512  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));
513 
514  const int metaTypeId = PayloadType::elementMetaTypeId();
515 
516  // make sure that we have a payload format represented by 'metaTypeId':
517  if ( !ensureMetaTypeId( metaTypeId ) )
518  throwPayloadException( PayloadType::sharedPointerId, metaTypeId );
519 
520  // Check whether we have the exact payload
521  // (metatype id and shared pointer type match)
522  if ( const Payload<T> * const p = Internal::payload_cast<T>( payloadBaseV2( PayloadType::sharedPointerId, metaTypeId ) ) )
523  return p->payload;
524 
525  T ret;
526  if ( !tryToClone<T>( &ret ) )
527  throwPayloadException( PayloadType::sharedPointerId, metaTypeId );
528  return ret;
529 }
530 
531 template <typename T>
532 typename boost::enable_if<Internal::is_shared_pointer<T>,bool>::type
533 Item::tryToClone( T * ret, const int * ) const
534 {
535  typedef Internal::PayloadTrait<T> PayloadType;
536  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));
537 
538  const int metaTypeId = PayloadType::elementMetaTypeId();
539 
540  // Check whether we have the same payload in 'the other
541  // shared pointer' (### make it recurse, trying to find one, but
542  // don't introduce infinite recursion):
543  typedef typename Internal::shared_pointer_traits<T>::next_shared_ptr NewT;
544  typedef Internal::PayloadTrait<NewT> NewPayloadType;
545 
546  if ( const Payload<NewT> * const p = Internal::payload_cast<NewT>( payloadBaseV2( NewPayloadType::sharedPointerId, metaTypeId ) ) ) {
547  // If found, attempt to make a clone (required the payload to provide virtual T * T::clone() const)
548  const T nt = PayloadType::clone( p->payload );
549  if ( !PayloadType::isNull( nt ) ) {
550  // if clone succeeded, add the clone to the Item:
551  std::auto_ptr<PayloadBase> npb( new Payload<T>( nt ) );
552  addPayloadBaseVariant( PayloadType::sharedPointerId, metaTypeId, npb );
553  // and return it
554  if ( ret ) *ret = nt;
555  return true;
556  }
557  }
558 
559  return false;
560 }
561 
562 template <typename T>
563 typename boost::disable_if<Internal::is_shared_pointer<T>, bool>::type
564 Item::tryToClone( T * ) const
565 {
566  typedef Internal::PayloadTrait<T> PayloadType;
567  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));
568 
569  return false;
570 }
571 
572 template <typename T>
573 bool Item::hasPayload() const
574 {
575  BOOST_STATIC_ASSERT( !boost::is_pointer<T>::value );
576  return hasPayload() && hasPayloadImpl<T>();
577 }
578 
579 template <typename T>
580 typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic,bool>::type
581 Item::hasPayloadImpl( const int * ) const
582 {
583  typedef Internal::PayloadTrait<T> PayloadType;
584  BOOST_STATIC_ASSERT(( PayloadType::isPolymorphic ));
585 
586  typedef typename Internal::get_hierarchy_root<T>::type Root_T;
587  typedef Internal::PayloadTrait<Root_T> RootType;
588  BOOST_STATIC_ASSERT(( !RootType::isPolymorphic )); // prevent endless recursion
589 
590  try {
591  return hasPayloadImpl<Root_T>()
592  && PayloadType::canCastFrom( payload<Root_T>() );
593  } catch ( const Akonadi::PayloadException & ) {
594  return false;
595  }
596 }
597 
598 template <typename T>
599 typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic,bool>::type
600 Item::hasPayloadImpl() const
601 {
602  typedef Internal::PayloadTrait<T> PayloadType;
603  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));
604 
605  const int metaTypeId = PayloadType::elementMetaTypeId();
606 
607  // make sure that we have a payload format represented by 'metaTypeId':
608  if ( !ensureMetaTypeId( metaTypeId ) )
609  return false;
610 
611  // Check whether we have the exact payload
612  // (metatype id and shared pointer type match)
613  if ( const Payload<T> * const p = Internal::payload_cast<T>( payloadBaseV2( PayloadType::sharedPointerId, metaTypeId ) ) )
614  return true;
615 
616  return tryToClone<T>( 0 );
617 }
618 
619 template <typename T>
620 void Item::setPayload( const T &p )
621 {
622  BOOST_STATIC_ASSERT(( !boost::is_pointer<T>::value ));
623  setPayloadImpl( p );
624 }
625 
626 template <typename T>
627 typename boost::enable_if_c<Internal::PayloadTrait<T>::isPolymorphic>::type
628 Item::setPayloadImpl( const T & p, const int * )
629 {
630  typedef Internal::PayloadTrait<T> PayloadType;
631  BOOST_STATIC_ASSERT(( PayloadType::isPolymorphic ));
632 
633  typedef typename Internal::get_hierarchy_root<T>::type Root_T;
634  typedef Internal::PayloadTrait<Root_T> RootType;
635  BOOST_STATIC_ASSERT(( !RootType::isPolymorphic )); // prevent endless recursion
636 
637  setPayloadImpl<Root_T>( p );
638 }
639 
640 template <typename T>
641 typename boost::disable_if_c<Internal::PayloadTrait<T>::isPolymorphic>::type
642 Item::setPayloadImpl( const T & p )
643 {
644  typedef Internal::PayloadTrait<T> PayloadType;
645  std::auto_ptr<PayloadBase> pb( new Payload<T>( p ) );
646  setPayloadBaseV2( PayloadType::sharedPointerId,
647  PayloadType::elementMetaTypeId(),
648  pb );
649 }
650 
651 template <typename T>
652 void Item::setPayload( T* p )
653 {
654  p->You_MUST_NOT_use_a_pointer_as_payload;
655 }
656 
657 template <typename T>
658 void Item::setPayload( std::auto_ptr<T> p )
659 {
660  p.Nice_try_but_a_std_auto_ptr_is_not_allowed_as_payload_either;
661 }
662 
663 template <typename T>
664 void Item::addToLegacyMapping( const QString & mimeType ) {
665  typedef Internal::PayloadTrait<T> PayloadType;
666  BOOST_STATIC_ASSERT(( !PayloadType::isPolymorphic ));
667  std::auto_ptr<PayloadBase> p( new Payload<T> );
668  addToLegacyMappingImpl( mimeType, PayloadType::sharedPointerId, PayloadType::elementMetaTypeId(), p );
669 }
670 
671 }
672 
673 Q_DECLARE_METATYPE(Akonadi::Item)
674 Q_DECLARE_METATYPE(Akonadi::Item::List)
675 
676 
677 #endif
This file is part of the KDE documentation.
Documentation copyright © 1996-2013 The KDE developers.
Generated on Sat Jul 13 2013 01:27:38 by doxygen 1.8.3.1 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.10.5 API Reference

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