Akonadi::Collection Class Reference

#include <collection.h>

Public Types
enum	CreateOption { AddIfMissing , DontCreate }
using	Id = qint64
using	List = QList<Collection>
enum	ListPreference { ListEnabled , ListDisabled , ListDefault }
enum	ListPurpose { ListSync , ListDisplay , ListIndex }
enum	Right {   ReadOnly = 0x0 , CanChangeItem = 0x1 , CanCreateItem = 0x2 , CanDeleteItem = 0x4 ,   CanChangeCollection = 0x8 , CanCreateCollection = 0x10 , CanDeleteCollection = 0x20 , CanLinkItem = 0x40 ,   CanUnlinkItem = 0x80 , AllRights }
typedef QFlags< Right >	Rights
enum	UrlType { UrlShort = 0 , UrlWithName = 1 }

Properties
QStringList	contentMimeTypes
QString	displayName
bool	enabled
Id	id
bool	isValid
bool	isVirtual
QString	name
QString	remoteIdd
QString	remoteRevision
QString	resource
Rights	rights

Public Member Functions
	Collection ()
	Collection (Collection &&other) noexcept
	Collection (const Collection &other)
	Collection (Id id)
	~Collection ()
void	addAttribute (Attribute *attribute)
template<typename T >
const T *	attribute () const
Attribute *	attribute (const QByteArray &name)
const Attribute *	attribute (const QByteArray &name) const
template<typename T >
T *	attribute (CreateOption option=DontCreate)
Attribute::List	attributes () const
CachePolicy	cachePolicy () const
void	clearAttributes ()
QStringList	contentMimeTypes () const
QString	displayName () const
bool	enabled () const
template<typename T >
bool	hasAttribute () const
bool	hasAttribute (const QByteArray &name) const
Id	id () const
bool	isValid () const
bool	isVirtual () const
QSet< QByteArray >	keepLocalChanges () const
ListPreference	localListPreference (ListPurpose purpose) const
QString	name () const
bool	operator!= (const Collection &other) const
bool	operator< (const Collection &other) const
Collection &	operator= (const Collection &other)
bool	operator== (const Collection &other) const
Collection &	parentCollection ()
Collection	parentCollection () const
QString	remoteId () const
QString	remoteRevision () const
template<typename T >
void	removeAttribute ()
void	removeAttribute (const QByteArray &name)
QString	resource () const
Rights	rights () const
void	setCachePolicy (const CachePolicy &policy)
void	setContentMimeTypes (const QStringList &types)
void	setEnabled (bool enabled)
void	setId (Id identifier)
void	setKeepLocalChanges (const QSet< QByteArray > &parts)
void	setLocalListPreference (ListPurpose purpose, ListPreference preference)
void	setName (const QString &name)
void	setParentCollection (const Collection &parent)
void	setRemoteId (const QString &id)
void	setRemoteRevision (const QString &revision)
void	setResource (const QString &identifier)
void	setRights (Rights rights)
void	setShouldList (ListPurpose purpose, bool shouldList)
void	setStatistics (const CollectionStatistics &statistics)
void	setVirtual (bool isVirtual)
bool	shouldList (ListPurpose purpose) const
CollectionStatistics	statistics () const
QUrl	url (UrlType type=UrlShort) const

Static Public Member Functions
static Collection	fromUrl (const QUrl &url)
static QString	mimeType ()
static Collection	root ()
static QString	virtualMimeType ()

Detailed Description

Represents a collection of PIM items.

This class represents a collection of PIM items, such as a folder on a mail- or groupware-server.

Collections are hierarchical, i.e., they may have a parent collection.

using namespace Akonadi;
 
// fetching all collections recursive, starting at the root collection
CollectionFetchJob *job = new CollectionFetchJob( Collection::root(), CollectionFetchJob::Recursive );
connect( job, SIGNAL(result(KJob*)), SLOT(fetchFinished(KJob*)) );
 
