Editing the documentation for consistency
[accounts-sso:vitalyrepins-signon.git] / lib / plugins / SignOn / authpluginif.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 AUTHPLUGINIF_H
28 #define AUTHPLUGINIF_H
29
30 #include <QtCore/qobject.h>
31 #include <QtCore/qpointer.h>
32 #include <QtCore/qplugin.h>
33
34 #include <QVariantMap>
35 #include <SignOn/sessiondata.h>
36 #include <SignOn/uisessiondata.h>
37 #include <SignOn/signonerror.h>
38
39 QT_BEGIN_NAMESPACE
40 class QString;
41 class QStringList;
42 class QByteArray;
43 class QVariant;
44 QT_END_NAMESPACE
45
46 /*!
47  * Predefined states to be used for progress reporting.
48  */
49 enum AuthPluginState {
50     PLUGIN_STATE_NONE = 0,             /**< State unknown. */
51     PLUGIN_STATE_RESOLVING,          /**< Resolving remote server host name. */
52     PLUGIN_STATE_CONNECTING,      /**< Connecting to remote server. */
53     PLUGIN_STATE_SENDING,             /**< Sending data to remote server. */
54     PLUGIN_STATE_WAITING,            /**< Waiting for reply from remote server. */
55     PLUGIN_STATE_PENDING,             /**< Waiting for response from user. */
56     PLUGIN_STATE_REFRESHING,       /**< Refreshing ui request. */
57     PLUGIN_STATE_CANCELING,         /**< Canceling current process. */
58     PLUGIN_STATE_HOLDING,            /**< Holding long non-expired token. Process should be kept alive. */
59     PLUGIN_STATE_DONE                    /**< Process is finished. Process can be terminated. */
60 };
61
62 /*!
63  * Macro to create declarations of
64  * SSO authentication plugin.
65  * */
66 #define SIGNON_PLUGIN_INSTANCE(pluginclass) \
67         { \
68             static AuthPluginInterface *_instance = 0; \
69             if (!_instance)      \
70                 _instance = static_cast<AuthPluginInterface *>(new pluginclass()); \
71             return _instance; \
72         }
73
74 #define SIGNON_DECL_AUTH_PLUGIN(pluginclass) \
75         Q_EXTERN_C AuthPluginInterface *auth_plugin_instance() \
76         SIGNON_PLUGIN_INSTANCE(pluginclass)
77
78 /*!
79  * @class AuthPluginInterface.
80  * Interface definition for authentication plugins
81  */
82 class AuthPluginInterface : public QObject
83 {
84     Q_OBJECT
85
86 public:
87     AuthPluginInterface(QObject *parent = 0) : QObject(parent)
88         { qRegisterMetaType<SignOn::Error>("SignOn::Error"); }
89
90     /*!
91      * Destructor
92      */
93     virtual ~AuthPluginInterface() {}
94
95     /*!
96      * Gets the type of the plugin
97      *
98      * @return Plugin type
99      */
100     virtual QString type() const = 0;
101
102     /*!
103      * Gets the list of supported mechanisms.
104      *
105      * @return List of mechanisms
106      */
107     virtual QStringList mechanisms() const = 0;
108
109     /*!
110      * Requests to cancel the process.
111      * Process is terminated after this call.
112      * Reimplement this in order to execute specific instructions before
113      * the effective cancel occurres.
114      */
115     virtual void cancel() {}
116
117     /*!
118      * Requests to abort the process.
119      * Process is terminated after this call.
120      * Reimplement this in order to execute specific instructions before
121      * process is killed.
122      */
123     virtual void abort() {}
124
125     /*!
126      * Process authentication.
127      * Authentication can be logging to a server, obtain token(s) from a server,
128      * calculate response using given challenge, etc.
129      * Given session data is used to do authentication and return response.
130      * Signal result() is emitted when authentication is completed,
131      * or signal error() if authentication failed.
132      * @see result
133      * @see error
134      *
135      * @param inData Input data for authentication
136      * @param mechanism Mechanism to use to do authentication
137      */
138     virtual void process(const SignOn::SessionData &inData,
139                          const QString &mechanism = QString()) = 0;
140
141 Q_SIGNALS:
142     /*!
143      * Emitted when authentication process has been completed for given data
144      * and there are no errors.
145      *
146      * @param data Resulting SessionData, need to be returned to client
147      */
148     void result(const SignOn::SessionData &data);
149
150     /*!
151      * Emitted when authentication process want to store session data parameters
152      * for later use. Stored parameters are added into SessionData in following process calls.
153      * This is useful when authentication is using permanent tokens.
154      *
155      * @note This is shared within same identity using same method only.
156      * @note There can be storage size limitation for data that can be stored.
157      *
158      * @param data Resulting SessionData, need to be returned to client
159      */
160     void store(const SignOn::SessionData &data);
161
162     /*!
163      * Emitted when authentication process has been completed for given data
164      * and resulting an error.
165      *
166      * @param err The error object
167      * @param errorMessage Resulting error message
168      */
169     void error(const SignOn::Error &err);
170
171     /*!
172      * Emitted when authentication process need to interact with user.
173      * Basic use cases are: query password, verify captcha, show url.
174      * Can also be used to get username/password for proxy authentication etc.
175      * Slot userActionFinished() is called when interaction is completed.
176      *
177      * @see userActionFinished
178      * @see SignOn::UiSessionData
179      * @note slot userActionFinished() should be reimplemented to get result.
180      *
181      * @param data Ui session data to be filled within user interaction
182      */
183     void userActionRequired(const SignOn::UiSessionData &data);
184
185     /*!
186      * Emitted when authentication process has completed refresh request.
187      * Plugin must emit signal refreshed() to response to refresh() call.
188      * @see refreshed
189      *
190      * @param data Refreshed ui session data
191      */
192     void refreshed(const SignOn::UiSessionData &data);
193
194      /*!
195      * Emitted to report status of authentication process to signond for
196      * informing client application.
197      *
198      * @param state Plugin process state @see AuthPluginState
199      * @param message Optional message for client application
200      */
201     void statusChanged(const AuthPluginState state,
202                        const QString &message = QString());
203
204 public Q_SLOTS:
205     /*!
206      * User interaction completed.
207      * Signond uses this slot to notice the end of ui session.
208      * This is a response to userActionRequired() signal.
209      * This must be reimplemented to get the response from the user interaction.
210      * @see UiSessionData
211      * @see userActionRequired
212      *
213      * @param data User completed ui session data
214      */
215     virtual void userActionFinished(const SignOn::UiSessionData &data) {
216         Q_UNUSED(data);
217     }
218
219     /*!
220      * Refreshes given session.
221      * Signond uses this slot to refresh data in given ui session.
222      * Mostly used to refresh a captcha images during the user interaction.
223      * Signal refreshed() or error() must be emitted when refresh is completed.
224      * This must be reimplemented to refresh the captcha image.
225      * @see UiSessionData
226      * @see refreshed
227      * @note emitting signal userActionRequired() is not allowed to use before ui session is finished.
228      *
229      * @param data Ui session data to be refreshed
230      */
231     virtual void refresh(const SignOn::UiSessionData &data) {
232         emit refreshed(data);
233     }
234
235 };
236
237 QT_BEGIN_NAMESPACE
238  Q_DECLARE_INTERFACE(AuthPluginInterface,
239                      "com.nokia.SingleSignOn.PluginInterface/1.3")
240 QT_END_NAMESPACE
241 #endif // AUTHPLUGINIF_H