Akonadi::Collection

#include <collection.h>

Inherited by CollectionRoot.

Public Types

enum  CreateOption { AddIfMissing, DontCreate }
 
typedef qint64 Id
 
typedef QVector< CollectionList
 
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< RightRights
 
enum  UrlType { UrlShort = 0, UrlWithName = 1 }
 

Public Member Functions

 Collection ()
 
 Collection (Id id)
 
 Collection (const Collection &other)
 
 Collection (Collection &&other) noexcept
 
 ~Collection ()
 
void addAttribute (Attribute *attribute)
 
Attributeattribute (const QByteArray &name)
 
const Attributeattribute (const QByteArray &name) const
 
template<typename T >
T * attribute (CreateOption option=DontCreate)
 
template<typename T >
const T * attribute () const
 
Attribute::List attributes () const
 
CachePolicy cachePolicy () const
 
void clearAttributes ()
 
QStringList contentMimeTypes () const
 
QString displayName () const
 
bool enabled () const
 
bool hasAttribute (const QByteArray &name) const
 
template<typename T >
bool hasAttribute () const
 
Id id () const
 
bool isValid () const
 
bool isVirtual () const
 
QSet< QByteArraykeepLocalChanges () const
 
ListPreference localListPreference (ListPurpose purpose) const
 
QString name () const
 
bool operator!= (const Collection &other) const
 
bool operator< (const Collection &other) const
 
Collectionoperator= (const Collection &other)
 
bool operator== (const Collection &other) const
 
Collection parentCollection () const
 
CollectionparentCollection ()
 
QString remoteId () const
 
QString remoteRevision () const
 
void removeAttribute (const QByteArray &name)
 
template<typename T >
void removeAttribute ()
 
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
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[email protected][email protected][email protected]de.or[email protected]g

Definition at line 63 of file collection.h.

Member Typedef Documentation

typedef qint64 Akonadi::Collection::Id

Describes the unique id type.

Definition at line 69 of file collection.h.

Describes a list of collections.

Definition at line 74 of file collection.h.

Member Enumeration Documentation

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 269 of file collection.h.

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 457 of file collection.h.

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 468 of file collection.h.

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 79 of file collection.h.

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 397 of file collection.h.

Constructor & Destructor Documentation

Akonadi::Collection::Collection ( )

Creates an invalid collection.

Collection::Collection ( Id  id)
explicit

Create a new collection.

Parameters
idThe unique identifier of the collection.

Definition at line 80 of file collection.cpp.

Collection::~Collection ( )
default

Destroys the collection.

Collection::Collection ( const Collection other)

Creates a collection from an other collection.

Definition at line 85 of file collection.cpp.

Collection::Collection ( Collection &&  other)
defaultnoexcept

Move constructor.

Member Function Documentation

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
attributeThe new attribute.
Note
The collection takes the ownership of the attribute.

Definition at line 154 of file collection.cpp.

Attribute * Collection::attribute ( const QByteArray name)

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

Definition at line 179 of file collection.cpp.

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
optionThe create options.

Definition at line 543 of file collection.h.

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 563 of file collection.h.

Attribute::List Collection::attributes ( ) const

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 169 of file collection.cpp.

CachePolicy Collection::cachePolicy ( ) const

Returns the cache policy of the collection.

Definition at line 340 of file collection.cpp.

void Akonadi::Collection::clearAttributes ( )

Removes and deletes all attributes of the collection.

Definition at line 174 of file collection.cpp.

QStringList Collection::contentMimeTypes ( ) const

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 243 of file collection.cpp.

QString Collection::displayName ( ) const

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 217 of file collection.cpp.

bool Collection::enabled ( ) const

Returns the collection's enabled state.

Since
4.14
See also
localListPreference

Definition at line 367 of file collection.cpp.

Collection Collection::fromUrl ( const QUrl url)
static

Creates a collection from the given url.

Definition at line 270 of file collection.cpp.

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 164 of file collection.cpp.

template<typename T >
bool Akonadi::Collection::hasAttribute ( ) const
inline

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

Definition at line 584 of file collection.h.

Collection::Id Collection::id ( ) const

Returns the unique identifier of the collection.

Definition at line 99 of file collection.cpp.

bool Collection::isValid ( ) const

Returns whether the collection is valid.

