Contents

Akonadi::Item Class

class Akonadi::Item

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

Header: #include <Akonadi/Item>
CMake: find_package(KPim6 REQUIRED COMPONENTS AkonadiCore)
target_link_libraries(mytarget PRIVATE KPim6::AkonadiCore)

Public Types

enum CreateOption { AddIfMissing, DontCreate }
enum UrlType { UrlShort, UrlWithMimeType }

Public Functions

Item()
Item(Akonadi::Item::Id id)
Item(const QString &mimeType)
Item(const Akonadi::Item &other)
Item(Akonadi::Item &&)
~Item()
void addAttribute(Akonadi::Attribute *attribute)
void apply(const Akonadi::Item &other)
const T *attribute() const
T *attribute(Akonadi::Item::CreateOption option = DontCreate)
Akonadi::Attribute *attribute(const QByteArray &name)
Akonadi::Attribute::List attributes() const
QList<int> availablePayloadMetaTypeIds() const
QSet<QByteArray> availablePayloadParts() const
QSet<QByteArray> cachedPayloadParts() const
void clearAttributes()
void clearFlag(const QByteArray &name)
void clearFlags()
void clearPayload()
Akonadi::Item::Flags flags() const
QString gid() const
bool hasAttribute() const
bool hasAttribute(const QByteArray &name) const
bool hasFlag(const QByteArray &name) const
bool hasPayload() const
bool hasPayload() const
Akonadi::Item::Id id() const
bool isValid() const
QSet<QByteArray> loadedPayloadParts() const
QString mimeType() const
QDateTime modificationTime() const
Akonadi::Collection &parentCollection()
Akonadi::Collection parentCollection() const
T payload() const
QByteArray payloadData() const
QString payloadPath() const
QString remoteId() const
QString remoteRevision() const
void removeAttribute()
void removeAttribute(const QByteArray &name)
int revision() const
void setFlag(const QByteArray &name)
void setFlags(const Akonadi::Item::Flags &flags)
void setGid(const QString &gid)
void setId(Akonadi::Item::Id identifier)
void setMimeType(const QString &mimeType)
void setModificationTime(const QDateTime &datetime)
void setParentCollection(const Akonadi::Collection &parent)
void setPayload(const 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 setVirtualReferences(const Akonadi::Collection::List &collections)
qint64 size() const
Akonadi::Collection::Id storageCollectionId() const
QUrl url(Akonadi::Item::UrlType type = UrlShort) const
Akonadi::Collection::List virtualReferences() const
bool operator!=(const Akonadi::Item &other) const
Akonadi::Item &operator=(const Akonadi::Item &other)
bool operator==(const Akonadi::Item &other) const

Static Public Members

const char[] FullPayload
Akonadi::Item fromUrl(const QUrl &url)

Detailed Description

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.

<h4>Payload</h4>

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

Member Type Documentation

enum Item::CreateOption

Describes the options that can be passed to access attributes.

enum Item::UrlType

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

Member Function Documentation

Item::Item()

Creates a new item.

[explicit] Item::Item(Akonadi::Item::Id id)

Creates a new item with the given unique id.

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

Creates a new item with the given mime type.

mimeType The mime type of the item.

Item::Item(const Akonadi::Item &other)

Creates a new item from an other item.

[noexcept] Item::Item(Akonadi::Item &&)

Move constructor.

[noexcept] Item::~Item()

Destroys the item.

void Item::addAttribute(Akonadi::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.

attribute The new attribute.

Note: The collection takes the ownership of the attribute.

void Item::apply(const Akonadi::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. other the item to get values from

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

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

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

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.

option The create options.

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

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

Akonadi::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.

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).

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.

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

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

See also ItemFetchJob and ItemFetchScope.

void Item::clearAttributes()

Removes and deletes all attributes of the item.

void Item::clearFlag(const QByteArray &name)

Removes the flag with the given name from the item.

void Item::clearFlags()

Removes all flags from the item.

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.

Akonadi::Item::Flags Item::flags() const

Returns all flags of this item.

See also setFlags().

[static] Akonadi::Item Item::fromUrl(const QUrl &url)

Creates an item from the given url.

QString Item::gid() const

Returns the gid of the entity.

See also setGid().

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

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

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

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

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

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

bool Item::hasPayload() const

Returns whether the item has a payload object.

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.

Akonadi::Item::Id Item::id() const

Returns the unique identifier of the item.

See also setId().

bool Item::isValid() const

Returns whether the item is valid.

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.

QString Item::mimeType() const

Returns the mime type of the item.

See also setMimeType().

QDateTime Item::modificationTime() const

Returns the timestamp of the last modification of this item.

See also setModificationTime().

Akonadi::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.

See also setParentCollection().

Akonadi::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.

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.

See also setPayload().

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.

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.

See also setPayloadPath().

QString Item::remoteId() const

Returns the remote id of the item.

See also setRemoteId().

QString Item::remoteRevision() const

Returns the remote revision of the item.

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

See also setRemoteRevision().

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

Removes and deletes the attribute of the requested type.

void Item::removeAttribute(const QByteArray &name)

Removes and deletes the attribute of the given type name.

int Item::revision() const

Returns the revision number of the item.

See also setRevision().

void Item::setFlag(const QByteArray &name)

Sets the flag with the given name in the item.

See also hasFlag().

void Item::setFlags(const Akonadi::Item::Flags &flags)

Overwrites all flags of the item by the given flags.

See also flags().

void Item::setGid(const QString &gid)

Sets the gid of the entity.

See also gid().

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

Sets the unique identifier of the item.

See also id().

void Item::setMimeType(const QString &mimeType)

Sets the mime type of the item to mimeType.

See also mimeType().

void Item::setModificationTime(const QDateTime &datetime)

Sets the timestamp of the last modification of this item. datetime the modification time to set

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

See also modificationTime().

void Item::setParentCollection(const Akonadi::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. parent The parent collection.

See also parentCollection().

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

Sets the payload object of this PIM item.

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

See also payload().

void Item::setPayloadFromData(const QByteArray &data)

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

data The encoded data.

See also fullPayloadData.

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 payloadPath(), setPayload(), and setPayloadFromData().

void Item::setRemoteId(const QString &id)

Sets the remote id of the item.

See also remoteId().

void Item::setRemoteRevision(const QString &revision)

Sets the remote revision of the item. revision the 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.

See also remoteRevision().

void Item::setRevision(int revision)

Sets the revision number of the item. revision the revision number to set

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

See also revision().

void Item::setSize(qint64 size)

Set the size of the item in bytes. size the size of the item in bytes

See also size().

void Item::setVirtualReferences(const Akonadi::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.

See also virtualReferences().

qint64 Item::size() const

Returns the size of the items in bytes.

See also setSize().

Akonadi::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.

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

Returns the url of the item.

Akonadi::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.

See also setVirtualReferences().

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

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

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

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

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

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

Member Variable Documentation

const char[] Item::FullPayload

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