...
 
MyClass::fetchFinished( KJob *job )
{
  if ( job->error() ) {
    qDebug() << "Error occurred";
    return;
  }
 
  CollectionFetchJob *fetchJob = qobject_cast<CollectionFetchJob*>( job );
 
  const Collection::List collections = fetchJob->collections();
  for ( const Collection &collection : collections ) {
    qDebug() << "Name:" << collection.name();
  }
}

Author

Volker Krause vkrau.nosp@m.se@k.nosp@m.de.or.nosp@m.g

Definition at line 61 of file collection.h.

Member Typedef Documentation

Id

using Akonadi::Collection::Id = qint64

Describes the unique id type.

Definition at line 79 of file collection.h.

List

using Akonadi::Collection::List = QList<Collection>

Describes a list of collections.

Definition at line 84 of file collection.h.

Rights

QFlags< Right > Akonadi::Collection::Rights

Definition at line 102 of file collection.h.

Member Enumeration Documentation

CreateOption

enum Akonadi::Collection::CreateOption

Describes the options that can be passed to access attributes.

Enumerator
AddIfMissing	Creates the attribute if it is missing.
DontCreate	Default value.

Definition at line 280 of file collection.h.

ListPreference

enum Akonadi::Collection::ListPreference

Describes the list preference value.

Since

4.14

Enumerator
ListEnabled	Enable collection for specified purpose.
ListDisabled	Disable collection for specified purpose.
ListDefault	Fallback to enabled state.

Definition at line 468 of file collection.h.

ListPurpose

enum Akonadi::Collection::ListPurpose

Describes the purpose of the listing.

Since

4.14

Enumerator
ListSync	Listing for synchronization.
ListDisplay	Listing for display to the user.
ListIndex	Listing for indexing the content.

Definition at line 479 of file collection.h.

Right

enum Akonadi::Collection::Right

Describes rights of a collection.

Enumerator
ReadOnly	Can only read items or subcollection of this collection.
CanChangeItem	Can change items in this collection.
CanCreateItem	Can create new items in this collection.
CanDeleteItem	Can delete items in this collection.
CanChangeCollection	Can change this collection.
CanCreateCollection	Can create new subcollections in this collection.
CanDeleteCollection	Can delete this collection.
CanLinkItem	Can create links to existing items in this virtual collection. Since 4.4
CanUnlinkItem	Can remove links to items in this virtual collection. Since 4.4
AllRights	Has all rights on this storage collection.

Definition at line 89 of file collection.h.

UrlType

enum Akonadi::Collection::UrlType

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

Since

4.7

Enumerator
UrlShort	A short url which contains the identifier only (equivalent to url())
UrlWithName	A url with identifier and name.

Definition at line 408 of file collection.h.

Property Documentation

contentMimeTypes

QStringList Akonadi::Collection::contentMimeTypes

readwrite

Definition at line 73 of file collection.h.

displayName

QString Akonadi::Collection::displayName

read

Definition at line 71 of file collection.h.

enabled

bool Akonadi::Collection::enabled

readwrite

Definition at line 68 of file collection.h.

id

Id Akonadi::Collection::id

readwrite

Definition at line 64 of file collection.h.

isValid

bool Akonadi::Collection::isValid

read

Definition at line 66 of file collection.h.

isVirtual

bool Akonadi::Collection::isVirtual

readwrite

Definition at line 69 of file collection.h.

name

QString Akonadi::Collection::name

readwrite

Definition at line 70 of file collection.h.

remoteIdd

QString Akonadi::Collection::remoteIdd

readwrite

Definition at line 65 of file collection.h.

remoteRevision

QString Akonadi::Collection::remoteRevision

readwrite

Definition at line 67 of file collection.h.

resource

QString Akonadi::Collection::resource

readwrite

Definition at line 74 of file collection.h.

rights

Rights Akonadi::Collection::rights

readwrite

Definition at line 72 of file collection.h.

