1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
|
Exceptions
========================
.. py:currentmodule:: sdbus.exceptions
Error name bound exceptions
+++++++++++++++++++++++++++++++
These exceptions are bound to specific D-Bus error names. For example,
:py:exc:`DbusFailedError` is bound to `org.freedesktop.DBus.Error.Failed`
error name.
This means if the remote object sends an error message with this error name
the Python will receive this exception.
When raised in a method callback an error message will be sent
back to caller.
See `list of error exceptions`_.
New error bound exceptions
+++++++++++++++++++++++++++++++
If you want to create a new error bound exception you should subclass
it from :py:exc:`DbusFailedError` and provide a **unique** ``dbus_error_name``
attribute in the exception body definition.
Example: ::
class DbusExampleError(DbusFailedError):
dbus_error_name = 'org.example.Error'
If ``dbus_error_name`` is not unique the :py:exc:`ValueError` will be raised.
Defining an exception will automatically bind incoming error message to this
new exception.
Existing exceptions can be manually binded using :py:func:`map_exception_to_dbus_error`
function.
Python built-in exceptions
+++++++++++++++++++++++++++
All Python built-in exceptions are mapped to D-Bus errors.
The D-Bus error name is created by appending ``org.python.Error.``
to the exception name.
For example, ``AssertionError`` is bound
to ``org.python.Error.AssertionError`` name.
Functions
+++++++++
.. py:function:: map_exception_to_dbus_error(exception, dbus_error_name)
Map exception to a D-bus error. Error name must be unique.
:param Type[Exception] exception: Exception to bind.
:param str dbus_error_name: D-Bus error name to bind to.
Other exceptions
+++++++++++++++++++++++++
.. py:exception:: SdBusBaseError
Base exceptions for all exceptions defined in sdbus.
.. py:exception:: SdBusUnmappedMessageError
Message error that is unmapped.
The exceptions argument is a tuple of
error name and error message.
.. py:exception:: SdBusLibraryError
sd-bus library returned error.
Exception message contains line number and the error name.
.. _name-request-exceptions:
Name request exceptions
+++++++++++++++++++++++
These exceptions will be raise if an error related to ownership of D-Bus
names occurs when calling :py:func:`.request_default_bus_name_async` or
:py:func:`.request_default_bus_name`.
.. py:exception:: SdBusRequestNameError
Common base exception for any name ownership error.
.. py:exception:: SdBusRequestNameInQueueError
Someone already owns the name but the request has been placed in queue.
.. py:exception:: SdBusRequestNameExistsError
Someone already owns the name.
.. py:exception:: SdBusRequestNameAlreadyOwnerError
The caller already owns the name.
.. _list of error exceptions:
Error name exception list
++++++++++++++++++++++++++++++
.. py:exception:: DbusFailedError
Generic failure exception.
Recommended to subclass to create a new exception.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.Failed
.. py:exception:: DbusNoMemoryError
Remote object is out of memory.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.NoMemory
.. py:exception:: DbusServiceUnknownError
No service with such name exists.
Probably should only be raised by bus daemon.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.ServiceUnknown
.. py:exception:: DbusNameHasNoOwnerError
No process owns the name you called.
Probably should only be raised by bus daemon.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.NameHasNoOwner
.. py:exception:: DbusNoReplyError
Timeout on reply.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.NoReply
.. py:exception:: DbusIOError
Input/Output error.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.IOError
.. py:exception:: DbusBadAddressError
Bad address.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.BadAddress
.. py:exception:: DbusNotSupportedError
Something is unsupported on this platform.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.NotSupported
.. py:exception:: DbusLimitsExceededError
Some resource was exhausted. (for example, file descriptors)
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.LimitsExceeded
.. py:exception:: DbusAccessDeniedError
Caller does not have enough privileges.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.AccessDenied
.. py:exception:: DbusAuthFailedError
Authentication failed.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.AuthFailed
.. py:exception:: DbusNoServerError
Unable to connect to bus.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.NoServer
.. py:exception:: DbusTimeoutError
Socket timeout.
This is different from :py:exc:`DbusNoReplyError` as here the
connection to bus timeout not the remote object not replying.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.Timeout
.. py:exception:: DbusNoNetworkError
No network access.
Encountered you use D-Bus over TCP or SSH.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.NoNetwork
.. py:exception:: DbusAddressInUseError
Address in use.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.AddressInUse
.. py:exception:: DbusDisconnectedError
Disconnected from bus.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.Disconnected
.. py:exception:: DbusInvalidArgsError
Method call args are invalid.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.InvalidArgs
.. py:exception:: DbusFileNotFoundError
File not found.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.FileNotFound
.. py:exception:: DbusFileExistsError
Generic failure exception.
Recommended to subclass to create a new exception.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.FileExists
.. py:exception:: DbusUnknownMethodError
Unknown D-Bus method.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.UnknownMethod
.. py:exception:: DbusUnknownObjectError
Unknown D-Bus object.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.UnknownObject
.. py:exception:: DbusUnknownInterfaceError
Unknown D-Bus interface.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.UnknownInterface
.. py:exception:: DbusUnknownPropertyError
Unknown D-Bus property.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.UnknownProperty
.. py:exception:: DbusPropertyReadOnlyError
D-Bus property is read only.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.PropertyReadOnly
.. py:exception:: DbusUnixProcessIdUnknownError
PID does not exists.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.UnixProcessIdUnknown
.. py:exception:: DbusInvalidSignatureError
Invalid D-Bus type signature.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.InvalidSignature
.. py:exception:: DbusInvalidFileContentError
Invalid file content.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.InvalidFileContent
.. py:exception:: DbusInconsistentMessageError
D-Bus message is malformed.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.InconsistentMessage
.. py:exception:: DbusMatchRuleNotFound
Match rule does not exist.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.MatchRuleNotFound
.. py:exception:: DbusMatchRuleInvalidError
Match rule is invalid.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.MatchRuleInvalid
.. py:exception:: DbusInteractiveAuthorizationRequiredError
Requires interactive authorization.
.. py:attribute:: dbus_error_name
:type: str
:value: org.freedesktop.DBus.Error.InteractiveAuthorizationRequired
|
