Next: , Previous: Alternative Buses, Up: Top

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. These errors can be made visible when dbus-debug is set to t.

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

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

bus identifies the D-Bus the message is coming from. It is either the symbol :system or the symbol :session.

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.

service and path are the unique name and the object path of the D-Bus object emitting the message. interface and member denote the message which has been sent.

handler is the callback function which has been registered for this message (see Signals). When a dbus-event event arrives, handler is called with args as arguments.

In order to inspect the dbus-event data, you could extend the definition of the callback function in 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

Returns the bus name event is coming from. The result is either the symbol :system or the symbol :session.

— Function: dbus-event-message-type event

Returns the message type of the corresponding D-Bus message. The result is a natural number.

— Function: dbus-event-serial-number event

Returns the serial number of the corresponding D-Bus message. The result is a natural number.

— Function: dbus-event-service-name event

Returns the unique name of the D-Bus object event is coming from.

— Function: dbus-event-path-name event

Returns the object path of the D-Bus object event is coming from.

— Function: dbus-event-interface-name event

Returns the interface name of the D-Bus object event is coming from.

— Function: dbus-event-member-name event

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

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 t. 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 the 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 shall take into account, that there might be other D-Bus applications running. Therefore, they shall check carefully, whether a given D-Bus error is related to them.