Constructor & Destructor Documentation

Collection() [1/4]

Collection::Collection

(

)

Creates an invalid collection.

Definition at line 70 of file collection.cpp.

Collection() [2/4]

Collection::Collection ( Id id )

explicit

Create a new collection.

Parameters

id	The unique identifier of the collection.

Definition at line 77 of file collection.cpp.

~Collection()

Collection::~Collection ( )

default

Destroys the collection.

Collection() [3/4]

Collection::Collection

(

const Collection &

other

)

Creates a collection from an other collection.

Definition at line 82 of file collection.cpp.

Collection() [4/4]

Collection::Collection ( Collection && other )

defaultnoexcept

Move constructor.

Member Function Documentation

addAttribute()

void Collection::addAttribute

(

Attribute *

attribute

)

Adds an attribute to the collection.

If an attribute of the same type name already exists, it is deleted and replaced with the new one.

Parameters

attribute

The new attribute.

Note

The collection takes the ownership of the attribute.

Definition at line 151 of file collection.cpp.

attribute() [1/4]

template<typename T >

const T * Akonadi::Collection::attribute ( ) const

inline

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

Definition at line 573 of file collection.h.

attribute() [2/4]

Attribute * Collection::attribute

(

const QByteArray &

name

)

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

Definition at line 176 of file collection.cpp.

attribute() [3/4]

const Attribute * Collection::attribute

(

const QByteArray &

name

)

const

Definition at line 182 of file collection.cpp.

attribute() [4/4]

template<typename T >

T * Akonadi::Collection::attribute ( Collection::CreateOption option = DontCreate )

inline

Returns the attribute of the requested type.

If the collection has no attribute of that type yet, passing AddIfMissing as an argument will create and add it to the entity

Parameters

option

The create options.

Definition at line 554 of file collection.h.

attributes()

Attribute::List Collection::attributes ( ) const

nodiscard

Returns a list of all attributes of the collection.

Warning

Do not modify the attributes returned from this method, the change will not be reflected when updating the Collection through CollectionModifyJob.

Definition at line 166 of file collection.cpp.

cachePolicy()

CachePolicy Collection::cachePolicy ( ) const

nodiscard

Returns the cache policy of the collection.

Definition at line 336 of file collection.cpp.

clearAttributes()

void Akonadi::Collection::clearAttributes

(

)

Removes and deletes all attributes of the collection.

Definition at line 171 of file collection.cpp.

contentMimeTypes()

QStringList Collection::contentMimeTypes ( ) const

nodiscard

Returns a list of possible content mimetypes, e.g.

message/rfc822, x-akonadi/collection for a mail folder that supports sub-folders.

Definition at line 240 of file collection.cpp.

displayName()

QString Collection::displayName ( ) const

nodiscard

Returns the display name (EntityDisplayAttribute::displayName()) if set, and Collection::name() otherwise.

For human-readable strings this is preferred over Collection::name().

Since

4.11

Definition at line 214 of file collection.cpp.

enabled()

bool Collection::enabled ( ) const

nodiscard

Returns the collection's enabled state.

Since

4.14

See also

localListPreference

Definition at line 363 of file collection.cpp.

fromUrl()

Collection Collection::fromUrl ( const QUrl & url )

static

Creates a collection from the given url.

Definition at line 267 of file collection.cpp.

hasAttribute() [1/2]

template<typename T >

bool Akonadi::Collection::hasAttribute ( ) const

inline

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

Definition at line 593 of file collection.h.

hasAttribute() [2/2]

bool Collection::hasAttribute

(

const QByteArray &

name

)

const

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

Definition at line 161 of file collection.cpp.

id()

Collection::Id Collection::id ( ) const

nodiscard

Returns the unique identifier of the collection.

Definition at line 96 of file collection.cpp.

isValid()

bool Collection::isValid ( ) const

nodiscard

Returns whether the collection is valid.

Definition at line 121 of file collection.cpp.