Definition at line 124 of file collection.cpp.

bool Collection::isVirtual ( ) const

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

Since
4.6

Definition at line 351 of file collection.cpp.

QSet< QByteArray > Collection::keepLocalChanges ( ) const

Returns what parts are only default values.

Definition at line 423 of file collection.cpp.

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

Returns the local list preference for the specified purpose.

Since
4.14
See also
setLocalListPreference

Definition at line 388 of file collection.cpp.

QString Collection::mimeType ( )
static

Returns the mimetype used for collections.

Definition at line 295 of file collection.cpp.

QString Collection::name ( ) const

Returns the i18n'ed name of the collection.

Definition at line 212 of file collection.cpp.

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

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

Definition at line 135 of file collection.cpp.

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

For use with containers only.

Since
4.8

Definition at line 149 of file collection.cpp.

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

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

Parameters
otherthe collection to assign

Definition at line 140 of file collection.cpp.

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

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

Definition at line 129 of file collection.cpp.

Collection Collection::parentCollection ( ) const

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 198 of file collection.cpp.

Collection & Collection::parentCollection ( )

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 190 of file collection.cpp.

QString Collection::remoteId ( ) const

Returns the remote id of the collection.

Definition at line 109 of file collection.cpp.

QString Collection::remoteRevision ( ) const

Returns the remote revision of the collection.

Note
This method is supposed to be used by resources only.
Since
4.5

Definition at line 119 of file collection.cpp.

void Collection::removeAttribute ( const QByteArray name)

Removes and deletes the attribute of the given type name.

Definition at line 159 of file collection.cpp.

template<typename T >
void Akonadi::Collection::removeAttribute ( )
inline

Removes and deletes the attribute of the requested type.

Definition at line 578 of file collection.h.

QString Collection::resource ( ) const

Returns the identifier of the resource owning the collection.

Definition at line 305 of file collection.cpp.

Collection::Rights Collection::rights ( ) const

Returns the rights the user has on the collection.

Definition at line 229 of file collection.cpp.

Collection Collection::root ( )
static

Returns the root collection.

Definition at line 290 of file collection.cpp.

void Collection::setCachePolicy ( const CachePolicy policy)

Sets the cache policy of the collection.

Definition at line 345 of file collection.cpp.

void Collection::setContentMimeTypes ( const QStringList types)

Sets the list of possible content mime types.

Definition at line 248 of file collection.cpp.

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 361 of file collection.cpp.

void Collection::setId ( Collection::Id  identifier)

Sets the unique identifier of the collection.

Definition at line 94 of file collection.cpp.

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 418 of file collection.cpp.

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 372 of file collection.cpp.

void Collection::setName ( const QString name)

Sets the i18n'ed name of the collection.

Parameters
nameThe new collection name.

Definition at line 224 of file collection.cpp.

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
parentThe parent collection.
Since
4.4

Definition at line 207 of file collection.cpp.

void Collection::setRemoteId ( const QString id)

Sets the remote id of the collection.

Definition at line 104 of file collection.cpp.

void Collection::setRemoteRevision ( const QString revision)

Sets the remote revision of the collection.

Parameters
revisionthe 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 114 of file collection.cpp.

void Collection::setResource ( const QString identifier)

Sets the identifier of the resource owning the collection.

Definition at line 310 of file collection.cpp.

void Collection::setRights ( Rights  rights)

Sets the rights the user has on the collection.

Definition at line 238 of file collection.cpp.

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 409 of file collection.cpp.

void Collection::setStatistics ( const CollectionStatistics statistics)

Sets the collection statistics for the collection.

Definition at line 335 of file collection.cpp.

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
isVirtualvirtual collection if true, otherwise a normal collection
Since
4.10

Definition at line 356 of file collection.cpp.

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

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 401 of file collection.cpp.

CollectionStatistics Collection::statistics ( ) const

Returns the collection statistics of the collection.

Definition at line 330 of file collection.cpp.

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

Returns the url of the collection.

Parameters
typethe type of url
Since
4.7

Definition at line 256 of file collection.cpp.

QString Akonadi::Collection::virtualMimeType ( )
static

Returns the mimetype used for virtual collections.

Since
4.11

Definition at line 300 of file collection.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Fri Aug 7 2020 23:14:20 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.