9 Errors and events.

The internal actions can be traced by running in a debug mode.

Variable: dbus-debug ¶

If this variable is non-nil, D-Bus specific debug messages are raised.

Input parameters of dbus-call-method, dbus-call-method-asynchronously, dbus-send-signal, dbus-register-method, dbus-register-property and dbus-register-signal are checked for correct D-Bus types. If there is a type mismatch, the Lisp error wrong-type-argument D-Bus arg is raised.

All errors raised by D-Bus are signaled with the error symbol dbus-error. If possible, error messages from D-Bus are appended to the dbus-error.

Special Form: dbus-ignore-errors forms… ¶

This executes forms exactly like a progn, except that dbus-error errors are ignored during the forms (the macro returns nil then). These errors can be made visible when dbus-debug is set to non-nil.

Incoming D-Bus messages are handled as Emacs events, see (elisp)Misc Events. They are retrieved only, when Emacs runs in interactive mode. The generated event has this form:

(dbus-event bus type serial service destination path interface member
            handler &rest args)

bus identifies the D-Bus the message is coming from. It is either a Lisp keyword, :system, :session, :system-private or :session-private, or a string denoting the bus address.

type is the D-Bus message type which has caused the event. It can be dbus-message-type-invalid, dbus-message-type-method-call, dbus-message-type-method-return, dbus-message-type-error, or dbus-message-type-signal. serial is the serial number of the received D-Bus message, unless type is equal dbus-message-type-error.

service and path are the unique name and the object path of the D-Bus object emitting the message. destination is the D-Bus name the message is dedicated to, or nil in case the message is a broadcast signal.

interface and member denote the message which has been sent. When type is dbus-message-type-error, member is the error name.

handler is the callback function which has been registered for this message (see Sending and receiving signals.). args are the typed arguments as returned from the message. They are passed to handler without type information, when it is called during event handling in dbus-handle-event.

In order to inspect the dbus-event data, you could extend the definition of the callback function in Sending and receiving signals.:

(defun my-dbus-signal-handler (&rest args)
  (message "my-dbus-signal-handler: %S" last-input-event))

There exist convenience functions which could be called inside a callback function in order to retrieve the information from the event.

Function: dbus-event-bus-name event ¶

This function returns the bus name event is coming from. The result is either the keyword :system or the keyword :session.

Function: dbus-event-message-type event ¶

This function returns the message type of the corresponding D-Bus message. The result is a natural number.

Function: dbus-event-serial-number event ¶

This function returns the serial number of the corresponding D-Bus message. The result is a natural number.

Function: dbus-event-service-name event ¶

This function returns the unique name of the D-Bus object event is coming from.

Function: dbus-event-destination-name event ¶

This function returns the unique name of the D-Bus object event is dedicated to.

Function: dbus-event-path-name event ¶

This function returns the object path of the D-Bus object event is coming from.

Function: dbus-event-interface-name event ¶

This function returns the interface name of the D-Bus object event is coming from.

Function: dbus-event-member-name event ¶

This function returns the member name of the D-Bus object event is coming from. It is either a signal name or a method name.

Function: dbus-event-handler event ¶

This function returns the handler the D-Bus object event is applied with.

Function: dbus-event-arguments event ¶

This function returns the arguments the D-Bus object event is carrying on.

D-Bus errors are not propagated during event handling, because it is usually not desired. D-Bus errors in events can be made visible by setting the variable dbus-debug to non-nil. They can also be handled by a hook function.

Variable: dbus-event-error-functions ¶

This hook variable keeps a list of functions, which are called when a D-Bus error happens in the event handler. Every function must accept two arguments, the event and the error variable caught in condition-case by dbus-error.

Such functions can be used to adapt the error signal to be raised. Example:

(defun my-dbus-event-error-handler (event error)
  (when (string-equal (concat dbus-interface-emacs ".FileManager")
                      (dbus-event-interface-name event))
    (message "my-dbus-event-error-handler: %S %S" event error)
    (signal 'file-error (cdr error))))

(add-hook 'dbus-event-error-functions #'my-dbus-event-error-handler)

Hook functions should take into account that there might be other D-Bus applications running. They should therefore check carefully, whether a given D-Bus error is related to them.