isVirtual()

bool Collection::isVirtual ( ) const

nodiscard

Returns whether the collection is virtual, for example a search collection.

Since

4.6

Definition at line 347 of file collection.cpp.

keepLocalChanges()

QSet< QByteArray > Collection::keepLocalChanges

(

)

const

Returns what parts are only default values.

Definition at line 419 of file collection.cpp.

localListPreference()

Collection::ListPreference Collection::localListPreference ( Collection::ListPurpose purpose ) const

nodiscard

Returns the local list preference for the specified purpose.

Since

4.14

See also

setLocalListPreference

Definition at line 384 of file collection.cpp.

mimeType()

QString Collection::mimeType ( )

staticnodiscard

Returns the mimetype used for collections.

Definition at line 292 of file collection.cpp.

name()

QString Collection::name ( ) const

nodiscard

Returns the i18n'ed name of the collection.

Definition at line 209 of file collection.cpp.

operator!=()

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

nodiscard

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

Definition at line 132 of file collection.cpp.

operator<()

bool Akonadi::Collection::operator< ( const Collection & other ) const

nodiscard

For use with containers only.

Since

4.8

Definition at line 146 of file collection.cpp.

operator=()

Collection & Collection::operator=

(

const Collection &

other

)

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

Parameters

other

the collection to assign

Definition at line 137 of file collection.cpp.

operator==()

bool Collection::operator== ( const Collection & other ) const

nodiscard

Returns whether this collections's id equals the id of the other collection.

Definition at line 126 of file collection.cpp.

parentCollection() [1/2]

Collection & Collection::parentCollection ( )

nodiscard

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.

Since

4.4

Definition at line 187 of file collection.cpp.

parentCollection() [2/2]

Collection Collection::parentCollection ( ) const

nodiscard

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.

Since

4.4

Definition at line 195 of file collection.cpp.

remoteId()

QString Collection::remoteId ( ) const

nodiscard

Returns the remote id of the collection.

Definition at line 106 of file collection.cpp.

remoteRevision()

QString Collection::remoteRevision ( ) const

nodiscard

Returns the remote revision of the collection.

Note

This method is supposed to be used by resources only.

Since

4.5

Definition at line 116 of file collection.cpp.

removeAttribute() [1/2]

template<typename T >

void Akonadi::Collection::removeAttribute ( )

inline

Removes and deletes the attribute of the requested type.

Definition at line 587 of file collection.h.

removeAttribute() [2/2]

void Collection::removeAttribute

(

const QByteArray &

name

)

Removes and deletes the attribute of the given type name.

Definition at line 156 of file collection.cpp.

resource()

QString Collection::resource ( ) const

nodiscard

Returns the identifier of the resource owning the collection.

Definition at line 302 of file collection.cpp.

rights()

Collection::Rights Collection::rights ( ) const

nodiscard

Returns the rights the user has on the collection.

Definition at line 226 of file collection.cpp.

root()

Collection Collection::root ( )

staticnodiscard

Returns the root collection.

Definition at line 287 of file collection.cpp.

setCachePolicy()

void Collection::setCachePolicy

(

const CachePolicy &

policy

)

Sets the cache policy of the collection.

Definition at line 341 of file collection.cpp.

setContentMimeTypes()

void Collection::setContentMimeTypes

(

const QStringList &

types

)

Sets the list of possible content mime types.

Definition at line 245 of file collection.cpp.

setEnabled()

void Collection::setEnabled

(

bool

enabled

)

Sets the collection's enabled state.

Use this mechanism to set if a collection should be available to the user or not.

This can be used in conjunction with the local list preference for finer grained control to define if a collection should be included depending on the purpose.

For example: A collection is by default enabled, meaning it is displayed to the user, synchronized by the resource, and indexed by the indexer. A disabled collection on the other hand is not displayed, synchronized or indexed. The local list preference allows to locally override that default value for each purpose individually.

