#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< QByteArray >	attributes () const

bool	cacheOnly () const

bool	checkForCachedPayloadPartsOnly () const

void	fetchAllAttributes (bool fetch=true)

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

template<typename T >
void	fetchAttribute (bool fetch=true)

KDateTime	fetchChangedSince () const

void	fetchFullPayload (bool fetch=true)

bool	fetchGid () const

bool	fetchModificationTime () const

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

bool	fetchRemoteIdentification () const

bool	fetchTags () const

bool	fetchVirtualReferences () const

bool	fullPayload () const

bool	ignoreRetrievalErrors () const

bool	isEmpty () const

ItemFetchScope &	operator= (const ItemFetchScope &other)

QSet< QByteArray >	payloadParts () const

void	setAncestorRetrieval (AncestorRetrieval ancestorDepth)

void	setCacheOnly (bool cacheOnly)

void	setCheckForCachedPayloadPartsOnly (bool check=true)

void	setFetchChangedSince (const KDateTime &changedSince)

void	setFetchGid (bool retrieveGID)

void	setFetchModificationTime (bool retrieveMtime)

void	setFetchRemoteIdentification (bool retrieveRid)

void	setFetchTags (bool fetchTags)

void	setFetchVirtualReferences (bool fetchVRefs)

void	setIgnoreRetrievalErrors (bool enabled)

void	setTagFetchScope (const TagFetchScope &fetchScope)

TagFetchScope &	tagFetchScope ()

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

Akonadi::ItemFetchJob *job = new Akonadi::ItemFetchJob( collection );
job->fetchScope().fetchFullPayload();
job->fetchScope().fetchAttribute<MyAttribute>();

Example: replacing an ItemFetchJob's scope

Akonadi::ItemFetchScope scope;
scope.fetchFullPayload();
scope.fetchAttribute<MyAttribute>();
Akonadi::ItemFetchJob *job = new Akonadi::ItemFetchJob( collection );
job->setFetchScope( scope );

This class is implicitly shared.

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

Definition at line 69 of file itemfetchscope.h.

Member Enumeration Documentation

enum Akonadi::ItemFetchScope::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 76 of file itemfetchscope.h.

Constructor & Destructor Documentation

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 28 of file itemfetchscope.cpp.

ItemFetchScope::ItemFetchScope ( const ItemFetchScope & other )

Creates a new item fetch scope from an other.

Definition at line 33 of file itemfetchscope.cpp.

ItemFetchScope::~ItemFetchScope ( )

Destroys the item fetch scope.

Definition at line 38 of file itemfetchscope.cpp.

Member Function Documentation

bool ItemFetchScope::allAttributes ( ) const

Returns whether all available attributes should be fetched.

See also: fetchAllAttributes()

Definition at line 89 of file itemfetchscope.cpp.

ItemFetchScope::AncestorRetrieval ItemFetchScope::ancestorRetrieval ( ) const

Returns the ancestor retrieval depth.

See also: setAncestorRetrieval()

Since: 4.4

Definition at line 127 of file itemfetchscope.cpp.

QSet< QByteArray > ItemFetchScope::attributes ( ) const

Returns all explicitly fetched attributes.

Undefined if fetchAllAttributes() returns true.

See also: fetchAttribute()

Definition at line 75 of file itemfetchscope.cpp.

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 104 of file itemfetchscope.cpp.

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 122 of file itemfetchscope.cpp.

void ItemFetchScope::fetchAllAttributes ( bool fetch = true )

Sets whether all available attributes should be fetched.

The default is false.

Parameters

fetch true if all available attributes should be fetched, false otherwise.

Definition at line 94 of file itemfetchscope.cpp.

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

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

Parameters

type	The attribute type to fetch.
fetch	`true` if the attribute should be fetched, `false` otherwise.

Definition at line 80 of file itemfetchscope.cpp.

template<typename T >

void Akonadi::ItemFetchScope::fetchAttribute ( bool fetch = true )

inline

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

Parameters

fetch true if the attribute should be fetched, false otherwise.

Definition at line 158 of file itemfetchscope.h.

KDateTime ItemFetchScope::fetchChangedSince ( ) const

Returns timestamp of the oldest item to fetch.

Definition at line 172 of file itemfetchscope.cpp.

void ItemFetchScope::fetchFullPayload ( bool fetch = true )

Sets whether the full payload shall be fetched.

The default is false.

Parameters

fetch true if the full payload should be fetched, false otherwise.

