Akonadi::ItemFetchScope

Search for usage in LXR

Akonadi::ItemFetchScope Class Reference

#include <itemfetchscope.h>

Public Types

enum  AncestorRetrieval { None , Parent , All }
 

Public Member Functions

 ItemFetchScope ()
 
 ItemFetchScope (const ItemFetchScope &other)
 
 ~ItemFetchScope ()
 
bool allAttributes () const
 
AncestorRetrieval ancestorRetrieval () const
 
QSet< QByteArrayattributes () const
 
bool cacheOnly () const
 
bool checkForCachedPayloadPartsOnly () const
 
void fetchAllAttributes (bool fetch=true)
 
template<typename T >
void fetchAttribute (bool fetch=true)
 
void fetchAttribute (const QByteArray &type, bool fetch=true)
 
QDateTime fetchChangedSince () const
 
void fetchFullPayload (bool fetch=true)
 
bool fetchGid () const
 
bool fetchModificationTime () const
 
void fetchPayloadPart (const QByteArray &part, bool fetch=true)
 
bool fetchRelations () const
 
bool fetchRemoteIdentification () const
 
bool fetchTags () const
 
bool fetchVirtualReferences () const
 
bool fullPayload () const
 
bool ignoreRetrievalErrors () const
 
bool isEmpty () const
 
ItemFetchScopeoperator= (const ItemFetchScope &other)
 
QSet< QByteArraypayloadParts () const
 
void setAncestorRetrieval (AncestorRetrieval ancestorDepth)
 
void setCacheOnly (bool cacheOnly)
 
void setCheckForCachedPayloadPartsOnly (bool check=true)
 
void setFetchChangedSince (const QDateTime &changedSince)
 
void setFetchGid (bool retrieveGID)
 
void setFetchModificationTime (bool retrieveMtime)
 
void setFetchRelations (bool fetchRelations)
 
void setFetchRemoteIdentification (bool retrieveRid)
 
void setFetchTags (bool fetchTags)
 
void setFetchVirtualReferences (bool fetchVRefs)
 
void setIgnoreRetrievalErrors (bool enabled)
 
void setTagFetchScope (const TagFetchScope &fetchScope)
 
TagFetchScopetagFetchScope ()
 
TagFetchScope tagFetchScope () const
 

Detailed Description

Specifies which parts of an item should be fetched from the Akonadi storage.

When items are fetched from server either by using ItemFetchJob explicitly or when it is being used internally by other classes, e.g. ItemModel, the scope of the fetch operation can be tailored to the application's current needs.

There are two supported ways of changing the currently active ItemFetchScope of classes:

  • in-place: modify the ItemFetchScope object the other class holds as a member
  • replace: replace the other class' member with a new scope object

Example: modifying an ItemFetchJob's scope in-place

job->fetchScope().fetchAttribute<MyAttribute>();
Job that fetches items from the Akonadi storage.
ItemFetchScope & fetchScope()
Returns the item fetch scope.
void fetchAttribute(const QByteArray &type, bool fetch=true)
Sets whether the attribute of the given type should be fetched.
void fetchFullPayload(bool fetch=true)
Sets whether the full payload shall be fetched.

Example: replacing an ItemFetchJob's scope

scope.fetchAttribute<MyAttribute>();
job->setFetchScope( scope );
Specifies which parts of an item should be fetched from the Akonadi storage.

This class is implicitly shared.

Author
Kevin Krammer kevin.nosp@m..kra.nosp@m.mmer@.nosp@m.gmx..nosp@m.at

Definition at line 57 of file itemfetchscope.h.

Member Enumeration Documentation

◆ AncestorRetrieval

Describes the ancestor retrieval depth.

Since
4.4
Enumerator
None 

No ancestor retrieval at all (the default)

Parent 

Only retrieve the immediate parent collection.

All 

Retrieve all ancestors, up to Collection::root()

Definition at line 64 of file itemfetchscope.h.

Constructor & Destructor Documentation

◆ ItemFetchScope() [1/2]

ItemFetchScope::ItemFetchScope ( )

