Use of org.freedesktop.DBus.Error

[Simon McVittie]

On 15/09/15 19:01, Thomas Downing wrote:
> The larger picture as it seems to me, is that published standards (such as 
> org.freedesktop.StatusNotifierItem, in my case) should also specify a set of 
> error names to be used by those implementing the standards.

They probably should, but please raise this with the publishers of those
standards.

> Absent that, 
> having an error name in an error message doesn't seem have any value beyond 
> that of the free form error string also allowed in an error message.

Yes, although it's possible that in this particular standard, there are
no errors that would make sense to distinguish, and the only
machine-readable error reporting that is desired is "success" or "error".

D-Bus errors are intended to act as a pair of complementary values
(machine-readable name, human-readable message), similar to typed
exceptions in C++, Java, Python etc. (the type becomes the name, the
message is the message). If the only machine-readable distinction you
want is between "error" and "no error", then the name is not
particularly useful and you can use anything, in the same way you could
do all your error handling in Python via "raise Exception(message)" if
you knew the type was going to be ignored anyway.

The machine-readable part is only non-optional to simplify error
handling; if you don't care what it is, just use anything (for example
org.freedesktop.DBus.Failed or com.example.YourApp.Failed).

The machine-readable part becomes useful in two main situations:

* where you want the consumer of errors to translate a finite set of
  well-known error conditions into messages chosen by a UI designer,
  filling in additional context if it's available, and either
  discarding the (often cryptic and technical) human-readable
  message or keeping it as secondary "advanced/debug" information;

* where you want the consumer of errors to treat some errors
  differently,for example retrying operations that temporarily failed
  after a while, but not retrying operations that permanently failed
  (like the difference between HTTP 5xx and 4xx)

I used to work on Telepathy, which is an example of a specification with
a relatively rich vocabulary of D-Bus errors. We used them for both
those reasons.

-- 
Simon McVittie
Collabora Ltd. <http://www.collabora.com/>