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 | |
19 | namespace KAuth |
20 | { |
21 | class 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 | */ |
37 | class KAUTHCORE_EXPORT ActionReply |
38 | { |
39 | public: |
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 | |
350 | private: |
351 | QSharedDataPointer<ActionReplyData> d; |
352 | }; |
353 | |
354 | } // namespace Auth |
355 | |
356 | Q_DECLARE_METATYPE(KAuth::ActionReply) |
357 | |
358 | #endif |
359 | |