Creates an empty item fetch scope.

Using an empty scope will only fetch the very basic meta data of items, e.g. local id, remote id and mime type

Definition at line 13 of file itemfetchscope.cpp.

◆ ItemFetchScope() [2/2]

ItemFetchScope::ItemFetchScope ( const ItemFetchScope & other)

Creates a new item fetch scope from an other.

Definition at line 18 of file itemfetchscope.cpp.

◆ ~ItemFetchScope()

ItemFetchScope::~ItemFetchScope ( )

Destroys the item fetch scope.

Definition at line 23 of file itemfetchscope.cpp.

Member Function Documentation

◆ allAttributes()

bool ItemFetchScope::allAttributes ( ) const

Returns whether all available attributes should be fetched.

See also
fetchAllAttributes()

Definition at line 74 of file itemfetchscope.cpp.

◆ ancestorRetrieval()

ItemFetchScope::AncestorRetrieval ItemFetchScope::ancestorRetrieval ( ) const

Returns the ancestor retrieval depth.

See also
setAncestorRetrieval()
Since
4.4

Definition at line 115 of file itemfetchscope.cpp.

◆ attributes()

QSet< QByteArray > ItemFetchScope::attributes ( ) const

Returns all explicitly fetched attributes.

Undefined if fetchAllAttributes() returns true.

See also
fetchAttribute()

Definition at line 60 of file itemfetchscope.cpp.

◆ cacheOnly()

bool ItemFetchScope::cacheOnly ( ) const

Returns whether payload data should be requested from remote sources or just from the local cache.

See also
setCacheOnly()

Definition at line 92 of file itemfetchscope.cpp.

◆ checkForCachedPayloadPartsOnly()

bool ItemFetchScope::checkForCachedPayloadPartsOnly ( ) const

Returns whether payload data should be fetched or only checked for presence in the cache.

See also
setCheckForCachedPayloadPartsOnly()
Since
4.11

Definition at line 110 of file itemfetchscope.cpp.

◆ fetchAllAttributes()

void ItemFetchScope::fetchAllAttributes ( bool fetch = true)

Sets whether all available attributes should be fetched.

The default is false.

Parameters
fetchtrue if all available attributes should be fetched, false otherwise.

Definition at line 79 of file itemfetchscope.cpp.

◆ fetchAttribute() [1/2]

template<typename T >
void Akonadi::ItemFetchScope::fetchAttribute ( bool fetch = true)
inline

Sets whether the attribute of the requested type should be fetched.

Parameters
fetchtrue if the attribute should be fetched, false otherwise.

Definition at line 147 of file itemfetchscope.h.

◆ fetchAttribute() [2/2]

void ItemFetchScope::fetchAttribute ( const QByteArray & type,
bool fetch = true )

Sets whether the attribute of the given type should be fetched.

Parameters
typeThe attribute type to fetch.
fetchtrue if the attribute should be fetched, false otherwise.

Definition at line 65 of file itemfetchscope.cpp.

◆ fetchChangedSince()

QDateTime ItemFetchScope::fetchChangedSince ( ) const

Returns timestamp of the oldest item to fetch.

Definition at line 160 of file itemfetchscope.cpp.

◆ fetchFullPayload()

void ItemFetchScope::fetchFullPayload ( bool fetch = true)

Sets whether the full payload shall be fetched.

The default is false.

Parameters
fetchtrue if the full payload should be fetched, false otherwise.

Definition at line 55 of file itemfetchscope.cpp.

◆ fetchGid()

bool ItemFetchScope::fetchGid ( ) const

Returns whether item GID should be retrieved.

See also
setFetchGid()
Since
4.12

Definition at line 140 of file itemfetchscope.cpp.

◆ fetchModificationTime()

bool ItemFetchScope::fetchModificationTime ( ) const

Returns whether item modification time should be retrieved.

See also
setFetchModificationTime()
Since
4.6

Definition at line 130 of file itemfetchscope.cpp.

◆ fetchPayloadPart()

