Akonadi::Item

Search for usage in LXR

#include <item.h>

Public Types

enum  CreateOption { AddIfMissing , DontCreate }
 
using Flag = QByteArray
 
using Flags = QSet<QByteArray>
 
using Id = qint64
 
using List = QList<Item>
 
enum  UrlType { UrlShort = 0 , UrlWithMimeType = 1 }
 

Public Member Functions

 Item ()
 
 Item (const Item &other)
 
 Item (const QString &mimeType)
 
 Item (Id id)
 
 Item (Item &&) noexcept
 
 ~Item ()
 
void addAttribute (Attribute *attribute)
 
void apply (const Item &other)
 
template<typename T >
const T * attribute () const
 
Attributeattribute (const QByteArray &name)
 
const Attributeattribute (const QByteArray &name) const
 
template<typename T >
T * attribute (CreateOption option=DontCreate)
 
Attribute::List attributes () const
 
QList< int > availablePayloadMetaTypeIds () const
 
QSet< QByteArrayavailablePayloadParts () const
 
QSet< QByteArraycachedPayloadParts () const
 
void clearAttributes ()
 
void clearFlag (const QByteArray &name)
 
void clearFlags ()
 
void clearPayload ()
 
void clearTag (const Tag &tag)
 
void clearTags ()
 
Flags flags () const
 
QString gid () const
 
template<typename T >
bool hasAttribute () const
 
bool hasAttribute (const QByteArray &name) const
 
bool hasFlag (const QByteArray &name) const
 
bool hasPayload () const
 
template<typename T >
bool hasPayload () const
 
bool hasTag (const Tag &tag) const
 
Id id () const
 
bool isValid () const
 
QSet< QByteArrayloadedPayloadParts () const
 
QString mimeType () const
 
QDateTime modificationTime () const
 
bool operator!= (const Item &other) const
 
bool operator< (const Item &other) const
 
Itemoperator= (const Item &other)
 
bool operator== (const Item &other) const
 
CollectionparentCollection ()
 
Collection parentCollection () const
 
template<typename T >
payload () const
 
QByteArray payloadData () const
 
QString payloadPath () const
 
Relation::List relations () const
 
QString remoteId () const
 
QString remoteRevision () const
 
template<typename T >
void removeAttribute ()
 
void removeAttribute (const QByteArray &name)
 
int revision () const
 
void setCachedPayloadParts (const QSet< QByteArray > &cachedParts)
 
void setFlag (const QByteArray &name)
 
void setFlags (const Flags &flags)
 
void setGid (const QString &gid)
 
void setId (Id identifier)
 
void setMimeType (const QString &mimeType)
 
void setModificationTime (const QDateTime &datetime)
 
void setParentCollection (const Collection &parent)
 
template<typename T >
void setPayload (const T &p)
 
template<typename T >
void setPayload (T *p)
 
void setPayloadFromData (const QByteArray &data)
 
void setPayloadPath (const QString &filePath)
 
void setRemoteId (const QString &id)
 
void setRemoteRevision (const QString &revision)
 
void setRevision (int revision)
 
void setSize (qint64 size)
 
void setTag (const Tag &tag)
 
void setTags (const Tag::List &list)
 
void setVirtualReferences (const Collection::List &collections)
 
qint64 size () const
 
Collection::Id storageCollectionId () const
 
Tag::List tags () const
 
QUrl url (UrlType type=UrlShort) const
 
Collection::List virtualReferences () const
 

Static Public Member Functions

static Item fromUrl (const QUrl &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 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 QSharedPointer or std::shared_ptr).

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 std::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 std::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 100 of file item.h.

Member Typedef Documentation

◆ Flag

Describes a flag name.

Definition at line 116 of file item.h.

◆ Flags

Describes a set of flag names.

Definition at line 121 of file item.h.

◆ Id

using Akonadi::Item::Id = qint64

Describes the unique id type.

Definition at line 106 of file item.h.

◆ List

Describes a list of items.

Definition at line 111 of file item.h.

Member Enumeration Documentation

◆ CreateOption

Describes the options that can be passed to access attributes.

Enumerator
AddIfMissing 

Creates the attribute if it is missing.

