1 | /* |
2 | This file is part of KDE. |
3 | |
4 | Copyright (c) 2005 Cornelius Schumacher <schumacher@kde.org> |
5 | |
6 | This library is free software; you can redistribute it and/or |
7 | modify it under the terms of the GNU Library General Public |
8 | License as published by the Free Software Foundation; either |
9 | version 2 of the License, or (at your option) any later version. |
10 | |
11 | This library is distributed in the hope that it will be useful, |
12 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | Library General Public License for more details. |
15 | |
16 | You should have received a copy of the GNU Library General Public License |
17 | along with this library; see the file COPYING.LIB. If not, write to |
18 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | Boston, MA 02110-1301, USA. |
20 | */ |
21 | /** |
22 | @file |
23 | This file is part of the API for handling calendar data and |
24 | defines the CalendarLocal class. |
25 | |
26 | @author Cornelius Schumacher \<schumacher@kde.org\> |
27 | */ |
28 | #ifndef KRESULT_H |
29 | #define KRESULT_H |
30 | |
31 | #include <QtCore/QString> |
32 | #include "kcal_export.h" |
33 | |
34 | namespace KCal { |
35 | |
36 | /** |
37 | @brief |
38 | This class represents the result of an operation. It's meant to be used |
39 | as return value of functions for returning status and especially error |
40 | information. |
41 | |
42 | There are three main types of result: Ok (operation successful completed), |
43 | InProgress (operation still in progress) and Error (operation failed). |
44 | InProgress is used by asynchronous operations. Functions which start an |
45 | operation and return before the operation is finished should return the |
46 | InProgress type result. |
47 | |
48 | An error result can include information about the type of the error and a |
49 | detailed error message. Translated error messages for the error types are |
50 | available through the message() function. Additional detailed error messages |
51 | can be set by the setDetails() function. A full error message including the |
52 | type specific message and the details is available through fullMessage(). |
53 | |
54 | KResult objects can be chained using the chain function. If an operation |
55 | executes a suboperation which indicates failure by returning a KResult object |
56 | the operation can create a new KResult object and chain the suboperation's |
57 | KResult object to it. The error information of chained results is available |
58 | through the chainedMessage() function. |
59 | |
60 | Examples: |
61 | |
62 | A function returning ok: |
63 | |
64 | KResult load() |
65 | { |
66 | return KResultOk(); |
67 | } |
68 | |
69 | Alternative notation: |
70 | |
71 | KResult load() |
72 | { |
73 | return KResult::Ok; |
74 | } |
75 | |
76 | A function returning an error with a specific error message: |
77 | |
78 | KResult load() |
79 | { |
80 | return KResultError( i18n("Details about error") ); |
81 | } |
82 | |
83 | A function returning an error of a sepcific type: |
84 | |
85 | KResult load() |
86 | { |
87 | return KResultError( KResult::InvalidUrl ); |
88 | } |
89 | |
90 | Chaining errors: |
91 | |
92 | KResult loadFile() |
93 | { |
94 | KResult result = mFile.load(); |
95 | if ( !result.isError() ) { |
96 | return KResultError( "File load error" ).chain( result ); |
97 | } else { |
98 | return result; |
99 | } |
100 | } |
101 | |
102 | Checking for errors: |
103 | |
104 | KResult load() { ... } |
105 | |
106 | ... |
107 | if ( !load() ) error(); |
108 | */ |
109 | class KCAL_DEPRECATED_EXPORT KResult |
110 | { |
111 | public: |
112 | /** |
113 | The different types of results. |
114 | */ |
115 | enum Type { |
116 | Ok, /**< Operation successfully completed */ |
117 | InProgress, /**< Operation still in-progress */ |
118 | Error /**< Operation failed */ |
119 | }; |
120 | |
121 | /** |
122 | The different types of error conditions. |
123 | */ |
124 | enum ErrorType { |
125 | NotAnError, /**< Not an error */ |
126 | Undefined, /**< Undefined error */ |
127 | InvalidUrl, /**< Invalid URL */ |
128 | WrongParameter, /**< Invalid parameter */ |
129 | ConnectionFailed, /**< unable to establish a connection */ |
130 | WriteError, /**< Write error */ |
131 | ReadError, /**< Read error */ |
132 | ParseError, /**< Parse error */ |
133 | WrongSchemaRevision /**< Invalid schema revision */ |
134 | }; |
135 | |
136 | /** |
137 | Constructs a KResult object. Default Type is Ok. |
138 | */ |
139 | KResult(); |
140 | |
141 | /** |
142 | Copy constructor. |
143 | */ |
144 | KResult( const KResult & ); |
145 | |
146 | /** |
147 | Creates a KResult object of the specified Type. |
148 | @param type is the result #Type. |
149 | */ |
150 | explicit KResult( Type type ); |
151 | |
152 | /** |
153 | Creates a KResult object of the specified ErrorType and an optional |
154 | detailed error message. |
155 | @param error is the #ErrorType. |
156 | @param details is a QString containing optional details to add |
157 | to the message corresponding to this error. |
158 | */ |
159 | explicit KResult( ErrorType error, const QString &details = QString() ); |
160 | |
161 | /** |
162 | Destroys the result. |
163 | */ |
164 | ~KResult(); |
165 | |
166 | /** |
167 | Behave like a bool in the corresponding context. Ok and InProgress are |
168 | considered as success and return true, Error is considered as failure and |
169 | returns false. |
170 | */ |
171 | operator bool() const; |
172 | |
173 | /** |
174 | Returns true if the result is Ok. |
175 | */ |
176 | bool isOk() const; |
177 | |
178 | /** |
179 | Returns true if the result is InProgress. |
180 | */ |
181 | bool isInProgress() const; |
182 | |
183 | /** |
184 | Returns true if the result is Error. |
185 | */ |
186 | bool isError() const; |
187 | |
188 | /** |
189 | Returns the specific result ErrorType. |
190 | */ |
191 | ErrorType error() const; |
192 | |
193 | /** |
194 | Returns a translated string describing the result corresponding to Type |
195 | and ErrorType. |
196 | @see fullMessage(). |
197 | */ |
198 | QString message() const; |
199 | |
200 | /** |
201 | Sets a detailed error message. This error message should include all |
202 | details needed to understand and recover from the error. This could be |
203 | information like the URL which was tried, the file which could not be |
204 | written or which parameter was missing. |
205 | |
206 | @param details is a QString containing details to add to the message |
207 | for this error. |
208 | @see details(). |
209 | */ |
210 | void setDetails( const QString &details ); |
211 | |
212 | /** |
213 | Returns the detailed error message. |
214 | @see setDetails(). |
215 | */ |
216 | QString details() const; |
217 | |
218 | /** |
219 | Returns the full error message. This includes the type-specific message |
220 | (see message()) and the detailed message (see details()). |
221 | */ |
222 | QString fullMessage() const; |
223 | |
224 | /** |
225 | Chains result objects. This can be used to remember the cause of an error. |
226 | The full error messages including the messages from chained objects can be |
227 | accessed through chainedMessage(). |
228 | @param result is another KResult to chain this one to. |
229 | */ |
230 | KResult &chain( const KResult &result ); |
231 | |
232 | /** |
233 | Returns true if the KResult object has a chained KResult object; |
234 | else returns false. |
235 | */ |
236 | bool hasChainedResult() const; |
237 | |
238 | /** |
239 | Returns a chained KResult object. |
240 | */ |
241 | KResult chainedResult() const; |
242 | |
243 | /** |
244 | Returns an error message including full details of all chained messages. |
245 | This can constitute a backtrace of a error. |
246 | */ |
247 | QString chainedMessage() const; |
248 | |
249 | private: |
250 | //@cond PRIVATE |
251 | class Private; |
252 | Private *const d; |
253 | //@endcond |
254 | }; |
255 | |
256 | /** |
257 | @brief |
258 | Convenience class for creating a KResult of type Ok. |
259 | */ |
260 | class KCAL_DEPRECATED_EXPORT KResultOk : public KResult |
261 | { |
262 | public: |
263 | /** |
264 | Create KResult object of type Ok. |
265 | */ |
266 | KResultOk() : KResult( Ok ), d( 0 ) {} |
267 | |
268 | private: |
269 | //@cond PRIVATE |
270 | class Private; |
271 | Private *const d; |
272 | //@endcond |
273 | }; |
274 | |
275 | /** |
276 | @brief |
277 | Convenience class for creating a KResult of type InProgress. |
278 | */ |
279 | class KCAL_DEPRECATED_EXPORT KResultInProgress : public KResult |
280 | { |
281 | public: |
282 | /** |
283 | Create KResult object of type InProgress. |
284 | */ |
285 | KResultInProgress() : KResult( InProgress ), d( 0 ) {} |
286 | |
287 | private: |
288 | //@cond PRIVATE |
289 | class Private; |
290 | Private *const d; |
291 | //@endcond |
292 | }; |
293 | |
294 | /** |
295 | @brief |
296 | Convenience class for creating a KResult of type Error. |
297 | */ |
298 | class KCAL_DEPRECATED_EXPORT KResultError : public KResult |
299 | { |
300 | public: |
301 | /** |
302 | Create KResult object of type Error. |
303 | */ |
304 | KResultError() : KResult( Error ), d( 0 ) {} |
305 | |
306 | /** |
307 | Create KResult object of type Error with given error type and optionally |
308 | a detailed error message. |
309 | |
310 | @param error is the #ErrorType. |
311 | @param details is a QString containing optional details to add |
312 | to the message corresponding to this error. |
313 | */ |
314 | explicit KResultError( ErrorType error, const QString &details = QString() ) |
315 | : KResult( error, details ), d( 0 ) {} |
316 | |
317 | /** |
318 | Create KResult object of type Error with given detailed error message. |
319 | |
320 | @param details is a QString containing optional details to add |
321 | to the message corresponding to this error. |
322 | */ |
323 | KResultError( const QString &details ) : |
324 | KResult( Undefined, details ), d( 0 ) {} |
325 | |
326 | private: |
327 | //@cond PRIVATE |
328 | Q_DISABLE_COPY( KResultError ) |
329 | class Private; |
330 | Private *const d; |
331 | //@endcond PRIVATE |
332 | }; |
333 | |
334 | } |
335 | |
336 | #endif |
337 | |