Improve the credentialsId() method
[accounts-sso:accounts-qt.git] / Accounts / account.h
1 /* vi: set et sw=4 ts=4 cino=t0,(0: */
2 /*
3  * This file is part of libaccounts-qt
4  *
5  * Copyright (C) 2009-2010 Nokia Corporation.
6  *
7  * Contact: Alberto Mardegan <alberto.mardegan@nokia.com>
8  *
9  * This library is free software; you can redistribute it and/or
10  * modify it under the terms of the GNU Lesser General Public License
11  * version 2.1 as published by the Free Software Foundation.
12  *
13  * This library is distributed in the hope that it will be useful, but
14  * WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16  * Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public
19  * License along with this library; if not, write to the Free Software
20  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
21  * 02110-1301 USA
22  */
23
24 #ifndef ACCOUNT_H
25 #define ACCOUNT_H
26
27
28 #include <QObject>
29 #include <QSettings>
30 #include <QStringList>
31
32 #include "Accounts/accountscommon.h"
33 #include "Accounts/service.h"
34
35 #define ACCOUNTS_KEY_CREDENTIALS_ID QLatin1String("CredentialsId")
36
37 extern "C"
38 {
39     typedef struct _AgAccount AgAccount;
40     typedef struct _AgAccountWatch *AgAccountWatch;
41 }
42
43 /*! @namespace Accounts
44  *
45  */
46
47 #define ACCOUNTS_EXPORT
48
49 namespace Accounts
50 {
51 typedef quint32 AccountId;
52 typedef QList<AccountId> AccountIdList;
53 class Manager;
54
55 /*!
56  * Tells the origin of an account setting: whether it was set on the account,
57  * or it's a default value in the service template, or whether it's unset.
58  */
59 enum SettingSource
60 {
61     NONE,
62     ACCOUNT,
63     TEMPLATE
64 };
65
66 enum ErrorCode
67 {
68     /* The value of this enum must be the same as AgError */
69     Database = 0,
70     Disposed,
71     Deleted,
72 };
73
74 /*!
75  * @class Watch
76  *
77  * @brief Monitors an account key or group of keys.
78  *
79  * @details A watch is created via the Account::watch method and is a simple
80  * object which will emit the notify() signal when the value of the key (or
81  * group) that it's monitoring is changed.
82  */
83 class ACCOUNTS_EXPORT Watch : public QObject
84 {
85     Q_OBJECT
86
87 public:
88     /* We don't want to document these.
89      * \cond
90      */
91     Watch(QObject *parent = 0);
92     ~Watch();
93
94     void setWatch(AgAccountWatch w) { watch = w; };
95     class Private;
96     // \endcond
97
98 signals:
99     /*!
100      * Emitted when the value of the keys monitored by this watch change.
101      * @param key The string that was used to create this watch. Note that if
102      * this watch is monitor multiple keys this param only identifies their
103      * common prefix, and not the actual key being changed.
104      */
105     void notify(const char *key);
106
107     // \cond
108 private:
109     AgAccountWatch watch;
110     friend class Private;
111     // \endcond
112 };
113
114 /*! @class Account
115  *
116  * @brief The Account class provides an interface to account settings.
117  *
118  * @details The Account class is used to access account and service settings.
119  * This class has no constructor, therefore to instantiate one Account object
120  * one has to either use the Manager::createAccount method (to create a new
121  * empty account) or Manager::account (to load an existing account).
122  *
123  * Most of the methods in the Account class act on the selected service: for
124  * example, calling setEnabled(false) on the NULL service (this is the service
125  * to be used for changing settings globally on the account) will disable the
126  * account, while the code
127  * \code
128  * account->selectService(myService);
129  * account->setEnabled(false);
130  * \endcode
131  * will disable the "myService" service.
132  *
133  * All changes made on an account (including deletion) are not stored until
134  * sync() is called.
135  */
136 class ACCOUNTS_EXPORT Account : public QObject
137 {
138     Q_OBJECT
139
140 public:
141
142     /*!
143      * Destroy current account object and free all resources
144      */
145     virtual ~Account();
146
147     /*!
148      * Returns the AccountId of this account (0 if the account has not yet been
149      * stored into the database).
150      */
151     AccountId id() const;
152
153     /*!
154      * Returns the Manager.
155      */
156     Manager *manager() const;
157
158     /*!
159      * Checks whether the account supports the given service
160      */
161     bool supportsService(const QString &serviceType) const;
162
163     /*!
164      * Return a list of services supported by this account.
165      *
166      * This is currently computed by returning all services having the same
167      * provider as the account.
168      */
169     ServiceList services(const QString &serviceType = NULL) const;
170
171     /*!
172      * Checks whether the account is enabled.
173      */
174     bool enabled() const;
175
176     /*!
177      * Enables/disables the account.
178      * The change will be written only when sync() is called.
179      *
180      * This method operates on the currently selected service.
181      */
182     void setEnabled(bool);
183
184     /*!
185      * Get the account's credentials id in signon DB.
186      *
187      * The credentials ID is first read from the currently selected service;
188      * if it's not found, then it is ready from the global account settings.
189      * In any case, the currently selected service is not altered.
190      */
191     qint32 credentialsId();
192
193     /*!
194      * set the accounts credentials id
195      * The change will be written only when sync() is called.
196      *
197      * This method operates on the currently selected service.
198      */
199     void setCredentialsId(const qint32 id) {
200         setValue(ACCOUNTS_KEY_CREDENTIALS_ID, id);
201     }
202
203     /*!
204      * Returns the display name of the account.
205      *
206      * This method operates on the currently selected service.
207      */
208     QString displayName() const;
209
210     /*!
211      * Changes the display name of the account.
212      * The change will be written only when sync() is called.
213      */
214     void setDisplayName(const QString &displayName);
215
216     /*!
217      * Returns the name of the provider of the account.
218      */
219     QString providerName() const;
220
221     /*!
222      * Selects the Service for the subsequent operations.
223      * @param service The Service to select. If this is NULL, the global
224      * account settings will be selected.
225      */
226     void selectService(const Service *service = 0);
227
228     /*!
229      * Returns the currently selected service.
230      */
231     Service *selectedService() const;
232
233     /* QSettings-like methods */
234
235     /*!
236      * Returns all keys in the current group.
237      *
238      * This method operates on the currently selected service.
239      */
240     QStringList allKeys() const;
241
242     /*!
243      * Enters a group. This method never fails.
244      *
245      * This method operates on the currently selected service.
246      */
247     void beginGroup(const QString &prefix);
248
249     /*!
250      * Returns all the groups which are direct children of the current group.
251      *
252      * This method operates on the currently selected service.
253      */
254     QStringList childGroups() const;
255
256     /*!
257      * Return all the keys which are direct children of the current group.
258      *
259      * This method operates on the currently selected service.
260      */
261     QStringList childKeys() const;
262
263     /*!
264      * Removes all the keys in the currently selected service.
265      * @see remove(const QString &key)
266      */
267     void clear();
268
269     /*!
270      * Check whether the given key is in the current group.
271      *
272      * This method operates on the currently selected service.
273      */
274     bool contains(const QString &key) const;
275
276     /*!
277      * Exits a group.
278      *
279      * This method operates on the currently selected service.
280      */
281     void endGroup();
282
283     /*!
284      * Returns the name of the current group.
285      *
286      * This method operates on the currently selected service.
287      */
288     QString group() const;
289
290     /*!
291      * Checks whether the account is writable. This always returns true.
292      */
293     bool isWritable() const;
294
295     /*!
296      * Remove the given key. If the key is the empty string, all keys in the
297      * current group are removed.
298      *
299      * This method operates on the currently selected service.
300      */
301     void remove(const QString &key);
302
303     /*!
304      * Changes the value of an account setting.
305      * @param key The key name of the setting.
306      * @param value The new value.
307      *
308      * This method operates on the currently selected service.
309      */
310     void setValue(const QString &key, const QVariant &value);
311
312     /*!
313      * Stores all account settings into the database.
314      * The signal synced() will be emitted in case of success, or
315      * error() in case of failure. No assumption must be made about when these
316      * signals will be emitted: if the database is locked, the signals might
317      * be emitted asynchronously, whereas if the operation can happen
318      * synchronously then the signals can be emitted before this method
319      * returns.
320      * If for some reason one would want to process the signals asynchronously
321      * from the event loop, one can use the Qt::QueuedConnection connection
322      * type as last parameter of the QObject::connect call.
323      */
324     void sync();
325
326     /*!
327      * Blocking version of the sync() method: execution of the current thread
328      * will block until the operation has completed.
329      * Usage of this method is discouraged, especially for UI applications.
330      *
331      * @return true on success, false otherwise.
332      */
333     bool syncAndBlock();
334
335     /*!
336      * Retrieves the value of an account setting, as a QVariant.
337      * @param key The key whose value must be retrieved.
338      * @param value A QVariant initialized to the expected type of the value.
339      * @see valueAsString
340      * @see valueAsInt
341      * @see valueAsBool
342      *
343      * @return Whether the value comes from the account, the service template
344      * or was unset.
345      *
346      * This method operates on the currently selected service.
347      */
348     SettingSource value(const QString &key, QVariant &value) const;
349
350     /*!
351      * Gets an account setting as a string.
352      * @param key The key whose value must be retrieved.
353      * @param default_value Value returned if the key is unset.
354      * @param source Indicates whether the value comes from the account, the
355      * service template or was unset.
356      *
357      * This method operates on the currently selected service.
358      */
359     QString valueAsString(const QString &key,
360                           QString default_value = 0,
361                           SettingSource *source = 0) const;
362
363     /*!
364      * Gets an account setting as an integer.
365      * @param key The key whose value must be retrieved.
366      * @param default_value Value returned if the key is unset.
367      * @param source Indicates whether the value comes from the account, the
368      * service template or was unset.
369      *
370      * This method operates on the currently selected service.
371      */
372     int valueAsInt(const QString &key,
373                    int default_value = 0,
374                    SettingSource *source = 0) const;
375
376     /*!
377      * Gets an account setting as an usigned long long integer.
378      * @param key The key whose value must be retrieved.
379      * @param default_value Value returned if the key is unset.
380      * @param source Indicates whether the value comes from the account, the
381      * service template or was unset.
382      *
383      * This method operates on the currently selected service.
384      */
385     quint64 valueAsUInt64(const QString &key,
386                    quint64 default_value = 0,
387                    SettingSource *source = 0) const;
388
389     /*!
390      * Gets an account setting as a boolean.
391      * @param key The key whose value must be retrieved.
392      * @param default_value Value returned if the key is unset.
393      * @param source Indicates whether the value comes from the account, the
394      * service template or was unset.
395      *
396      * This method operates on the currently selected service.
397      */
398     bool valueAsBool(const QString &key,
399                      bool default_value = false,
400                      SettingSource *source = 0) const;
401     /*!
402      * Install a key/group watch.
403      *
404      * @param key The key to watch; if %NULL, watches the currently selected
405      * group.
406      *
407      * @return A Watch object.
408      *
409      * This method operates on the currently selected service.
410      */
411     Watch *watchKey(const QString &key = NULL);
412
413     /*!
414      * Marks the account for removal.
415      * The account will be deleted only when the sync() method is called.
416      */
417     void remove();
418
419     /*!
420      * Creates signature of key with given token.
421      * @param key The key or the prefix of set of the keys to be signed.
422      * @param token The token to be used for signing the key.
423      *
424      * This method operates on the currently selected service.
425      */
426     void sign(const QString &key, const char *token);
427
428     /*!
429      * Verify if the key is signed and the signature matches the value
430      * and provides the token which was used for signing the key.
431      *
432      * @param key The name of the key or prefix of the keys to be verified.
433      * @param token Token to be retrieved.
434      *
435      * @return true if the key is signed and the signature matches the value.
436      *
437      * This method operates on the currently selected service.
438      */
439     bool verify(const QString &key, const char **token);
440
441     /*!
442      * Verify if the key is signed with any of the tokens and the signature
443      * is valid.
444      *
445      * @param key The name of the key or prefix of the keys to be verified.
446      * @param tokens Array of the tokens.
447      *
448      * @return true if the key is signed with any of the token and the signature
449      * is valid.
450      *
451      * This method operates on the currently selected service.
452      */
453     bool verifyWithTokens(const QString &key, QList<const char*> tokens);
454
455 signals:
456     void displayNameChanged(const QString &displayName);
457     void enabledChanged(const QString &serviceName, bool enabled);
458
459     void error(Accounts::ErrorCode errorCode);
460     void synced();
461
462     void removed();
463
464 protected:
465     // Don't include constructor in docs: \cond
466     Account(AgAccount *account, QObject *parent = 0);
467     // \endcond
468
469 private:
470     // Don't include private data in docs: \cond
471     class Private;
472     friend class Manager;
473     friend class Account::Private;
474     friend class Watch;
475
476     Private *d;
477     // \endcond
478 };
479
480
481 } //namespace Accounts
482
483 #endif // ACCOUNT_H