Akonadi::Item Class Reference
Represents a PIM item stored in Akonadi storage.
More...
#include <item.h>
List of all members.
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
Describes a flag name.
Definition at line 97 of file item.h.
Describes a set of flag names.
Definition at line 102 of file item.h.
Describes a list of items.
Definition at line 92 of file item.h.
Member Enumeration Documentation
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
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.
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.
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:
-
- 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.
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
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: