Item Class Reference

from PyKDE4.akonadi import *

Inherits: Akonadi.Entity
Namespace: Akonadi

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.

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

Enumerations
UrlType	{ UrlShort, UrlWithMimeType }
Attributes
QString	FullPayload
Methods
	__init__ (self)
	__init__ (self, QString mimeType)
	__init__ (self, Akonadi.Item other)
	__init__ (self, long id)
	apply (self, Akonadi.Item other)
QVector	availablePayloadMetaTypeIds (self)
QSet	availablePayloadParts (self)
	clearFlag (self, QByteArray name)
	clearFlags (self)
	clearPayload (self)
QSet	flags (self)
bool	hasFlag (self, QByteArray name)
bool	hasPayload (self)
QSet	loadedPayloadParts (self)
QString	mimeType (self)
QDateTime	modificationTime (self)
QByteArray	payloadData (self)
int	revision (self)
	setFlag (self, QByteArray name)
	setFlags (self, QSet flags)
	setMimeType (self, QString mimeType)
	setModificationTime (self, QDateTime datetime)
	setPayloadFromData (self, QByteArray data)
	setRevision (self, int revision)
	setSize (self, long size)
long	size (self)
long	storageCollectionId (self)
KUrl	url (self, Akonadi.Item.UrlType type=Akonadi.Item.UrlShort)
Static Methods
Akonadi.Item	fromUrl (KUrl url)

Method Documentation

__init__ ( self )

Creates a new item.

__init__	(	self,
		QString	mimeType
	)

Creates a new item with the given mime type.

Parameters:

mimeType

The mime type of the item.

__init__	(	self,
		Akonadi.Item	other
	)

Creates a new item from an other item.

__init__	(	self,
		long	id
	)

Creates a new item with the given unique id.

apply	(	self,
		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.

Since:: 4.4

QVector availablePayloadMetaTypeIds ( self )

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 availablePayloadParts ( self )

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

clearFlag	(	self,
		QByteArray	name
	)

Removes the flag with the given name from the item.

clearFlags ( self )

Removes all flags from the item.

clearPayload ( self )

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

QSet flags ( self )

Returns all flags of this item.

bool hasFlag	(	self,
		QByteArray	name
	)

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

bool hasPayload ( self )

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 loadedPayloadParts ( self )

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 mimeType ( self )

Returns the mime type of the item.

QDateTime modificationTime ( self )

Returns the timestamp of the last modification of this item.

Since:: 4.2

QByteArray payloadData ( self )

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.

int revision ( self )

Returns the revision number of the item.

setFlag	(	self,
		QByteArray	name
	)

Sets the flag with the given name in the item.

setFlags	(	self,
		QSet	flags
	)

Overwrites all flags of the item by the given flags.

setMimeType	(	self,
		QString	mimeType
	)

Sets the mime type of the item to mimeType.

setModificationTime	(	self,
		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

setPayloadFromData	(	self,
		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

setRevision	(	self,
		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.

setSize	(	self,
		long	size
	)

Set the size of the item in bytes.

Since:: 4.2

long size ( self )

Returns the size of the items in bytes.

Since:: 4.2

long storageCollectionId ( self )

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

KUrl url	(	self,
		Akonadi.Item.UrlType	type=Akonadi.Item.UrlShort
	)

Returns the url of the item.

Static Method Documentation

Akonadi.Item fromUrl	(	KUrl	url
	)

Creates an item from the given url.

Attribute Documentation

QString FullPayload

Enumeration Documentation

UrlType

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

Enumerator:

UrlShort = 0
UrlWithMimeType = 1

Item Class Reference

Detailed Description

Enumerations

Attributes

Methods

Static Methods

Method Documentation

Static Method Documentation

Attribute Documentation

Enumeration Documentation

Modules