Next: Errors and events., Previous: Sending and receiving signals., Up: D-Bus integration in Emacs [Contents][Index]
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 with a known address. This is a UNIX
domain or TCP/IP socket. Everywhere, where a bus is mentioned
as argument of a function (the keyword :system
or the keyword
:session
), this address can be used instead. The connection to
this bus must be initialized first.
This function establishes the connection to D-Bus bus.
bus can be either the keyword :system
or the keyword
: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.
If Emacs was invoked when there was no D-Bus session bus available
yet, you can set the environment variable
DBUS_SESSION_BUS_ADDRESS
once the session bus daemon is running
and offering the address. Calling dbus-init-bus
initializes
the connection to the session bus.
(setenv "DBUS_SESSION_BUS_ADDRESS" "unix:path=/run/user/1000/bus") ⇒ "unix:path=/run/user/1000/bus" (dbus-init-bus :session) ⇒ 2
dbus-init-bus
returns the number of 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+. If bus is the keyword :system
or
the keyword :session
, the new private connection is identified
by the keywords :system-private
or :session-private
,
respectively.
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 supersedes the ;; previous one. (dbus-init-bus my-bus 'private) ⇒ 1 (dbus-get-unique-name my-bus) ⇒ ":1.20"
D-Bus addresses can specify a different transport. A possible address could be based on TCP/IP sockets, see next example. Which transport is supported depends on the bus daemon configuration, however.
This function sets the value of the bus environment variable to value.
bus is either a Lisp keyword, :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, this function signals a dbus-error
.
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
Next: Errors and events., Previous: Sending and receiving signals., Up: D-Bus integration in Emacs [Contents][Index]