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
27class KConfigBase;
28class KConfig;
29class QStringList;
30
31namespace KPIMIdentities
32{
33
34 class Identity;
35 /**
36 * @short Manages the list of identities.
37 * @author Marc Mutz <mutz@kde.org>
38 **/
39class 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