Use of org.freedesktop.DBus.Error

[Simon McVittie]

On 15/09/15 16:13, Thomas Downing wrote:
> 1. where can I find the specification for org.freedesktop.DBus.Error?  Or a list 
> of all the defined error names for the same (e.g. UnknownMethod, etc.).

See dbus/dbus-protocol.h in the reference implementation (libdbus).

> 2. If a process experiences an error while servicing a method call, but it is 
> not a fatal error (the process is still consistent and operating), what is the 
> prefered error name under org.freedesktop.DBus.Error, if there is such?

There is no single correct answer to this question, because all D-Bus
errors describe different versions of this situation. If we only wanted
a finite set of errors, we'd have used a spec-defined integer (enum)
instead of a namespaced string. D-Bus errors are not like errno, they're
more like GLib's GError: defining your own error strings in your own
namespace (analogous to a GError domain) is encouraged.

If the method failed for a domain-specific reason, you should use a
domain-specific error. For instance, if you're writing a Telepathy
component, you should use Telepathy errors, such as
<http://telepathy.freedesktop.org/spec/errors.html#Error:Connection%20Refused>.
If you are designing your own D-Bus interface, you will probably want to
define a set of error strings to go with it. For example, if your
service is com.example.Downloader, you might define error strings that
include com.example.Downloader.Error.PermissionDenied and
com.example.Downloader.Error.NotFound. It's vaguely conventional to use
...Error.* as a D-Bus error domain, and to use ...Error.Failed if you
need a generic catch-all error within that domain.

I would advise not using the well-known error strings in dbus-protocol.h
unless they fit your situation perfectly; they are mostly there to be
used by dbus-daemon itself, or by D-Bus libraries such as libdbus or
GDBus, to report errors relating to the D-Bus protocol. For instance,
org.freedesktop.DBus.Error.AccessDenied means access to a D-Bus method
was denied, and it would be needlessly confusing if you recycled it as a
way to report that com.example.Downloader had encountered HTTP error 403.

Returning an error as a response to a method call means that the method
call has failed, and that there will be no other reply to that
particular call. However, all D-Bus errors that are sent by services
would normally be sent by a service that is still in a consistent state
and can still respond to other method calls.

If a service is *not* in a consistent state in which it can respond to
method calls, it might as well disconnect from the bus, or just crash
(potentially after replying to a currently-pending method call, if its
state is still sufficiently consistent to do so). dbus-daemon will
automatically send a NoReply error response to any method calls that
were "in flight" at the time of disconnection, and if the service leaves
the bus, then its name will become available for a subsequently started
instance, perhaps automatically started by D-Bus activation.

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