The enabled state can be synchronized by backends. E.g. an imap resource may synchronize this with the subscription state.

Since

4.14

See also

setLocalListPreference, setShouldList

Definition at line 357 of file collection.cpp.

setId()

void Collection::setId

(

Collection::Id

identifier

)

Sets the unique identifier of the collection.

Definition at line 91 of file collection.cpp.

setKeepLocalChanges()

void Collection::setKeepLocalChanges

(

const QSet< QByteArray > &

parts

)

Set during sync to indicate that the provided parts are only default values;.

Since

4.15

Definition at line 414 of file collection.cpp.

setLocalListPreference()

void Collection::setLocalListPreference	(	Collection::ListPurpose	purpose,
		Collection::ListPreference	preference )

Sets the local list preference for the specified purpose.

The local list preference overrides the enabled state unless set to ListDefault. In case of ListDefault the enabled state should be taken as fallback (shouldList() implements this logic).

The default value is ListDefault.

Since

4.14

See also

shouldList, setEnabled

Definition at line 368 of file collection.cpp.

setName()

void Collection::setName

(

const QString &

name

)

Sets the i18n'ed name of the collection.

Parameters

name	The new collection name.

Definition at line 221 of file collection.cpp.

setParentCollection()

void Collection::setParentCollection

(

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

Parameters

parent

The parent collection.

Since

4.4

Definition at line 204 of file collection.cpp.

setRemoteId()

void Collection::setRemoteId

(

const QString &

id

)

Sets the remote id of the collection.

Definition at line 101 of file collection.cpp.

setRemoteRevision()

void Collection::setRemoteRevision

(

const QString &

revision

)

Sets the remote revision of the collection.

Parameters

revision

the collections'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.

Since

4.5

Definition at line 111 of file collection.cpp.

setResource()

void Collection::setResource

(

const QString &

identifier

)

Sets the identifier of the resource owning the collection.

Definition at line 307 of file collection.cpp.

setRights()

void Collection::setRights

(

Rights

rights

)

Sets the rights the user has on the collection.

Definition at line 235 of file collection.cpp.

setShouldList()

void Collection::setShouldList	(	ListPurpose	purpose,
		bool	shouldList )

Sets whether the collection should be listed or not for the specified purpose.

Takes enabled state and local preference into account.

Use this instead of sestEnabled and setLocalListPreference to automatically set the right setting.

Since

4.14

See also

setLocalListPreference, setEnabled

Definition at line 405 of file collection.cpp.

setStatistics()

void Collection::setStatistics

(

const CollectionStatistics &

statistics

)

Sets the collection statistics for the collection.

Definition at line 331 of file collection.cpp.

setVirtual()

void Akonadi::Collection::setVirtual

(

bool

isVirtual

)

Sets whether the collection is virtual or not.

Virtual collections can't be converted to non-virtual and vice versa.

Parameters

isVirtual

virtual collection if true, otherwise a normal collection

Since

4.10

Definition at line 352 of file collection.cpp.

shouldList()

bool Collection::shouldList ( Collection::ListPurpose purpose ) const

nodiscard

Returns whether the collection should be listed or not for the specified purpose Takes enabled state and local preference into account.

Since

4.14

See also

setLocalListPreference, setEnabled

Definition at line 397 of file collection.cpp.

statistics()

CollectionStatistics Collection::statistics ( ) const

nodiscard

Returns the collection statistics of the collection.

Definition at line 326 of file collection.cpp.

url()

QUrl Collection::url ( UrlType type = UrlShort ) const

nodiscard

Returns the url of the collection.

Parameters

type	the type of url

Since

4.7

Definition at line 253 of file collection.cpp.

virtualMimeType()

QString Akonadi::Collection::virtualMimeType ( )

staticnodiscard

Returns the mimetype used for virtual collections.

Since

4.11

Definition at line 297 of file collection.cpp.

---

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

• collection.h
• collection.cpp