Info Catalog dbus: Receiving Method Calls dbus: Top dbus: Alternative Buses

dbus: Signals

 
 7 Sending and receiving signals.
 ********************************
 
 Signals are one way messages.  They carry input parameters, which are
 received by all objects which have registered for such a signal.
 
  -- Function: dbus-send-signal bus service path interface signal &rest
           args
      This function is similar to ‘dbus-call-method’.  The difference is,
      that there are no returning output parameters.
 
      The function emits SIGNAL on the D-Bus BUS.  BUS is either the
      symbol ‘:system’ or the symbol ‘:session’.  It doesn’t matter
      whether another object has registered for SIGNAL.
 
      Signals can be unicast or broadcast messages.  For broadcast
      messages, SERVICE must be ‘nil’.  Otherwise, SERVICE is the D-Bus
      service name the signal is sent to as unicast message.(1)  PATH is
      the D-Bus object path SIGNAL is sent from.  INTERFACE is an
      interface available at PATH.  It must provide SIGNAL.
 
      All other arguments args are passed to SIGNAL as arguments.  They
      are converted into D-Bus types as described in Type
      Conversion.  Example:
 
           (dbus-send-signal
             :session nil dbus-path-emacs
             (concat dbus-interface-emacs ".FileManager") "FileModified"
             "/home/albinus/.emacs")
 
  -- Function: dbus-register-signal bus service path interface signal
           handler &rest args
      With this function, an application registers for a signal on the
      D-Bus BUS.
 
      BUS is either the symbol ‘:system’ or the symbol ‘:session’.
 
      SERVICE is the D-Bus service name used by the sending D-Bus object.
      It can be either a known name or the unique name of the D-Bus
      object sending the signal.  A known name will be mapped onto the
      unique name of the object, owning SERVICE at registration time.
      When the corresponding D-Bus object disappears, signals won’t be
      received any longer.
 
      PATH is the corresponding D-Bus object path, SERVICE is registered
      at.  INTERFACE is an interface offered by SERVICE.  It must provide
      SIGNAL.
 
      SERVICE, PATH, INTERFACE and SIGNAL can be ‘nil’.  This is
      interpreted as a wildcard for the respective argument.
 
      HANDLER is a Lisp function to be called when the SIGNAL is
      received.  It must accept as arguments the output parameters SIGNAL
      is sending.
 
      The remaining arguments ARGS can be keywords or keyword string
      pairs.(2)  The meaning is as follows:
 
         • ‘:argN’ STRING:
           ‘:pathN’ STRING:
           This stands for the Nth argument of the signal.  ‘:pathN’
           arguments can be used for object path wildcard matches as
           specified by D-Bus, while an ‘:argN’ argument requires an
           exact match.
 
         • ‘:arg-namespace’ STRING:
           Register for the signals, which first argument defines the
           service or interface namespace STRING.
 
         • ‘:path-namespace’ STRING:
           Register for the object path namespace STRING.  All signals
           sent from an object path, which has STRING as the preceding
           string, are matched.  This requires PATH to be ‘nil’.
 
         • ‘:eavesdrop’:
           Register for unicast signals which are not directed to the
           D-Bus object Emacs is registered at D-Bus BUS, if the security
           policy of BUS allows this.  Otherwise, this argument is
           ignored.
 
      ‘dbus-register-signal’ returns a Lisp object, which can be used as
      argument in ‘dbus-unregister-object’ for removing the registration
      for SIGNAL.  Example:
 
           (defun my-dbus-signal-handler (device)
             (message "Device %s added" device))
 
           ⇒ my-dbus-signal-handler
 
           (dbus-register-signal
             :system "org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
             "org.freedesktop.Hal.Manager" "DeviceAdded"
             'my-dbus-signal-handler)
 
           ⇒ ((:signal :system "org.freedesktop.Hal.Manager" "DeviceAdded")
               ("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
                my-signal-handler))
 
      As we know from the introspection data of interface
      ‘org.freedesktop.Hal.Manager’, the signal ‘DeviceAdded’ provides
      one single parameter, which is mapped into a Lisp string.  The
      callback function ‘my-dbus-signal-handler’ must define one single
      string argument therefore.  Plugging an USB device to your machine,
      when registered for signal ‘DeviceAdded’, will show you which
      objects the GNU/Linux ‘hal’ daemon adds.
 
      Some of the match rules have been added to a later version of
      D-Bus.  In order to test the availability of such features, you
      could register for a dummy signal, and check the result:
 
           (dbus-ignore-errors
             (dbus-register-signal
               :system nil nil nil nil 'ignore :path-namespace "/invalid/path"))
 
           ⇒ nil
 
    ---------- Footnotes ----------
 
    (1) For backward compatibility, a broadcast message is also emitted
 if SERVICE is the known or unique name Emacs is registered at D-Bus BUS.
 
    (2) For backward compatibility, the arguments ARGS can also be just
 strings.  They stand for the respective arguments of SIGNAL in their
 order, and are used for filtering as well.  A ‘nil’ argument might be
 used to preserve the order.
 

Info Catalog dbus: Receiving Method Calls dbus: Top dbus: Alternative Buses