Info Catalog dbus: Alternative Buses dbus: Top dbus: Index

dbus: Errors and Events

 
 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 
 (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 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.
 

Info Catalog dbus: Alternative Buses dbus: Top dbus: Index