• Skip to content
  • Skip to link menu
KDE 4.3 API Reference
  • KDE API Reference
  • KDE-PIM Libraries
  • Sitemap
  • Contact Us
 

akonadi

Akonadi::Item

Akonadi::Item Class Reference

Represents a PIM item stored in Akonadi storage. More...

#include <item.h>

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

List of all members.

Public Types

typedef QByteArray Flag
typedef QSet< QByteArray > Flags
typedef QList< Item > List
enum  UrlType { UrlShort = 0, UrlWithMimeType = 1 }

Public Member Functions

void clearFlag (const QByteArray &name)
void clearFlags ()
Flags flags () const
bool hasFlag (const QByteArray &name) const
template<typename T >
bool hasPayload () const
bool hasPayload () const
 Item (const Item &other)
 Item (const QString &mimeType)
 Item (Id id)
 Item ()
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 (std::auto_ptr< T > p)
template<typename T >
void setPayload (T *p)
template<typename T >
void setPayload (const 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
 ~Item ()

Static Public Member Functions

static Item fromUrl (const KUrl &url)

Static Public Attributes

static const char * FullPayload = "RFC822"

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 contains beside some type-agnostic information (flags, revision) a single payload object representing its actual data. Which objects these actually are depends on the mimetype of the item and the corresponding serializer plugin.

This class is implicitly shared.

Payload

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 recommended in case the payload uses polymorphic types. 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.

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 <vkrause@kde.org>, Till Adam <adam@kde.org>

Definition at line 86 of file item.h.


Member Typedef Documentation

typedef QByteArray Akonadi::Item::Flag

Describes a flag name.

Definition at line 97 of file item.h.

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

Describes a set of flag names.

Definition at line 102 of file item.h.

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

Describes a list of items.

Definition at line 92 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 309 of file item.h.


Constructor & Destructor Documentation

Item::Item (  ) 

Creates a new item.

Definition at line 34 of file item.cpp.

Item::Item ( Id  id  )  [explicit]

Creates a new item with the given unique id.

Definition at line 39 of file item.cpp.

Item::Item ( const QString &  mimeType  )  [explicit]

Creates a new item with the given mime type.

Parameters:
mimeType The mime type of the item.

Definition at line 44 of file item.cpp.

Item::Item ( const Item &  other  ) 

Creates a new item from an other item.

Definition at line 50 of file item.cpp.

Item::~Item (  ) 

Destroys the item.

Definition at line 55 of file item.cpp.


Member Function Documentation

void Item::clearFlag ( const QByteArray &  name  ) 

Removes the flag with the given name from the item.

Definition at line 72 of file item.cpp.

void Item::clearFlags (  ) 

Removes all flags from the item.

Definition at line 87 of file item.cpp.

Item::Flags Item::flags (  )  const

Returns all flags of this item.

Definition at line 59 of file item.cpp.

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

Creates an item from the given url.

Definition at line 186 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 104 of file item.cpp.

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

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.

bool Akonadi::Item::hasPayload (  )  const [inline]

Returns whether the item has a payload object.

Definition at line 169 of file item.cpp.

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 109 of file item.cpp.

QString Item::mimeType (  )  const

Returns the mime type of the item.

Definition at line 147 of file item.cpp.

QDateTime Item::modificationTime (  )  const

Returns the timestamp of the last modification of this item.

Since:
4.2

Definition at line 94 of file item.cpp.

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

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 340 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 114 of file item.cpp.

int Item::revision (  )  const

Returns the revision number of the item.

Definition at line 127 of file item.cpp.

void Item::setFlag ( const QByteArray &  name  ) 

Sets the flag with the given name in the item.

Definition at line 64 of file item.cpp.

void Item::setFlags ( const Flags &  flags  ) 

Overwrites all flags of the item by the given flags.

Definition at line 80 of file item.cpp.

void Item::setMimeType ( const QString &  mimeType  ) 

Sets the mime type of the item to mimeType.

Definition at line 164 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 99 of file item.cpp.

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

Sets the payload object of this PIM item.

Parameters:
p The 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 384 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:
data The encoded data.
See also:
fullPayloadData

Definition at line 122 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 132 of file item.cpp.

void Item::setSize ( qint64  size  ) 

Set the size of the item in bytes.

Since:
4.2

Definition at line 152 of file item.cpp.

qint64 Item::size (  )  const

Returns the size of the items in bytes.

Since:
4.2

Definition at line 159 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 know, -1 otherwise.
Since:
4.3

Definition at line 137 of file item.cpp.

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

Returns the url of the item.

Definition at line 174 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 108 of file item.h.


The documentation for this class was generated from the following files:
  • item.h
  • item.cpp

akonadi

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

KDE-PIM Libraries

Skip menu "KDE-PIM Libraries"
  • akonadi
  • kabc
  • kblog
  • kcal
  • kholidays
  • kimap
  • kioslave
  •   imap4
  •   mbox
  • kldap
  • kmime
  • kpimidentities
  • kpimtextedit
  •   richtextbuilders
  • kpimutils
  • kresources
  • ktnef
  • kxmlrpcclient
  • mailtransport
  • microblog
  • qgpgme
  • syndication
  •   atom
  •   rdf
  •   rss2
Generated for KDE-PIM Libraries by doxygen 1.6.1
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal