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 keyword :system or the keyword :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 a unicast message.⁶ path is the D-Bus object path signal is sent from. interface is an interface available at path. It must provide signal.

The remaining arguments args are passed to signal as arguments. They are converted into D-Bus types as described in Mapping Lisp types and D-Bus types.. 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 keyword :system or the keyword :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 will no longer be received.

path is the corresponding D-Bus object path that 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.⁷ Their 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 those signals, whose first argument names a service or interface within the 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))

(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 therefore define a single string argument. Plugging a USB device into 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