File indexing completed on 2024-05-12 05:11:12
0001 /* 0002 SPDX-FileCopyrightText: 2009 Constantin Berzan <exit3219@gmail.com> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #pragma once 0008 0009 #include "akonadi-mime_export.h" 0010 0011 #include <Akonadi/SpecialCollections> 0012 0013 namespace Akonadi 0014 { 0015 class SpecialMailCollectionsPrivate; 0016 0017 /** 0018 @short Interface to special mail collections such as inbox, outbox etc. 0019 0020 This class is the central interface to the local mail folders. These folders 0021 can either be in the default resource (stored in ~/.local/share/local-mail) 0022 or in any number of custom resources. Special collections of the following types 0023 are supported: inbox, outbox, sent-mail, trash, drafts, templates and spam. 0024 0025 To check whether a special mail collection is available, simply use the hasCollection() and 0026 hasDefaultCollection() methods. Available special mail collections are accessible through 0027 the collection() and defaultCollection() methods. 0028 0029 To create a special mail collection, use a SpecialMailCollectionsRequestJob. 0030 This will create the special mail collections you request and automatically 0031 register them with SpecialMailCollections, so that it now knows they are available. 0032 0033 This class monitors all special mail collections known to it, and removes it 0034 from the known list if they are deleted. Note that this class does not 0035 automatically rebuild the collections that disappeared. 0036 0037 The defaultCollectionsChanged() and collectionsChanged() signals are emitted when 0038 the special mail collections for a resource change (i.e. some became available or some 0039 become unavailable). 0040 0041 @code 0042 if ( SpecialMailCollections::self()->hasDefaultCollection( SpecialMailCollections::Outbox ) ) { 0043 const Collection col = SpecialMailCollections::self()->defaultCollection( SpecialMailCollections::Outbox ); 0044 // ... 0045 } else { 0046 // ... use SpecialMailCollectionsRequestJob to request the collection... 0047 } 0048 @endcode 0049 0050 @author Constantin Berzan <exit3219@gmail.com> 0051 @since 4.4 0052 */ 0053 class AKONADI_MIME_EXPORT SpecialMailCollections : public SpecialCollections 0054 { 0055 Q_OBJECT 0056 0057 public: 0058 /** 0059 * Describes the possible types of special mail collections. 0060 * 0061 * Generally, there may not be two special mail collections of 0062 * the same type in the same resource. 0063 */ 0064 enum Type { 0065 Invalid = -1, ///< An invalid special collection. 0066 Root = 0, ///< The root collection containing the local folders. 0067 Inbox, ///< The inbox collection. 0068 Outbox, ///< The outbox collection. 0069 SentMail, ///< The sent-mail collection. 0070 Trash, ///< The trash collection. 0071 Drafts, ///< The drafts collection. 0072 Templates, ///< The templates collection. 0073 LastType ///< @internal marker 0074 }; 0075 0076 /** 0077 * Returns the global SpecialMailCollections instance. 0078 */ 0079 static SpecialMailCollections *self(); 0080 0081 /** 0082 * Returns whether the given agent @p instance has a special collection of 0083 * the given @p type. 0084 */ 0085 [[nodiscard]] bool hasCollection(Type type, const AgentInstance &instance) const; 0086 0087 /** 0088 * Returns the special mail collection of the given @p type in the given agent 0089 * @p instance, or an invalid collection if such a collection is unknown. 0090 */ 0091 [[nodiscard]] Akonadi::Collection collection(Type type, const AgentInstance &instance) const; 0092 0093 /** 0094 * Returns the special collection type for a given collection, or empty if the collection 0095 * doesn't have a special type. 0096 * @since 4.11 0097 */ 0098 [[nodiscard]] static Type specialCollectionType(const Akonadi::Collection &collection); 0099 0100 /** 0101 * Registers the given @p collection as a special mail collection 0102 * with the given @p type. 0103 * @param type the type of collection 0104 * @param collection the collection to register 0105 * The collection must be owned by a valid resource. 0106 * Registering a new collection of a previously registered type forgets the 0107 * old collection. 0108 */ 0109 bool registerCollection(Type type, const Akonadi::Collection &collection); 0110 0111 /** 0112 * Unregisters the given @p collection as a special mail collection 0113 * @param collection the collection to unregister 0114 * The collection must be owned by a valid resource. 0115 * @since 4.12 0116 */ 0117 bool unregisterCollection(const Collection &collection); 0118 0119 /** 0120 * Returns whether the default resource has a special mail collection of 0121 * the given @p type. 0122 */ 0123 [[nodiscard]] bool hasDefaultCollection(Type type) const; 0124 0125 /** 0126 * Returns the special mail collection of given @p type in the default 0127 * resource, or an invalid collection if such a collection is unknown. 0128 */ 0129 [[nodiscard]] Akonadi::Collection defaultCollection(Type type) const; 0130 0131 void verifyI18nDefaultCollection(Type type); 0132 private Q_SLOTS: 0133 void slotCollectionModified(KJob *job); 0134 0135 private: 0136 //@cond PRIVATE 0137 friend class SpecialMailCollectionsPrivate; 0138 0139 #if 1 // TODO do this only if building tests: 0140 friend class SpecialMailCollectionsTesting; 0141 friend class LocalFoldersTest; 0142 #endif 0143 0144 SpecialMailCollections(SpecialMailCollectionsPrivate *dd); 0145 0146 SpecialMailCollectionsPrivate *const d; 0147 //@endcond 0148 }; 0149 } // namespace Akonadi