Editing the documentation for consistency
[accounts-sso:vitalyrepins-signon.git] / lib / plugins / SignOn / uisessiondata.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 #ifndef UISESSIONDATA_H
28 #define UISESSIONDATA_H
29
30 #include <SignOn/SessionData>
31 /*!
32  * Error codes for ui interaction.
33  */
34
35 namespace SignOn {
36
37 enum QueryError {
38     QUERY_ERROR_NONE = 0,        /**< No errors. */
39     QUERY_ERROR_GENERAL,         /**< Generic error during interaction. */
40     QUERY_ERROR_NO_SIGNONUI,     /**< Cannot send request to signon-ui. */
41     QUERY_ERROR_BAD_PARAMETERS,  /**< Signon-Ui cannot create dialog based on the given UiSessionData. */
42     QUERY_ERROR_CANCELED,        /**< User canceled action. Plugin should not retry automatically after this. */
43     QUERY_ERROR_NOT_AVAILABLE,   /**< Requested ui is not available. For example browser cannot be started. */
44     QUERY_ERROR_BAD_URL,         /**< Given url was not valid. */
45     QUERY_ERROR_BAD_CAPTCHA,     /**< Given captcha image was not valid. */
46     QUERY_ERROR_BAD_CAPTCHA_URL, /**< Given url for capctha loading was not valid. */
47     QUERY_ERROR_REFRESH_FAILED,  /**< Refresh failed. */
48     QUERY_ERROR_FORBIDDEN,       /**< Showing ui forbidden by ui policy. */
49     QUERY_ERROR_FORGOT_PASSWORD  /**< User pressed forgot password. */
50     //TODO add more errors
51 };
52
53 /*!
54  * Predefined messages to be shown to user while querying input.
55  */
56 enum QueryMessageId {
57     QUERY_MESSAGE_EMPTY = 0,          /**< No predefined message. */
58     QUERY_MESSAGE_LOGIN,     /**< Login without prior errors. */
59     QUERY_MESSAGE_NOT_AUTHORIZED          /**< Authentication failed. */
60     //TODO add more messages
61 };
62
63 /*!
64  * @class UiSessionData
65  * Data container to hold values for authentication session.
66  * Inherit this class if you want to extend the property range.
67  *
68  * @warning All this class' definitions must be inline.
69  */
70 class UiSessionData : public SessionData
71 {
72 public:
73     /*!
74      * Constructor. Creates a UiSessionData with data 'data'.
75      * @param data The data to be contained by the UiSessionData
76      * @attention internal use only recommended. As a SSO client application developer
77      *            use setters/gettters for specific SessionData properties.
78      */
79     UiSessionData(const QVariantMap &data = QVariantMap()) { m_data = data; }
80
81     /*!
82      * Declares the property QueryError setter and getter.
83      * QueryError is used to report errors in ui interaction
84      * that is shown to user.
85      * @see QueryError
86      */
87     SIGNON_SESSION_DECLARE_PROPERTY(int, QueryErrorCode)
88
89     /*!
90      * Declare the property Caption setter and getter.
91      * Caption is used to set dialog title.
92      * Empty caption is discarded.
93      * @warning This string is shown to user as it is,
94      * plugin is responsible for localization.
95      */
96     SIGNON_SESSION_DECLARE_PROPERTY(QString, Caption)
97
98     /*!
99      * Declares the property QueryMessageId setter and getter.
100      * QueryMessageId is used to select predefined localized message
101      * that is shown to user.
102      * @see QueryMessageId
103      */
104     SIGNON_SESSION_DECLARE_PROPERTY(int, QueryMessageId)
105
106     /*!
107      * Declares the property QueryMessage setter and getter.
108      * QueryMessage is used to show given message to user.
109      * Empty message is discarded.
110      * @warning This string is shown to user as it is,
111      * plugin is responsible for localization.
112      */
113     SIGNON_SESSION_DECLARE_PROPERTY(QString, QueryMessage)
114
115     /*!
116      * Declares the property QueryUserName setter and getter.
117      * QueryUserName is used to enable username input in signon-ui.
118      */
119     SIGNON_SESSION_DECLARE_PROPERTY(bool, QueryUserName)
120
121     /*!
122      * Declares the property QueryPassword setter and getter.
123      * QueryPassword is used to enable password input in signon-ui.
124      */
125     SIGNON_SESSION_DECLARE_PROPERTY(bool, QueryPassword)
126
127     /*!
128      * Declares the property RememberPassword setter and getter.
129      * RememberPassword is used to enable password storing signond.
130      */
131     SIGNON_SESSION_DECLARE_PROPERTY(bool, RememberPassword)
132
133     /*!
134      * Declares the property ShowRealm setter and getter.
135      * ShowRealm is used to show realm in signon-ui.
136      */
137     SIGNON_SESSION_DECLARE_PROPERTY(bool, ShowRealm)
138
139     /*!
140      * Declares the property OpenUrl setter and getter.
141      * This url is passed to signon-ui to be opened and shown to user.
142      * Empty url does not open the url view.
143      */
144     SIGNON_SESSION_DECLARE_PROPERTY(QString, OpenUrl)
145
146     /*!
147      * Declares the property UrlResponse setter and getter.
148      * Response from signon-ui for OpenUrl request.
149      * After completion UrlResponse contains redirect target url, if there was redirection.
150      */
151     SIGNON_SESSION_DECLARE_PROPERTY(QString, UrlResponse)
152
153     /*!
154      * Declares the property CaptchaUrl setter and getter.
155      * CaptchaUrl contains url to the captcha image to be verified by user.
156      * CaptchaUrl is used in signon-ui when plugin requires the captcha verification from user.
157      * If this is empty, captcha query is not shown, unless CaptchaImage contain valid image.
158      */
159     SIGNON_SESSION_DECLARE_PROPERTY(QString, CaptchaUrl)
160
161     /*!
162      * Declares the property CaptchaImage setter and getter.
163      * CaptchaImage contains the captcha image to be verified by user.
164      * CaptchaImage is passed to signon-ui when plugin requires the captcha verification from user.
165      * If this is empty, captcha query is not shown, unless CaptchaUrl point to valid image.
166      */
167     SIGNON_SESSION_DECLARE_PROPERTY(QByteArray, CaptchaImage)
168
169     /*!
170      * Declares the property CaptchaResponse setter and getter
171      * CaptchaResponse is passed to plugin after signon-ui has processed the captcha query.
172      * It contains user input for captcha query.
173      * @see CaptchaUrl
174      * @see CaptchaImage.
175      */
176     SIGNON_SESSION_DECLARE_PROPERTY(QString, CaptchaResponse)
177
178     /*!
179      * Declares the property ForgotPassword setter and getter
180      * ForgotPassword string is shown as a link to user.
181      * @see ForgotPasswordUrl
182      */
183     SIGNON_SESSION_DECLARE_PROPERTY(QString, ForgotPassword)
184
185     /*!
186      * Declares the property ForgotPasswordUrl setter and getter
187      * ForgotPasswordUrl is shown to user if ForgotPassword link is pressed.
188      * @see ForgotPassword
189      */
190     SIGNON_SESSION_DECLARE_PROPERTY(QString, ForgotPasswordUrl)
191
192 };
193
194 } //namespace SignOn
195
196 Q_DECLARE_METATYPE(SignOn::UiSessionData)
197 #endif // UISESSIONDATA_H