dbus: Alternative Buses
8 Alternative buses and environments.
*************************************
Until now, we have spoken about the system and the session buses, which
are the default buses to be connected to. However, it is possible to
connect to any bus, from which the address is known. This is a UNIX
domain or TCP/IP socket. Everywhere, where a BUS is mentioned as
argument of a function (the symbol ‘:system’ or the symbol ‘:session’),
this address can be used instead. The connection to this bus must be
initialized first.
-- Function: dbus-init-bus bus &optional private
Establish the connection to D-Bus BUS.
BUS can be either the symbol ‘:system’ or the symbol ‘:session’, or
it can be a string denoting the address of the corresponding bus.
For the system and session buses, this function is called when
loading ‘dbus.el’, there is no need to call it again.
The function returns a number, which counts the connections this
Emacs session has established to the BUS under the same unique name
(see ‘dbus-get-unique-name’). It depends on the libraries Emacs is
linked with, and on the environment Emacs is running. For example,
if Emacs is linked with the gtk toolkit, and it runs in a GTK-aware
environment like Gnome, another connection might already be
established.
When PRIVATE is non-‘nil’, a new connection is established instead
of reusing an existing one. It results in a new unique name at the
bus. This can be used, if it is necessary to distinguish from
another connection used in the same Emacs process, like the one
established by GTK+. It should be used with care for at least the
‘:system’ and ‘:session’ buses, because other Emacs Lisp packages
might already use this connection to those buses.
Example: You initialize a connection to the AT-SPI bus on your
host:
(setq my-bus
(dbus-call-method
:session "org.a11y.Bus" "/org/a11y/bus"
"org.a11y.Bus" "GetAddress"))
⇒ "unix:abstract=/tmp/dbus-2yzWHOCdSD,guid=a490dd26625870ca1298b6e10000fd7f"
;; If Emacs is built with gtk support, and you run in a GTK enabled
;; environment (like a GNOME session), the initialization reuses the
;; connection established by GTK's atk bindings.
(dbus-init-bus my-bus)
⇒ 2
(dbus-get-unique-name my-bus)
⇒ ":1.19"
;; Open a new connection to the same bus. This obsoletes the
;; previous one.
(dbus-init-bus my-bus 'private)
⇒ 1
(dbus-get-unique-name my-bus)
⇒ ":1.20"
D-Bus addresses can specify different transport. A possible
address could be based on TCP/IP sockets, see next example.
However, it depends on the bus daemon configuration, which
transport is supported.
-- Function: dbus-setenv bus variable value
Set the value of the BUS environment variable VARIABLE to VALUE.
BUS is either a Lisp symbol, ‘:system’ or ‘:session’, or a string
denoting the bus address. Both VARIABLE and VALUE should be
strings.
Normally, services inherit the environment of the bus daemon. This
function adds to or modifies that environment when activating
services.
Some bus instances, such as ‘:system’, may disable setting the
environment. In such cases, or if this feature is not available in
older D-Bus versions, a ‘dbus-error’ error is raised.
As an example, it might be desirable to start X11 enabled services
on a remote host’s bus on the same X11 server the local Emacs is
running. This could be achieved by
(setq my-bus "unix:host=example.gnu.org,port=4711")
⇒ "unix:host=example.gnu.org,port=4711"
(dbus-init-bus my-bus)
⇒ 1
(dbus-setenv my-bus "DISPLAY" (getenv "DISPLAY"))
⇒ nil
Info Catalog
dbus: Signals
dbus: Top
dbus: Errors and Events