void ItemFetchScope::fetchPayloadPart ( const QByteArray & part,
bool fetch = true )

Sets which payload parts shall be fetched.

Parameters
partThe payload part identifier. Valid values depend on the item type.
fetchtrue to fetch this part, false otherwise.

Definition at line 41 of file itemfetchscope.cpp.

◆ fetchRelations()

bool ItemFetchScope::fetchRelations ( ) const

Returns whether relations should be retrieved.

See also
setFetchRelations()
Since
4.15

Definition at line 215 of file itemfetchscope.cpp.

◆ fetchRemoteIdentification()

bool ItemFetchScope::fetchRemoteIdentification ( ) const

Returns whether item remote identification should be retrieved.

See also
setFetchRemoteIdentification()
Since
4.12

Definition at line 170 of file itemfetchscope.cpp.

◆ fetchTags()

bool ItemFetchScope::fetchTags ( ) const

Returns whether tags should be retrieved.

See also
setFetchTags()
Since
4.13

Definition at line 180 of file itemfetchscope.cpp.

◆ fetchVirtualReferences()

bool ItemFetchScope::fetchVirtualReferences ( ) const

Returns whether virtual references should be retrieved.

See also
setFetchVirtualReferences()
Since
4.14

Definition at line 205 of file itemfetchscope.cpp.

◆ fullPayload()

bool ItemFetchScope::fullPayload ( ) const

Returns whether the full payload should be fetched.

See also
fetchFullPayload()

Definition at line 50 of file itemfetchscope.cpp.

◆ ignoreRetrievalErrors()

bool ItemFetchScope::ignoreRetrievalErrors ( ) const

Returns whether retrieval errors should be ignored.

See also
setIgnoreRetrievalErrors()
Since
4.10

Definition at line 150 of file itemfetchscope.cpp.

◆ isEmpty()

bool ItemFetchScope::isEmpty ( ) const

Returns true if there is nothing to fetch.

Definition at line 84 of file itemfetchscope.cpp.

◆ operator=()

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

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

Definition at line 27 of file itemfetchscope.cpp.

◆ payloadParts()

QSet< QByteArray > ItemFetchScope::payloadParts ( ) const

Returns the payload parts that should be fetched.

See also
fetchPayloadPart()

Definition at line 36 of file itemfetchscope.cpp.

◆ setAncestorRetrieval()

void ItemFetchScope::setAncestorRetrieval ( AncestorRetrieval ancestorDepth)

Sets how many levels of ancestor collections should be included in the retrieval.

The default is AncestorRetrieval::None.

Parameters
ancestorDepthThe desired ancestor retrieval depth.
Since
4.4

Definition at line 120 of file itemfetchscope.cpp.

◆ setCacheOnly()

void ItemFetchScope::setCacheOnly ( bool cacheOnly)

Sets whether payload data should be requested from remote sources or just from the local cache.

Parameters
cacheOnlytrue if no remote data should be requested, false otherwise (the default).

Definition at line 97 of file itemfetchscope.cpp.

◆ setCheckForCachedPayloadPartsOnly()

void ItemFetchScope::setCheckForCachedPayloadPartsOnly ( bool check = true)

Sets whether payload will be fetched or there will be only a test performed if the requested payload is in the cache.

Calling it calls

See also
setCacheOnly with true automatically. Default is fetching the data.
Since
4.11

Definition at line 102 of file itemfetchscope.cpp.

◆ setFetchChangedSince()

void ItemFetchScope::setFetchChangedSince ( const QDateTime & changedSince)

Only fetch items that were added or modified after given timestamp.

When this property is set, all results are filtered, i.e. even when you request an item with a specific ID, it will not be fetched unless it was modified after changedSince timestamp.

Parameters
changedSinceThe timestamp of oldest modified item to fetch
Since
4.11

Definition at line 155 of file itemfetchscope.cpp.

◆ setFetchGid()

void ItemFetchScope::setFetchGid ( bool retrieveGID)

Enables retrieval of the item GID.

This is disabled by default.

