KIdentityManagement

identitymanager.h
1 /*
2  SPDX-FileCopyrightText: 2002 Marc Mutz <[email protected]>
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 
17 namespace KIdentityManagementCore
18 {
19 class IdentityManagerPrivate;
20 class Identity;
21 /**
22  * @short Manages the list of identities.
23  * @author Marc Mutz <[email protected]>
24  **/
25 class KIDENTITYMANAGEMENTCORE_EXPORT IdentityManager : public QObject
26 {
27  Q_OBJECT
28 public:
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  */
47  static IdentityManager *self();
48 
49 public:
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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT bool hasPendingChanges() const;
87 
88  /** @return the list of identities */
89  Q_REQUIRED_RESULT QStringList identities() const;
90 
91  /** Convenience method.
92 
93  @return the list of (shadow) identities, ie. the ones currently
94  under configuration.
95  */
96  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  **/
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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT QStringList allEmails() const;
188 
189 Q_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. */
201  void changed(const KIdentityManagementCore::Identity &ident);
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 */
208  void added(const KIdentityManagementCore::Identity &ident);
209 
210  void needToReloadIdentitySettings();
211 
212  void identitiesChanged(const QString &id);
213 
214 protected:
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 
223 protected Q_SLOTS:
224  void slotRollback();
225 
226 private:
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.
User identity information.
Definition: identity.h:71
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Sep 21 2023 03:48:43 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.