Akonadi

specialcollections.h
1/*
2 SPDX-FileCopyrightText: 2009 Constantin Berzan <exit3219@gmail.com>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#pragma once
8
9#include "akonadicore_export.h"
10#include "collection.h"
11#include "item.h"
12
13#include <QObject>
14
15#include <memory>
16
18
19namespace Akonadi
20{
21class AgentInstance;
22class SpecialCollectionsPrivate;
23
24/**
25 @short An interface to special collections.
26
27 This class is the central interface to special collections like inbox or
28 outbox in a mail resource or recent contacts in a contacts resource.
29 The class is not meant to be used directly, but to inherit the a type
30 specific special collections class from it (e.g. SpecialMailCollections).
31
32 To check whether a special collection is available, simply use the hasCollection() and
33 hasDefaultCollection() methods. Available special collections are accessible through
34 the collection() and defaultCollection() methods.
35
36 To create a special collection, use a SpecialCollectionsRequestJob.
37 This will create the special collections you request and automatically
38 register them with SpecialCollections, so that it now knows they are available.
39
40 This class monitors all special collections known to it, and removes it
41 from the known list if they are deleted. Note that this class does not
42 automatically rebuild the collections that disappeared.
43
44 The defaultCollectionsChanged() and collectionsChanged() signals are emitted when
45 the special collections for a resource change (i.e. some became available or some
46 become unavailable).
47
48 @author Constantin Berzan <exit3219@gmail.com>
49 @since 4.4
50*/
51class AKONADICORE_EXPORT SpecialCollections : public QObject
52{
53 Q_OBJECT
54
55public:
56 /**
57 * Destroys the special collections object.
58 */
60
61 /**
62 * Returns whether the given agent @p instance has a special collection of
63 * the given @p type.
64 */
65 [[nodiscard]] bool hasCollection(const QByteArray &type, const AgentInstance &instance) const;
66
67 /**
68 * Returns the special collection of the given @p type in the given agent
69 * @p instance, or an invalid collection if such a collection is unknown.
70 */
71 [[nodiscard]] Akonadi::Collection collection(const QByteArray &type, const AgentInstance &instance) const;
72
73 /**
74 * Registers the given @p collection as a special collection
75 * with the given @p type.
76 * @param type the special type of @c collection
77 * @param collection the given collection to register
78 * The collection must be owned by a valid resource.
79 * Registering a new collection of a previously registered type forgets the
80 * old collection.
81 */
82 bool registerCollection(const QByteArray &type, const Akonadi::Collection &collection);
83
84 /**
85 * Unregisters the given @p collection as a special collection.
86 * @param type the special type of @c collection
87 * @since 4.12
88 */
89 bool unregisterCollection(const Collection &collection);
90
91 /**
92 * unsets the special collection attribute which marks @p collection as being a special
93 * collection.
94 * @since 4.12
95 */
96 static void unsetSpecialCollection(const Akonadi::Collection &collection);
97
98 /**
99 * Sets the special collection attribute which marks @p collection as being a special
100 * collection of type @p type.
101 * This is typically used by configuration dialog for resources, when the user can choose
102 * a specific special collection (ex: IMAP trash).
103 *
104 * @since 4.11
105 */
106 static void setSpecialCollectionType(const QByteArray &type, const Akonadi::Collection &collection);
107
108 /**
109 * Returns whether the default resource has a special collection of
110 * the given @p type.
111 */
112 [[nodiscard]] bool hasDefaultCollection(const QByteArray &type) const;
113
114 /**
115 * Returns the special collection of given @p type in the default
116 * resource, or an invalid collection if such a collection is unknown.
117 */
118 [[nodiscard]] Akonadi::Collection defaultCollection(const QByteArray &type) const;
119
120Q_SIGNALS:
121 /**
122 * Emitted when the special collections for a resource have been changed
123 * (for example, some become available, or some become unavailable).
124 *
125 * @param instance The instance of the resource the collection belongs to.
126 */
128
129 /**
130 * Emitted when the special collections for the default resource have
131 * been changed (for example, some become available, or some become unavailable).
132 */
134
135protected:
136 /**
137 * Creates a new special collections object.
138 *
139 * @param config The configuration skeleton that provides the default resource id.
140 * @param parent The parent object.
141 */
142 explicit SpecialCollections(KCoreConfigSkeleton *config, QObject *parent = nullptr);
143
144private:
145 /// @cond PRIVATE
146 friend class SpecialCollectionsRequestJob;
147 friend class SpecialCollectionsRequestJobPrivate;
148 friend class SpecialCollectionsPrivate;
149#ifdef BUILD_TESTING
150 friend class SpecialMailCollectionsTesting;
151 friend class LocalFoldersTest;
152#endif
153
154 std::unique_ptr<SpecialCollectionsPrivate> const d;
155 /// @endcond
156};
157
158} // namespace Akonadi
Represents one agent instance and takes care of communication with it.
A representation of an agent instance.
Represents a collection of PIM items.
Definition collection.h:62
A job to request SpecialCollections.
An interface to special collections.
~SpecialCollections() override
Destroys the special collections object.
void defaultCollectionsChanged()
Emitted when the special collections for the default resource have been changed (for example,...
void collectionsChanged(const Akonadi::AgentInstance &instance)
Emitted when the special collections for a resource have been changed (for example,...
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:01:42 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.