Parameters
retrieveGIDtrue to retrieve the GID, false otherwise
Since
4.12

Definition at line 135 of file itemfetchscope.cpp.

◆ setFetchModificationTime()

void ItemFetchScope::setFetchModificationTime ( bool retrieveMtime)

Enables retrieval of the item modification time.

This is enabled by default for backward compatibility reasons.

Parameters
retrieveMtimetrue to retrieve the modification time, false otherwise
Since
4.6

Definition at line 125 of file itemfetchscope.cpp.

◆ setFetchRelations()

void ItemFetchScope::setFetchRelations ( bool fetchRelations)

Fetch relations for items.

The default is false.

Parameters
fetchRelationswhether or not to load relations.
Since
4.15

Definition at line 210 of file itemfetchscope.cpp.

◆ setFetchRemoteIdentification()

void ItemFetchScope::setFetchRemoteIdentification ( bool retrieveRid)

Fetch remote identification for items.

These include Akonadi::Item::remoteId() and Akonadi::Item::remoteRevision(). This should be off for normal clients usually, to save memory (not to mention normal clients should not be concerned with these information anyway). It is however crucial for resource agents. For backward compatibility the default is true.

Parameters
retrieveRidwhether or not to load remote identification.
Since
4.12

Definition at line 165 of file itemfetchscope.cpp.

◆ setFetchTags()

void ItemFetchScope::setFetchTags ( bool fetchTags)

Fetch tags for items.

The fetched tags have only the Tag::id() set and need to be fetched first to access further attributes.

The default is false.

Parameters
fetchTagswhether or not to load tags.
Since
4.13

Definition at line 175 of file itemfetchscope.cpp.

◆ setFetchVirtualReferences()

void ItemFetchScope::setFetchVirtualReferences ( bool fetchVRefs)

Returns whether to fetch list of virtual collections the item is linked to.

Parameters
fetchVRefswhether or not to fetch virtualc references
Since
4.14

Definition at line 200 of file itemfetchscope.cpp.

◆ setIgnoreRetrievalErrors()

void ItemFetchScope::setIgnoreRetrievalErrors ( bool enabled)

Ignore retrieval errors while fetching items, and always deliver what is available.

If items have missing parts and the part can't be retrieved from the resource (i.e. because the system is offline), the fetch job would normally just fail. By setting this flag, the errors are ignored, and all items which could be fetched completely are returned. Note that all items that are returned are completely fetched, and incomplete items are simply ignored. This flag is useful for displaying everything that is available, where it is not crucial to have all items. Never use this for things like data migration or alike.

Since
4.10

Definition at line 145 of file itemfetchscope.cpp.

◆ setTagFetchScope()

void ItemFetchScope::setTagFetchScope ( const TagFetchScope & fetchScope)

Sets the tag fetch scope.

The TagFetchScope controls how much of an tags's data is fetched from the server.

By default setFetchIdOnly is set to true on the tag fetch scope.

Parameters
fetchScopeThe new fetch scope for tag fetch operations.
See also
fetchScope()
Since
4.15

Definition at line 185 of file itemfetchscope.cpp.

◆ tagFetchScope() [1/2]

TagFetchScope & ItemFetchScope::tagFetchScope ( )

Returns the tag fetch scope.

Since this returns a reference it can be used to conveniently modify the current scope in-place, i.e. by calling a method on the returned reference without storing it in a local variable. See the TagFetchScope documentation for an example.

By default setFetchIdOnly is set to true on the tag fetch scope.

Returns
a reference to the current tag fetch scope
See also
setFetchScope() for replacing the current tag fetch scope
Since
4.15

Definition at line 190 of file itemfetchscope.cpp.

◆ tagFetchScope() [2/2]

TagFetchScope ItemFetchScope::tagFetchScope ( ) const

Returns the tag fetch scope.

By default setFetchIdOnly is set to true on the tag fetch scope.

Returns
a reference to the current tag fetch scope
See also
setFetchScope() for replacing the current tag fetch scope
Since
4.15

Definition at line 195 of file itemfetchscope.cpp.


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.