Signals are one way messages. They carry input parameters, which are received by all objects which have registered for such a signal.
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
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.6 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")
With this function, an application registers for a signal on the D-Bus bus.
bus is either the symbol
:system or the symbol
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
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.7 The meaning is as follows:
:pathNarguments can be used for object path wildcard matches as specified by D-Bus, while an
:argNargument requires an exact match.
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
For backward compatibility, a broadcast message is also emitted if service is the known or unique name Emacs is registered at D-Bus bus.
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.