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

akonadi

  • Akonadi
  • Item
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
Akonadi::Item Class Reference

#include <item.h>

Inheritance diagram for Akonadi::Item:
Akonadi::Entity

Public Types

typedef QByteArray Flag
 
typedef QSet< QByteArray > Flags
 
typedef QList< Item > List
 
enum  UrlType { UrlShort = 0, UrlWithMimeType = 1 }
 
- Public Types inherited from Akonadi::Entity
enum  CreateOption { AddIfMissing }
 
typedef qint64 Id
 

Public Member Functions

 Item ()
 
 Item (Id id)
 
 Item (const QString &mimeType)
 
 Item (const Item &other)
 
 ~Item ()
 
template<typename T >
void addToLegacyMapping (const QString &mimeType)
 
void apply (const Item &other)
 
QVector< int > availablePayloadMetaTypeIds () const
 
QSet< QByteArray > availablePayloadParts () const
 
void clearFlag (const QByteArray &name)
 
void clearFlags ()
 
void clearPayload ()
 
Flags flags () const
 
bool hasFlag (const QByteArray &name) const
 
bool hasPayload () const
 
template<typename T >
bool hasPayload () const
 
QSet< QByteArray > loadedPayloadParts () const
 
QString mimeType () const
 
QDateTime modificationTime () const
 
template<typename T >
T payload () const
 
QByteArray payloadData () const
 
int revision () const
 
void setFlag (const QByteArray &name)
 
void setFlags (const Flags &flags)
 
void setMimeType (const QString &mimeType)
 
void setModificationTime (const QDateTime &datetime)
 
template<typename T >
void setPayload (const T &p)
 
template<typename T >
void setPayload (T *p)
 
template<typename T >
void setPayload (std::auto_ptr< T > p)
 
void setPayloadFromData (const QByteArray &data)
 
void setRevision (int revision)
 
void setSize (qint64 size)
 
qint64 size () const
 
Entity::Id storageCollectionId () const
 
KUrl url (UrlType type=UrlShort) const
 
- Public Member Functions inherited from Akonadi::Entity
void addAttribute (Attribute *attribute)
 
Attribute * attribute (const QByteArray &name) const
 
template<typename T >
T * attribute (CreateOption option)
 
template<typename T >
T * attribute () const
 
Attribute::List attributes () const
 
void clearAttributes ()
 
bool hasAttribute (const QByteArray &name) const
 
template<typename T >
bool hasAttribute () const
 
Id id () const
 
bool isValid () const
 
bool operator!= (const Entity &other) const
 
bool operator< (const Entity &other) const
 
Entity & operator= (const Entity &other)
 
bool operator== (const Entity &other) const
 
Collection parentCollection () const
 
Collection & parentCollection ()
 
QString remoteId () const
 
QString remoteRevision () const
 
void removeAttribute (const QByteArray &name)
 
template<typename T >
void removeAttribute ()
 
void setId (Id identifier)
 
void setParentCollection (const Collection &parent)
 
void setRemoteId (const QString &id)
 
void setRemoteRevision (const QString &revision)
 

Static Public Member Functions

template<typename T >
static void addToLegacyMapping (const QString &mimeType)
 
static Item fromUrl (const KUrl &url)
 

Static Public Attributes

static const char * FullPayload = "RFC822"
 

Additional Inherited Members

- Protected Member Functions inherited from Akonadi::Entity
 Entity (const Entity &other)
 
 ~Entity ()
 

Detailed Description

Represents a PIM item stored in Akonadi storage.

A PIM item consists of one or more parts, allowing a fine-grained access on its content where needed (eg. mail envelope, mail body and attachments).

There is also a namespace (prefix) for special parts which are local to Akonadi. These parts, prefixed by "akonadi-" will never be fetched in the resource. They are useful for local extensions like agents which might want to add meta data to items in order to handle them but the meta data should not be stored back to the resource.

This class is implicitly shared.

Payload

This class contains, beside some type-agnostic information (flags, revision), zero or more payload objects representing its actual data. Which objects these actually are depends on the mimetype of the item and the corresponding serializer plugin(s).

Technically the only restriction on payload objects is that they have to be copyable. For safety reasons, pointer payloads are forbidden as well though, as the ownership would not be clear. In this case, usage of a shared pointer is recommended (such as boost::shared_ptr or QSharedPointer).

Using a shared pointer is also required in case the payload is a polymorphic type. For supported shared pointer types implicit casting is provided when possible.

When using a value-based class as payload, it is recommended to use one that does support implicit sharing as setting and retrieving a payload as well as copying an Akonadi::Item object imply copying of the payload object.

Since KDE 4.6, Item supports multiple payload types per mime type, and will automatically convert between them using the serialiser plugins (which is slow). It also supports mixing shared pointer types, e.g. inserting a boost::shared_ptr<Foo> and extracting a QSharedPointer<Foo>. Since the two shared pointer types cannot share ownership of the same object, the payload class T needs to provide a clone() method with the usual signature, ie.

