1/*
2 SPDX-FileCopyrightText: 2008 Nicola Gigante <nicola.gigante@gmail.com>
3 SPDX-FileCopyrightText: 2009-2012 Dario Freddi <drf@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.1-or-later
6*/
7
8#ifndef KAUTH_ACTION_REPLY_H
9#define KAUTH_ACTION_REPLY_H
10
11#include "kauthcore_export.h"
12
13#include <QDataStream>
14#include <QMap>
15#include <QSharedDataPointer>
16#include <QString>
17#include <QVariant>
18
19namespace KAuth
20{
21class ActionReplyData;
22
23/*!
24 * \class KAuth::ActionReply
25 * \inmodule KAuth
26 * \inheaderfile KAuth/ActionReply
27 *
28 * \brief Class that encapsulates a reply coming from the helper after executing
29 * an action.
30 *
31 * Helper applications will return this to describe the result of the action.
32 *
33 * Callers should access the reply though the KAuth::ExecuteJob job.
34 *
35 * \since 4.4
36 */
37class KAUTHCORE_EXPORT ActionReply
38{
39public:
40 /*!
41 * Enumeration of the different kinds of replies.
42 *
43 * \value KAuthErrorType An error reply generated by the library itself
44 * \value HelperErrorType An error reply generated by the helper
45 * \value SuccessType The action has been completed successfully
46 */
47 enum Type {
48 KAuthErrorType,
49 HelperErrorType,
50 SuccessType,
51 };
52
53 /*!
54 * An empty successful reply. Same as using the default constructor
55 */
56 static const ActionReply SuccessReply();
57
58 /*!
59 * An empty reply with type() == HelperError and errorCode() == -1
60 */
61 static const ActionReply HelperErrorReply();
62
63 /*!
64 * An empty reply with type() == HelperError and error is set to the passed value
65 */
66 static const ActionReply HelperErrorReply(int error);
67
68 /*!
69 * errorCode() == NoResponder
70 */
71 static const ActionReply NoResponderReply();
72
73 /*!
74 * errorCode() == NoSuchAction
75 */
76 static const ActionReply NoSuchActionReply();
77
78 /*!
79 * errorCode() == InvalidAction
80 */
81 static const ActionReply InvalidActionReply();
82
83 /*!
84 * errorCode() == AuthorizationDenied
85 */
86 static const ActionReply AuthorizationDeniedReply();
87
88 /*!
89 * errorCode() == UserCancelled
90 */
91 static const ActionReply UserCancelledReply();
92
93 /*!
94 * errorCode() == HelperBusy
95 */
96 static const ActionReply HelperBusyReply();
97
98 /*!
99 * errorCode() == AlreadyStartedError
100 */
101 static const ActionReply AlreadyStartedReply();
102
103 /*!
104 * errorCode() == DBusError
105 */
106 static const ActionReply DBusErrorReply();
107
108 /*!
109 * The enumeration of the possible values of errorCode() when type() is ActionReply::KAuthError
110 *
111 * \value NoError No error
112 * \value NoResponderError The helper responder object hasn't been set. This shouldn't happen if you use the KAUTH_HELPER macro in the helper source
113 * \value NoSuchActionError The action you tried to execute doesn't exist
114 * \value InvalidActionError You tried to execute an invalid action object
115 * \value AuthorizationDeniedError You don't have the authorization to execute the action
116 * \value UserCancelledError Action execution has been cancelled by the user
117 * \value HelperBusyError The helper is busy executing another action (or group of actions). Try later
118 * \value AlreadyStartedError The action was already started and is currently running
119 * \value DBusError An error from D-Bus occurred
120 * \value BackendError The underlying backend reported an error
121 */
122 enum Error {
123 NoError = 0,
124 NoResponderError,
125 NoSuchActionError,
126 InvalidActionError,
127 AuthorizationDeniedError,
128 UserCancelledError,
129 HelperBusyError,
130 AlreadyStartedError,
131 DBusError,
132 BackendError,
133 };
134
135 /*!
136 * Default constructor. Sets type() to Success and errorCode() to zero.
137 */
138 ActionReply();
139
140 /*!
141 * \brief Constructor to directly set the type.
142 *
143 * This constructor directly sets the reply type. You shouldn't need to
144 * directly call this constructor, because you can use the more convenient
145 * predefined replies constants. You also shouldn't create a reply with
146 * the KAuthError type because it's reserved for errors coming from the
147 * library.
148 *
149 * \a type The type of the new reply
150 */
151 ActionReply(Type type);
152
153 /*!
154 * \brief Constructor that creates a KAuthError reply with a specified error code.
155 * Do not use outside the library.
156 *
157 * This constructor is for internal use only, since it creates a reply
158 * with KAuthError type, which is reserved for errors coming from the library.
159 *
160 * \a errorCode The error code of the new reply
161 */
162 ActionReply(int errorCode);
163
164 ActionReply(const ActionReply &reply);
165
166 virtual ~ActionReply();
167
168 /*!
169 * \brief Sets the custom data to send back to the application
170 *
171 * In the helper's code you can use this function to set an QVariantMap
172 * with custom data that will be sent back to the application.
173 *
174 * \a data The new QVariantMap object.
175 */
176 void setData(const QVariantMap &data);
177
178 /*!
179 * \brief Returns the custom data coming from the helper.
180 *
181 * This method is used to get the object that contains the custom
182 * data coming from the helper. In the helper's code, you can set it
183 * using setData() or the convenience method addData().
184 *
185 * Returns the data coming from (or that will be sent by) the helper
186 */
187 QVariantMap data() const;
188
189 /*!
190 * \brief Convenience method to add some data to the reply.
191 *
192 * This method adds the pair \c key/value to the QVariantMap used to
193 * report back custom data to the application.
194 *
195 * Use this method if you don't want to create a new QVariantMap only to
196 * add a new entry.
197 *
198 * \a key The new entry's key
199 * \a value The value of the new entry
200 */
201 void addData(const QString &key, const QVariant &value);
202
203 /*!
204 * Returns the reply's type
205 */
206 Type type() const;
207
208 /*!
209 * \brief Sets the reply type
210 *
211 * Every time you create an action reply, you implicitly set a type.
212 * Default constructed replies or ActionReply::SuccessReply have
213 * type() == Success.
214 * ActionReply::HelperErrorReply has type() == HelperError.
215 * Predefined error replies have type() == KAuthError.
216 *
217 * This means you rarely need to change the type after the creation,
218 * but if you need to, don't set it to KAuthError, because it's reserved
219 * for errors coming from the library.
220 *
221 * \a type The new reply type
222 */
223 void setType(Type type);
224
225 /*!
226 * Returns true if type() == Success
227 */
228 bool succeeded() const;
229
230 /*!
231 * Returns true if type() != Success
232 */
233 bool failed() const;
234
235 /*!
236 * \brief Returns the error code of an error reply
237 *
238 * The error code returned is one of the values in the ActionReply::Error
239 * enumeration if type() == KAuthError, or is totally application-dependent if
240 * type() == HelperError. It also should be zero for successful replies.
241 *
242 * Returns the reply error code
243 */
244 int error() const;
245
246 /*!
247 * \brief Returns the error code of an error reply
248 *
249 * The error code returned is one of the values in the ActionReply::Error
250 * enumeration if type() == KAuthError.
251 * Result is only valid if the type() == HelperError
252 *
253 * Returns the reply error code
254 */
255 Error errorCode() const;
256
257 /*!
258 * \brief Sets the error code of an error reply
259 *
260 * If you're setting the error code in the helper because
261 * you need to return an error to the application, please make sure
262 * you already have set the type to HelperError, either by calling
263 * setType() or by creating the reply in the right way.
264 *
265 * If the type is Success when you call this method, it will become KAuthError
266 *
267 * \a error The new reply error code
268 */
269 void setError(int error);
270
271 /*!
272 * \brief Sets the error code of an error reply
273 *
274 * If you're setting the error code in the helper, use setError(int)
275 *
276 * If the type is Success when you call this method, it will become KAuthError
277 *
278 * \a errorCode The new reply error code
279 */
280 void setErrorCode(Error errorCode);
281
282 /*!
283 * \brief Gets a human-readble description of the error, if available
284 *
285 * Currently, replies of type KAuthError rarely report an error description.
286 * This situation could change in the future.
287 *
288 * By now, you can use this method for custom errors of type HelperError.
289 *
290 * Returns the error human-readable description
291 */
292 QString errorDescription() const;
293
294 /*!
295 * \brief Sets a human-readble description of the error
296 *
297 * Call this method from the helper if you want to send back a description for
298 * a custom error. Note that this method doesn't affect the errorCode in any way
299 *
300 * \a error The new error description
301 */
302 void setErrorDescription(const QString &error);
303
304 /*!
305 * \brief Serialize the reply into a QByteArray.
306 *
307 * This is a convenience method used internally to sent the reply to a remote peer.
308 * To recreate the reply, use deserialize()
309 *
310 * Returns a QByteArray representation of this reply
311 */
312 QByteArray serialized() const;
313
314 /*!
315 * \brief Deserialize a reply from a QByteArray
316 *
317 * This method returns a reply from a QByteArray obtained from
318 * the serialized() method.
319 *
320 * \a data A QByteArray obtained with serialized()
321 */
322 static ActionReply deserialize(const QByteArray &data);
323
324 ActionReply &operator=(const ActionReply &reply);
325
326 /*!
327 * \brief Comparison operator
328 *
329 * Returns true if the type and the error code of this and \a reply are the same.
330 * It \e doesn't compare the data or the error descriptions, so be careful.
331 *
332 * The suggested use is to compare a reply against one of the predefined error replies:
333 * \code
334 * if(reply == ActionReply::HelperBusyReply) {
335 * // Do something...
336 * }
337 * \endcode
338 *
339 * Note that you can do it also by compare errorCode() with the relative enumeration value.
340 */
341 bool operator==(const ActionReply &reply) const;
342
343 /*!
344 * \brief Negated comparison operator
345 *
346 * See the operator==() for an important notice.
347 */
348 bool operator!=(const ActionReply &reply) const;
349
350private:
351 QSharedDataPointer<ActionReplyData> d;
352};
353
354} // namespace Auth
355
356Q_DECLARE_METATYPE(KAuth::ActionReply)
357
358#endif
359

source code of kauth/src/actionreply.h