1 | /* |
2 | Copyright (c) 2002 Marc Mutz <mutz@kde.org> |
3 | |
4 | This library is free software; you can redistribute it and/or modify it |
5 | under the terms of the GNU Library General Public License as published by |
6 | the Free Software Foundation; either version 2 of the License, or (at your |
7 | option) any later version. |
8 | |
9 | This library is distributed in the hope that it will be useful, but WITHOUT |
10 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
11 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public |
12 | License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to the |
16 | Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA |
17 | 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef KPIMIDENTITIES_IDENTITYMANAGER_H |
21 | #define KPIMIDENTITIES_IDENTITYMANAGER_H |
22 | |
23 | #include <kpimidentities/kpimidentities_export.h> |
24 | #include <kconfiggroup.h> |
25 | #include <QtCore/QObject> |
26 | |
27 | class KConfigBase; |
28 | class KConfig; |
29 | class QStringList; |
30 | |
31 | namespace KPIMIdentities |
32 | { |
33 | |
34 | class Identity; |
35 | /** |
36 | * @short Manages the list of identities. |
37 | * @author Marc Mutz <mutz@kde.org> |
38 | **/ |
39 | class KPIMIDENTITIES_EXPORT IdentityManager : public QObject |
40 | { |
41 | Q_OBJECT |
42 | public: |
43 | /** |
44 | * Create an identity manager, which loads the emailidentities file |
45 | * to create identities. |
46 | * @param readonly if true, no changes can be made to the identity manager |
47 | * This means in particular that if there is no identity configured, |
48 | * the default identity created here will not be saved. |
49 | * It is assumed that a minimum of one identity is always present. |
50 | */ |
51 | explicit IdentityManager( bool readonly = false, QObject *parent=0, |
52 | const char *name=0 ); |
53 | virtual ~IdentityManager(); |
54 | |
55 | public: |
56 | typedef QList<Identity>::Iterator Iterator; |
57 | typedef QList<Identity>::ConstIterator ConstIterator; |
58 | |
59 | /** |
60 | * Typedef for STL style iterator |
61 | */ |
62 | typedef Iterator iterator; |
63 | |
64 | /** |
65 | * Typedef for STL style iterator |
66 | */ |
67 | typedef ConstIterator const_iterator; |
68 | |
69 | /** @return a unique name for a new identity based on @p name |
70 | * @param name the name of the base identity |
71 | */ |
72 | QString makeUnique( const QString &name ) const; |
73 | |
74 | /** @return whether the @p name is unique |
75 | * @param name the name to be examined |
76 | */ |
77 | bool isUnique( const QString &name ) const; |
78 | |
79 | /** Commit changes to disk and emit changed() if necessary. */ |
80 | void commit(); |
81 | |
82 | /** Re-read the config from disk and forget changes. */ |
83 | void rollback(); |
84 | |
85 | /** Check whether there are any unsaved changes. */ |
86 | bool hasPendingChanges() const; |
87 | |
88 | /** @return the list of identities */ |
89 | QStringList identities() const; |
90 | |
91 | /** Convenience method. |
92 | |
93 | @return the list of (shadow) identities, ie. the ones currently |
94 | under configuration. |
95 | */ |
96 | QStringList shadowIdentities() const; |
97 | |
98 | /** Sort the identities by name (the default is always first). This |
99 | operates on the @em shadow list, so you need to @ref commit for |
100 | the changes to take effect. |
101 | **/ |
102 | void sort(); |
103 | |
104 | /** @return an identity whose address matches any in @p addresses |
105 | or @ref Identity::null if no such identity exists. |
106 | @param addresses the string of addresses to scan for matches |
107 | **/ |
108 | const Identity &identityForAddress( const QString &addresses ) const; |
109 | |
110 | /** @return true if @p addressList contains any of our addresses, |
111 | false otherwise. |
112 | @param addressList the addressList to examine |
113 | @see #identityForAddress |
114 | **/ |
115 | bool thatIsMe( const QString &addressList ) const; |
116 | |
117 | /** @return the identity with Unique Object Identifier (UOID) @p |
118 | uoid or @ref Identity::null if not found. |
119 | @param uoid the Unique Object Identifier to find identity with |
120 | **/ |
121 | const Identity &identityForUoid( uint uoid ) const; |
122 | |
123 | /** Convenience menthod. |
124 | |
125 | @return the identity with Unique Object Identifier (UOID) @p |
126 | uoid or the default identity if not found. |
127 | @param uoid the Unique Object Identifier to find identity with |
128 | **/ |
129 | const Identity &identityForUoidOrDefault( uint uoid ) const; |
130 | |
131 | /** @return the default identity */ |
132 | const Identity &defaultIdentity() const; |
133 | |
134 | /** Sets the identity with Unique Object Identifier (UOID) @p uoid |
135 | to be new the default identity. As usual, use @ref commit to |
136 | make this permanent. |
137 | |
138 | @param uoid the default identity to set |
139 | @return false if an identity with UOID @p uoid was not found |
140 | **/ |
141 | bool setAsDefault( uint uoid ); |
142 | |
143 | /** @return the identity named @p identityName. This method returns a |
144 | reference to the identity that can be modified. To let others |
145 | see this change, use @ref commit. |
146 | @param identityName the identity name to return modifiable reference |
147 | **/ |
148 | Identity &modifyIdentityForName( const QString &identityName ); |
149 | |
150 | /** @return the identity with Unique Object Identifier (UOID) @p uoid. |
151 | This method returns a reference to the identity that can |
152 | be modified. To let others see this change, use @ref commit. |
153 | **/ |
154 | Identity &modifyIdentityForUoid( uint uoid ); |
155 | |
156 | /** Removes the identity with name @p identityName |
157 | Will return false if the identity is not found, |
158 | or when one tries to remove the last identity. |
159 | @param identityName the identity to remove |
160 | **/ |
161 | bool removeIdentity( const QString &identityName ); |
162 | |
163 | /** |
164 | * Removes the identity with name @p identityName |
165 | * Will return @c false if the identity is not found, @c true otherwise. |
166 | * |
167 | * @note In opposite to removeIdentity, this method allows to remove the |
168 | * last remaining identity. |
169 | * |
170 | * @since 4.6 |
171 | */ |
172 | bool removeIdentityForced( const QString &identityName ); |
173 | |
174 | ConstIterator begin() const; |
175 | ConstIterator end() const; |
176 | /// Iterator used by the configuration dialog, which works on a separate list |
177 | /// of identities, for modification. Changes are made effective by commit(). |
178 | Iterator modifyBegin(); |
179 | Iterator modifyEnd(); |
180 | |
181 | Identity &newFromScratch( const QString &name ); |
182 | Identity &newFromControlCenter( const QString &name ); |
183 | Identity &newFromExisting( const Identity &other, |
184 | const QString &name=QString() ); |
185 | |
186 | /** Returns the list of all email addresses (only name@host) from all |
187 | identities */ |
188 | QStringList allEmails() const; |
189 | |
190 | Q_SIGNALS: |
191 | /** Emitted whenever a commit changes any configure option */ |
192 | void changed(); |
193 | /** Emitted whenever the identity with Unique Object Identifier |
194 | (UOID) @p uoid changed. Useful for more fine-grained change |
195 | notifications than what is possible with the standard @ref |
196 | changed() signal. */ |
197 | void changed( uint uoid ); |
198 | /** Emitted whenever the identity @p ident changed. Useful for more |
199 | fine-grained change notifications than what is possible with the |
200 | standard @ref changed() signal. */ |
201 | void changed( const KPIMIdentities::Identity &ident ); |
202 | /** Emitted on @ref commit() for each deleted identity. At the time |
203 | this signal is emitted, the identity does still exist and can be |
204 | retrieved by @ref identityForUoid() if needed */ |
205 | void deleted( uint uoid ); |
206 | /** Emitted on @ref commit() for each new identity */ |
207 | void added( const KPIMIdentities::Identity &ident ); |
208 | |
209 | protected: |
210 | /** |
211 | * This is called when no identity has been defined, so we need to |
212 | * create a default one. The parameters are filled with some default |
213 | * values from KUser, but reimplementations of this method can give |
214 | * them another value. |
215 | */ |
216 | virtual void createDefaultIdentity( QString&/*fullName*/, |
217 | QString&/*emailAddress*/ ) {} |
218 | |
219 | protected Q_SLOTS: |
220 | void slotRollback(); |
221 | |
222 | protected: |
223 | /** The list that will be seen by everyone */ |
224 | QList<Identity> mIdentities; |
225 | /** The list that will be seen by the config dialog */ |
226 | QList<Identity> mShadowIdentities; |
227 | |
228 | Q_SIGNALS: |
229 | void identitiesChanged( const QString &id ); |
230 | |
231 | private Q_SLOTS: |
232 | // Connected to the DBus signal |
233 | void slotIdentitiesChanged( const QString &id ); |
234 | |
235 | private: |
236 | void writeConfig() const; |
237 | void readConfig( KConfig *config ); |
238 | QStringList groupList( KConfig *config ) const; |
239 | void createDefaultIdentity(); |
240 | |
241 | // returns a new Unique Object Identifier |
242 | int newUoid(); |
243 | |
244 | private: |
245 | KConfig *mConfig; |
246 | bool mReadOnly; |
247 | }; |
248 | |
249 | } // namespace |
250 | |
251 | #endif // _KMAIL_IDENTITYMANAGER_H_ |
252 | |