virtual T * T::clone() const

If the class that does not have a clone() method, asking for an incompatible shared pointer will throw a PayloadException.

Since using different shared pointer types and different payload types for the same mimetype incurs slow conversions (between payload types) and cloning (between shared pointer types), as well as manifold memory usage (results of conversions are cached inside the Item, and only destroyed when a new payload is set by the user of the class), you want to restrict yourself to just one type and one shared pointer type. This mechanism was mainly introduced for backwards compatibility (e.g., putting in a boost::shared_ptr<KCal::Incidence> and extracting a QSharedPointer<KCalCore::Incidence>), so it is not optimized for performance.

The availability of a payload of a specific type can be checked using hasPayload(), payloads can be retrieved by using payload() and set by using setPayload(). Refer to the documentation of those methods for more details.

Author
Volker Krause vkrau.nosp@m.se@k.nosp@m.de.or.nosp@m.g, Till Adam adam@.nosp@m.kde..nosp@m.org, Marc Mutz mutz@.nosp@m.kde..nosp@m.org

Definition at line 115 of file item.h.

Member Typedef Documentation

typedef QByteArray Akonadi::Item::Flag

Describes a flag name.

Definition at line 126 of file item.h.

typedef QSet<QByteArray> Akonadi::Item::Flags

Describes a set of flag names.

Definition at line 131 of file item.h.

typedef QList<Item> Akonadi::Item::List

Describes a list of items.

Definition at line 121 of file item.h.

Member Enumeration Documentation

enum Akonadi::Item::UrlType

Describes the type of url which is returned in url().

Enumerator
UrlShort 

A short url which contains the identifier only (default)

UrlWithMimeType 

A url with identifier and mimetype.

Definition at line 357 of file item.h.

Constructor & Destructor Documentation

Item::Item ( )

Creates a new item.

Definition at line 113 of file item.cpp.

Item::Item ( Id  id)
explicit

Creates a new item with the given unique id.

Definition at line 118 of file item.cpp.

Item::Item ( const QString &  mimeType)
explicit

Creates a new item with the given mime type.

Parameters
mimeTypeThe mime type of the item.

Definition at line 123 of file item.cpp.

Item::Item ( const Item &  other)

Creates a new item from an other item.

Definition at line 129 of file item.cpp.

Item::~Item ( )

Destroys the item.

Definition at line 134 of file item.cpp.

Member Function Documentation

template<typename T >
static void Akonadi::Item::addToLegacyMapping ( const QString &  mimeType)
static

Registers T as a legacy type for mime type mimeType.

This is required information for Item to return the correct type from payload() when clients have not been recompiled to use the new code.

Since
4.6
void Item::apply ( const Item &  other)

Applies the parts of Item other to this item.

Any parts or attributes available in other, will be applied to this item, and the payload parts of other will be inserted into this item, overwriting any existing parts with the same part name.

If there is an ItemSerialzerPluginV2 for the type, the merge method in that plugin is used to perform the merge. If only an ItemSerialzerPlugin class is found, or the merge method of the -V2 plugin is not implemented, the merge is performed with multiple deserializations of the payload.

Since
4.4

Definition at line 463 of file item.cpp.

QVector< int > Item::availablePayloadMetaTypeIds ( ) const

Returns a list of metatype-ids, describing the different variants of payload that are currently contained in this item.

The result is always sorted (increasing ids).

Definition at line 451 of file item.cpp.

QSet< QByteArray > Item::availablePayloadParts ( ) const

Returns the parts available for this item.

The returned set refers to parts available on the akonadi server or remotely, but does not include the loadedPayloadParts() of this item.

Since
4.4

Definition at line 446 of file item.cpp.

void Item::clearFlag ( const QByteArray &  name)

Removes the flag with the given name from the item.

Definition at line 156 of file item.cpp.

void Item::clearFlags ( )

Removes all flags from the item.

Definition at line 176 of file item.cpp.

void Item::clearPayload ( )

Marks that the payload shall be cleared from the cache when this item is passed to an ItemModifyJob the next time.

This will trigger a refetch of the payload from the backend when the item is accessed afterwards. Only resources should have a need for this functionality.

Since
4.5

Definition at line 216 of file item.cpp.

Item::Flags Item::flags ( ) const

Returns all flags of this item.

Definition at line 138 of file item.cpp.

Item Item::fromUrl ( const KUrl &  url)
static

Creates an item from the given url.

Definition at line 281 of file item.cpp.

bool Item::hasFlag ( const QByteArray &  name) const

Returns whether the flag with the given name is set in the item.

Definition at line 193 of file item.cpp.

bool Akonadi::Item::hasPayload ( ) const

