~unity-api-team/storage-framework/devel
» Revision
126
: include/unity/storage/provider/Exceptions.h
« back to all changes in this revision
Viewing changes to include/unity/storage/provider/Exceptions.h
- browse files at revision 126
- compare with another revision
- download diff
- download tarball
- view history from revision 126
- Committer: Tarmac
- Author(s): Michi Henning
- Date: 2017-04-06 08:09:37 UTC
- mfrom: (118.2.14 add-doc)
- Revision ID: tarmac-20170406080937-97zduhlyym3yzftj
Added tutorial and provider reference documentation.
Approved by unity-api-1-bot, Michi Henning, James Henstridge.
Approved by unity-api-1-bot, Michi Henning, James Henstridge.
- files added:
- debian/storage-framework-doc.install
- doc
- files modified:
- CMakeLists.txt
added
removed
include/unity/storage/provider/Exceptions.h
37
37
// - src/qt/internal/unmarshal_error.cpp
38
38
39
39
/**
40
\brief Base exception class for all server-side exceptions.
40
\brief Abstract base exception class for all server-side exceptions.
41
41
*/
42
42
43
class UNITY_STORAGE_EXPORT StorageException : public std::exception
43
44
{
44
45
public:
46
/**
47
\brief Constructs a StorageException.
48
\param exception_type The concrete type name of the exception, such as "ConflictException".
49
\param error_message The error message text for the exception.
50
*/
45
51
StorageException(std::string const& exception_type, std::string const& error_message);
46
52
47
53
protected:
48
54
~StorageException();
49
55
50
56
public:
57
/**
58
\brief Returns an error string.
59
\return The error message prefixed by the exception type, such as "ConflictException: ETag mismatch".
60
*/
51
61
virtual char const* what() const noexcept override;
52
62
63
/**
64
\brief Returns the exception type name.
65
\return The value of the <code>exception_type</code> parameter that was passed to the constructor.
66
*/
53
67
std::string type() const;
68
69
/**
70
\brief Returns the except error message.
71
\return The value of the <code>error_message</code> parameter that was passed to the constructor.
72
*/
54
73
std::string error_message() const;
55
74
56
75
private:
61
80
62
81
/**
63
82
\brief Indicates errors in the communication between the storage provider and the cloud service.
83
84
Use this exception for unexpected communication errors, such as the remote server being unreachable
85
or returning garbled data.
64
86
*/
87
65
88
class UNITY_STORAGE_EXPORT RemoteCommsException : public StorageException
66
89
{
67
90
public:
91
/**
92
\brief Construct a RemoteCommsException.
93
\param error_message The error message for the exception.
94
*/
68
95
RemoteCommsException(std::string const& error_message);
69
96
~RemoteCommsException();
70
97
};
71
98
72
99
/**
73
\brief Indicates that an item does not exist or could not be found.
100
\brief Indicates that an item does not exist.
101
102
Use this exception only if the remote cloud service has <i>authoritatively</i> indicated non-existence
103
(such as with an HTTP 404 response). Do not use this exception for non-authoritative errors, such as
104
timeouts or similar.
74
105
*/
106
75
107
class UNITY_STORAGE_EXPORT NotExistsException : public StorageException
76
108
{
77
109
public:
110
/**
111
\brief Construct a RemoteCommsException.
112
\param error_message The error message for the exception.
113
\param key The name or identity of the non-existent item.
114
*/
78
115
NotExistsException(std::string const& error_message, std::string const& key);
79
116
~NotExistsException();
80
117
118
/**
119
\brief Return the key.
120
\return The value of the <code>key</code> parameter that was passed to the constructor.
121
*/
81
122
std::string key() const;
82
123
83
124
private:
85
126
};
86
127
87
128
/**
88
\brief Indicates that an item cannot be created because it exists already.
129
\brief Indicates that an item already exists.
130
131
Use this exception only if the remote cloud service has <i>authoritatively</i> indicated that an operation
132
cannot be carried out because an item exists already. Do not use this exception for non-authoritative errors,
133
such as timeouts or similar.
89
134
*/
135
90
136
class UNITY_STORAGE_EXPORT ExistsException : public StorageException
91
137
{
92
138
public:
139
/**
140
\brief Construct an ExistsException.
141
\param error_message The error message for the exception.
142
\param identity The identity of the item.
143
\param name The name of the item.
144
*/
93
145
ExistsException(std::string const& error_message, std::string const& identity, std::string const& name);
94
146
~ExistsException();
95
147
148
/**
149
\brief Return the identity.
150
\return The value of the <code>identity</code> parameter that was passed to the constructor.
151
*/
96
152
std::string native_identity() const;
153
154
/**
155
\brief Return the name of the item.
156
\return The value of the <code>name</code> parameter that was passed to the constructor.
157
*/
97
158
std::string name() const;
98
159
99
160
private:
102
163
};
103
164
104
165
/**
105
\brief Indicates that an upload or download detected a version mismatch.
166
\brief Indicates that an upload or download detected a ETag mismatch.
106
167
*/
168
107
169
class UNITY_STORAGE_EXPORT ConflictException : public StorageException
108
170
{
109
171
public:
172
/**
173
\brief Construct a ConflictException.
174
\param error_message The error message for the exception.
175
*/
110
176
ConflictException(std::string const& error_message);
111
177
~ConflictException();
112
178
};
113
179
114
180
/**
115
\brief Indicates that an operation failed because the authentication credentials are invalid or expired.
181
\brief Indicates that an operation failed because the credentials are invalid or have expired.
116
182
117
183
A provider implementation must throw this exception if it cannot reach
118
its provider because the credentials are invalid. Do not throw this
184
its provider because the credentials are invalid. Do <i>not</i> throw this
119
185
exception if the credentials are valid, but an operation failed due to
120
186
insufficient permission for an item (such as an attempt to write to a
121
187
read-only file).
122
188
123
Typically, this will cause the request to be retried after refreshing
124
the authentication credentials, but may be returned to the client on
125
repeated failures.
189
Typically, this exception will cause the runtime to retry the operation after refreshing
190
the credentials; the exception may be returned to the client on repeated failures.
126
191
127
192
\see PermissionException
128
193
*/
194
129
195
class UNITY_STORAGE_EXPORT UnauthorizedException : public StorageException
130
196
{
131
197
public:
198
/**
199
\brief Construct an UnauthorizedException.
200
\param error_message The error message for the exception.
201
*/
132
202
UnauthorizedException(std::string const& error_message);
133
203
~UnauthorizedException();
134
204
};
139
209
A provider implementation must throw this exception if it can
140
210
authenticate with its provider, but the provider denied the operation
141
211
due to insufficient permission for an item (such as an attempt to
142
write to a read-only file). Do not throw this exception for failure to
212
write to a read-only file). Do <i>not</i> throw this exception for failure to
143
213
authenticate with the provider.
144
214
145
215
\see UnauthorizedException
146
216
*/
217
147
218
class UNITY_STORAGE_EXPORT PermissionException : public StorageException
148
219
{
149
220
public:
221
/**
222
\brief Construct a PermissionException.
223
\param error_message The error message for the exception.
224
*/
150
225
PermissionException(std::string const& error_message);
151
226
~PermissionException();
152
227
};
153
228
154
229
/**
155
\brief Indicates that an update failed because the provider ran out of space.
230
\brief Indicates that an update failed because the provider ran out of space or exceeded
231
the maximum number of files or folders.
156
232
*/
233
157
234
class UNITY_STORAGE_EXPORT QuotaException : public StorageException
158
235
{
159
236
public:
237
/**
238
\brief Construct a QuotaException.
239
\param error_message The error message for the exception.
240
*/
160
241
QuotaException(std::string const& error_message);
161
242
~QuotaException();
162
243
};
163
244
164
245
/**
165
246
\brief Indicates that an upload or download was cancelled before it could complete.
247
\note Due to the way the provider API is structured, you will not ever need to throw this exception. It is provided for
248
completeness and to allow for provider implementations that do not use the storage framework API.
166
249
*/
250
167
251
class UNITY_STORAGE_EXPORT CancelledException : public StorageException
168
252
{
169
253
public:
254
/**
255
\brief Construct a CancelledException.
256
\param error_message The error message for the exception.
257
*/
170
258
CancelledException(std::string const& error_message);
171
259
~CancelledException();
172
260
};
173
261
174
262
/**
175
\brief Indicates incorrect use of the API, such as calling methods in the wrong order.
263
\brief Indicates incorrect use of the API.
264
265
Use this exception for errors that the client could avoid, such as calling methods in the wrong order or attempting
266
to list the contents of file (as opposed to a folder).
267
\note Do <i>not</i> throw this exception to indicate arguments that are malformed or out of range.
268
\see InvalidArgumentException
176
269
*/
177
270
class UNITY_STORAGE_EXPORT LogicException : public StorageException
178
271
{
179
272
public:
273
/**
274
\brief Construct a LogicException.
275
\param error_message The error message for the exception.
276
*/
180
277
LogicException(std::string const& error_message);
181
278
~LogicException();
182
279
};
183
280
184
281
/**
185
\brief Indicates an invalid parameter, such as a negative value when a positive one was
282
\brief Indicates an invalid parameter.
283
284
Use this exception for errors such as a negative parameter value when a positive one was
186
285
expected, or a string that does not parse correctly or is empty when it should be non-empty.
286
\note Do <i>not</i> throw this exception to indicate incorrect use of the API.
287
\see LogicException
187
288
*/
289
188
290
class UNITY_STORAGE_EXPORT InvalidArgumentException : public StorageException
189
291
{
190
292
public:
293
/**
294
\brief Construct an InvalidArgumentException.
295
\param error_message The error message for the exception.
296
*/
191
297
InvalidArgumentException(std::string const& error_message);
192
298
~InvalidArgumentException();
193
299
};
194
300
195
301
/**
196
\brief Indicates a system error, such as failure to create a file or folder,
197
or any other (usually non-recoverable) kind of error that should not arise during normal operation.
302
\brief Indicates a system error.
303
304
This is a generic "catch-all" exception that you can throw to indicate unexpected errors that do not fit into
305
any of the other categories. For example, ResourceException is appropriate to indicate out of
306
file descriptors, failure to locate a configuration file, or any other unexpected system error. You should
307
provide as much contextual information about such errors as possible. In particular, unexpected errors
308
typically need to be diagnosed from log files. This means that you should provide, at least, the full error
309
message you received from the cloud service (or the operating system), together with all other relevant
310
details, such as the name of the file, the URL of a failed request, any HTTP error information, and so on.
198
311
*/
312
199
313
class UNITY_STORAGE_EXPORT ResourceException : public StorageException
200
314
{
201
315
public:
316
/**
317
\brief Construct an InvalidArgumentException.
318
\param error_message The error message for the exception.
319
\param error_code The system (or library) error code for the exception.
320
In case of system call failures, <code>error_code</code> should be the value of <code>errno</code>.
321
If the error code represents something else, such as a <code>QFileDevice::FileError</code>,
322
also indicate in the error message what that error code is; otherwise, it can be
323
impossible to diagnose a problem, especially when looking at log files after the fact.
324
*/
202
325
ResourceException(std::string const& error_message, int error_code);
203
326
~ResourceException();
204
327
328
/**
329
\brief Return the error code.
330
\return The value of the <code>error_code</code> parameter that was passed to the constructor.
331
*/
205
332
int error_code() const noexcept;
206
333
207
334
private:
209
336
};
210
337
211
338
/**
212
\brief Indicates that the server side caught an exception that does not derive from
213
StorageException, such as a std::exception, or caught some other unknown type (such as `int`).
339
\brief Indicates that a provider threw an exception not derived from StorageException.
340
341
The runtime translates all exception that are thrown by a provider and that do not derive from StorageException
342
to UnknownException.
343
344
Do not throw this exception explicitly; is is a "catch-all" exception that the runtime uses to
345
indicate that something completely unexpected happened. (If a client receives this exception from your
346
provider, chances are that you have forgotten to handle an error condition somewhere.)
214
347
*/
348
215
349
class UNITY_STORAGE_EXPORT UnknownException : public StorageException
216
350
{
217
351
public:
352
/**
353
\brief Construct an UnknownArgumentException.
354
\param error_message The error message for the exception. This is the string returned by <code>what()</code>
355
for <code>std::exception</code> or "Unknown exception" for exceptions that do not derive
356
from <code>std::exception</code>.
357
*/
218
358
UnknownException(std::string const& error_message);
219
359
~UnknownException();
220
360
};
Loggerhead is a web-based interface for Breezy
Version: 2.0.1