DontCreate 

Do not create the attribute if it is missing (default)

Definition at line 306 of file item.h.

◆ 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 610 of file item.h.

Constructor & Destructor Documentation

◆ Item() [1/5]

Item::Item ( )

Creates a new item.

Definition at line 36 of file item.cpp.

◆ Item() [2/5]

Item::Item ( Id id)
explicit

Creates a new item with the given unique id.

Definition at line 41 of file item.cpp.

◆ Item() [3/5]

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

◆ Item() [4/5]

Item::Item ( const Item & other)
default

Creates a new item from an other item.

◆ Item() [5/5]

Akonadi::Item::Item ( Item && )
noexcept

Move constructor.

◆ ~Item()

Item::~Item ( )
default

Destroys the item.

Member Function Documentation

◆ addAttribute()

void Item::addAttribute ( Attribute * attribute)

Adds an attribute to the item.

If an attribute of the same type name already exists, it is deleted and replaced with the new one.

Parameters
attributeThe new attribute.
Note
The collection takes the ownership of the attribute.

Definition at line 118 of file item.cpp.

◆ apply()

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.

Parameters
otherthe item to get values from
Since
4.4

Definition at line 534 of file item.cpp.

◆ attribute() [1/3]

template<typename T >
const T * Item::attribute ( ) const
inline

Returns the attribute of the requested type or 0 if it is not available.

Definition at line 736 of file item.h.

◆ attribute() [2/3]

Attribute * Akonadi::Item::attribute ( const QByteArray & name)

Returns the attribute of the given type name if available, 0 otherwise.

◆ attribute() [3/3]

template<typename T >
T * Item::attribute ( Item::CreateOption option = DontCreate)
inline

Returns the attribute of the requested type.

If the item has no attribute of that type yet, a new one is created and added to the entity.

Parameters
optionThe create options.

Definition at line 718 of file item.h.

◆ attributes()

Attribute::List Item::attributes ( ) const

Returns a list of all attributes of the item.

Warning
Do not modify the attributes returned from this method, the change will not be reflected when updating the Item through ItemModifyJob.

Definition at line 133 of file item.cpp.

◆ availablePayloadMetaTypeIds()

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

◆ availablePayloadParts()

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

◆ cachedPayloadParts()

QSet< QByteArray > Item::cachedPayloadParts ( ) const

Returns the parts available for this item in the cache.

The list might be a subset of the actual parts in cache, as it contains only the requested parts. See

See also
ItemFetchJob and
ItemFetchScope

The returned set refers to parts available on the akonadi server.

Since
4.11

Definition at line 494 of file item.cpp.

◆ clearAttributes()

void Item::clearAttributes ( )

Removes and deletes all attributes of the item.

Definition at line 138 of file item.cpp.

◆ clearFlag()

void Item::clearFlag ( const QByteArray & name)

Removes the flag with the given name from the item.

Definition at line 194 of file item.cpp.

◆ clearFlags()

void Item::clearFlags ( )

Removes all flags from the item.

Definition at line 214 of file item.cpp.

◆ clearPayload()

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

◆ clearTag()

void Item::clearTag ( const Tag & tag)

Definition at line 260 of file item.cpp.

◆ clearTags()

void Item::clearTags ( )

Definition at line 254 of file item.cpp.

◆ flags()

Item::Flags Item::flags ( ) const

Returns all flags of this item.

Definition at line 175 of file item.cpp.

◆ fromUrl()

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

Creates an item from the given url.

Definition at line 391 of file item.cpp.

◆ gid()

QString Item::gid ( ) const

Returns the gid of the entity.

Since
4.12

Definition at line 357 of file item.cpp.

◆ hasAttribute() [1/2]

template<typename T >
bool Item::hasAttribute ( ) const
inline

Returns whether the item has an attribute of the requested type.

Definition at line 756 of file item.h.

◆ hasAttribute() [2/2]

bool Akonadi::Item::hasAttribute ( const QByteArray & name) const

Returns true if the item has an attribute of the given type name, false otherwise.

◆ hasFlag()

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

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

Definition at line 230 of file item.cpp.

◆ hasPayload() [1/2]

