1/*
2* Copyright (C) 2008 Nicola Gigante <nicola.gigante@gmail.com>
3*
4* This program is free software; you can redistribute it and/or modify
5* it under the terms of the GNU Lesser General Public License as published by
6* the Free Software Foundation; either version 2.1 of the License, or
7* (at your option) any later version.
8*
9* This program is distributed in the hope that it will be useful,
10* but WITHOUT ANY WARRANTY; without even the implied warranty of
11* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12* GNU General Public License for more details.
13*
14* You should have received a copy of the GNU Lesser General Public License
15* along with this program; if not, write to the
16* Free Software Foundation, Inc.,
17* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA .
18*/
19
20#ifndef ACTION_WATCHER_H
21#define ACTION_WATCHER_H
22
23#include <QtCore/QObject>
24#include <QtCore/QString>
25
26#include <kdecore_export.h>
27
28#include "kauthactionreply.h"
29#include "kauthaction.h"
30
31namespace KAuth
32{
33
34/**
35 * @brief Class used to receive notifications about the status of an action execution.
36 *
37 * The ActionWatcher class provides some signals useful to track the execution of an action.
38 * The Action class is designed to be very ligthweight, so it's not the case to make it
39 * a QObject subclass. This means the action object can't expose signals. This is the reason
40 * why every action (not every Action object) used by the app has an associated ActionWatcher.
41 *
42 * You don't create watchers directly. Instead, you should get one from the Action::watcher() method,
43 * if you have an action object, or with the ActionWatcher::watcher() static method, which takes the
44 * action name string.
45 *
46 * See the documentation of single signals for more details about them.
47 *
48 * @since 4.4
49 */
50class KDECORE_EXPORT ActionWatcher : public QObject
51{
52 Q_OBJECT
53
54 class Private;
55 Private * const d;
56
57 ActionWatcher();
58 ActionWatcher(const QString &action);
59
60 Q_PRIVATE_SLOT(d, void actionStartedSlot(const QString &action))
61 Q_PRIVATE_SLOT(d, void actionPerformedSlot(const QString &action, const ActionReply &reply))
62 Q_PRIVATE_SLOT(d, void progressStepSlot(const QString &action, int i))
63 Q_PRIVATE_SLOT(d, void progressStepSlot(const QString &action, const QVariantMap &data))
64 Q_PRIVATE_SLOT(d, void statusChangedSlot(const QString &action, Action::AuthStatus status))
65
66public:
67 /**
68 * @brief Factory method to get watchers
69 *
70 * This method allows you to obtain (and create if needed) an
71 * action watcher from the action string identifier.
72 * It's more common to obtain a watcher using Action::watcher(),
73 * which actually calls this method.
74 *
75 * Every signal of this class
76 * is emitted whichever method you used to execute the action.
77 * This means you could connect to the signal actionPerformed()
78 * even if you're using the execute() method (which already returns the reply)
79 * and you'll get the same reply.
80 *
81 * @param action The action string identifier for the creation of the watcher
82 * @return The action watcher associated with the given action
83 */
84 static ActionWatcher *watcher(const QString &action);
85
86 /// Virtual destructor
87 virtual ~ActionWatcher();
88
89 /// Returns the action name associated with this watcher
90 QString action() const;
91
92Q_SIGNALS:
93 /**
94 * @brief Signal emitted when an action starts the execution
95 *
96 * This signal is emitted whe In case of
97 * execute() and executeAsync(), the signal is emitted about
98 * immediately, because the request is very fast.
99 *
100 * If you execute a group of actions using Action::executeActions(),
101 * this signal is emitted when the single action is actually about
102 * to be executed, not when the whole group starts executing.
103 * This means you can use this signal to start some kind of timeout
104 * to handle helper crashes, if you feel the need.
105 */
106 void actionStarted();
107
108 /**
109 * @brief Signal emitted when an action completed the execution
110 *
111 * This signal provides the only way to obtain the reply from the helper
112 * in case of asynchronous calls. The reply object is the same returned
113 * by the helper, or an error reply from the library if something went
114 * wrong.
115 *
116 * @param reply The reply coming from the helper
117 */
118 void actionPerformed(const ActionReply &reply);
119
120 /**
121 * @brief Signal emitted by the helper to notify the action's progress
122 *
123 * This signal is emitted every time the helper's code calls the
124 * HelperSupport::progressStep(int) method. This is useful to let the
125 * helper notify the execution status of a long action.
126 * The meaning of the integer passed here is totally application-dependent.
127 * If you need to be more expressive, you can use the other signal that
128 * pass a QVariantMap.
129 *
130 * @param progress The progress indicator from the helper
131 */
132 void progressStep(int progress);
133
134 /**
135 * @brief Signal emitted by the helper to notify the action's progress
136 *
137 * This signal is emitted every time the helper's code calls the
138 * HelperSupport::progressStep(QVariantMap) method. This is useful to let the
139 * helper notify the execution status of a long action, also providing
140 * some data, for example if you want to achieve some sort of progressive loading.
141 * The meaning of the data passed here is totally application-dependent.
142 * If you only need to pass some percentage, you can use the other signal that
143 * pass an int.
144 *
145 * @param data The progress data from the helper
146 */
147 void progressStep(const QVariantMap &data);
148
149 void statusChanged(int status);
150};
151
152} // namespace Auth
153
154#endif
155