Returns whether the item has a payload object.

Definition at line 263 of file item.cpp.

template<typename T >
bool Akonadi::Item::hasPayload ( ) const

Returns whether the item has a payload of type T.

This method will only return true if either you requested the exact same payload type that was put in or the payload uses a supported shared pointer type (currently boost::shared_ptr and QSharedPointer), and is castable to the requested type. For this to work there needs to be a specialization of Akonadi::super_trait of the used classes.

Trying to retrieve a pointer type will fail to compile.

QSet< QByteArray > Item::loadedPayloadParts ( ) const

Returns the list of loaded payload parts.

This is not necessarily identical to all parts in the cache or to all available parts on the backend.

Definition at line 198 of file item.cpp.

QString Item::mimeType ( ) const

Returns the mime type of the item.

Definition at line 241 of file item.cpp.

QDateTime Item::modificationTime ( ) const

Returns the timestamp of the last modification of this item.

Since
4.2

Definition at line 183 of file item.cpp.

template<typename T >
T Akonadi::Item::payload ( ) const

Returns the payload object of this PIM item.

This method will only succeed if either you requested the exact same payload type that was put in or the payload uses a supported shared pointer type (currently boost::shared_ptr and QSharedPointer), and is castable to the requested type. For this to work there needs to be a specialization of Akonadi::super_trait of the used classes.

If a mismatching or non-castable payload type is requested, an Akonadi::PayloadException is thrown. Therefore it is generally recommended to guard calls to payload() with a corresponding hasPayload() call.

Trying to retrieve a pointer type will fail to compile.

Definition at line 483 of file item.h.

QByteArray Item::payloadData ( ) const

Returns the full payload in its canonical representation, e.g.

the binary or textual format usually used for data with this mime type. This is useful when communicating with non-Akonadi application by e.g. drag&drop, copy&paste or stored files.

Definition at line 203 of file item.cpp.

int Item::revision ( ) const

Returns the revision number of the item.

Definition at line 221 of file item.cpp.

void Item::setFlag ( const QByteArray &  name)

Sets the flag with the given name in the item.

Definition at line 143 of file item.cpp.

void Item::setFlags ( const Flags &  flags)

Overwrites all flags of the item by the given flags.

Definition at line 169 of file item.cpp.

void Item::setMimeType ( const QString &  mimeType)

Sets the mime type of the item to mimeType.

Definition at line 258 of file item.cpp.

void Item::setModificationTime ( const QDateTime &  datetime)

Sets the timestamp of the last modification of this item.

Note
Do not modify this value from within an application, it is updated automatically by the revision checking functions.
Since
4.2

Definition at line 188 of file item.cpp.

template<typename T >
void Akonadi::Item::setPayload ( const T &  p)

Sets the payload object of this PIM item.

Parameters
pThe payload object. Must be copyable and must not be a pointer, will cause a compilation failure otherwise. Using a type that can be copied fast (such as implicitly shared classes) is recommended. If the payload type is polymorphic and you intend to set and retrieve payload objects with mismatching but castable types, make sure to use a supported shared pointer implementation (currently boost::shared_ptr and QSharedPointer) and make sure there is a specialization of Akonadi::super_trait for your class.

Definition at line 620 of file item.h.

void Item::setPayloadFromData ( const QByteArray &  data)

Sets the payload based on the canonical representation normally used for data of this mime type.

Parameters
dataThe encoded data.
See Also
fullPayloadData

Definition at line 211 of file item.cpp.

void Item::setRevision ( int  revision)

Sets the revision number of the item.

Note
Do not modify this value from within an application, it is updated automatically by the revision checking functions.

Definition at line 226 of file item.cpp.

void Item::setSize ( qint64  size)

Set the size of the item in bytes.

Since
4.2

Definition at line 246 of file item.cpp.

qint64 Item::size ( ) const

Returns the size of the items in bytes.

Since
4.2

Definition at line 253 of file item.cpp.

Entity::Id Item::storageCollectionId ( ) const

Returns the unique identifier of the collection this item is stored in.

There is only a single such collection, although the item can be linked into arbitrary many virtual collections. Calling this method makes sense only after running an ItemFetchJob on the item.

Returns
the collection ID if it is known, -1 otherwise.
Since
4.3

Definition at line 231 of file item.cpp.

KUrl Item::url ( UrlType  type = UrlShort) const

Returns the url of the item.

Definition at line 268 of file item.cpp.

Member Data Documentation

const char * Item::FullPayload = "RFC822"
static

Describes the part name that is used to fetch the full payload of an item.

Definition at line 137 of file item.h.


The documentation for this class was generated from the following files:
  • item.h
  • item.cpp
This file is part of the KDE documentation.
Documentation copyright © 1996-2013 The KDE developers.
Generated on Sat Jul 13 2013 01:27:49 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