bool Akonadi::Item::hasPayload ( ) const

Returns whether the item has a payload object.

◆ hasPayload() [2/2]

template<typename T >
bool 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 QSharedPointer and std::shared_ptr), 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.

Definition at line 372 of file item.cpp.

◆ hasTag()

bool Item::hasTag ( const Tag & tag) const

Definition at line 273 of file item.cpp.

◆ id()

Item::Id Item::id ( ) const

Returns the unique identifier of the item.

Definition at line 63 of file item.cpp.

◆ isValid()

bool Item::isValid ( ) const

Returns whether the item is valid.

Definition at line 88 of file item.cpp.

◆ loadedPayloadParts()

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

◆ mimeType()

QString Item::mimeType ( ) const

Returns the mime type of the item.

Definition at line 331 of file item.cpp.

◆ modificationTime()

QDateTime Item::modificationTime ( ) const

Returns the timestamp of the last modification of this item.

Since
4.2

Definition at line 220 of file item.cpp.

◆ operator!=()

bool Item::operator!= ( const Item & other) const

Returns whether the item's id does not equal the id of the other item.

Definition at line 99 of file item.cpp.

◆ operator<()

bool Item::operator< ( const Item & other) const

For use with containers only.

Since
4.8

Definition at line 113 of file item.cpp.

◆ operator=()

Item & Item::operator= ( const Item & other)

Assigns the other to this item and returns a reference to this item.

Parameters
otherthe item to assign

Definition at line 104 of file item.cpp.

◆ operator==()

bool Item::operator== ( const Item & other) const

Returns whether this item's id equals the id of the other item.

Definition at line 93 of file item.cpp.

◆ parentCollection() [1/2]

Collection & Item::parentCollection ( )

Returns a reference to the parent collection of this object.

Note
This will of course only return a useful value if it was explicitly retrieved from the Akonadi server.
Since
4.4

Definition at line 153 of file item.cpp.

◆ parentCollection() [2/2]

Collection Item::parentCollection ( ) const

Returns the parent collection of this object.

Note
This will of course only return a useful value if it was explicitly retrieved from the Akonadi server.
Since
4.4

Definition at line 161 of file item.cpp.

◆ payload()

template<typename T >
T 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 QSharedPointer and std::shared_ptr), 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 762 of file item.h.

◆ payloadData()

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

◆ payloadPath()

QString Item::payloadPath ( ) const

Returns path to the payload file set by setPayloadPath()

If payload was set via setPayload() or setPayloadFromData() then this method will return a null string.

Definition at line 529 of file item.cpp.

◆ relations()

Relation::List Item::relations ( ) const

Returns all relations of this item.

Since
4.15
See also
RelationCreateJob, RelationDeleteJob to modify relations

Definition at line 283 of file item.cpp.

◆ remoteId()

QString Item::remoteId ( ) const

Returns the remote id of the item.

Definition at line 73 of file item.cpp.

◆ remoteRevision()

QString Item::remoteRevision ( ) const

Returns the remote revision of the item.

Note
This method is supposed to be used by resources only.
Since
4.5

Definition at line 83 of file item.cpp.

◆ removeAttribute() [1/2]

template<typename T >
void Item::removeAttribute ( )
inline

Removes and deletes the attribute of the requested type.

Definition at line 750 of file item.h.

◆ removeAttribute() [2/2]

void Akonadi::Item::removeAttribute ( const QByteArray & name)

Removes and deletes the attribute of the given type name.

◆ revision()

int Item::revision ( ) const

Returns the revision number of the item.

Definition at line 311 of file item.cpp.

◆ setCachedPayloadParts()

void Item::setCachedPayloadParts ( const QSet< QByteArray > & cachedParts)

Definition at line 499 of file item.cpp.

◆ setFlag()

void Item::setFlag ( const QByteArray & name)

Sets the flag with the given name in the item.

Definition at line 180 of file item.cpp.

◆ setFlags()

void Item::setFlags ( const Flags & flags)

Overwrites all flags of the item by the given flags.

Definition at line 208 of file item.cpp.

◆ setGid()

void Item::setGid ( const QString & gid)

Sets the gid of the entity.

