Akonadi Mime

specialmailcollections.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 "akonadi-mime_export.h"
10
11#include <Akonadi/SpecialCollections>
12
13namespace Akonadi
14{
15class SpecialMailCollectionsPrivate;
16
17/**
18 @short Interface to special mail collections such as inbox, outbox etc.
19
20 This class is the central interface to the local mail folders. These folders
21 can either be in the default resource (stored in ~/.local/share/local-mail)
22 or in any number of custom resources. Special collections of the following types
23 are supported: inbox, outbox, sent-mail, trash, drafts, templates and spam.
24
25 To check whether a special mail collection is available, simply use the hasCollection() and
26 hasDefaultCollection() methods. Available special mail collections are accessible through
27 the collection() and defaultCollection() methods.
28
29 To create a special mail collection, use a SpecialMailCollectionsRequestJob.
30 This will create the special mail collections you request and automatically
31 register them with SpecialMailCollections, so that it now knows they are available.
32
33 This class monitors all special mail collections known to it, and removes it
34 from the known list if they are deleted. Note that this class does not
35 automatically rebuild the collections that disappeared.
36
37 The defaultCollectionsChanged() and collectionsChanged() signals are emitted when
38 the special mail collections for a resource change (i.e. some became available or some
39 become unavailable).
40
41 @code
42 if ( SpecialMailCollections::self()->hasDefaultCollection( SpecialMailCollections::Outbox ) ) {
43 const Collection col = SpecialMailCollections::self()->defaultCollection( SpecialMailCollections::Outbox );
44 // ...
45 } else {
46 // ... use SpecialMailCollectionsRequestJob to request the collection...
47 }
48 @endcode
49
50 @author Constantin Berzan <exit3219@gmail.com>
51 @since 4.4
52*/
53class AKONADI_MIME_EXPORT SpecialMailCollections : public SpecialCollections
54{
55 Q_OBJECT
56
57public:
58 /**
59 * Describes the possible types of special mail collections.
60 *
61 * Generally, there may not be two special mail collections of
62 * the same type in the same resource.
63 */
64 enum Type {
65 Invalid = -1, ///< An invalid special collection.
66 Root = 0, ///< The root collection containing the local folders.
67 Inbox, ///< The inbox collection.
68 Outbox, ///< The outbox collection.
69 SentMail, ///< The sent-mail collection.
70 Trash, ///< The trash collection.
71 Drafts, ///< The drafts collection.
72 Templates, ///< The templates collection.
73 LastType ///< @internal marker
74 };
75
76 /**
77 * Returns the global SpecialMailCollections instance.
78 */
79 static SpecialMailCollections *self();
80
81 /**
82 * Returns whether the given agent @p instance has a special collection of
83 * the given @p type.
84 */
85 [[nodiscard]] bool hasCollection(Type type, const AgentInstance &instance) const;
86
87 /**
88 * Returns the special mail collection of the given @p type in the given agent
89 * @p instance, or an invalid collection if such a collection is unknown.
90 */
91 [[nodiscard]] Akonadi::Collection collection(Type type, const AgentInstance &instance) const;
92
93 /**
94 * Returns the special collection type for a given collection, or empty if the collection
95 * doesn't have a special type.
96 * @since 4.11
97 */
98 [[nodiscard]] static Type specialCollectionType(const Akonadi::Collection &collection);
99
100 /**
101 * Registers the given @p collection as a special mail collection
102 * with the given @p type.
103 * @param type the type of collection
104 * @param collection the collection to register
105 * The collection must be owned by a valid resource.
106 * Registering a new collection of a previously registered type forgets the
107 * old collection.
108 */
109 [[nodiscard]] bool registerCollection(Type type, const Akonadi::Collection &collection);
110
111 /**
112 * Unregisters the given @p collection as a special mail collection
113 * @param collection the collection to unregister
114 * The collection must be owned by a valid resource.
115 * @since 4.12
116 */
117 [[nodiscard]] bool unregisterCollection(const Collection &collection);
118
119 /**
120 * Returns whether the default resource has a special mail collection of
121 * the given @p type.
122 */
123 [[nodiscard]] bool hasDefaultCollection(Type type) const;
124
125 /**
126 * Returns the special mail collection of given @p type in the default
127 * resource, or an invalid collection if such a collection is unknown.
128 */
129 [[nodiscard]] Akonadi::Collection defaultCollection(Type type) const;
130
131 void verifyI18nDefaultCollection(Type type);
132private Q_SLOTS:
133 void slotCollectionModified(KJob *job);
134
135private:
136 //@cond PRIVATE
137 friend class SpecialMailCollectionsPrivate;
138
139#if 1 // TODO do this only if building tests:
140 friend class SpecialMailCollectionsTesting;
141 friend class LocalFoldersTest;
142#endif
143
144 SpecialMailCollections(SpecialMailCollectionsPrivate *dd);
145
146 SpecialMailCollectionsPrivate *const d;
147 //@endcond
148};
149} // namespace Akonadi
Interface to special mail collections such as inbox, outbox etc.
Type
Describes the possible types of special mail collections.
@ SentMail
The sent-mail collection.
@ Templates
The templates collection.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Mon Nov 4 2024 16:32:40 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.