Editing the documentation for consistency
[accounts-sso:vitalyrepins-signon.git] / lib / SignOn / sessiondata.h
1 /*
2  * This file is part of signon
3  *
4  * Copyright (C) 2009-2010 Nokia Corporation.
5  *
6  * Contact: Alberto Mardegan <alberto.mardegan@nokia.com>
7  *
8  * This library is free software; you can redistribute it and/or
9  * modify it under the terms of the GNU Lesser General Public License
10  * version 2.1 as published by the Free Software Foundation.
11  *
12  * This library is distributed in the hope that it will be useful, but
13  * WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with this library; if not, write to the Free Software
19  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20  * 02110-1301 USA
21  */
22 /*!
23  * @copyright Copyright (C) 2009-2011 Nokia Corporation.
24  * @license LGPL
25  */
26
27 /*!
28  * @todo move this to a common includes folder.
29  * This is part of the plugin development kit, too.
30  */
31
32 #ifndef SESSIONDATA_H
33 #define SESSIONDATA_H
34
35 #include <QMap>
36 #include <QString>
37 #include <QStringList>
38 #include <QVariant>
39
40 #include <SignOn/libsignoncommon.h>
41
42 namespace SignOn {
43
44 /*!
45  * A macro to create declarations for parameter setter and getter.
46  * This supports the same types as @see QVariant.
47  * For user specified types @see QMetaType.
48  *
49  * @param type_ Type of parameter
50  * @param name_ Name of property
51  */
52 #define SIGNON_SESSION_DECLARE_PROPERTY(type_, name_) \
53           void set##name_(const type_ &value ) { m_data.insert(QLatin1String(#name_), value); } \
54           type_ name_() const { return m_data.value(QLatin1String(#name_)).value<type_>(); }
55
56 /*!
57  * Property which holds the access control tokens that the requesting application has.
58  * @note to be used by the plugins developers only.
59  */
60 #define SSO_ACCESS_CONTROL_TOKENS QLatin1String("AccessControlTokens")
61
62 /*!
63  * @enum SignonUiPolicy
64  * Policy to define how the plugin interacts with the user.
65  * This is a hint for plugin how to handle user interaction.
66  * NoUserInteractionPolicy does not allow any ui interaction to happen
67  * and plugin will get error reply QUERY_ERROR_FORBIDDEN.
68  * @see UiPolicy
69  */
70 enum SignonUiPolicy {
71     DefaultPolicy = 0,          /**< Plugin can decide when to show ui. */
72     RequestPasswordPolicy,      /**< Force user to enter password. */
73     NoUserInteractionPolicy,    /**< No ui elements are shown to user. */
74     ValidationPolicy,           /**< UI elements can be shown to the user only
75                                   when captcha-like security measures are
76                                   required */
77 };
78
79 /*!
80  * @class SessionData
81  * @headerfile sessiondata.h SignOn/SessionData
82  *
83  * Data container to hold values for authentication session.
84  * Inherit this class if you want to extend the property range.
85  *
86  *
87  * @warning All this class' definitions must be inline.
88  */
89 class SIGNON_EXPORT SessionData
90 {
91 public:
92     /*!
93      * Constructor. Creates a SessionData with data 'data'.
94      * @param data The data to be contained by the SessionData
95      * @attention internal use only recommended. As a SSO client application developer
96      *            use setters/gettters for specific SessionData properties.
97      */
98     SessionData(const QVariantMap &data = QVariantMap()) { m_data = data; }
99
100     /*!
101      * Copy constructor.
102      * @param other SessionData object to be copied to this instance
103      */
104     SessionData(const SessionData &other) { m_data = other.m_data; }
105
106     /*!
107      * Assignment operator
108      * @param other SessionData object to be assigned to this instance
109      * @return Reference to this object
110      */
111     SessionData &operator=(const SessionData &other) {
112         m_data = other.m_data;
113         return *this;
114     }
115
116     /*!
117      * Addition operator
118      * @param other SessionData object to be added to this instance.
119      * @return reference to this object
120      */
121     SessionData &operator+=(const SessionData &other) {
122         m_data.unite(other.m_data);
123         return *this;
124     }
125
126     /*!
127      * Access the list of runtime existing properties of the SessionData.
128      * @return String list containing the property names
129      */
130     const QStringList propertyNames() const {
131         return m_data.keys();
132     }
133
134     /*!
135      * Access the list of runtime existing properties of the SessionData.
136      * @param propertyName Name of the property to be accessed
137      * @return Variant containing the property value of propertyName, or an empty variant if
138      *          property does not exist at runtime.
139      */
140     const QVariant getProperty(const QString &propertyName) const {
141         return m_data.value(propertyName, QVariant());
142     }
143
144     /*!
145      * Gets the access control tokens that the requesting application has.
146      * @note to be used by the plugins developers only.
147      */
148     QStringList getAccessControlTokens() const {
149         return getProperty(SSO_ACCESS_CONTROL_TOKENS).toStringList();
150     }
151
152     /*!
153      * Creates an instance of type T, which must be derived from SessionData.
154      * The instance will contain the data of this instance.
155      * @return Instance of type T, containing the data of this instance.
156      */
157     template <class T> T data() const {
158         T dataImpl;
159         dataImpl.m_data = m_data;
160         return dataImpl;
161     }
162
163     /*!
164      * Declares the property Secret setter and getter.
165      * setSecret(const QString secret);
166      * const QString Secret() const;
167      */
168     SIGNON_SESSION_DECLARE_PROPERTY(QString, Secret)
169
170     /*!
171      * Declares the property UserName setter and getter.
172      */
173     SIGNON_SESSION_DECLARE_PROPERTY(QString, UserName)
174
175     /*!
176      * Declares the property Realm setter and getter.
177      * Realm that is used for authentication.
178      */
179     SIGNON_SESSION_DECLARE_PROPERTY(QString, Realm)
180
181     /*!
182      * Declares the property NetworkProxy setter and getter.
183      * Network proxy to be used instead of system default.
184      */
185     SIGNON_SESSION_DECLARE_PROPERTY(QString, NetworkProxy)
186
187     /*!
188      * Declares the property UiPolicy setter and getter.
189      * Use UiPolicy to define how plugin interacts with the user.
190      * @see SignonUiPolicy
191      */
192     SIGNON_SESSION_DECLARE_PROPERTY(int, UiPolicy)
193
194     /*!
195      * Declares the property Caption setter and getter.
196      * Caption is to tell user which application/credentials/provider is
197      * requesting signon-ui.
198      *
199      * @note Caption is taken from database if not defined by application
200      * or authentication plugin.
201      */
202     SIGNON_SESSION_DECLARE_PROPERTY(QString, Caption)
203
204     /*!
205      * Declares the property NetworkTimeout setter and getter.
206      * Sets the timeout for network related operations in milliseconds.
207      * To be used when a remote service does not reply in a reasonable amount of time.
208      */
209     SIGNON_SESSION_DECLARE_PROPERTY(quint32, NetworkTimeout)
210
211     /*!
212      * Declares the property WindowId setter and getter.
213      * This is to be used for setting signon-ui dialog application modal.
214      */
215     SIGNON_SESSION_DECLARE_PROPERTY(quint32, WindowId)
216
217     /*!
218      * Declares the property RenewToken setter and getter.
219      * This is used by a signon plugin to check whether
220      * the access token has to be renewed. When this
221      * property is set, the signon plugin will remove the
222      * old set of access tokens and get a new set.
223      */
224     SIGNON_SESSION_DECLARE_PROPERTY(bool, RenewToken)
225
226 protected:
227     QVariantMap m_data;
228 };
229
230 } //namespace SignOn
231
232 Q_DECLARE_METATYPE(SignOn::SessionData)
233 #endif // SESSIONDATA_H