Definition at line 70 of file itemfetchscope.cpp.

bool ItemFetchScope::fetchGid ( ) const

Returns whether item GID should be retrieved.

See also: setFetchGid()

Since: 4.12

Definition at line 152 of file itemfetchscope.cpp.

bool ItemFetchScope::fetchModificationTime ( ) const

Returns whether item modification time should be retrieved.

See also: setFetchModificationTime()

Since: 4.6

Definition at line 142 of file itemfetchscope.cpp.

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

Sets which payload parts shall be fetched.

Parameters

part	The payload part identifier. Valid values depend on the item type.
fetch	`true` to fetch this part, `false` otherwise.

Definition at line 56 of file itemfetchscope.cpp.

bool ItemFetchScope::fetchRemoteIdentification ( ) const

Returns whether item remote identification should be retrieved.

See also: setFetchRemoteIdentification()

Since: 4.12

Definition at line 182 of file itemfetchscope.cpp.

bool ItemFetchScope::fetchTags ( ) const

Returns whether tags should be retrieved.

See also: setFetchTags()

Since: 4.13

Definition at line 192 of file itemfetchscope.cpp.

bool ItemFetchScope::fetchVirtualReferences ( ) const

Returns whether virtual references should be retrieved.

See also: setFetchVirtualReferences()

Since: 4.14

Definition at line 217 of file itemfetchscope.cpp.

bool ItemFetchScope::fullPayload ( ) const

Returns whether the full payload should be fetched.

See also: fetchFullPayload()

Definition at line 65 of file itemfetchscope.cpp.

bool ItemFetchScope::ignoreRetrievalErrors ( ) const

Returns whether retrieval errors should be ignored.

See also: setIgnoreRetrievalErrors()

Since: 4.10

Definition at line 162 of file itemfetchscope.cpp.

bool ItemFetchScope::isEmpty ( ) const

Returns true if there is nothing to fetch.

Definition at line 99 of file itemfetchscope.cpp.

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

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

Definition at line 42 of file itemfetchscope.cpp.

QSet< QByteArray > ItemFetchScope::payloadParts ( ) const

Returns the payload parts that should be fetched.

See also: fetchPayloadPart()

Definition at line 51 of file itemfetchscope.cpp.

void ItemFetchScope::setAncestorRetrieval ( AncestorRetrieval ancestorDepth )

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

The default is AncestorRetrieval::None.

Parameters

ancestorDepth The desired ancestor retrieval depth.

Since: 4.4

Definition at line 132 of file itemfetchscope.cpp.

void ItemFetchScope::setCacheOnly ( bool cacheOnly )

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

Parameters

cacheOnly true if no remote data should be requested, false otherwise (the default).

Definition at line 109 of file itemfetchscope.cpp.

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 114 of file itemfetchscope.cpp.

void ItemFetchScope::setFetchChangedSince ( const KDateTime & 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

changedSince The timestamp of oldest modified item to fetch

Since: 4.11

Definition at line 167 of file itemfetchscope.cpp.

void ItemFetchScope::setFetchGid ( bool retrieveGID )

Enables retrieval of the item GID.

This is disabled by default.

Parameters

retrieveGID true to retrieve the GID, false otherwise

Since: 4.12

Definition at line 147 of file itemfetchscope.cpp.

void ItemFetchScope::setFetchModificationTime ( bool retrieveMtime )

Enables retrieval of the item modification time.

This is enabled by default for backward compatibility reasons.

Parameters

retrieveMtime true to retrieve the modification time, false otherwise

Since: 4.6

Definition at line 137 of file itemfetchscope.cpp.

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

retrieveRid whether or not to load remote identification.

Since: 4.12

Definition at line 177 of file itemfetchscope.cpp.

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

fetchTags whether or not to load tags.

Since: 4.13

Definition at line 187 of file itemfetchscope.cpp.

void ItemFetchScope::setFetchVirtualReferences ( bool fetchVRefs )

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

Parameters

fetchVRefs whether or not to fetch virtualc references

Since: 4.14

Definition at line 212 of file itemfetchscope.cpp.

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 157 of file itemfetchscope.cpp.

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

fetchScope The new fetch scope for tag fetch operations.

See also: fetchScope()

Since: 4.15

Definition at line 197 of file itemfetchscope.cpp.

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 202 of file itemfetchscope.cpp.

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 207 of file itemfetchscope.cpp.

The documentation for this class was generated from the following files:

akonadi

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

akonadi

kdepimlibs API Reference

Search