KIdentityManagement

identitymanager.h
1/*
2 SPDX-FileCopyrightText: 2002 Marc Mutz <mutz@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#pragma once
8
9#include "kidentitymanagementcore_export.h"
10
11#include <QList>
12#include <QObject>
13#include <QStringList>
14
15#include <memory>
16
17namespace KIdentityManagementCore
18{
19class IdentityManagerPrivate;
20class Identity;
21/**
22 * @short Manages the list of identities.
23 * @author Marc Mutz <mutz@kde.org>
24 **/
25class KIDENTITYMANAGEMENTCORE_EXPORT IdentityManager : public QObject
26{
27 Q_OBJECT
28public:
29 /**
30 * Create an identity manager, which loads the emailidentities file
31 * to create identities.
32 * @param readonly if true, no changes can be made to the identity manager
33 * This means in particular that if there is no identity configured,
34 * the default identity created here will not be saved.
35 * It is assumed that a minimum of one identity is always present.
36 */
37 explicit IdentityManager(bool readonly = false, QObject *parent = nullptr, const char *name = nullptr);
38 ~IdentityManager() override;
39
40 /**
41 * Creates or reuses the identity manager instance for this process.
42 * It loads the emailidentities file to create identities.
43 * This sets readonly to false, so you should create a separate instance
44 * if you need it to be readonly.
45 * @since 5.2.91
46 */
48
49public:
50 using Iterator = QList<Identity>::Iterator;
51 using ConstIterator = QList<Identity>::ConstIterator;
52
53 /**
54 * Typedef for STL style iterator
55 */
56 using iterator = Iterator;
57
58 /**
59 * Typedef for STL style iterator
60 */
61 using const_iterator = ConstIterator;
62
63 /** @return a unique name for a new identity based on @p name
64 * @param name the name of the base identity
65 */
66 [[nodiscard]] QString makeUnique(const QString &name) const;
67
68 /** @return whether the @p name is unique
69 * @param name the name to be examined
70 */
71 [[nodiscard]] bool isUnique(const QString &name) const;
72
73 /** Commit changes to disk and emit changed() if necessary. */
74 void commit();
75
76 /** Re-read the config from disk and forget changes. */
77 void rollback();
78
79 /** Store a new identity or modify an existing identity based on an
80 * independent identity object
81 * @param ident the identity to be saved
82 */
83 void saveIdentity(const Identity &ident);
84
85 /** Check whether there are any unsaved changes. */
86 [[nodiscard]] bool hasPendingChanges() const;
87
88 /** @return the list of identities */
89 [[nodiscard]] QStringList identities() const;
90
91 /** Convenience method.
92
93 @return the list of (shadow) identities, ie. the ones currently
94 under configuration.
95 */
96 [[nodiscard]] 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 [[nodiscard]] 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 method.
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 **/
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 **/
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 [[nodiscard]] 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 [[nodiscard]] 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, const QString &name = QString());
184
185 /** Returns the list of all email addresses (only name@host) from all
186 identities */
187 [[nodiscard]] QStringList allEmails() const;
188
189Q_SIGNALS:
190 /** Emitted whenever a commit changes any configure option */
191 void changed();
192 void identitiesWereChanged();
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. */
202 void identityChanged(const KIdentityManagementCore::Identity &ident);
203 /** Emitted on @ref commit() for each deleted identity. At the time
204 this signal is emitted, the identity does still exist and can be
205 retrieved by @ref identityForUoid() if needed */
206 void deleted(uint uoid);
207 /** Emitted on @ref commit() for each new identity */
209
210 void needToReloadIdentitySettings();
211
212 void identitiesChanged(const QString &id);
213
214protected:
215 /**
216 * This is called when no identity has been defined, so we need to
217 * create a default one. The parameters are filled with some default
218 * values from KUser, but reimplementations of this method can give
219 * them another value.
220 */
221 virtual void createDefaultIdentity(QString & /*fullName*/, QString & /*emailAddress*/);
222
223protected Q_SLOTS:
224 void slotRollback();
225
226private:
227 //@cond PRIVATE
228 friend class IdentityManagerPrivate;
229 std::unique_ptr<IdentityManagerPrivate> const d;
230 //@endcond
231 Q_PRIVATE_SLOT(d, void slotIdentitiesChanged(const QString &id))
232};
233} // namespace
Manages the list of identities.
bool removeIdentityForced(const QString &identityName)
Removes the identity with name identityName Will return false if the identity is not found,...
QStringList allEmails() const
Returns the list of all email addresses (only name@host) from all identities.
void rollback()
Re-read the config from disk and forget changes.
virtual void createDefaultIdentity(QString &, QString &)
This is called when no identity has been defined, so we need to create a default one.
static IdentityManager * self()
Creates or reuses the identity manager instance for this process.
void changed(const KIdentityManagementCore::Identity &ident)
Emitted whenever the identity ident changed.
QStringList shadowIdentities() const
Convenience method.
const Identity & identityForUoid(uint uoid) const
Identity & modifyIdentityForName(const QString &identityName)
Identity & modifyIdentityForUoid(uint uoid)
Iterator modifyBegin()
Iterator used by the configuration dialog, which works on a separate list of identities,...
void changed(uint uoid)
Emitted whenever the identity with Unique Object Identifier (UOID) uoid changed.
void commit()
Commit changes to disk and emit changed() if necessary.
const Identity & defaultIdentity() const
bool hasPendingChanges() const
Check whether there are any unsaved changes.
void saveIdentity(const Identity &ident)
Store a new identity or modify an existing identity based on an independent identity object.
bool removeIdentity(const QString &identityName)
Removes the identity with name identityName Will return false if the identity is not found,...
void added(const KIdentityManagementCore::Identity &ident)
Emitted on commit() for each new identity.
void sort()
Sort the identities by name (the default is always first).
const Identity & identityForUoidOrDefault(uint uoid) const
Convenience method.
void deleted(uint uoid)
Emitted on commit() for each deleted identity.
QString makeUnique(const QString &name) const
bool setAsDefault(uint uoid)
Sets the identity with Unique Object Identifier (UOID) uoid to be new the default identity.
IdentityManager(bool readonly=false, QObject *parent=nullptr, const char *name=nullptr)
Create an identity manager, which loads the emailidentities file to create identities.
void changed()
Emitted whenever a commit changes any configure option.
const Identity & identityForAddress(const QString &addresses) const
bool thatIsMe(const QString &addressList) const
bool isUnique(const QString &name) const
User identity information.
Definition identity.h:74
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:11:25 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.