Since
4.12

Definition at line 352 of file item.cpp.

◆ setId()

void Item::setId ( Item::Id identifier)

Sets the unique identifier of the item.

Definition at line 58 of file item.cpp.

◆ setMimeType()

void Item::setMimeType ( const QString & mimeType)

Sets the mime type of the item to mimeType.

Definition at line 347 of file item.cpp.

◆ setModificationTime()

void Item::setModificationTime ( const QDateTime & datetime)

Sets the timestamp of the last modification of this item.

Parameters
datetimethe modification time to set
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 225 of file item.cpp.

◆ setParentCollection()

void Item::setParentCollection ( const Collection & parent)

Set the parent collection of this object.

Note
Calling this method has no immediate effect for the object itself, such as being moved to another collection. It is mainly relevant to provide a context for RID-based operations inside resources.
Parameters
parentThe parent collection.
Since
4.4

Definition at line 170 of file item.cpp.

◆ setPayload() [1/2]

template<typename T >
void 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 QSharedPointer and std::shared_ptr) and make sure there is a specialization of Akonadi::super_trait for your class.

Definition at line 913 of file item.h.

◆ setPayload() [2/2]

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

Definition at line 942 of file item.h.

◆ setPayloadFromData()

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

◆ setPayloadPath()

void Item::setPayloadPath ( const QString & filePath)

Sets a path to a file with full payload.

This method can only be used by Resources and should not be used by Akonadi clients. Clients should use setPayload() instead.

Akonadi will not duplicate content of the file in its database but will instead directly refer to this file. This means that the file must be persistent (don't use this method with a temporary files), and the Akonadi resource that owns the storage is responsible for updating the file path if the file is changed, moved or removed.

The payload can still be accessed via payload() methods.

See also
setPayload(), setPayloadFromData()
Since
5.6

Definition at line 520 of file item.cpp.

◆ setRemoteId()

void Item::setRemoteId ( const QString & id)

Sets the remote id of the item.

Definition at line 68 of file item.cpp.

◆ setRemoteRevision()

void Item::setRemoteRevision ( const QString & revision)

Sets the remote revision of the item.

Parameters
revisionthe item's remote revision The remote revision can be used by resources to store some revision information of the backend to detect changes there.
Note
This method is supposed to be used by resources only.
Since
4.5

Definition at line 78 of file item.cpp.

◆ setRevision()

void Item::setRevision ( int revision)

Sets the revision number of the item.

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

Definition at line 316 of file item.cpp.

◆ setSize()

void Item::setSize ( qint64 size)

Set the size of the item in bytes.

Parameters
sizethe size of the item in bytes
Since
4.2

Definition at line 336 of file item.cpp.

◆ setTag()

void Item::setTag ( const Tag & tag)

Definition at line 241 of file item.cpp.

◆ setTags()

void Item::setTags ( const Tag::List & list)

Definition at line 235 of file item.cpp.

◆ setVirtualReferences()

void Item::setVirtualReferences ( const Collection::List & collections)

Sets the virtual collections that this item is linked into.

Note
Note that changing this value makes no effect on what collections this item is linked to. To link or unlink an item to/from a virtual collection, use LinkJob and UnlinkJob.
Since
4.14

Definition at line 362 of file item.cpp.

◆ size()

qint64 Item::size ( ) const

Returns the size of the items in bytes.

Since
4.2

Definition at line 342 of file item.cpp.

◆ storageCollectionId()

Collection::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 321 of file item.cpp.

◆ tags()

Tag::List Item::tags ( ) const

Definition at line 278 of file item.cpp.

◆ url()

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

Returns the url of the item.

Definition at line 377 of file item.cpp.

◆ virtualReferences()

Collection::List Item::virtualReferences ( ) const

Lists virtual collections that this item is linked to.

Note
This value is populated only when this item was retrieved by ItemFetchJob with fetchVirtualReferences set to true in ItemFetchScope, otherwise this list is always empty.
Since
4.14

Definition at line 367 of file item.cpp.

Member Data Documentation

◆ FullPayload

const char Item::FullPayload = "RFC822"
static

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

Definition at line 127 of file item.h.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:38:52 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.